Numero 02 del 2021

Titolo: Gli script di Jaws 10. Posizione, Contrassegni e Ricerche.

Autore: Abramo Volpato.

Articolo:
Gli script di Jaws 10. Posizione, Contrassegni e Ricerche.

Di Abramo Volpato.

10.1. Velocemente, ed al posto giusto!

Dopo il tempo impiegato soprattutto a realizzare procedure generiche, ecco un capitolo al termine del quale potremmo dire di aver compiuto del lavoro concreto. Non siamo ancora alla fine del nostro viaggio, tutt'altro, ma quando ci saremo lasciati alle spalle queste pagine potremo dire di aver praticamente concluso il lavoro fin qui iniziato.

Il filo comune di tutto questo codice sarà il muoversi velocemente, ed il trovarsi "al posto giusto", così come recita il titolo, nel documento aperto. Si tratta di una pratica molto redditizia in termini di tempo, che ha il merito di lasciare, non solo a chi usa la sintesi vocale, un maggiore spazio per concentrarsi su quel che c'è da fare, più che pensare a dove ci si trovi in quel momento.

In particolare, creeremo un sistema per memorizzare dei contrassegni, in ciascun applicativo e per ciascun diverso documento, risolvendo così entrambi i difetti che aveva il sistema approntato per il solo Blocco Note. Così, al rientro in un determinato file, si potrà tornare al punto in cui si erano premuti i comandi per l'uscita dal programma o dalla finestra attiva, sia in modo automatico, sia eseguendo un determinato script.

L'aspetto importante è che, per realizzare questo sistema, non inventeremo nulla, bensì prenderemo il modello dei contrassegni creati da Jaws dentro al programma Microsoft Word, allargandolo ed adattandolo anche per gli altri applicativi. Così facendo, potremo anche interagire con i comandi di Jaws, ad esempio quelli previsti a tale scopo proprio dentro allo stesso Word, adattandoci anche allo standard imposto dai tasti usati da questo applicativo.

La funzionalità in più, rispetto al sistema utilizzato in Word, sarà quello di creare un elenco degli ultimi dieci contrassegni registrati. Questo piccolo archivio si potrà scorrere in avanti ed indietro, ripercorrendo i passi del proprio lavoro, e stavolta usando i suoni per orientarsi nell'elenco.

Avremo poi l'occasione di dare un altro scopo preciso alla funzione di ricerca testo, creata due capitoli fa, finalizzandola al muoversi tra le etichette personali di inizio codice. Potremo così porre dei contrassegni anche reali nei nostri documenti, che ci consentano di passare velocemente dall'uno all'altro dei punti principali dei file trattati.

Un lavoro piuttosto articolato, quindi, dove si cercherà di essere il più possibile chiari seppur sintetici. Non prendete paura per la lunghezza del capitolo, per metà occupato solo da codice, in un lavoro che inizieremo comunque sempre allo stesso modo.

Esercizio 10.1.1. Aggiornare il file Personale delle Costanti.

LUNGHEZZA = "Lunghezza", ; termine omonimo
RIGHE = "Righe", ; termine omonimo
POSIZIONE = "Posizione", ; termine omonimo
JKM = ".JKM", ; estensione omonima
JAWS_FILE = "Default", ; nome dei file predefiniti di Jaws
SEGNI = 5, ; valore che identifica l'archivio dei settaggi personalizzati
CLASSIC = "Classic", ; termine omonimo
SUFFISSO_JSI = "_MarkedPlaceDocuments.JSI", ; suffisso per archivi dei contrassegni
TEMPORANEO = 6, ; valore che identifica un archivio valido solo per le singole sessioni
CARTELLA_SESSIONE = "transient-session", ; cartella per i file delle singole sessioni
TMP = ".TMP", ; estensione per file temporanei
CTS = "CTS_", ; base per sezione speciale dei contrassegni
CHIAVE_SEGNI = "MarkedPlace", ; nome della chiave per il valore dei contrassegni
CONTRASSEGNO = "Contrassegno", ; termine omonimo
MAX_SEGNI = 9, ; numero massimo dei contrassegni tra le ultime registrazioni
NUOVE = 19, ; numero versione di Jaws dalla quale è si registrano contrassegni temporanei
ESCE = "Esce", ; termine omonimo
CHIUDE = "Chiude", ; termine omonimo
APERTURA = "Apertura", ; termine omonimo
ULTIMO = "Ultimo", ; termine omonimo
ERRORE1 = "Click3", ; suono per errore in alto
ULTIMO_SEGNO = "descend", ; suono per chiusura in basso
PRIMO_SEGNO = "ascend", ; suono per chiusura in alto
SALTA = 2, ; valore per non ripetere la pressione degli ultimi tasti di attivazione
CERCA = "Cerca", ; termine omonimo
SALVA = "Salva", ; termine omonimo
TORNA = "Torna", ; termine omonimo
CONTROL_F = "Control+F", ; combinazione tasti omologa
MARK_PLACE = "ScriveSegno (iCurCharPos); registra il dato con l'apposita funzione",
FOCUS_CHANGED = "GestisceDato (TORNA, APERTURA); _Ps Codice",
SHIFT_CONTROL_T = "Shift+Control+T", ; combinazione tasti omologa
ALT_F4 = "Alt+F4", ; combinazione tasti omologa
ALTF4 = "AltF4", ; combinazione tasti omonima
_A = "a", ; carattere omonimo
OPZIONE_STANDARD = "<< Standard", ; titolo di opzione nella finestra Cerca e Sostituisci
ALT_L = "Alt+L", ; combinazione tasti omologa
ALT_C = "Alt+C", ; combinazione tasti omologa
_G = "G", ; carattere omonimo
_S = "s", ; carattere omonimo
ALT_A = "Alt+A", ; combinazione omologa
OK_RICERCA = "Trova successivo", ; nome del controllo all'uscita da una ricerca in Word
CAMPO_MAIUSCOLE = 20, ; codice del controllo all'uscita da un'errata ricerca in Wordpad

Esercizio 10.1.2. Aggiornare il file Personale delle Variabili Globali.

String gsPartenza, ; nome del punto di partenza di uno spostamento

Esercizio 10.1.3. Aggiornare il file Personale dei Messaggi.

; tre termini separati da caratteri Controbarra
@msg3Controbarra
%1\%2\%3
@@
; Contrassegno nel documento già registrato
@hlpGiaSegno
Contrassegno già salvato
@@
; Contrassegno nel documento già registrato - versione corta
@hlpGiaSegno_corto
Già salvato.
@@
; salvataggio del contrassegno riuscito
@hlpOkSegno
Contrassegno%1 salvato.
@@
; salvataggio del contrassegno riuscito - versione corta
@hlpOkSegno_corto
%1 Salvato
@@
; mancato salvataggio del contrassegno
@hlpNoCts
Impossibile salvare contrassegno%1.
@@
; mancato salvataggio del contrassegno - versione corta
@hlpNoCts_corto
%1 Non salvato
@@
; ritorno all'elemento ed al valore specificati
@msgTornaA
Torna a %1 %2
@@
; mancata registrazione dei dati della finestra
@hlpNoRegistra
Dati non ancora registrati per la finestra corrente.
@@
; mancata registrazione dei dati della finestra - versione corta
@hlpNoRegistra_corto
Finestra non registrata.
@@
; nessun contrassegno memorizzato per il documento corrente
@hlpNoSegno
Nessun contrassegno%1 per il documento corrente.
@@
; nessun contrassegno memorizzato per il documento corrente - versione corta
@hlpNoSegno_corto
Nessun contrassegno%1.
@@
; cursore già posto sul contrassegno
@hlpSulPosto
Siamo già sul contrassegno.
@@
; cursore già posto sul contrassegno - versione corta
@hlpSulPosto_corto
Già sul posto.
@@
; azione da compiere non riconosciuta
@hlpNoAzione
Azione %1 non valida.
@@
; azione da compiere non riconosciuta - versione corta
@hlpNoAzione_corto
Non valida.
@@
; titolo di conferma per continuare la ricerca
@ttlContinuaCerca
Raggiunt%1 %2 del documento.
@@
; suffisso per la fine
@msgFine
la fine
@@
; messaggio di conferma per continuare la ricerca
@msgContinuaCerca
Continuare la ricerca dal%1?
@@
; suffisso per l'inizio
@msgInizio
l'inizio
@@

***

10.2. Riga, colonna e Lunghezza nei quattro applicativi.

Iniziamo concludendo il lavoro avviato lo scorso capitolo, quando abbiamo realizzato la procedura per leggere i dati dalla Barra di stato. Avevamo già evidenziato, infatti, che tale procedura non sarebbe stata sufficiente a restituirci tutti i dati a noi necessari, o almeno non in tutti gli applicativi di nostro interesse.

Per questo, come già anticipato, faremo una semplicissima modifica ai tre script di lettura realizzati, limitandoci a cambiarne il titolo. Per reperire i dati, invece, creeremo altre tre funzioni, due di esse da una sola riga, e l'altra che risulta la versione generale di una già creata nel Blocco Note.

Esercizio 10.2.1. La funzione ValoreRiga.

FileScript. Default.JSS

Nome. ValoreRiga

Descrizione. Restituisce il numero della riga su cui è posizionato il cursore, chiamando la funzione nativa di Jaws.

Ritorni. Di tipo Int. Il numero della riga su cui è posto il cursore.

Note.

1. A questa funzione, e alla sua gemella che proporremo di seguito, non servono controlli sulle finestre, in quanto esse saranno chiamate solo dall'interno della funzione generica di gestione, la quale effettua già questo tipo di controlli.

Codice.

Int Function ValoreRiga ()
Return GetCursorRow (); restituisce il dato della funzione nativa
EndFunction

Esercizio 10.2.2. La funzione ValoreColonna.

FileScript. Default.JSS

Nome. ValoreColonna

Descrizione. Restituisce il numero della colonna su cui è posizionato il cursore, chiamando la funzione nativa di Jaws.

Ritorni. Di tipo Int. Il numero della colonna su cui è posto il cursore.

Novità.

1. La funzione integrata "GetCursorCol", (OttieniColonnaSulCursore), che legge il dato omonimo. Così come quella analoga per le righe, la funzione ha due parametri, ma entrambi sono opzionali e quindi di norma non sono da esprimere. In ogni caso, tramite essi, si possono specificare:

- con il primo, un valore che esprime il tipo di cursore di cui rilevare la posizione; quando non si esprime nulla, si assume che sia il cursore attivo in quel momento;
- col secondo, l'unità di misura in cui si vuole sia espressa la posizione; se non si esprime nulla, si tenterà di restituire la posizione in caratteri.

Codice.

Int Function ValoreColonna ()
Return GetCursorCol (); restituisce il valore della funzione nativa
EndFunction

Esercizio 10.2.3. La versione di ValoreLunghezza () per il file script Predefinito.

FileScript. Default.JSS

Nome. ValoreLunghezza

Descrizione. Restituisce il valore corrispondente alla lunghezza totale del documento corrente, utilizzando vari metodi sulla base del tipo di finestra aperta nell'applicativo.

Ritorni. Di tipo Int. La lunghezza del documento aperto nell'applicativo corrente.

Novità.

1. La funzione integrata "GetCurrentDocumentLength", (OttieniLunghezzaDocumentoCorrente), che restituisce il numero di caratteri nel documento aperto. Funziona in applicativi come Microsoft Word o Wordpad. Senza parametri.

2. Le costanti "LUNGHEZZA", "RIGHE" e "POSIZIONE", tutte equivalenti al termine omonimo, la prima delle quali rappresenta un tipo di dato da leggere nella Barra di stato, mentre le altre due sono altrettanti tipi di finestra da confrontare con quella attiva.

Fasi.

1. In una prima struttura di controllo, si verifica se ci si trovi dentro all'Editor di Script, ed in tal caso si rileva il dato tramite la nostra funzione "InfoStato ()".

2. Se invece ci si trova in un altro applicativo gestito a righe, il dato viene raccolto tramite la funzione nativa "GetLineCount ()", conosciuta lo scorso capitolo.

3. Nel terzo controllo, ancora, si verifica se l'applicativo corrente sia gestito tramite la posizione assoluta, ed in tal caso il dato lo rileva un'altra funzione nativa, "GetCurrentDocumentLength ()", appena illustrata.

4. Se nessun altro dei precedenti controlli ha intercettato il flusso, nel caso in cui fossero stati premuti due volte velocemente i tasti di attivazione, si sarebbe avvisati che la finestra corrente non è valida per tale funzione. In ogni caso, sarà comunque restituito un risultato nullo.

Note.

1. Questa funzione ha lo stesso nome di quella realizzata per il Blocco Note un paio di capitoli fa. Proprio per questo, essa sarà valida per gli altri tre applicativi cui noi abbiamo rivolto le nostre attenzioni, mentre nello stesso Blocco Note rimarrà valida quella versione che agirà a livello locale.

Codice.

Int Function ValoreLunghezza ()
If SiamoNellaFinestra (MANAGER) Then; se ci si trova nella finestra dell'Editor di Script,
; restituisce il valore numerico, convertito dal risultato dell'apposita funzione
Return StringToInt (InfoStato (LUNGHEZZA, IsSameScript ()))
ElIf SiamoNellaFinestra (RIGHE) Then; se invece si è in un applicativo gestito a righe,
Return GetLineCount (); restituisce il valore rilevato dalla funzione nativa per le righe
ElIf SiamoNellaFinestra (POSIZIONE) Then; se infine si basa sulla posizione assoluta,
Return GetCurrentDocumentLength (); restituisce la posizione tramite la funzione nativa
Else; altrimenti, nelle altre finestre,
If IsSameScript () Then; se è stata attivata la fase Aiuto,
SayMessage (OT_ERROR, hlpNoFinestra, hlpNoFinestra_corto); legge l'avviso
EndIf; fine controllo Aiuto
Return FALSE; restituisce un risultato nullo
EndIf; fine controllo finestre
EndFunction

Esercizio 10.2.4. La versione di PronunciaValoreRiga () per il file script Predefinito.

FileScript. Default.JSS

Nome. PronunciaValoreRiga

Sommario. Legge il numero di riga.

Descrizione. Richiama la funzione generica di gestione, attivando i comandi di lettura del dato relativo al numero della riga in cui è posto il cursore.

TastiAttivazione. Control+J

Novità.

1. Il primo utilizzo della nostra funzione "ValoreRiga ()", sia pure indiretto poiché tale elemento di codice sarà materialmente chiamato da quella di Gestione dei Dati.

Note.

1. Come accennato nella premessa, questo elemento di codice, ed i due successivi "PronunciaStatoColonna ()" e "PronunciaStatoLunghezza ()", sono la versione aggiornata di quelli da noi già realizzati lo scorso capitolo. Pertanto, ci si dovrà portare dentro al codice degli script, per entrare poi nella schermata di modifica, dove sostituire il termine centrale del nome, "Stato",con "Valore", lasciando infine invariati anche i precedenti tasti di Attivazione.

Codice.

Script PronunciaValoreRiga ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.2.5. Lo script PronunciaValoreColonna.

FileScript. Default.JSS

Nome. PronunciaValoreColonna

Sommario. Legge il numero di colonna.

Descrizione. Richiama la funzione generica di gestione, attivando i comandi di lettura del dato relativo al numero della colonna in cui è posto il cursore.

TastiAttivazione. Control+K

Novità.

1. Il primo utilizzo della nostra funzione "ValoreColonna ()", sia pure indiretto poiché essa sarà materialmente chiamata da quella di Gestione dei Dati.

Codice.

Script PronunciaValoreColonna ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.2.6. La versione di PronunciaValoreLunghezza () per il file script Predefinito.

FileScript. Default.JSS

Nome. PronunciaValoreLunghezza

Sommario. Legge la lunghezza del documento.

Descrizione. Richiama la funzione generica di gestione, attivando i comandi di lettura del dato relativo alla lunghezza del documento aperto nell'applicativo.

TastiAttivazione. Control+ OGrave

Novità.

1. Il primo utilizzo della versione della nostra funzione "ValoreLunghezza ()" per il file script Predefinito, sia pure indiretto poiché essa sarà materialmente chiamata da quella di Gestione dei Dati.

Codice.

Script PronunciaValoreLunghezza ()
GestisceDato (); chiama l'apposita funzione
EndScript

Collaudo.

Una volta salvato il lavoro compilando, il collaudo dovrebbe essere solo quello di premere i tre diversi comandi in ciascuno dei quattro applicativi su cui operiamo. Tale prova dovrebbe avere un esito positivo, e comunque resta solo da evidenziare che:

1. Il dato sulla lunghezza totale nell'Editor di Script è l'unico dei tre che non viene fornito da funzioni native di Jaws. Se capitasse che di tale dato non sia letto nulla, premendo "Control+OGrave", tenete presente che premendo due volte velocemente potrete avere dalla procedura delle indicazioni sull'origine del problema.

2. Sempre nell'Editor di Script, può capitare che all'ingresso nell'applicativo, prima di muovere qualsiasi altro tasto, il valore letto come numero di riga non sia quello corrente, bensì il numero della riga al momento di uscire dall'applicativo la volta precedente. Questo problema si risolve da solo dopo la prima pressione di un tasto di movimento verticale, e poi sarà reso inutile anche dalla procedura che realizzeremo per il ritorno automatico all'ultima posizione effettiva di uscita dai singoli file.

3. In Microsoft Word, se avete seguito le nostre indicazioni, avete la scorsa volta realizzato le versioni locali degli script che leggono tali informazioni dalla Barra di stato, a seguito di un'opportuna configurazione. Se volete, da questo punto in poi, per leggere almeno il numero di colonna, potreste in teoria cancellare la versione locale di "PronunciaStatoColonna ()", ed utilizzare quella corrispondente appena realizzata. In questo caso, se avete già collaudato in Microsoft Word gli altri script, dovreste già avere impostato il tipo di finestra "Editing" per questo programma, altrimenti usate "Control+Windows+I" per registrarla nel file di configurazione.

***

10.3. I contrassegni nel documento.

Siamo così giunti alla procedura principale del capitolo, non solo per i numerosi elementi di codice che la compongono. Essa rappresenta un esempio concreto di come si possano integrare ed ampliare le funzionalità di Jaws, aggiungendovi nuovi comandi che prendano spunto dalle esigenze d'utilizzo quotidiano.

Come detto nella premessa, il punto di partenza è il modo che Jaws ha in Word per salvare dei contrassegni, che noi avevamo esaminato fin dal terzo capitolo. Se ricordate, in quel caso avevamo anche già prodotto un nostro script, "SalvaContrassegno ()" appunto, il quale si limitava a chiamare una funzione di Jaws che crea un contrassegno temporaneo, al fine poi di selezionare del testo a partire da quel punto.

In realtà, dentro a Word lo script collegato al comando che attiva anche il nostro script, "Control+Windows+K", non si limita a segnare un punto da dove far partire la selezione, bensì annota anche la posizione del cursore al momento della pressione dei tasti. Tale dato viene scritto in un file in formato "INI", presente in una delle sottocartelle delle "Impostazioni personali", creata al momento dell'installazione di Jaws e denominata "PersonalizedSettings", (ImpostazioniPersonalizzate).

In questa cartella, il nome del file che contiene i dati salvati inizia con l'etichetta che Jaws associa ai singoli applicativi. A questa etichetta si aggiunge un lungo suffisso, "_MarkedPlaceDocuments", che significa (PostiSegnatiDeiDocumenti), e l'estensione "JSI", che è specifica di questo tipo di file. Pertanto, nel caso del programma Word, l'archivio creato da Jaws per annotare i contrassegni di un file sarà il seguente:

word_MarkedPlaceDocuments.JSI

All'interno di questo archivio, le sezioni saranno il nome del singolo documento di cui si annotano i contrassegni, mentre la chiave del dato sarà la coppia di termini "MarkedPlace", (PostoSegnato). Pertanto, se ipotizzassimo di aver salvato un contrassegno alla posizione 1000 in un file chiamato "MioDocumento.docx", l'annotazione nel citato file archivio sarebbe la seguente:

[MioDocumento.docx]
MarkedPlace=1000

Grazie a questa annotazione, oltre a fornire il punto d'inizio di una successiva selezione, Word consente di tornare alla posizione registrata, agendo sulla combinazione "Alt+Windows+K". Si tratta di una funzione molto utile perché consente di salvare una posizione, spostarsi in un altro punto del documento magari anche con un comando di ricerca testo, e poi tornare al punto salvato per continuare il lavoro.

Noi, come detto, alla fine di questo capitolo avremo realizzato la procedura che allarga queste funzionalità ad almeno gli altri tre applicativi, oltre a Word, su cui stiamo agendo, l'Editor di Script, il Blocco Note e Wordpad. In più, come accennato, creeremo un registro con gli ultimi dieci contrassegni salvati, che potremo scorrere tramite appositi comandi per tornare a ritroso sui nostri punti di maggiore interesse, anche dentro a Word.

Forse questa funzionalità non sembrerà un granché importante, esaminandola ora. Capiremo però più avanti la sua reale utilità, quando faremo il collaudo della procedura con alcuni esempi di utilizzo del sistema a contrassegni.

Se non altro, essa ci darà modo di usare finalmente i suoni a supporto degli script, in quanto ci serviremo di una scala di note per orientarci durante lo scorrimento dell'elenco dei vari contrassegni registrati. Oltre ai comandi per andare al contrassegno precedente o successivo, doteremo il sistema anche di comandi per andare al più vecchio ed al più recente di tali contrassegni.

Esercizio 10.3.1. La funzione NumeroVersione.

FileScript. Default.JSS

Nome. NumeroVersione

Descrizione. Restituisce un valore che identifica le prime due cifre della versione di Jaws.

Ritorni. Di tipo Int. Il valore corrispondente alla versione attiva di Jaws.

Novità.

1. La funzione integrata "GetJFWVersion", (OttieniVersioneJaws), che restituisce un numero intero a sette cifre. Senza parametri.

Note.

1. Poiché come detto il valore restituito ha molte cifre, le più significative delle quali sono le prime due, lo scopo della funzione è di estrarre solo queste due prime cifre e riconvertirle in valore numerico.

Codice.

Int Function NumeroVersione ()
; restituisce il valore corrispondente alle prime due cifre della versione di Jaws
Return StringToInt (StringLeft (IntToString (GetJFWVersion ()), 2))
EndFunction

Collaudo.

Come sempre in caso di procedure complesse, il collaudo viene rinviato all'ultimo degli script da realizzare.

Esercizio 10.3.2. La nuova versione di NomeArchivio ().

FileScript. Default.JSS

Nome. NomeArchivio

Novità.

1. La funzione integrata "GetUserSettingsDirectory", (OttieniCartellaImpostazioniUtente), che restituisce il percorso completo della cartella per le "Impostazioni personali". Da notare che tale percorso viene concluso dall'ultimo carattere della cartella, e non quindi da un carattere Controbarra, Ascii 92.

2. Le costanti "SEGNI" e "TEMPORANEO", che corrispondono nell'ordine ai valori 5 e 6, le quali indicano il tipo di archivio da creare.

3. Le costanti "SUFFISSO_JSI" e "TMP", le quali rappresentano, rispettivamente, il suffisso standard per i file di inizializzazione di Jaws, proposto nella premessa, e l'omonima estensione per i file temporanei.

4. Le ultime costanti, "CLASSIC" e "CARTELLA_SESSIONE", che equivalgono nell'ordine all'omonimo suffisso inglese per certi file script Office, ed alla sottocartella "transient-session", (SessioneTransitoria), la quale contiene dei file che sono cancellati ad ogni avvio di Jaws.

Note.

1. La modifica alla prima versione della funzione si effettua aggiungendo due strutture di controllo che verificano se il valore passato come primo parametro corrisponda alle due costanti citate tra le novità.

2. Se il dato controllato equivale a "SEGNI",sono impostati gli archivi dove registrare i Contrassegni. In questo caso, all'etichetta dell'applicativo corrente viene dapprima tolto il citato suffisso inglese, se presente, quindi si aggiunge l'apposito suffisso del nome, comprensivo dell'estensione.

3. Se invece il dato corrisponde a "TEMPORANEO", si definisce l'archivio per le annotazioni omonime, ed in tal caso viene espresso il nome completo di percorso all'interno dell'apposita sottocartella temporanea.

4. In entrambe queste aggiunte, data la lunghezza dell'istruzione completa, ripristiniamo il vecchio formato con i parametri ciascuno su una riga.

Codice.

String Function NomeArchivio (int iTipo)
If iTipo == CORRENTE Then; se l'archivio da elaborare è quello dell'applicazione attiva,
Return GetActiveConfiguration () + JCF; ne restituisce il nome aggiungendo l'estensione
ElIf iTipo == PERSONALE Then; se invece l'archivio da elaborare è quello personale,
Return PS_FILE + JCF; ne restituisce il nome aggiungendo l'estensione
ElIf iTipo == APP Then; per il file Tasti dell'applicazione attiva,
Return GetActiveConfiguration () + JKM; si serve ancora della funzione di Jaws
ElIf iTipo == JAWS Then; per il file Tasti Predefinito,
Return JAWS_FILE + JKM; utilizza l'altra costante impostata
ElIf iTipo == SEGNI Then; se l'archivio da elaborare è quello per i contrassegni,
; rimuove i riferimenti ai suffissi inglesi dei nomi, ed aggiunge etichetta ed estensione
Return FormatString ( ; restituisce il nome formattato,
msg2, ; messaggio base,
StringReplaceSubstrings (GetActiveConfiguration (), CLASSIC, NULLO), ; rimuove un suffisso,
SUFFISSO_JSI); e ne aggiunge un altro, comprensivo d'estensione
ElIf iTipo == TEMPORANEO Then; se infine è richiesto un archivio solo per la sessione,
Return FormatString ( ; restituisce nome e percorso dell'archivio temporaneo
msg3Controbarra, ; messaggio base,
GetUserSettingsDirectory (), ; percorso completo delle Impostazioni personali,
CARTELLA_SESSIONE, ; nome della sottocartella dove salvare le annotazioni,
GetActiveConfiguration () + TMP); etichetta dell'applicativo corrente
EndIf; fine controllo tipo archivio
EndFunction

Esercizio 10.3.3. La funzione PosizioneCursore () del file script Predefinito.

FileScript. Default.JSS

Nome. PosizioneCursore

Descrizione. Restituisce la posizione del cursore, sulla base del sistema usato dall'applicativo.

Ritorni. Di tipo Int. Il valore relativo alla posizione corrente del cursore.

Note.

1. Questa funzione prende il posto di quella realizzata per il Blocco Note, che abbiamo poi spostato nel file script collegato. Essa va posta nel file script Predefinito proprio perché essa può essere valida per più applicativi, non solo l'Editor di Script ed il Blocco Note. Nei programmi che sono gestiti tramite la posizione assoluta, come Word e Wordpad, questa funzione sarà invece realizzata a livello locale, in forme diverse tra di esse.

Codice.

Int Function PosizioneCursore ()
Return GetCursorRow (); restituisce il valore dalla funzione nativa
EndFunction

Esercizio 10.3.4. La Funzione ScrivePuntatore.

FileScript. Default.JSS

Nome. ScrivePuntatore

Descrizione. Trascrive il valore nell'archivio dei contrassegni, convertendolo in forma testuale e salvandolo nella chiave composta dal nome base casomai completato dal numero progressivo indicato.

Ritorni. Di tipo Int. L'esito della scrittura: TRUE per la riuscita, FALSE per un fallimento.

Parametri.

1. sNomeFile. Il nome con l'estensione del documento aperto. Di tipo String.

2. iValore. Valore numerico da salvare nell'archivio. Di tipo Int.

3. sProg. Numero progressivo, in forma testuale, dell'elemento da elaborare. Di tipo String.

Novità.

1. La costante "CTS", che rappresenta la sigla omonima seguita da un carattere Sottolineato, la quale costituisce la base iniziale della sezione speciale in cui scrivere una seconda serie di dati relativi ai contrassegni, ed in questo caso al suo puntatore.

2. La costante "CHIAVE_SEGNI", che contiene la chiave originale di Jaws usata per i contrassegni, "MarkedPlace", citata nella premessa.

Note.

1. Questa funzione ha il solo scopo di semplificare il codice, riunendo alcuni dati fissi che andrebbero altrimenti ripetuti ad ogni chiamata dell'apposita funzione di scrittura.

Note.

1. I dati che vanno registrati hanno un valore numerico ma, poiché sarà poi necessario trascrivere anche il valore 0, è obbligatorio usare la funzione di scrittura dei dati testuali, in quanto la corrispondente funzione numerica non sarebbe in grado di eseguire tale compito.

Codice.

Int Function ScrivePuntatore (string sNomeFile, string sProg, int iValore)
Return ScriveDato (; restituisce l'esito della scrittura di puntatore o contrassegni numerati
SEGNI, ; valore che identifica l'archivio in cui scrivere
CTS + sNomeFile, ; sezione dell'archivio
CHIAVE_SEGNI + sProg, ; chiave del dato
IntToString (iValore)); dato da scrivere, convertito in forma testuale
EndFunction

Esercizio 10.3.5. La Funzione LeggeSegni.

FileScript. Default.JSS

Nome. LeggeSegni

Descrizione. Verifica il tipo di lettura da eseguire nell'archivio dei Contrassegni, se nell'elenco di quelli registrati oppure in quello dei Contrassegni numerati, sulla base dei parametri indicati.

Ritorni. Di tipo Int. Il valore letto nell'archivio dei Contrassegni.

Parametri.

1. sNomeFile. Il nome con l'estensione del documento aperto. Di tipo String.

2. sOggetto. Tipo di azione da svolgere. Di tipo String.

3. sProg. Numero progressivo, in forma testuale, dell'elemento da elaborare. Di tipo String.

Novità.

1. La nostra funzione "LeggeValore ()", creata nello scorso capitolo ma giunta ora al suo primo utilizzo.

2. La costante "CONTRASSEGNO", che equivale al termine omonimo, la quale serve in questo caso come nome di oggetto da confrontare con quello indicato tra i parametri.

Note.

Codice.

Int Function LeggeSegni (string sNomeFile, string sProg, string sOggetto)
Var String sPrefisso; termine da premettere nella sezione
If sProg ; se è stato specificato un numero progressivo,
&& sOggetto == CONTRASSEGNO Then; e se si vuole un contrassegno numerato o l'ultimo,
If sProg == ZERO Then; se è stata indicata la cifra del valore 0,
Let sProg = NULLO; cancella il dato
EndIf; fine controllo cifra progressiva
Let sPrefisso = CTS; inserisce comunque un prefisso per il nome della sezione in cui scrivere
EndIf; fine controllo preliminare
Return LeggeValore (SEGNI, sPrefisso + sNomeFile, CHIAVE_SEGNI + sProg); legge il dato
EndFunction

Esercizio 10.3.6. La funzione PuntatoreSegni.

FileScript. Default.JSS

Nome. PuntatoreSegni

Descrizione. Aggiorna il puntatore dei contrassegni, qualora il valore passato come parametro non sia negativo, mentre restituisce il numero del puntatore corrente, nel caso in cui il valore indicato sia inferiore a zero.

Ritorni. Di tipo Int. L'esito della funzione: TRUE o FALSE in caso di aggiornamento del puntatore, il valore del puntatore stesso in caso di lettura del dato.

Parametri.

1. sNomeFile. Il nome del documento aperto. Di tipo String.

2. iValore. Se di valore 0 o positivo, il numero da assegnare al puntatore,oppure un valore negativo per indicare la lettura del puntatore corrente. Di tipo Int.

Novità.

1. Le nostre funzioni "ScrivePuntatore ()" e "LeggeSegni ()".

Fasi.

1. Una prima struttura di controllo intercetta il flusso quando si immette come parametro un valore maggiore o uguale a 0. Qui viene aggiornato il puntatore dei contrassegni annotando tale valore, e restituendo il risultato della scrittura.

2. Un secondo controllo intercetta il flusso nel caso sia stato invece specificato un valore negativo. In questo caso, si restituisce il valore che risulta quello attuale del puntatore dei contrassegni.

Codice.

Int Function PuntatoreSegni (string sNomeFile, int iValore)
If iValore >= FALSE Then; se un valore non è negativo,
; reimposta il puntatore dei contrassegni e ne restituisce l'esito
Return ScrivePuntatore (sNomeFile, NULLO, iValore)
Else; altrimenti,
Return LeggeSegni (sNomeFile, ZERO, CONTRASSEGNO); ritorna il valore del puntatore
EndIf; fine controllo valore
EndFunction

Esercizio 10.3.7. La funzione AggiornaSegni.

FileScript. Default.JSS

Nome. AggiornaSegni

Descrizione. Gestisce l'aggiornamento dei contrassegni, registrando con un numero progressivo quelli precedenti, fino ad un massimo di dieci. Dopo questo valore, viene cancellato man mano quello meno recente, così da far rimanere in memoria sempre le ultime dieci annotazioni sulla posizione del cursore.

Ritorni. Di tipo Int. L'esito della funzione: TRUE per la riuscita, FALSE per il fallimento.

Parametri.

1. sNomeFile. Il nome del documento aperto. Di tipo String.

2. iValore. La posizione nel documento da salvare. Di tipo Int.

3. sProg. L'eventuale numero progressivo del contrassegno da registrare, in forma testuale. Di tipo String. Parametro Opzionale.

Novità.

1. La nostra funzione "PuntatoreSegni ()", usata in questo caso solo per riazzerare il puntatore che indica l'ultimo contrassegno elaborato, nel caso in cui riuscisse l'aggiornamento dei contrassegni.

2. L'altra nostra funzione creata il capitolo scorso, "ScriveValore ()".

3. L'utilizzo della parola chiave "Descending", all'interno di un ciclo "For", che se ricordate va diminuire di un'unità il contatore ad ogni iterazione del ciclo, anziché aumentarlo.

4. La costante "MAX_SEGNI",equivalente al valore 9, che rappresenta il numero più alto dei contrassegni da registrare. Essi sono in realtà dieci, perché ai nove numeri con un valore positivo va aggiunto anche quello che ha il valore 0.

Fasi.

1. Un primo controllo intercetta il flusso quando sia stato specificato un numero progressivo da assegnare al contrassegno. In tal caso, ci si limita ad aggiornare l'apposita sezione speciale nel file archivio dei contrassegni, interrompendo poi il flusso.

2. Se invece il flusso prosegue, si leggono dapprima i contrassegni registrati per il documento corrente. Se ve n'è almeno uno, si avvia il ciclo per l'aggiornamento, dove si legge il valore di un contrassegno e lo si sovrascrive a quello del contrassegno seguente.

3. Al termine del ciclo di aggiornamento, si tenta di salvare il contrassegno da registrare. Se la scrittura riesce, si restituisce il risultato dell'aggiornamento del puntatore nell'elenco dei contrassegni, che viene portato a zero.

4. Nel caso in cui il salvataggio del contrassegno non riuscisse, sarebbe restituito un valore nullo.

Codice.

Int Function AggiornaSegni (string sNomeFile, int iValore, string sProg)
Var
int i, ; il contatore del ciclo
String sChiavi, ; l'elenco delle chiavi dei contrassegni registrati
Int iContrassegni, ; il numero dei contrassegni
Int iPrima; il valore del contrassegno precedente

If sProg Then; se un numero progressivo è stato specificato,
; restituisce l'esito della scrittura nell'apposita sezione, interrompendo il flusso
Return ScrivePuntatore (sNomeFile, sProg, iValore)
EndIf; fine controllo numero progressivo
Let sChiavi = LeggeChiavi (SEGNI, sNomeFile); rileva le chiavi dei contrassegni registrati
Let iContrassegni = StringSegmentCount (sChiavi, PIPE); conta i contrassegni rilevati
If iContrassegni Then; se vi è almeno un dato registrato,
For i = iContrassegni To 1 Descending; fa scalare le precedenti registrazioni
If i <= MAX_SEGNI Then; se il contatore è inferiore o uguale al loro numero massimo,
; rileva il dato del contrassegno precedente,
Let iPrima = LeggeValore (SEGNI, sNomeFile, CHIAVE_SEGNI + NoZero (i - 1))
; e sovrascrive, o crea, un contrassegno con il valore appena rilevato
ScriveValore (SEGNI, sNomeFile, CHIAVE_SEGNI + NoZero (i), iPrima)
EndIf; fine controllo numero massimo
EndFor; fine ciclo di sovrascrittura
EndIf; fine controllo numero contrassegni
If ScriveValore (SEGNI, sNomeFile, CHIAVE_SEGNI, iValore) Then; se la scrittura riesce,
Return PuntatoreSegni (sNomeFile, FALSE); inizializza il puntatore dei contrassegni
Else; altrimenti,
Return FALSE; restituisce un valore nullo
EndIf; fine controllo scrittura
EndFunction

Collaudo.

Pur confermando il test complessivo più tardi, ricordiamo che in questa funzione l'ultimo parametro è opzionale . Pertanto, nell'ormai collaudata sequenza delle modifiche da apportare, ricordiamo di effettuare la modifica, salvare prima il file di documentazione poi di nuovo compilare, quindi uscire dall'Editor per confermare i cambiamenti.

Esercizio 10.3.8. La funzione SalvaDato.

FileScript. Default.JSS

Nome. SalvaDato

Descrizione. Gestisce la registrazione dei contrassegni nel documento aperto.

Ritorni. Di tipo Int. L'esito del salvataggio: 1 o TRUE per la riuscita, 0 o FALSE per il fallimento.

Parametri.

1. sNomeFile. Il nome con l'estensione del documento aperto. Di tipo String.

2. sOggetto. Tipo di azione da svolgere. Di tipo String. Parametro Opzionale.

3. sProg. Numero progressivo, in forma testuale, dell'elemento da elaborare. Di tipo String. Parametro Opzionale.

4. iAiuto. Indica lo stato di attivazione dell'omonima fase. Di tipo Int. Parametro Opzionale.

Novità.

1. Le nostre funzioni "NumeroVersione ()" e "AggiornaSegni ()".

2. La funzione integrata "DeleteFile", (CancellaFile), che consente di eliminare il file di cui si indichi il nome, completo di percorso, nell'unico parametro.

3. La costante "NUOVE", che corrisponde al numero della versione dalla quale le funzioni di salvataggio e di selezione di un contrassegno temporaneo sono state rese valide per tutti gli applicativi.

4. Le costanti "ESCE" e "CHIUDE", equivalenti agli omonimi termini, che rappresentano il tipo di uscita, nell'ordine, dall'intero programma o dalla sola finestra corrente.

5. La costante "APERTURA", equivalente al termine omonimo, che rappresenta la sezione in cui scrivere i dati relativi all'apertura di un file.

Fasi.

1. Un primo controllo verifica se la versione di Jaws è superiore alla 18, ed in tal caso esegue lo script nativo "DefineATempPlaceMarker ()", per segnare il punto d'inizio di eventuali selezioni, disabilitando poi la fase Aiuto. In caso contrario, viene invece chiamata la funzione nativa "SaveCurrentLocation ()".

2. Una seconda struttura di controllo esamina se sia stata indicata l'uscita dal programma, ed in tal caso cancella l'intero file delle annotazioni temporanee tramite la funzione nativa "DeleteFile ()". Se invece fosse stata specificata la chiusura della finestra corrente, tramite la nostra funzione "CancellaChiave ()" si elimina il solo riferimento al documento da chiudere.

3. Viene controllato poi, tramite una terza struttura di controllo, se il contrassegno da registrare sia uguale all'ultimo registrato, ed in tal caso, se fosse attiva la fase Aiuto, sarebbe letto un avviso ed interrotto il flusso.

4. In un'ulteriore controllo, si verifica se il salvataggio del contrassegno sia riuscito, tramite la nostra funzione "AggiornaSegni ()". In tal caso, se attiva la fase Aiuto, viene letto l'avviso.

5. Se infine il salvataggio non fosse riuscito, sarà pronunciato un avviso, sempre subordinato all'Attivazione della fase Aiuto.

Note.

1. Fate attenzione alla prima fase di quelle appena elencate, dove viene analizzata la versione di Jaws che si sta utilizzando, al fine determinare quale tipo di marcatore temporaneo far eseguire. Questo controllo, in pratica, riunifica le diverse forme dello script "SalvaContrassegno ()",che nel terzo capitolo avevamo appunto realizzato in un modo per gli utenti di Jaws fino alla 18, e in un altro per quelli delle versioni più recenti. Anticipiamo già che, più avanti, sarà proposta la forma definitiva di tale script, che chiamerà alla fine questa funzione dopo essere passato prima da quella di gestione generica.

Codice.

Int Function SalvaDato (string sNomeFile, string sOggetto, String sProg, int iAiuto)
Var
Int iValore; posizione da registrare

If NumeroVersione () >= NUOVE Then; se quella in uso è una versione di Jaws dalla 2018,
SpeechOff (); spegne la sintesi
PerformScript DefineATempPlaceMarker(); esegue lo script nativo
SpeechOn (); riattiva la sintesi
Else; Altrimenti, per le versioni precedenti,
SaveCurrentLocation (); registra la posizione per i puntatori interni di Jaws
EndIf; fine controllo versione
If sOggetto == ESCE Then; se si è usciti dall'applicazione,
DeleteFile (NomeArchivio (TEMPORANEO)); si cancella l'intero file con le aperture
ElIf sOggetto == CHIUDE Then; se invece si è chiuso solo il documento corrente,
CancellaChiave (TEMPORANEO, APERTURA, sNomeFile); rimuove solo la nota sul file
EndIf; fine controllo tipo di azione
Let iValore = PosizioneCursore (); rileva il dato da registrare
If !iValore Then; se il valore è nullo,
Return FALSE; interrompe il flusso, restituendo un risultato nullo
EndIf; fine controllo valore
; se il nuovo contrassegno è uguale all'ultimo registrato,
If iValore == LeggeSegni (sNomeFile, sProg, sOggetto) Then
If iAiuto Then; se è attiva la fase,
SayMessage (OT_ERROR, hlpGiaSegno, hlpGiaSegno_corto); legge l'avviso
EndIf; fine controllo aiuto
Return FALSE; interrompe il flusso, restituendo un risultato nullo
ElIf AggiornaSegni (sNomeFile, iValore, sProg) Then; se invece la registrazione riesce,
If iAiuto Then; se è attiva la fase, avvisa dell'esito
SayFormattedMessage (OT_ERROR, hlpOkSegno, hlpOkSegno_corto, sProg)
EndIf; fine controllo Aiuto
Return TRUE; in ogni caso, restituisce l'esito positivo
Else; Altrimenti, se la scrittura fallisce,
If iAiuto Then; se è attiva la fase, segnala l'errore
SayFormattedMessage (OT_ERROR, hlpNoCts, hlpNoCts_corto, sProg)
EndIf; fine controllo Aiuto
Return FALSE; in ogni caso, restituisce un risultato nullo
EndIf; fine controllo scrittura
EndFunction

Collaudo.

1. Anche qui ricordiamo i parametri opzionali, che sono ben quattro su cinque complessivi, con la solita sequenza di azioni. Tra tutte ricordiamo l'uscita dall'Editor dopo la ricompilazione, fortemente consigliata.

Esercizio 10.3.9. La funzione ScorreSegni.

FileScript. Default.JSS

Nome. ScorreSegni

Descrizione. Gestisce lo spostamento al contrassegno indicato, all'interno dell'archivio di quelli già registrati.

Ritorni. Di tipo Int. L'esito della funzione: TRUE per lo spostamento confermato, FALSE per una richiesta non valida.

Parametri.

1. sNomeFile. Il nome con l'estensione del documento aperto. Di tipo String.

2. sOggetto. Tipo di azione da svolgere. Di tipo String.

3. sChiavi. L'elenco dei contrassegni registrati. Di tipo String.

4. iConta. Il numero dei contrassegni registrati nell'archivio. Di tipo Int.

5. sProg. Per Riferimento. Il numero progressivo, in forma testuale, del contrassegno cui portarsi. Di tipo String.

Novità.

1. Le costanti "ERRORE1", "ULTIMO_SEGNO" e "PRIMO_SEGNO", che corrispondono ad altrettanti file audio da eseguire.

Fasi.

1. Una prima struttura di controllo verifica a quale contrassegno ci si debba portare, sulla base del tipo di azione specificata, ed imposta i valori conseguenti.

2. Una seconda struttura di controllo verifica se il contrassegno richiesto non sia valido, ed in tal caso emette un suono d'errore ed interrompe il flusso restituendo un risultato nullo.

3. Nel caso in cui il contrassegno sia invece valido, un ulteriore controllo determina quale suono emettere, eseguendo un arpeggio di note ascendente o discendente nel caso si sia richiesto il contrassegno più vecchio o più recente. In tutti gli altri casi, sarà emessa una nota corrispondente alla posizione del contrassegno richiesto nell'archivio. In ogni caso, viene poi restituito l'esito positivo della funzione .

Codice.

Int Function ScorreSegni (string sNomeFile, string sOggetto, ; prima riga d'intestazione,
string sChiavi, int iConta, string ByRef sProg); seconda riga, con gli altri tre parametri
Var
Int iAttuale, ; valore del puntatore dei contrassegni
Int iPosiz; posizione del contrassegno nell'archivio

Let iAttuale = PuntatoreSegni (sNomeFile, -1); rileva l'attuale puntatore dei contrassegni
If sOggetto == PRIMO Then; se si è chiesto il contrassegno più vecchio,
Let iPosiz = iConta; imposta il valore relativo
ElIf sOggetto == ULTIMO Then; se invece si è richiesto l'ultimo registrato,
Let iPosiz = FALSE; azzera il valore
ElIf sOggetto == PRECEDENTE Then; se si è chiesto il contrassegno prima,
Let iPosiz = iAttuale + 1; aumenta il valore
ElIf sOggetto == SUCCESSIVO Then; se infine si è chiesto il contrassegno dopo,
Let iPosiz = iAttuale - 1; diminuisce il valore
EndIf; fine controllo tipo azione
If iPosiz == iAttuale ; se il contrassegno chiesto è quello già sul puntatore,
|| iPosiz > iConta ; o se quello chiesto è oltre il primo registrato,
|| iPosiz < FALSE Then; oppure se il valore è inferiore a zero,
Suona (ERRORE1); emette un suono di avviso,
Return FALSE; e restituisce un risultato nullo
Else; se invece la posizione è valida,
Let sProg = NoZero (iPosiz); aggiorna il valore da trasmettere
PuntatoreSegni (sNomeFile, iPosiz); aggiorna anche il contatore
If iPosiz == FALSE Then; se si è sul contrassegno più recente,
Suona (ULTIMO_SEGNO); emette il suono relativo
ElIf iPosiz == iConta Then; se invece si è sul contrassegno meno recente,
Suona (PRIMO_SEGNO); emette il suono relativo
Else; altrimenti
Suona (Nota (iPosiz)); emette la nota corrispondente
EndIf; fine controllo suoni
Return TRUE; consente di proseguire il flusso nella funzione chiamante
EndIf; fine controllo valore
EndFunction

Collaudo.

1. Anche in questo caso dovremo aprire il file "Default.JSD" per rendere opzionale un parametro, ma non nella funzione che stiamo trattando, bensì in una chiamata da essa. Questa è la funzione "Suona ()", realizzata ancora nel sesto capitolo, e che ora conviene usare senza il qui inutile secondo parametro. Ponete quindi il termine ":Optional" tra i due parametri della funzione, ricompilate e uscite dall'Editor per rendere effettive le modifiche.

Esercizio 10.3.10. La versione di MuoveAllaRiga () per il file script Predefinito.

FileScript. Default.JSS

Nome. MuoveAllaRiga

Descrizione. Richiama il comando locale di spostamento alla riga specificata, casomai spegnendo e riaccendendo la sintesi vocale.

Ritorni. Di tipo Void. Nessuno.

Note.

1. Anche questa funzione ha fatto la sua prima comparsa nel Blocco Note, ed anch'essa era stata spostata in un primo tempo nel file script collegato. Il suo contenuto, da quella versione, è stato notevolmente semplificato, in quanto i controlli in essa contenuti saranno svolti in questo caso dalle successive funzioni di gestione.

Codice.

Int Function MuoveAllaRiga (int iValore)
Var Int iStato; indica lo stato di attivazione della sintesi
Let iStato = ControllaSintesi (FALSE); verifica se la sintesi è spenta, salvandone l'esito
TypeKey (CONTROL_G); richiama il comando di spostamento alla riga
Pause ()
TypeString (IntToString (iValore)); immette la riga a cui portarsi
EnterKey ()
Pause ()
ControllaSintesi (iStato); verifica se riattivare la sintesi
EndFunction

Esercizio 10.3.11. La funzione SpostaCursore.

FileScript. Default.JSS

Nome. SpostaCursore

Descrizione. Esegue lo spostamento del cursore, sulla base dell'applicativo corrente.

Ritorni. Di tipo Void. Nessuno.

Parametri.

1. iPosiz. La posizione del documento in cui spostarsi. Di tipo Int.

2. sProg. Per Riferimento. L'eventuale numero progressivo, in forma testuale, del contrassegno cui portarsi. Di tipo String. Parametro Opzionale.

3. iAiuto. Indica lo stato di attivazione dell'omonima fase. Di tipo Int. Parametro Opzionale.

Novità.

1. La nostra funzione "MuoveAllaRiga ()".

2. La funzione integrata "MoveToDocumentOffset", (MuoviAlDocumentoSlittato), che serve a muovere il cursore all'interno del Documento Virtuale, in pratica negli applicativi gestiti sulla base della posizione assoluta. Senza parametri.

3. La costante "ULTIMO", che corrisponde all'omonimo termine, la quale è utilizzata in questo caso per formattare i messaggi lunghi.

Fasi.

1. In un primo controllo , si verifica se ci si trovi in un applicativo gestito a righe, ed in tal caso si esegue lo spostamento tramite la nostra funzione "MuoveAllaRiga ()". Poi, se è attiva la fase Aiuto, viene letto il messaggio che informa sull'esito del movimento.

2. Se invece ci si trovasse in un applicativo gestito sulla base della posizione assoluta, sarebbe chiamata in causa la funzione nativa "MoveToDocumentOffset ()". Quindi, anche in questo caso, sarebbero letti dei messaggi qualora fosse attiva la fase Aiuto. Questi sarebbero tuttavia differenziati anche sulla base del fatto se il contrassegno cui muoversi sia l'ultimo registrato, oppure uno identificato da un valore numerico.

3. Se non si fosse in nessuna delle due finestre controllate in precedenza, e si fosse nella fase Aiuto, viene letto un avviso di finestra non valida.

Codice.

Void Function SpostaCursore (int iPosiz, string sProg, int iAiuto)
If SiamoNellaFinestra (RIGHE) Then; se l'applicativo corrente funziona a righe,
MuoveAllaRiga (iPosiz); effettua lo spostamento con il comando dell'applicativo
If iAiuto Then; se è attiva la fase,
SayFormattedMessage (OT_ERROR, msgTornaA, msgSecondo, RIGA, iPosiz)
EndIf; fine controllo Aiuto
ElIf SiamoNellaFinestra (POSIZIONE) Then; se invece conta la posizione assoluta,
MoveToDocumentOffset (iPosiz ); si sposta alla posizione memorizzata
If iAiuto Then; se è attiva la fase,
If !sProg Then; se non è indicato alcun numero, avvisa di portarsi all'ultimo contrassegno
SayFormattedMessage (OT_ERROR, msg2, msg1, ULTIMO, CONTRASSEGNO)
Else; altrimenti, se un valore è stato rilevato, avvisa di portarsi al contrassegno numerato
SayFormattedMessage (OT_ERROR, msg2, msgSecondo, CONTRASSEGNO, sProg)
EndIf; fine controllo tipo contrassegno
EndIf; fine controllo messaggi
Else; se la finestra non è stata riconosciuta,
SayMessage (OT_ERROR, hlpNoRegistra, hlpNoRegistra_corto); legge l'avviso
EndIf; fine controllo finestre
EndFunction

Collaudo.

1. Con questo tipo di funzione, che ha ben due su tre parametri opzionali, normalmente vi sarebbe chiesto di provvedere subito a renderli tali, facendo le opportune modifiche. Stavolta, invece, avete l'opzione di poter posticipare l'intervento, facendolo una volta sola per questa e per le prossime due funzioni, anch'esse dotate di questo tipo di parametri.

Esercizio 10.3.12. La funzione TornaDato.

FileScript. Default.JSS

Nome. TornaDato

Descrizione. Gestisce il ritorno ad un contrassegno registrato.

Ritorni. Di tipo Int. L'esito dello spostamento: 1 o TRUE per la riuscita, 0 o FALSE per il fallimento.

Parametri.

1. sNomeFile. Il nome con l'estensione del documento aperto. Di tipo String.

2. sOggetto. Il tipo di azione da svolgere. Di tipo String. Parametro Opzionale.

3. sProg. L'eventuale numero progressivo del contrassegno da registrare, in forma testuale. Di tipo String. Parametro Opzionale.

4. iAiuto. Indica lo stato di attivazione dell'omonima fase. Di tipo Int. Parametro Opzionale.

Novità.

1. Le nostre funzioni "ScorreSegni ()" e "SpostaCursore ()".

Fasi.

1. La struttura iniziale verifica, dapprima, se si è specificato di controllare un'eventuale precedente apertura del documento corrente. Se così è, ed il file risultasse già aperto, si interrompe il flusso restituendo un risultato nullo; altrimenti, procede registrando l'apertura del documento.

2. In un secondo controllo della struttura, si verifica all'inizio che non sia stato specificato di tornare all'ultimo contrassegno. Se questo è il caso, si rilevano i contrassegni registrati e, se questi sono almeno due, si chiama la nostra funzione "ScorreSegni ()". Questa, controlla intanto che il contrassegno richiesto sia valido, casomai aggiornando la posizione di quello da leggere all'interno dell'archivio dei contrassegni registrati. Se questo controllo ha avuto esito negativo, viene restituito un valore nullo, interrompendo il flusso; altrimenti, ci si limita a farlo proseguire, disattivando la fase Aiuto.

3. Dopo aver rilevato il valore del contrassegno, una seconda struttura di controllo verifica dapprima se tale valore non sia nullo. In tal caso interrompe il flusso, leggendo un avviso qualora la fase Aiuto sia attiva.

4. Una struttura a sé stante verifica poi quale tipo di ritorno sia stato specificato. Se fosse all'ultimo contrassegno, resetta il puntatore dei contrassegni ponendolo a zero.

5. Un'ulteriore struttura verifica se non ci si trovi già sul contrassegno richiesto, ed in tal caso interrompe il flusso leggendo casomai un avviso.

6. Dopo aver tentato di leggere la lunghezza del documento, una terza struttura controlla dapprima che tale lunghezza sia stata in effetti rilevata e che essa sia inferiore al valore del contrassegno. Se così è, sono eseguiti una serie di ulteriori controlli che, se positivi, portano a chiamare la nostra funzione "SpostaCursore ()". In ogni caso, alla fine viene letta la riga corrente, se la fase Aiuto è attiva.

7. In un ultimo controllo, se invece il valore del contrassegno è maggiore o uguale alla lunghezza del documento, e nel caso questa lunghezza sia superiore all'unità, si chiama la funzione nativa "JAWSBottomOfFile ()" per andare a fine documento, leggendo poi un avviso nel caso in cui la fase Aiuto sia attiva.

Codice.

Int Function TornaDato (string sNomeFile, string sOggetto, String sProg, int iAiuto)
Var
Int iPosiz, ; posizione del cursore
Int iTotale, ; lunghezza del file aperto
Int iAperto, ; indicatore di una nuova apertura
String sChiavi, ; elenco dei contrassegni registrati
Int iConta; numero dei contrassegni rilevati

If sOggetto == APERTURA Then; se si deve verificare l'apertura del documento,
If LeggeDato(TEMPORANEO, APERTURA, sNomeFile) Then; se il file è già aperto,
Return FALSE; interrompe il flusso, restituendo un risultato nullo
Else; altrimenti, se si è al primo ingresso nel documento, ne annota l'apertura
Let iAperto = ScriveDato (TEMPORANEO, APERTURA, sNomeFile, ZERO)
EndIf; fine controllo apertura
ElIf sOggetto != CONTRASSEGNO Then; se invece non si è chiesto l'ultimo contrassegno,
Let sChiavi = LeggeChiavi (SEGNI, sNomeFile); rileva i contrassegni
Let iConta = StringSegmentCount (sChiavi, PIPE) - 1; conta i contrassegni, meno un'unità
If iConta Then; se vi sono almeno due contrassegni registrati, lo 0 e l'1,
If !ScorreSegni (sNomeFile, sOggetto, sChiavi, iConta, sProg) Then; se non è valido,
Return; interrompe il flusso
Else; altrimenti, se il flusso può proseguire,
Let iAiuto = FALSE; disattiva l'omonima fase
EndIf; fine controllo scorrimento
EndIf; fine controllo numero contrassegni
EndIf; fine controllo oggetto
Let iPosiz = LeggeSegni (sNomeFile, sProg, sOggetto); rileva il valore del contrassegno
If !iPosiz Then; se nessun valore è stato rilevato,
If iAiuto Then; se è attiva la fase, segnala l'errore
SayFormattedMessage (OT_ERROR, hlpNoSegno, hlpNoSegno_corto, sProg)
EndIf; fine controllo Aiuto
Return; in ogni caso, interrompe il flusso
EndIf; fine controllo valore
if sOggetto == CONTRASSEGNO Then; se si è chiesto l'ultimo contrassegno registrato,
PuntatoreSegni (sNomeFile, FALSE); resetta il puntatore dei contrassegni
EndIf; fine controllo tipo ritorno
If !iAperto ; se non si è appena rientrati nel file,
&& iPosiz == PosizioneCursore () Then; e se il cursore è già sul contrassegno,
If iAiuto Then; se è attiva la fase,
SayMessage (OT_ERROR, hlpSulPosto, hlpSulPosto_corto); legge l'avviso
EndIf; fine controllo aiuto
Return; in ogni caso, interrompe il flusso
EndIf; fine controllo contrassegno
Let iTotale = ValoreLunghezza (); tenta di rilevare la lunghezza del documento aperto
If !iTotale ; se la lunghezza totale non è stata rilevata,
|| (iTotale && iPosiz <= iTotale) Then; oppure se il valore c'è, ma non inferiore all'esistente,
SpostaCursore (iPosiz, sProg, iAiuto); esegue lo spostamento del cursore nel documento
Refresh (); resetta la schermata
SayLine (); legge la riga corrente
Else; se invece il numero memorizzato è superiore alla lunghezza complessiva,
If iTotale > 1 Then; se vi sono più di una riga nel file,
JAWSBottomOfFile (); si porta alla fine del documento
EndIf; fine controllo lunghezza
If iAiuto Then; se è attiva la fase,
SayMessage (OT_ERROR, hlpFineFile, hlpFineFile_corto); legge l'avviso
EndIf; fine controllo Aiuto
EndIf; fine controllo lunghezza documento
EndFunction

Collaudo.

Anche qui sono presenti parametri opzionali, e vale lo stesso discorso fatto nella funzione precedente: se volete impostarli ora, benissimo, altrimenti attendete anche la prossima e farete tutte e tre le modifiche assieme.

Esercizio 10.3.13. La versione aggiornata di GestisceDato ().

FileScript. Default.JSS

Nome. GestisceDato

Parametri.

1. sAzione. L'azione da eseguire. Di tipo String. Parametro Opzionale.

2. sOggetto. Il tipo di azione da compiere. Di tipo String. Parametro Opzionale.

Novità.

1. La funzione "CercaDato ()", che realizzeremo solo verso la fine del capitolo, ma che inseriamo già per non dover modificare il codice una seconda volta.

2. Le costanti "CERCA", "SALVA" e "TORNA", che corrispondono alle omonime azioni che si possono specificare ponendole come termine iniziale nei nomi di script.

3. La costante "SALTA", equivalente al valore 2, che indica di non ripetere i tasti premuti per attivare lo script.

Note.

Le modifiche da apportare alla prima versione sono le seguenti:

1. Aprire la schermata di modifica, ed aggiungere i due parametri elencati nell'apposita sezione.

2. Tornati al codice nell'Editor, eliminare le dichiarazioni delle due variabili, "sAzione" e "sOggetto", che sono state poste come parametri.

3. Sempre tra le dichiarazioni, aggiungere le tre elencate di seguito:

Int iNoVoce, ; imposta la disattivazione della fase Aiuto
String sNomeFile, ; nome completo del documento aperto
String sSuffisso; dato suppletivo da passare come parametro

4. nella prima struttura di controllo sulla finestra, posizionatevi sulla riga con l'istruzione "Return", ed inserite le seguenti tre righe di codice:

If !(sAzione + sOggetto) Then; se non sono stati specificati dei parametri,
TypeCurrentScriptKey (); ripete i tasti premuti
EndIf; fine controllo parametri

5. Dopo l'assegnazione del valore della funzione nativa "IsSameScript ()", inglobate alla successiva chiamata della nostra funzione "SeparaParole ()" nella seguente struttura di controllo:

If !sAzione Then; se l'azione da compiere non è stata specificata come parametro,
; estrae i dati contenuti nel nome dello script chiamante tramite l'apposita funzione
Let sProg = SeparaParole (sAzione, sCategoria, sOggetto)
Else; altrimenti
Let iNoVoce = SALTA; imposta la successiva disattivazione della fase Aiuto
EndIf; fine controllo parametro

6. Portatevi all'inizio della penultima istruzione, la fine del primo controllo sulle azioni, ed inserite queste righe di codice:

ElIf sAzione == CERCA Then; se si sono chieste delle ricerche,
CallFunctionByName (sAzione + DATO, sCategoria, sOggetto, iAiuto); esegue l'azione
Else; se servono operazioni su documenti,
If !DocumentoCorrente (sNomeFile, sSuffisso) Then; se non sono stati rilevati dei dati sul file,
If iAiuto Then; se è attiva la fase Aiuto, legge l'avviso
SayFormattedMessage (OT_ERROR, hlpNoDato, hlpNoDato_corto, msgTitolo)
EndIf; fine controllo aiuto
Return; in ogni caso, interrompe il flusso
EndIf; fine controllo documento
If sAzione == SALVA; se si vuole il salvataggio di un contrassegno,
|| sAzione == TORNA Then; o si vuole ritornarvi,
If !iNoVoce Then; se l'impostazione non è disattivata,
Let iAiuto = TRUE; imposta la fase
EndIf; fine controllo disattivazione
CallFunctionByName (sAzione + DATO, sNomeFile, sOggetto, sProg, iAiuto); esegue
Else; se invece l'azione non è stata riconosciuta,
If iAiuto Then; se la fase è attiva, legge l'avviso
SayFormattedMessage (OT_ERROR, hlpNoAzione, hlpNoAzione_corto, sAzione)
EndIf; fine controllo Aiuto
EndIf; fine secondo controllo azioni

7. Il primo controllo proposto in questo blocco, quello che verifica la costante "Cerca", non appartiene alla procedura sui Contrassegni, ma a quella che realizzeremo solo più avanti. Tale modifica, dunque, l'abbiamo inserita ora soltanto per non dover prendere più in mano la funzione prima della fine di questo capitolo.

Codice.

Void Function GestisceDato (string sAzione, string sOggetto)
If !SiamoNellaFinestra (EDITING) Then; se non si è nella finestra corretta,
If !(sAzione + sOggetto) Then; se non sono stati specificati dei parametri,
TypeCurrentScriptKey (); ripete i tasti premuti,
EndIf; fine controllo parametri
Return; interrompe il flusso
EndIf; fine controllo finestra
Var
Int iAiuto, ; stato di attivazione della fase Aiuto
Int iNoVoce, ; imposta la disattivazione della fase Aiuto
String sProg, ; eventuale numero progressivo indicato tramite il nome dello script
String sCategoria, ; tipologia dell'azione da compiere
String sDato, ; dato testuale da sottoporre all'azione
String sNomeFile, ; nome completo del documento aperto
String sSuffisso; dato suppletivo da passare come parametro

Let iAiuto = IsSameScript (); rileva l'eventuale doppia pressione dei tasti di attivazione
If !sAzione Then; se l'azione da compiere non è stata specificata come parametro,
Let sProg = SeparaParole (sAzione, sCategoria, sOggetto); estrae i dati dal nome script
Else; altrimenti
Let iNoVoce = SALTA; imposta la successiva disattivazione della fase Aiuto
EndIf; fine controllo parametro
If sAzione == PRONUNCIA Then; se si sono chieste azioni di lettura,
If sCategoria == STATO Then; se si sono richiesti dati dalla Barra di stato,
Let sDato = InfoStato (sOggetto, iAiuto); rileva il dato dalla funzione generica
Else; altrimenti, in tutti gli altri casi,
; Rileva il dato dalla funzione di cui si compone il nome
Let sDato = NoZero (CallFunctionByName (sCategoria + sOggetto))
EndIf; fine controllo categoria
CallFunctionByName (sAzione + DATO, sOggetto, sDato, iAiuto); esegue l'azione
ElIf sAzione == CERCA Then; se invece si sono chieste delle ricerche,
CercaDato (sCategoria, sOggetto, iAiuto); esegue l'azione
Else; se invece servono operazioni su documenti,
If !DocumentoCorrente (sNomeFile, sSuffisso) Then; se non vi sono dati sul file aperto,
If iAiuto Then; se è attiva la fase Aiuto,
SayFormattedMessage (OT_ERROR, hlpNoDato, hlpNoDato_corto, msgTitolo); legge l'avviso
EndIf; fine controllo aiuto
Return; in ogni caso, interrompe il flusso
EndIf; fine controllo documento
If sAzione == SALVA; se si vuole il salvataggio di un contrassegno,
|| sAzione == TORNA Then; o si vuole ritornarvi,
If !iNoVoce Then; se l'impostazione non è disattivata,
Let iAiuto = TRUE; imposta la fase
EndIf; fine controllo disattivazione
CallFunctionByName (sAzione + DATO, sNomeFile, sOggetto, sProg, iAiuto); esegue l'azione
Else; se invece l'azione non è stata riconosciuta,
If iAiuto Then; se la fase è attiva,
SayFormattedMessage (OT_ERROR, hlpNoAzione, hlpNoAzione_corto, sAzione); legge l'avviso
EndIf; fine controllo Aiuto
EndIf; fine secondo controllo azioni
EndIf; fine primo controllo azioni
EndFunction

Collaudo.

1. Eccoci arrivati alla terza funzione di fila con parametri opzionali. Se avete già reso tali quelli per le due funzioni precedenti, allora completate l'opera con questa.

2. Altrimenti, se avete atteso di farle tutte assieme, iniziate cercando "SpostaCursore", dove la parola chiave ":Optional" va inserita prima del secondo parametro.

3. Poi proseguite alla successiva funzione, che dovrebbe essere quella che segue, "TornaDato", anche qui rendendo opzionale tutti i parametri a partire dal secondo.

4. Tornate in ogni caso, o andate, all'inizio per cercare da lì questa funzione, "GestisceDato", che dovrebbe essere un po' più in su nel file, dove i parametri sono tutti opzionali e quindi la parola chiave va messa nella riga precedente al primo di questi.

5. Per finire, se avete fatto il lavoro in serie, a maggior ragione ricordatevi di uscire dall'Editor dopo aver salvato e ricompilato il file script.

Esercizio 10.3.14. La nuova versione di SalvaContrassegno ().

FileScript. Default.JSS

Nome. SalvaContrassegno

Note.

1. Come ricordato in precedenza, di questo script ne erano state prodotte già due forme diverse, una per chi aveva versioni di Jaws fino alla 18, ed un'altra per chi le aveva dalla 18 in poi. Questa versione definitiva unifica le due forme, e consente a tutti gli utenti di utilizzare lo stesso script.

2. Per quanto detto al punto precedente, la modifica al contenuto dello script è molto semplice: svuotarne il precedente contenuto, qualunque esso sia, e porre la riga centrale della forma proposta di seguito.

Codice.

Script SalvaContrassegno ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.3.15. Lo script TornaContrassegno.

FileScript. Default.JSS

Nome. TornaContrassegno

Sommario. Torna all'ultimo contrassegno.

Descrizione. Tenta di ritornare all'ultimo contrassegno registrato, pronunciandone il numero di riga, nel caso che l'applicativo abbia questo tipo di gestione, altrimenti segnalando il fatto che esso sia l'ultimo registrato, nel caso di applicativo che opera sulla base della posizione assoluta.

TastiAttivazione. Alt+Windows+K

Note.

1. Così come il precedente script e quelli posti di seguito, il suo contenuto sarà soltanto la chiamata senza parametri alla funzione di gestione.

Codice.

Script TornaContrassegno ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.3.16. Lo script TornaPrimo.

FileScript. Default.JSS

Nome. TornaPrimo

Sommario. Torna al contrassegno più vecchio.

Descrizione. Torna al contrassegno meno recente tra quelli salvati. Nel caso si sia già posizionati su di esso, emette un breve suono di avviso, altrimenti viene suonato un arpeggio ascendente.

TastiAttivazione. Alt+Windows+Home

Note.

1. Questo script, come i tre successivi, si differenziano dal precedente per la seconda parte del nome, che specifica il tipo di azione da compiere, ed ovviamente per i tasti di attivazione.

Codice.

Script TornaPrimo ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.3.17. Lo script TornaUltimo.

FileScript. Default.JSS

Nome. TornaUltimo

Sommario. Torna all'ultimo contrassegno.

Descrizione. Torna al contrassegno salvato più di recente. Nel caso si sia già posizionati su di esso, emette un breve suono di avviso, altrimenti viene suonato un arpeggio discendente.

TastiAttivazione. Alt+Windows+Fine

Codice.

Script TornaUltimo ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.3.18. Lo script TornaPrecedente.

FileScript. Default.JSS

Nome. TornaPrecedente

Sommario. Torna al contrassegno precedente.

Descrizione. Tenta di tornare al contrassegno precedente nell'elenco di quelli registrati, se esiste. Nel caso ve ne siano di ulteriori, suona una nota corrispondente alla posizione del contrassegno nell'elenco, se non ve ne sono emette un breve suono di avviso, mentre, se si torna al contrassegno meno recente tra quelli salvati, viene suonato un arpeggio ascendente.

TastiAttivazione. Alt+Windows+FrecciaSu

Codice.

Script TornaPrecedente ()
GestisceDato (); chiama l'apposita funzione
EndScript

Esercizio 10.3.19. Lo script TornaSuccessivo.

FileScript. Default.JSS

Nome. TornaSuccessivo

Sommario. Torna al contrassegno successivo.

Descrizione. Tenta di tornare al contrassegno seguente nell'elenco di quelli registrati, se esiste. Nel caso ve ne siano di ulteriori, suona una nota corrispondente alla posizione del contrassegno nell'elenco, se non ve ne sono emette un breve suono di avviso, mentre, se si torna al contrassegno salvato più di recente, viene suonato un arpeggio discendente.

TastiAttivazione. Alt+Windows+FrecciaGiù

Codice.

Script TornaSuccessivo ()
GestisceDato (); chiama l'apposita funzione
EndScript

Collaudo della procedura sui Contrassegni.

1. Se la compilazione di tutti gli script fosse andata a buon fine, il migliore test potrebbe essere iniziare ad usare questo sistema per segnare i punti dei documenti cui dovete tornare. Esercitatevi, quindi, ad usare "Control+Windows+K" e "Alt+Windows+K" per salvare e tornare ai contrassegni.

2. Dopo averne registrato un numero sufficiente, provate anche a scorrere l'archivio degli ultimi dieci, usando i tasti di Attivazione che hanno in comune "Alt+Windows". Nel dettaglio, ricordiamo che usando questa combinazione assieme ai tasti "FrecciaSu" e "FrecciaGiù", ci si porta al contrassegno precedente o a quello successivo, mentre premendoli con "Home" e "Fine", ci si porterà al contrassegno più vecchio e a quello più recente.

3. Si raccomanda soltanto di svolgere queste prove per il momento solo dentro all'Editor di Script, l'unico ambiente in cui sono già presenti tutti gli elementi necessari, oppure attendete la conclusione del prossimo titolo in cui completeremo l'opera qui intrapresa.

***

10.4. Utilizzare i Contrassegni negli Applicativi.

Fin qui lo schema che avevamo seguito, nel trattare gli argomenti di ciascun titolo, prevedeva di iniziare con le funzioni che appartengono ad una procedura, per poi arrivare agli script finali ed al collaudo. In questo caso agiremo diversamente, effettuando tutte le modifiche necessarie un file script alla volta, e collaudando il lavoro man mano che ve ne sarà l'opportunità.

Lo scopo di questa sezione sarà in ogni caso allargare l'utilizzo dei contrassegni anche agli altri tre applicativi di nostro riferimento, dapprima il Blocco Note, poi Word e Wordpad. Se operare per il primo sarà poco più che una formalità, un po' più di codice lo dovremo spendere per i prodotti di casa Microsoft, soprattutto Word, che è già dotato di un sistema analogo cui noi dovremo adeguarci.

Partiremo comunque con sistemare alcuni dettagli dentro al file script Predefinito, più che altro per allargare le possibilità di utilizzo della procedura appena realizzata. In generale, oltre agli elementi di codice già realizzati, per far funzionare la gestione dei Contrassegni, in ogni singolo applicativo, è necessario che:

1. Siano registrati i dati, comunque, per la finestra di tipo "Editing" e, a seconda dei casi, che sia configurato uno tra i tipi "Righe" o "Posizione", sulla base del fatto che l'applicativo sia gestito a righe o tramite la posizione nel documento virtuale.

2. La funzione del file script Predefinito "PosizioneCursore ()" sia in grado di restituire tale dato, oppure che tale compito sia svolto da una omonima funzione realizzata a livello locale.

3. Le combinazioni di tasti coinvolte nella procedura siano libere, o che si trovi un modo per renderle tali grazie a degli script realizzati a livello locale.

10.4.1. Le modifiche dentro al file script Predefinito.

Inizieremo creando una funzione che serve per essere chiamata da uno dei nostri primi script, "TrovaTesto ()". In quest'ultimo, poi, inseriremo la chiamata alla nostra funzione per gestire i dati, sostituendo la prima versione in cui si attivava la creazione di un contrassegno temporaneo.

In questo caso, tuttavia, la chiamata di "GestisceDato ()" non può sfruttare il nome dello script chiamante per capire cosa fare, in quanto lo scopo principale dello script è un altro. Proprio per questo motivo, nella nostra ultima versione di "GestisceDato ()", abbiamo previsto la possibilità di specificare fino a due parametri con i quali indicare l'azione da compiere.

Questa versione di "TrovaTesto ()", così com'è negli intenti del capitolo, sarà quella definitiva. Per tale motivo, coglieremo l'occasione di far sì che essa lavori in tutti gli applicativi, convertendo gli script realizzati a livello locale in funzioni chiamate dallo script del file predefinito.

Uno degli altri due script che andremo ad aggiornare sarà "SostituisceTesto ()", dove inseriremo il salvataggio della posizione per consentire poi di tornarci, al rientro nella schermata principale. Se ricordate, questa funzione l'avevamo sommariamente attuata anche nel Blocco Note, che così come anche l'Editor di Script, ha il difetto di non tornare alla riga di partenza dopo aver effettuato la sostituzione.

In questo file l'ultimo passaggio sarà su"SelezionaDalContrassegno ()", lo script che andava abbinato proprio al salvataggio di alcune posizioni nei documenti. Qui però faremo davvero presto, in quanto si dovrà soltanto aggiungere la nostra funzione per determinare quale versione di Jaws sia in uso.

Esercizio 10.4.2. La funzione ComandoTrova () Nel file script Predefinito.

FileScript. Default.JSS

Nome. ComandoTrova

Descrizione. Attiva il comando di ricerca testo dell'applicativo.

Ritorni. Di tipo Void. Nessuno.

Novità.

1. La costante "CONTROL_F", che equivale alla combinazione omologa.

Note.

1. Come illustrato nella premessa della sezione, questa è la versione per il file script Predefinito di una funzione che potrà avere versioni locali diverse, così come già succede attualmente per quella presente nel file script del Blocco Note.

Codice.

Void Function ComandoTrova ()
TypeKey (CONTROL_F); apre la finestra di dialogo per la ricerca
EndFunction

Collaudo.

Come sempre, rinviamo al prossimo script per il test.

Esercizio 10.4.3. La versione aggiornata di TrovaTesto () per il file script Predefinito.

FileScript. Default.JSS

Nome. TrovaTesto

Note.

1. In questa versione, la precedente chiamata della funzione nativa per il salvataggio della posizione, sia pure in un contrassegno temporaneo, diventa la chiamata alla nostra funzione di gestione, con lo stesso compito di salvare un contrassegno, che stavolta è però quello trascritto nel file archivio. La novità di questa chiamata, inoltre, sarà l'azione specificata direttamente come parametro, e non quindi desunta dal nome dello script chiamante.

2. La seconda istruzione dello script sarà la chiamata della nostra funzione "ComandoTrova ()", che attiva il comando dell'applicativo, e che va a sostituire l'istruzione diretta con la simulazione dei tasti. Questa soluzione si deve al fatto che, mentre quella indicata al punto precedente vale teoricamente per tutti gli applicativi, tale chiamata va rivolta invece alle versioni locali della funzione, che può contenere nei diversi applicativi il comando che, in quel caso, attiva la finestra di ricerca testo.

Codice.

Script TrovaTesto ()
GestisceDato (SALVA); tenta il salvataggio della posizione corrente
ComandoTrova (); richiama il comando dell'applicativo per la ricerca testo
EndScript

Collaudo.

1. Provate a premere "Control+F" da dentro all'Editor di Script, e vi dovrebbe essere proposta la finestra di dialogo "Trova".

2. Senza chiudere il file script Predefinito, aprite adesso il file script del Blocco Note, "Notepad.JSS".

3. Portatevi sull'istruzione "Use" che collegava il file script esterno, "BloccoNote.JSS", cancellatela e compilate.

4. Se adesso provate ad aprire il Blocco Note, non solo la scelta rapida "Control+F", attiverà la versione locale di "ComandoTrova ()", ma soprattutto potrete da questo momento in poi servirvi liberamente della procedura sui Contrassegni anche qui. Eliminando il collegamento al file script esterno, infatti, abbiamo anche rimosso tutti i conflitti, che la nostra procedura causava con gli elementi di codice realizzati per il sistema gestito dalle funzioni Evento.

Esercizio 10.4.4. La nuova versione di SostituisceTesto ().

FileScript. Default.JSS

Nome. SostituisceTesto

Note.

1. Come già annunciato, la modifica si limita ad inserire la nostra solita funzione "GestisceDato ()". La novità sta nell'uso del parametro "CHIUDE", che simula l'uscita dal documento aperto. Tale modifica la si effettua solo per completare il lavoro nel file script Predefinito, ma il suo vero significato lo potremo capire solo più avanti, quando potremo collaudare appieno il suo funzionamento.

Codice.

Script SostituisceTesto ()
GestisceDato (SALVA, CHIUDE); salva la posizione simulando la chiusura del documento
PronunciaEsegue (); ripete i tasti premuti, leggendo il nome dello script
EndScript

Esercizio 10.4.5. La nuova versione di SelezionaDalContrassegno ().

FileScript. Default.JSS

Nome. SelezionaDalContrassegno

Note.

1. Questa forma dello script si propone per il fatto di aver creato la funzione "NumeroVersione ()", che stabilisce quale tipo di Jaws sia in uso, e per creare un unico script che possa andare bene in entrambe le situazioni. Se volete, potreste lasciare anche la versione precedente, limitata alla forma di vostro interesse, ma il consiglio è quello di aggiornarla comunque, per poterla utilizzare senza preoccuparsi della versione sulla quale operi.

Codice.

Script SelezionaDalContrassegno ()
If NumeroVersione () >= NUOVE Then; se quella in uso è una versione di Jaws dalla 2018,
PerformScript SelectTextBetweenMarkedPlaceAndCurrentPosition (); esegue lo script nativo
Else; Altrimenti, per le versioni precedenti,
SelectFromSavedLocationToCurrent (); chiama la funzione originale
EndIf; fine controllo versione
EndScript

Collaudo.

Una volta compilato, per il test ipotizziamo di dover essere in un punto del file script, ma doverci portare in un altro dove copiare del testo, per poi tornare al punto di partenza. Provate quindi a seguire questi passi:

1. Rimanete nell'Editor di Jaws, e portatevi sulla riga di intestazione di una funzione a vostra scelta.

2. Qui premete "Control+F" per mostrare la finestra di ricerca testo. Nel frattempo, la preventiva chiamata alla nostra funzione di gestione ha provveduto a registrare, silenziosamente, il punto da cui avete premuto la scelta rapida per la ricerca.

3. Cercate un testo qualsiasi , uno che siete certi vi sia, come ad esempio "script", e premete Invio.

4. Uscite dalla finestra di ricerca e, una volta sull'occorrenza del termine, premete "Control+Windows+K" per fissare il punto d'inizio di un blocco da copiare.

5. Scendete di alcune righe, poi premete "Shift+Control+Windows+K" per selezionare il testo tra i due punti e, se volete, copiate il testo.

6. Ora, poiché l'ultimo punto registrato non è più quello da cui siamo partiti, bensì quello d'inizio del blocco di testo, noi dobbiamo tornare al penultimo contrassegno, operazione che si effettua premendo la combinazione "Alt+Windows+FrecciaSu", che corrisponde all'esecuzione del nostro script "TornaPrecedente ()".

10.4.6. Le modifiche del file script per Microsoft Word.

Come detto più volte, da qui siamo partiti, ed adesso qui torniamo. In realtà, l'opera di adattamento della nostra procedura sui Contrassegni può essere svolta in varie forme, più o meno invasive, più o meno complicate, e ciascuno può anche scegliere.

In ogni caso, l'oggetto della nostra attenzione principale è lo script "MarkPlace", che già abbiamo incontrato nel terzo capitolo, il quale gestisce la registrazione del contrassegno del file archivio. Nel dettaglio, questo script è costituito da una serie di controlli che, se superati tutti, portano alla scrittura materiale dei dati.

Tale elemento di codice consente anche di conoscere quale funzione sia chiamata da Jaws per leggere dentro a Word dove si trovi il cursore, il dato che serve appunto per scriverlo nel contrassegno. Tale funzione si chiama "GetCurCharPos", (OttieniPosizioneCarattereCorrente), che noi inseriremo nella versione locale di "PosizioneCursore ()".

La successiva modifica diretta allo script "MarkPlace ()",ci porterà invece a creare una nuova versione, che chiameremo "ScriveSegno". Essa, a sua volta, attiverà le parti essenziali della nostra procedura, in modo da sfruttare quasi completamente l'opera dello script originale.

A quel punto, ci basterà inserire alla fine dello script per Word la chiamata alla nostra funzione locale appena creata, e così avremo raggiunto il nostro scopo. In particolare, non solo sfrutteremo tutti i controlli effettuati dal codice di Jaws, ma lasceremo anche che siano i messaggi originali a leggerci l'esito sul salvataggio del contrassegno.

Per aiutarci a compiere velocemente questa modifica al codice originale di Jaws, ed un'altra che ci servirà più in là, inizieremo questa prima parte della sezione riprendendo il tema dell’inserire testo nei documenti tramite gli script, restando ad operare ancora nel file script Predefinito. In particolare, faremo un passo indietro ed uno in avanti, sfruttando dapprima la funzione di scrittura testo già utilizzata per "InserisceFirma ()" e "InizioCodice ()", ma utilizzando poi la forma nel nome di script che nel prossimo capitolo useremo per rendere organica tale funzionalità.

Per quanto riguarda i tasti usati per i contrassegni in Word, abbiamo già detto che le combinazioni per salvare e tornare al contrassegno sono quelle originali, così come sono gli script che andremo ad eseguire. Purtroppo, le combinazioni "Alt+Windows+FrecciaSu", per "TornaPrecedente ()", e "Alt+Windows+FrecciaGiù", per "TornaSuccessivo ()", sarebbero già occupate da due comandi di lettura riga.

Tali comandi, che nelle ultime versioni sono comunque duplicati nei tasti freccia del tastierino numerico, per fortuna agiscono solo all'interno delle tabelle di Word. Per questo, grazie ad una semplice funzione integrata, potremo realizzare a livello locale due versioni dei nostri citati script, i quali svolgano sia le funzioni per noi, nel testo normale, sia quelle originali di Jaws, all'interno delle tabelle.

Infine, realizzeremo anche dentro a Word la versione locale di "ComandoTrova ()", la funzione chiamata dal nostro script "TrovaTesto ()". Come detto, convertiremo la versione di questo script già presente nel file per Word, così come avevamo fatto con la versione nel Blocco Note modificata nell'ottavo capitolo.

Esercizio 10.4.7. Lo script MetteMacroTesto3.

FileScript. Default.JSS

Nome. MetteMacroTesto3

Sommario. Inserisce un testo nel documento.

Descrizione. Chiama l'apposita funzione di scrittura testo, per inserire nel documento il contenuto di una costante che corrisponda alla riga di codice da aggiungere.

TastiAttivazione. Shift+Control+3

Novità.

1. La costante "MARK_PLACE", la quale prende il nome dallo script originale che andremo a modificare, e che contiene la riga di codice da inserire all'interno dello script omonimo.

Note.

1. Avendone già illustrato nella premessa lo scopo, resta da chiarire che la struttura del nome dello script corrisponde a quella conosciuta lo scorso capitolo. Nel dettaglio, "Mette" è l'azione da compiere, "Macro" è la categoria e "Testo" è l'oggetto, in questo caso completo di suffisso numerico. Come detto, nel prossimo capitolo dedicheremo lo spazio necessario a spiegare meglio il significato delle varie parti del nome, anche se per quanto illustrato sinora potreste avervi già fatto un'idea abbastanza precisa almeno delle prime due. Se non altro, il primo riscontro al nome lo si ha subito nel codice, dove la funzione chiamata inizia con lo stesso termine.

2. Per quanto riguarda i tasti di attivazione , invece, va evidenziato che il suffisso nel nome corrisponde al numero aggiunto alla combinazione "Shift+Control", e che tale soluzione sarà adottata anche nel successivo elemento di codice da realizzare.

3. Per conoscere il contenuto della costante, che corrisponde come detto al codice da trascrivere, è sempre possibile andarlo a controllare nelle nostre assegnazioni ad inizio capitolo, ma lo analizzeremo comunque tra poco quando tratteremo della modifica materiale da compiere allo script.

Codice.

Script MetteMacroTesto3 ()
MetteTesto (MARK_PLACE, TRUE); inserisce la riga di codice, andando poi a capo
EndScript

Collaudo.

1. Pur essendo uno script, limitatevi a compilare, perché il test lo faremo quando tratteremo della modifica che deve apportare al codice.

2. Circa il codice in sé, il secondo parametro "TRUE" serve per far sì, come scritto nel commento, che dopo la scrittura dell'istruzione ci si limiti ad andare a capo riga.

Esercizio 10.4.8. Lo script MetteMacroTesto4.

FileScript. Default.JSS

Nome. MetteMacroTesto4

Sommario. Inserisce un testo nel documento.

Descrizione. Chiama l'apposita funzione di scrittura testo, per inserire nel documento il contenuto di una costante che corrisponda alla riga di codice da aggiungere.

TastiAttivazione. Shift+Control+4

Novità.

1. La costante "FOCUS_CHANGED", che è relativa ad un elemento di cui tratteremo solo più avanti, contiene anche in questo caso la riga di codice da inserire.

Codice.

Script MetteMacroTesto4 ()
MetteTesto (FOCUS_CHANGED, TRUE); inserisce la riga di codice, andando poi a capo
EndScript

Collaudo.

1. Stesso discorso dello script precedente, rinviando ancora più in là il test, all'inizio della prossima sezione.

2. Intanto, chiudiamo il file script Predefinito e passiamo finalmente alle modifiche da fare nell'applicativo principale di casa Microsoft.

Esercizio 10.4.9. La versione di PosizioneCursore () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. PosizioneCursore

Descrizione. Restituisce il valore corrispondente alla posizione assoluta del cursore nel documento virtuale.

Ritorni. Di tipo Int. Il numero della riga corrente.

Novità.

1. La funzione integrata "GetCurCharPos ()", già presentata nella premessa. Senza parametri.

Codice.

Int Function PosizioneCursore ()
Return GetCurCharPos (); restituisce la posizione rilevata tramite la funzione nativa
EndFunction

Collaudo.

Questa funzione sarà chiamata da vari elementi, tra i quali anche indirettamente la prossima funzione da noi realizzata.

Esercizio 10.4.10. La funzione ScriveSegno.

FileScript. Word.JSS o WordClassic.JSS

Nome. ScriveSegno

Descrizione. Inizializza e chiama l'apposita funzione per il salvataggio dei contrassegni.

Ritorni. Di tipo Void. Nessuno.

Parametri.

1. iValore. La posizione corrente del cursore nel documento virtuale. Di tipo Int.

Novità.

1. La nostra funzione "SalvaDato ()".

2. La funzione integrata "SetCurrentDocumentMarkedPlace", (ImpostaContrassegnoDocumentoCorrente), che si occupa di scrivere materialmente il valore passato come unico parametro nell'archivio dei contrassegni per il documento aperto.

Fasi.

1. Un primo controllo, costituito dalla nostra funzione "DocumentoCorrente ()",cerca di rilevare il nome del file aperto. Se lo acquisisce, il flusso prosegue trasmettendo per riferimento il nome rilevato.

2. Un secondo controllo, rappresentato stavolta dalla nostra funzione "SalvaDato ()",tenta di registrare come contrassegno un valore acquisito tramite la versione locale di "PosizioneCursore ()". Se questo riesce, il flusso s'interrompe tornando allo script chiamante.

3. Se uno dei due controlli precedenti fallisce, il flusso continua fino ad eseguire il salvataggio del contrassegno tramite la funzione nativa di Jaws, "SetCurrentDocumentMarkedPlace ()", che userà il valore passato come parametro.

Codice.

Void Function ScriveSegno (int iValore)
Var String sNomeFile; nome del documento aperto
If DocumentoCorrente (sNomeFile) Then; se un nome di file è stato rilevato,
If SalvaDato (sNomeFile) Then; se il salvataggio è riuscito,
Return; restituisce il flusso alla funzione chiamante
EndIf; fine controllo salvataggio
EndIf; fine controllo documento
SetCurrentDocumentMarkedPlace (iValore); chiama la funzione nativa per il salvataggio
EndFunction

Esercizio 10.4.11. La versione aggiornata dello script MarkPlace ().

FileScript. Word.JSS o WordClassic.JSS

Nome. MarkPlace

Novità.

1. La nostra funzione "ScriveSegno ()".

2. L'esecuzione dello script "MetteMacroTesto3 ()", che però non sarà inserito nel codice ma utilizzato per compiere materialmente l'inserimento di una nuova istruzione all'interno del codice.

Note.

1. Per effettuare la modifica, portatevi sullo script "MarkPlace ()", e scendete sino alla terz'ultima riga sulla seguente istruzione:

SetCurrentDocumentMarkedPlace (iCurCharPos)

2. Qui, ponete un carattere Punto e Virgola ad inizio riga, così da impedire che l'istruzione contenuta sia eseguita. Scendete all'inizio della riga sottostante, e premete la combinazione "Shift+Control+3", eseguendo così il nostro script "MetteMacroTesto3 ()", il quale scriverà nel codice la riga seguente:

ScriveSegno (iCurCharPos); registra il dato con l'apposita funzione

3. Come potete notare, la nostra funzione ha sostituito quella originale di Jaws, lasciando invariato il contenuto tra parentesi.

4. In questo caso vi è stato indicato di effettuare la modifica direttamente nel codice nativo, poiché ce lo consentiva la soluzione adottata, con una nostra funzione che ha apportato il minimo delle modifiche possibili alla forma originale. In realtà, sarebbe stato per certi versi anche meglio spostare materialmente lo script nella parte del file dove abbiamo anche tutti gli altri nostri elementi di codice, soluzione che invece adotteremo più avanti in una successiva occasione di modifica agli script di Jaws.

5. Nella forma di riepilogo seguente, non si è voluto riportare la prima parte del codice originale dello script, lasciando solo la nostra modifica e l'istruzione nativa che la segue, posta su due righe per motivi di impaginazione.

Codice.

Script MarkPlace ()
; spazio per il codice originale
; SetCurrentDocumentMarkedPlace (iCurCharPos)
ScriveSegno (iCurCharPos); registra il dato con l'apposita funzione
processMessage(msgMarkingPlace, null (), OT_HELP, cscNull,
MB_OK|MB_ICONINFORMATION)
EndScript

Collaudo.

1. Se dopo la compilazione tutto è a posto, da questo momento in poi la scrittura dei contrassegni sarà materialmente gestita dalla nostra procedura.

2. Provate quindi a posizionarvi dapprima in un punto, salvando in contrassegno con "Control+Windows+K", e poi portarvi in un secondo punto e compiere la stessa operazione. Intanto, i messaggi dell'operazione dovrebbero essere gli stessi rispetto a quelli che gli script per Word vi pronunciavano in precedenza.

3. Ora, agite sul comando "Alt+Windows+K" per tornare all'ultimo contrassegno, operazione che dovrebbe riuscire.

4. Infine, premete "Alt+Windows+FrecciaSu" per spostarvi al penultimo contrassegno registrato, e dovreste riposizionarvi sul primo che avete salvato.

Esercizio 10.4.12. La versione di TornaPrecedente () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. TornaPrecedente

Sommario. Torna al contrassegno precedente, nel documento, oppure legge la riga precedente in una tabella.

Descrizione. Effettua un controllo per verificare dapprima che non si sia dentro ad una tabella, e così tornare al contrassegno precedente qualora esista. Altrimenti, si esegue lo script nativo che legge la riga precedente della tabella.

TastiAttivazione. Alt+Windows+FrecciaSu

Novità.

1. La funzione integrata "InTable", (NellaTabella), che restituisce TRUE o FALSE a seconda che si sia o meno in una tabella. Questa funzione restituisce un risultato TRUE anche quando si è posizionati nelle celle dei fogli di calcolo, come ad esempio Microsoft Excel. Senza parametri.

2. Lo script nativo "SayPriorRow", (LeggiRigaPrecedente), che svolge all'interno delle tabelle di Word la funzione chiarita dalla sua traduzione.

Note.

1. Le istruzioni che eseguono gli script dall'interno del codice possono essere inserite tramite l'apposito comando dell'Editor, "Shift+Control+I".

2. L'omonimo script inserito nella prima istruzione, e che viene eseguito se non ci si trova in una tabella, è in realtà la sua versione originale, quella presente nel file script Predefinito.

3. Durante la procedura guidata, o successivamente nella schermata di modifica, i tasti assegnati allo script vanno inseriti direttamente, sovrascrivendoli a quelli abbinati agli script del file Predefinito, oppure cancellandoli e riscrivendoli, qualora all'ingresso nell'apposito campo questo risultasse già compilato.

Codice.

Script TornaPrecedente ()
If !InTable () Then; se non si è in una tabella
PerformScript TornaPrecedente (); esegue lo script della nostra procedura
Else; altrimenti,
PerformScript SayPriorRow (); legge la riga precedente nelle tabelle di Word
EndIf; fine controllo tabella
EndScript

Collaudo.

Se la compilazione riesce, attendete il prossimo script per collaudare assieme entrambi gli elementi di codice.

Esercizio 10.4.13. La versione di TornaSuccessivo () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. TornaSuccessivo

Sommario. Va al contrassegno successivo, nel documento, oppure legge la riga successiva in una tabella.

Descrizione. Effettua un controllo per verificare dapprima che non si sia dentro ad una tabella, e così andare al contrassegno successivo qualora esista. Altrimenti, si esegue lo script nativo che legge la riga successiva in una tabella.

TastiAttivazione. Alt+Windows+FrecciaGiù

Novità.

1. Lo script nativo "SayNextRow", (LeggiRigaSuccessiva), che svolge la funzione illustrata dal nome all'interno delle tabelle di Word.

Note.

1. Così come nel caso di "TornaPrecedente ()", lo script eseguito dalla prima istruzione è quello presente nel file script Predefinito.

Codice.

Script TornaSuccessivo ()
If !InTable () Then; se non si è in una tabella
PerformScript TornaSuccessivo (); esegue lo script della nostra procedura
Else; altrimenti,
PerformScript SayNextRow (); legge la riga successiva nelle tabelle di Word
EndIf; fine controllo tabella
EndScript

Collaudo.

1. Per collaudare gli ultimi due script, cercate o create un documento in Microsoft Word che abbia almeno una tabella, assieme a del testo normale. Assicuratevi di salvare almeno un paio di contrassegni, quindi agite sui tasti "Alt+Windows+FrecciaSu" e "Alt+Windows+FrecciaGiù", sia dentro le tabelle che fuori, e controllate che il comportamento sia diverso.

Esercizio 10.4.14. La versione di ComandoTrova () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. ComandoTrova

Descrizione. Richiama il comando dell'applicativo che apre la finestra di dialogo per la ricerca di testo.

Ritorni. Di tipo Void. Nessuno.

Novità.

1. La costante "SHIFT_CONTROL_T", che corrisponde all'omologa combinazione tasti per richiamare la finestra di ricerca testo del programma.

Note.

1. L'unica riga di codice della funzione va prelevata da quella contenuta nello script "TrovaTesto ()", che nel prossimo esercizio cambieremo nella sua forma definitiva.

Codice.

Void Function ComandoTrova ()
TypeKey (SHIFT_CONTROL_T); attiva la finestra di ricerca testo
EndFunction

Collaudo.

Questa funzione sarà chiamata indirettamente tramite il prossimo script, a cui rinviamo quindi per il test definitivo.

Esercizio 10.4.15. La nuova versione di TrovaTesto () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. TrovaTesto

Note.

1. Per aggiornare lo script, portatevi al suo interno e aprite la finestra di modifica.

2. Svuotate il suo contenuto, ed inserite l'istruzione che esegue lo script "TrovaTesto ()", il quale sarà nell'occasione quello che si trova nel file script Predefinito.

Codice.

Script TrovaTesto ()
PerformScript TrovaTesto (); esegue la versione nel file script Predefinito
EndScript

Collaudo.

1. Se la compilazione fosse andata a buon fine, il test potrebbe essere anche solo quello di premere la scelta rapida "Control+F" per far visualizzare la finestra di ricerca testo.

2. Se non altro, dopo queste modifiche, potete considerare pienamente operativa anche dentro a Word la procedura sui Contrassegni.

3. Circa la procedura appena citata, essa funziona pienamente anche se per il salvataggio di un contrassegno si utilizza lo script nativo "MarkPlace ()", grazie alla modifica che vi abbiamo apportato. Anche il ritorno all'ultimo contrassegno con lo script nativo si effettua regolarmente, ma in questo caso non funziona la sincronizzazione del puntatore nell'elenco dei contrassegni, come invece avviene nella fase 4 nella nostra funzione "TornaDato ()". Per garantire l'azzeramento del puntatore, e la conseguente sincronizzazione della posizione nell'elenco dei contrassegni da scorrere, ci si dovrà servire del nostro script "TornaUltimo ()", che si esegue premendo "Alt+Windows+Fine". Per tale motivo, il suo utilizzo per questo scopo sarebbe quindi da preferire rispetto a quello dello script nativo, almeno dentro a Word.

10.4.16. Le modifiche per Microsoft Wordpad.

Se ci siamo dilungati un po' per il fratello maggiore, in Wordpad ci sono invece da fare solo due modifiche: la conversione dello script "TrovaTesto ()" nella funzione "ComandoTrova ()",e la creazione di una versione piuttosto articolata di "PosizioneCursore ()".

A proposito di quest'ultima, si tratta dell'unico modo escogitato per rilevare la posizione del cursore, in questo caso dentro al documento Virtuale. Nel dettaglio, l'espediente è selezionare il testo, dall'inizio o dalla fine del file, e poi contare i caratteri selezionati.

Abbiamo dovuto attingere a funzioni native vecchie e nuove, per creare questa funzione, e malgrado ciò il lavorio di selezione che deve compiere la rende abbastanza lenta, specialmente in caso di chiamate ripetute. Si tratta comunque di una soluzione al problema, l'unica che siamo riusciti a trovare, e per chi può o sa fare meglio, attendiamo integrazioni.

Esercizio 10.4.17. La conversione di TrovaTesto () in ComandoTrova () per Wordpad.

FileScript. Wordpad.JSS

Nome. ComandoTrova

Descrizione. Attiva il comando di ricerca testo dell'applicativo.

Ritorni. Di tipo Void. Nessuno.

Note.

1. La conversione si avvia portandosi dentro allo script "TrovaTesto ()", e da lì attivando la schermata di modifica.

2. Qui, cambiate il nome dello script in "ComandoTrova", quindi disattivate il controllo "Può essere assegnato al tasto". Proseguite aggiornando la descrizione ed il ritorno, come indicato in precedenza nelle apposite sezioni.

3. Una volta tornati all'Editor, lasciate all'interno solo l'istruzione con "TypeKey ()", che avrà come parametro la costante "SHIFT_CONTROL_T", equivalente all'omologa scelta rapida.

Codice.

Void Function ComandoTrova ()
TypeKey (SHIFT_CONTROL_T); attiva la finestra di ricerca testo
EndFunction

Collaudo.

In un documento non vuoto, provate a premere la scelta rapida "Control+F", e dovrebbe comparire la finestra di ricerca testo.

Esercizio 10.4.18. La versione di PosizioneCursore () Per Wordpad.

FileScript. Wordpad.JSS

Nome. PosizioneCursore

Descrizione. Restituisce la posizione assoluta del cursore all'interno del documento Virtuale.

Ritorni. Di tipo Int. Il valore della posizione del cursore.

Novità.

1. La funzione integrata "GetDocumentPercentage", (OttieniPercentualeDocumento), la quale restituisce un numero intero che rappresenta la percentuale del documento, a partire dall'inizio fino alla posizione corrente del cursore. Senza parametri.

2. Le funzioni integrate "SelectFromTop", (SelezionaDallAlto), e "SelectToBottom", (SelezionaDalBasso), che servono a selezionare il testo, rispettivamente, dall'inizio e dalla fine del documento aperto.

3. La funzione nativa "GetSelectedText", (OttieniTestoSelezionato), che restituisce appunto il testo con tale attributo. Avrebbe due parametri, che sono però opzionali, e che non è necessario specificare. Fate però attenzione a cancellare il carattere Virgola che Jaws pone come separatore dei parametri nel caso usiate la procedura guidata per inserirla nel codice.

Fasi.

1. Dopo aver casomai spento la sintesi, si effettua un controllo se ci si trovi nella prima metà del documento corrente. Se così fosse, viene attivata la selezione del testo dal cursore sino all'inizio del documento, contando poi i caratteri selezionati.

2. Nel caso invece che ci si trovi nella seconda metà del documento, si seleziona il testo dal cursore sino alla fine del documento, e si calcola la lunghezza sottraendo il numero dei caratteri selezionati a quelli complessivi.

3. Rilevata la posizione, si ritorna a quel punto tramite la funzione "MoveToDocumentOffset ()", e così anche deselezionando il testo.

4. Dopo aver casomai riattivato la sintesi vocale, viene restituito il valore rilevato.

Note.

1. La presenza di una funzione che restituisce la percentuale del documento in cui è posizionato il cursore avrebbe anche consentito di calcolare direttamente la sua posizione, partendo dai caratteri complessivi e moltiplicandoli per la percentuale stessa. Il limite di restituire solo numeri interi, tuttavia, portava ad una approssimazione non sufficiente ad essere d'aiuto al nostro intento.

Codice.

Int Function PosizioneCursore ()
Var
Int iStato, ; registra lo stato della sintesi
Int iPosiz; posizione nel documento

Let iStato = ControllaSintesi (); verifica l'attivazione della sintesi, casomai spegnendola
If GetDocumentPercentage () <= 50 Then; Se ci si trova nella prima metà del documento,
SelectFromTop (); seleziona dal punto all'inizio del documento
Let iPosiz = StringLength (GetSelectedText ()); conta i caratteri selezionati
Else; se invece ci si trova dalla metà in giù,
SelectToBottom (); seleziona dal punto sino a fine documento,
; e sottrae il numero dei caratteri selezionati a quello dei totali
Let iPosiz = GetCurrentDocumentLength () - StringLength (GetSelectedText ())
EndIf; fine controllo posizione
MoveToDocumentOffset (iPosiz); torna alla posizione originaria
ControllaSintesi (iStato); verifica se riattivare la sintesi, sulla base del valore impostato
Return iPosiz; restituisce la posizione rilevata
EndFunction

Collaudo.

1. Una volta compilato, il semplice salvataggio di un contrassegno si serve già del nostro lavoro, perché viene utilizzata la funzione "PosizioneCursore ()" appena definita a livello locale.

2. Quindi, ufficialmente, da questo omento, anche il quarto degli applicativi che ci interessano è in grado di sfruttare appieno la nostra procedura.

***

10.5. Automatizzare i Contrassegni.

Ogni funzionalità che noi aggiungiamo tramite gli script dovrebbe avere il compito di semplificare il nostro lavoro quotidiano, e non certo quello di crearci ulteriori comandi manuali da imparare e poi, soprattutto, ricordare a memoria. Per questo, nella procedura dei Contrassegni si è scelto intanto di utilizzare dei tasti che Jaws usava già in un famoso programma, e poi di far ruotare attorno a queste combinazioni gli altri tasti da premere per muoversi tra i contrassegni registrati.

Meglio ancora sarebbe che la procedura trovasse il modo di automatizzare sia il salvataggio, sia il ritorno ai contrassegni memorizzati. Circa il primo di questi obiettivi, abbiamo già previsto che attivando la ricerca testo sia memorizzato anche il punto d'inizio della ricerca stessa, ed ora estenderemo questa funzionalità anche agli script che realizzeremo in questa sezione.

Per quel che riguarda invece l'automazione, anche qui abbiamo già fatto qualcosa, predisponendo le basi per questo tipo di lavoro nelle funzioni di salvataggio e ritorno. Qui, invece, con una sola istruzione, da porre all'interno di una funzione Evento di Jaws, creeremo le condizioni perché il cursore si muova da solo in determinate circostanze.

Nel dettaglio, la funzione da modificare è "FocusChangedEvent", (EventoDiFocusModificato). Come dice la traduzione, il suo compito è effettuare delle impostazioni ogni qual volta cambi il focus del sistema, in pratica ogni volta che succede qualcosa di rilevante. Per questo, essa è stata scelta tra le decine di funzioni Evento che si attivano durante la normale azione di Jaws, preferendola ad altre che agiscono troppo spesso, o ad altre che lo fanno troppo poco.

Quello che a noi interessa è che essa si attivi sia quando si entra in un'applicazione, compito che svolge anche la classica funzione "AutoStartEvent ()", ma anche quando appaia una nuova finestra, come ad esempio fa "WindowActivatedEvent ()". Quindi, anziché rivolgersi a più funzioni, cosa peraltro sempre possibile, si è scelto di puntare su una soltanto, che è appunto quella su cui andremo ad agire.

Per quanto riguarda il tipo di modifica, la soluzione più semplice sarebbe quella di effettuarla direttamente nel codice originale senza spostare l'elemento, così come abbiamo fatto nel precedente script dentro a Microsoft Word, "MarkPlace ()". In quel caso, tuttavia, avevamo una scelta, qui invece i margini sono molto più stretti. Per capirne il motivo, analizzate di seguito l'istruzione che dovremo inserire:

GestisceDato (TORNA, APERTURA)

Come si può notare, la funzione chiamata è la nostra solita di gestione, mentre come parametri sono specificate due costanti, da noi già impostate nel nostro file personale apposito, "_PsConst.JSH". Ora, mentre il nome della funzione basta che sia riferito ad una esistente, o raggiungibile, dal file script dove si opera, le costanti devono invece essere dichiarate, o come nel nostro caso richiamate tramite il comando "Include", prima della riga di codice in cui sono utilizzate.

Per questo, se noi vogliamo inserire l'uso di tali costanti, dovremo in questo caso selezionare la funzione da aggiornare e spostarla nella parte del file script dove sono posti tutti gli altri elementi di codice da noi prodotti, e quindi anche dopo la nostra etichetta di inizio personale e le inclusioni dei file esterni.

Naturalmente, per chi non volesse spostare la funzione nativa dalla sua posizione nel codice, esisterebbero ben due alternative:

1. La possibilità di spostare casomai la dichiarazione "Include" con il nome del file delle costanti in una riga vuota precedente alla funzione dove noi andiamo ad inserire delle nostre istruzioni.

2. Porre i termini da usare come parametri, anziché tramite le costanti, usando direttamente il testo tra virgolette, facendo un'eccezione alla regola di cercare di eliminarle dal codice.

Il consiglio, tuttavia, è quello di seguire le nostre indicazioni, anche perché questa è la forma contenuta nella costante che viene a sua volta inserita nel codice dal nostro script creato appositamente, "MetteMacroTesto4 ()". Inoltre, tale soluzione consente di sfruttare in modo più preciso una funzionalità che introdurremo alla fine di questo capitolo, la quale prevede di aggiungere, nella parte di commento all'istruzione, la nostra etichetta Personale "; _Ps Codice".

Concluderemo questa parte della procedura con una coppia di script, che ci consentirà di collaudare appieno sia le modifiche alla citata funzione di Jaws, sia tutto il sistema dei Contrassegni in sé.

Esercizio 10.5.1. La versione aggiornata della funzione FocusChangedEvent ().

FileScript. Default.JSS

Nome. FocusChangedEvent

Novità.

1. L'utilizzo dello script "MetteMacroTesto4 ()" che, come nella precedente occasione, ci servirà ad inserire una nuova istruzione all'interno del codice, evitando così di fare manualmente delle modifiche.

Note.

1. Portatevi all'interno della funzione "FocusChangedEvent ()", selezionate tutto il codice con "Control+R", e tagliate il testo.

2. Andate alla fine del file script, ed incollate subito la funzione Evento. Se volete, provate già a compilare, prima di fare l'effettiva modifica al suo contenuto.

3. Scendete fino al comando di chiusura della funzione, e premete la combinazione "Shift+Control+4" per inserire la seguente riga di codice:

GestisceDato (TORNA, APERTURA); _Ps Codice

4. Come già accennato, il fatto di aver posto l'etichetta di inizio codice Personale come commento, ci sarà utile più avanti, per poter tornarvi velocemente in caso di necessità.

5. Come nella modifica allo script proposta in precedenza, di seguito ometteremo il codice integrale della funzione, lasciando solo l'intestazione, la nostra istruzione e il comando di chiusura.

Codice.

Void Function FocusChangedEvent (Handle FocusWindow, Handle PrevWindow)
; spazio per il codice originale
GestisceDato (TORNA, APERTURA); _Ps Codice
EndFunction

Collaudo.

1. Se la compilazione non dà problemi, come al solito, rinviamo il test su questa funzione all'ultimo script del gruppo.

Esercizio 10.5.2. Lo script EsceProgramma.

FileScript. Default.JSS

Nome. EsceProgramma

Sommario. Esce dall'applicazione.

Descrizione. Esce dal programma attivo, salvando la posizione nel documento eventualmente aperto, qualora ciò sia possibile, e comunque cancellando tutte le annotazioni relative ai file aperti per quell'applicazione.

TastiAttivazione. Alt+F4

Novità.

1. La costante "ALT_F4", che contiene l'omologa combinazione tasti.

Fasi.

1. Si chiama la nostra funzione "GestisceDato ()", specificando come parametri il salvataggio della posizione ed il tipo di azione legato all'uscita dalle applicazioni.

2. Si chiama inoltre la nostra funzione "PronunciaEsegue ()", cui si specificano come parametri le costanti "ALT_F4", e "TRUE", per essere certi che sia passata tale combinazione di tasti all'applicativo sottostante, o al sistema operativo, anche se lo script venisse chiamato da un altro elemento di codice.

Note.

Lo scopo di questo script è multiplo:

1. Prima di uscire dall'applicativo, tentare il salvataggio della posizione del cursore in un contrassegno.

2. A prescindere se quanto descritto al punto 1 riesca, il secondo parametro della funzione serve ad indicare di cancellare tutte le annotazioni su eventuali file aperti nell'applicativo corrente.

3. Uscire dal programma, inviando all'applicazione sottostante la combinazione che attiva lo script.

4. Così facendo, ad una successiva chiamata della funzione "FocusChangedEvent ()", quando si avesse da tornare nello stesso applicativo e con lo stesso documento, l'istruzione da noi inserita nella citata funzione Evento porterebbe a tornare al contrassegno salvato in precedenza, o in ogni caso all'ultimo registrato per quel documento.

5. Nel caso si avessero più documenti aperti, in diverse chiamate dello stesso applicativo, si sconsiglia tuttavia di usare questo comando, che come detto cancella tutte le annotazioni dei documenti aperti per l'applicativo corrente. In questo caso, infatti, tornando ad uno di quei documenti aperti citati in precedenza, non essendoci più traccia della loro apertura, il sistema si comporta come se vi si entrasse per la prima volta, tornando all'ultimo contrassegno che, probabilmente, potrebbe non essere il punto da cui si è lasciato il documento. Se si fosse in questa situazione particolare, quindi, conviene servirsi del successivo script che realizzeremo, il quale si occupa appunto di chiudere solo il documento corrente.

Codice.

Script EsceProgramma ()
GestisceDato (SALVA, ESCE) ; esegue il salvataggio, annotando l'uscita dal documento
PronunciaEsegue (ALT_F4, TRUE); forza l'invio dei tasti specificati, leggendo lo script attivo
EndScript

Collaudo.

Nonostante sia già possibile effettuarlo, spostiamo il collaudo alla fine del prossimo esercizio, che chiuderà questa sezione del capitolo.

Esercizio 10.5.3. Lo script ChiudeFinestra.

FileScript. Default.JSS

Nome. ChiudeFinestra

Sommario. Chiude la finestra attiva.

Descrizione. Chiude la finestra attiva, salvando la posizione nel documento eventualmente aperto, Se possibile, e comunque eliminando l'annotazione sull'apertura del documento abbandonato.

TastiAttivazione. Control+F4

Note.

1. Le fasi e gran parte delle annotazioni relative allo script precedente, "EsceProgramma ()", valgono anche per questo .

2. La differenza più importante sta nel secondo parametro di "GestisceDato ()", che in questo caso indica, alla funzione chiamata, di rimuovere l'annotazione sull'apertura del solo documento corrente. Questo fa sì che, avendo altri file aperti tramite lo stesso applicativo, rimanendo intatte le annotazioni sulle loro aperture, quando si dovesse rientrare in tali documenti la nostra procedura non sposterebbe il cursore di sistema, che quindi rimarrà dove era stato lasciato l'ultima volta.

3. L'altra differenza sta nel fatto che non sono specificati parametri alla funzione "PronunciaEsegue ()", impostando così di ripetere la pressione dei tasti di attivazione dello script. In questo caso, infatti, non è prevista una esecuzione dello stesso script da dentro ad altri elementi di codice, e quindi si può usare l'impostazione predefinita della citata funzione, che ripete i tasti di attivazione originali dello script.

Codice.

Script ChiudeFinestra ()
GestisceDato (SALVA, CHIUDE) ; salva la posizione simulando la chiusura del documento
PronunciaEsegue (); ripete i tasti premuti, leggendo il nome dello script
EndScript

Collaudo.

Dopo aver compilato, seguite questi passi:

1. Restate nell'Editor di Jaws, posizionatevi in un determinato punto del file script aperto, e premete "Control+F4" per chiudere tale file. Dovrebbe esservi pronunciato "ChiudeFinestra", il nome dello script attivato.

2. Sempre da dentro l'Editor, richiamate il menu File, e premete "1", per riaprire l'ultimo documento appena chiuso, ed il cursore dovrebbe posizionarsi sul punto da dove si era usciti in precedenza.

3. La stessa cosa accade anche se si esegue l'altro script, "EsceProgramma ()".

4. Qualora questi tasti, che sono comuni a tutti gli applicativi, fossero premuti in finestre non registrate come di tipo "Editing", la chiamata alla funzione "GestisceDato ()" non avrebbe effetto.

5. Infine, avevamo impostato anche il ritorno alla riga di partenza dopo aver sostituito del testo, tramite il comando "Control+H". Per provarlo, basta andare nell'Editor di Script o nel Blocco Note, effettuare una sostituzione, ed al ritorno alla schermata principale si ritornerà alla riga da dove si era premuto il comando. Senza il nostro sistema, nel Blocco Note si tornerebbe comunque alla prima riga, mentre nell'Editor di Script si resterebbe nella posizione dove era stata eseguita l'ultima sostituzione.

10.5.4. I comandi di Uscita e Chiusura negli altri Applicativi.

Dopo aver realizzato, e opportunamente testato, i nostri script di Uscita all'interno dell'Editor di Jaws, bisogna accertarsi che lo stesso sistema sia efficace anche con gli altri tre applicativi che stiamo tentando di omologare.

Per quanto riguarda Microsoft Word, non ci sono script locali abbinati al comando di Chiusura Finestra , e quindi il nostro script appena realizzato può svolgere tranquillamente il suo compito anche lì.

Circa il comando di uscita, invece, dalla versione 18 Jaws ha un proprio script, che si chiama come la combinazione tasti, "AltF4". Dovremo quindi prevedere una versione locale di "EsceProgramma ()", la quale salvi il contrassegno in uscita ma, nel caso lo script nativo sia presente, attivi quello anziché la nostra funzione, "PronunciaEsegue ()".

Nel Blocco Note e in Wordpad, invece, che sono applicativi molto più semplici, Jaws non ha un proprio comando d'uscita abbinato alla combinazione "Alt+F4". Per questo, funzionerà quello che abbiamo realizzato nel file script Predefinito.

A proposito invece dello script per chiudere la finestra, in questi due applicativi un tale comando neppure esiste, poiché Blocco Note e Wordpad non consentono l'apertura di più file contemporaneamente.

Proprio per questa caratteristica, può capitare invece di avere nello stesso momento più istanze dello stesso programma aperto, con documenti diversi. In questo caso, se noi avessimo una versione dello script che simuli la chiusura della finestra, potremmo abbandonare comunque un singolo file pur evitando di cancellare le annotazioni su tutti i documenti aperti in quel momento nell'applicativo, come farebbe invece lo script di Uscita.

Per i dettagli su come questo avvenga, vi rinviamo alle note nei singoli elementi di codice. Iniziamo intanto con Word, e la sua versione locale dello script di uscita.

Esercizio 10.5.5. La versione di EsceProgramma () per Microsoft Word.

FileScript. Word.JSS o WordClassic.JSS

Nome. EsceProgramma

Sommario. Esce dall'applicazione.

Descrizione. Esce dal programma attivo, salvando la posizione nel documento eventualmente aperto, qualora ciò sia possibile, e comunque cancellando tutte le annotazioni relative ai file aperti per quell'applicazione.

TastiAttivazione. Alt+F4

Novità.

1. La funzione integrata "GetScriptKeyName", (OttieniNomeTastiScript), che restituisce gli eventuali tasti di Attivazione dello script il cui nome sia specificato nell'unico parametro.

2. La costante "ALTF4", da non confondere con quella che di diverso ha solo il carattere Sottolineato tra le due componenti del nome, e che in questo caso rappresenta non i tasti, bensì il nome dello script omonimo, da porre come parametro alla funzione integrata.

Fasi.

1. Si chiama la nostra funzione "GestisceDato ()", specificando come parametri il salvataggio della posizione ed il tipo di azione legato all'uscita dalle applicazioni.

2. Tramite la funzione integrata "GetScriptKeyName ()",Una struttura di controllo verifica se sia presente uno script nativo di Jaws che si attivi alla pressione della combinazione "Alt+F4". Se un tale script esiste, lo si esegue per chiudere il lavoro, altrimenti si chiama la nostra funzione "PronunciaEsegue ()".

Codice.

Script EsceProgramma ()
GestisceDato (SALVA, ESCE) ; esegue il salvataggio simulando l'uscita dal documento
If GetScriptKeyName (ALTF4) Then; se lo script originale esiste,
PerformScriptByName (ALTF4); lo esegue
Else; altrimenti,
PronunciaEsegue (); ripete i tasti di Attivazione , e pronuncia il nome dello script
EndIf; fine controllo presenza script nativo
EndScript

Collaudo.

1. Se la compilazione non dà problemi, come test provate ad uscire da dentro ad un documento di Word, avendo pronunciato il nome del programma.

2. Se poi riaprendo quel file, si rientrasse nel punto da dove si era usciti, si avrà la conferma che entrambe le funzionalità dello script sono state rispettate.

Esercizio 10.5.6. La versione di ChiudeFinestra () per Blocco Note.

FileScript. Notepad.JSS

Nome. ChiudeFinestra

Sommario. Chiude il file uscendo dal programma.

Descrizione. Chiude il file corrente, salvando la posizione in tale documento, Se possibile, e comunque eliminando l'annotazione sull'apertura del solo documento abbandonato.

TastiAttivazione. Nessuno

Note.

1. Il codice sarà in buona parte quello utilizzato nella versione per il file script Predefinito, con una sola grande differenza: dopo aver salvato come prima il contrassegno, ed aver rimosso l'annotazione sull'apertura del file, alla funzione "PronunciaEsegue ()" sarà specificata sia la combinazione"Alt+F4", sia il secondo parametro "TRUE". In tal modo, l'uscita dal programma avverrà simulando l'omonimo script, ma in realtà abbandonando il documento come se si fosse chiusa soltanto la finestra corrente.

2. Per questo, una volta tornati ad un eventuale documento aperto con il Blocco Note, il cursore non tornerà all'ultimo contrassegno registrato, così come si farebbe se si fosse eseguito il nostro script "EsceProgramma ()", bensì rimarrà nella posizione in cui lo avevate lasciato in precedenza.

Codice.

Script ChiudeFinestra ()
GestisceDato (SALVA, CHIUDE) ; salva la posizione simulando la chiusura del documento
PronunciaEsegue (ALT_F4, TRUE); forza l'invio dei tasti specificati, leggendo lo script attivo
EndScript

Collaudo.

1. Per testare lo script, provate ad aprire un primo documento non vuoto con il Blocco Note. Appena entrati, all'inizio del documento premete "Control+Windows+K" per salvare un contrassegno in quel punto, poi spostatevi in un altro punto facilmente riconoscibile del testo.

2. Dalla nuova posizione raggiunta nel documento, aprite tramite i comandi di sistema un'altra istanza del Blocco note, e da lì provate uscire premendo la nostra ultima versione dello script, "Control+F4"

3. Se non siete tornati direttamente al primo documento aperto, ritornatevi con "Alt+Tab", e qui potrete notare che vi trovate nel punto da cui avete aperto il nuovo file, quindi senza che la nostra procedura sui contrassegni abbia avuto alcun effetto.

4. Sempre da quel punto, aprite una nuova istanza del Blocco Note, dalla quale uscite però per l'occasione nel modo classico, premendo "Alt+F4". Quando tornerete nuovamente al primo script, stavolta la nostra procedura sui contrassegni sarà tornata in funzione, riportando il cursore dove avevate salvato l'ultimo contrassegno, all'inizio del documento.

Esercizio 10.5.7. La versione di ChiudeFinestra () per Wordpad.

FileScript. Wordpad.JSS

Nome. ChiudeFinestra

Sommario. Chiude il file uscendo dal programma.

Descrizione. Chiude il file corrente, salvando la posizione in tale documento, Se possibile, e comunque eliminando l'annotazione sull'apertura del solo documento abbandonato.

TastiAttivazione. Nessuno

Note.

1. Tutte le informazioni date con la versione per il Blocco Note valgono anche per questa, compreso il codice che è lo stesso dello script precedente.

2. Per lo stesso motivo, anche il collaudo non è necessario, dato che lo script serve soprattutto per completare la funzionalità di gestione dell'uscita in tutti e quattro gli applicativi di nostro interesse.

Codice.

Script ChiudeFinestra ()
GestisceDato (SALVA, CHIUDE) ; salva la posizione simulando la chiusura del documento
PronunciaEsegue (ALT_F4, TRUE); forza l'invio dei tasti specificati, leggendo lo script attivo
EndScript

10.5.8. Estendere le funzioni automatiche.

La procedura sui Contrassegni, e la sua automazione, sono state proposte in una forma base, che garantisce un funzionamento minimo. Come sempre, e com'è del resto nello spirito di questa opera divulgativa, il sistema può essere esteso e personalizzato da ciascuno, secondo le proprie esigenze.

In particolare, la funzione del ritorno all'ultimo contrassegno, quando si entra in un programma, presuppone che la procedura SAPPIA se, e quando, un file sia aperto. Al momento, tuttavia, gli unici due comandi a fornire tali informazioni sono appunto i nostri due script, "EsceProgramma ()" e "ChiudeFinestra ()", ma essi non sono gli unici in grado di chiudere un documento aperto.

Nei nostri quattro applicativi, ad esempio, anche "Salva con nome" chiude sempre il documento in cui si attiva questo comando. Nel Blocco Note ed in Wordpad, dato che questi programmi possono aprire solo un documento alla volta, anche altri comandi come "Nuovo", oppure "Apre" nel menu File, portano comunque a chiudere il documento aperto qualora fossero richiamati.

Pertanto, se si volesse assicurare un monitoraggio più completo della situazione, andrebbero realizzati anche per questi comandi delle versioni che prima attivano la nostra procedura, poi inviano i tasti premuti all'applicazione. Il problema, casomai, sarebbe che questi script suppletivi andrebbero realizzati soprattutto a livello locale, perché le funzioni che richiamano tali comandi possono essere anche molto diverse da programma a programma.

Anche per quanto riguarda i contrassegni nel documento, sinora noi abbiamo abbinato i nostri comandi allo script "TrovaTesto ()", ed a "SostituisceTesto ()" ma solo per l'Editor di Jaws ed il Blocco Note. Anche qui, tuttavia, ci sono altri comandi di spostamento, come ad esempio "Elenco Script" nell'Editor di Jaws, che si attiva con "Control+L", e rispetto al quale potrebbe essere utile poter tornare ad un contrassegno segnato automaticamente al momento del suo richiamo.

Per completare l'argomento, così come si era accennato parlando dei file "JSB" esterni, avvertiamo che tutti questi script collegati a comandi di comune utilizzo smettono di funzionare quando ci fosse un errore nella compilazione del file script Predefinito, creando disagi fin quando tale errore non venga risolto. Va detto che si tratta di una situazione limite, e che chi vi scrive, se può interessare, ha aggiunto tutte queste funzionalità al sistema perché i benefici sono sicuramente maggiori dei rischi.

In ogni caso, per chi volesse realizzare qualche altro script, basta prendere come modello i nostri due script per le uscite dai file, e predisporre la loro attivazione tramite i tasti che attivano i rispettivi comandi nei singoli programmi. Più avanti, alla fine del nostro viaggio, vedremo come poter aggiungere in modo più semplice degli script abbinati ai comandi degli applicativi, sempre sfruttando l'elaborazione con gli archivi in formato "INI".

***

10.6. Ricercare un testo preimpostato.

Nell'ottavo capitolo ci eravamo già serviti di una funzione che, appoggiandosi ai comandi degli applicativi, avviava una ricerca testo. Ora, possiamo riprendere ed ampliare quel sistema, sfruttando ancora una volta la nostra funzione di gestione dati.

Lo scopo sarà quello di cercare delle stringhe di testo preimpostate, la prima delle quali sarà la nostra etichetta di inizio codice Personale. Grazie a questo metodo, come già preannunciato, potremo abbinare tale richiesta a delle combinazioni di tasti, per andare alla prima, all'ultima, alla precedente o alla successiva occorrenza di questa stringa.

Dato che ci siamo, ne approfitteremo anche per completare l'integrazione alle funzionalità di ricerca nel Blocco Note. Nel dettaglio, aggiungeremo la possibilità, quando non si trovano più occorrenze del testo da cercare, di iniziare la ricerca dall'altro lato del documento, come succede negli altri tre applicativi sui quali stiamo operando.

Esercizio 10.6.1. La funzione VaiEstremi.

FileScript. Default.JSS

Nome. VaiEstremi

Descrizione. Porta all'inizio o alla fine del documento corrente, sulla base del tipo di ricerca passato come parametro.

Ritorni. Di tipo Void. Nessuno.

Novità.

1. La funzione integrata "JAWSTopOfFile", (InizioFileDiJaws), che sposta il cursore all'inizio del documento aperto. Senza parametri.

Fasi.

1. Un primo controllo verifica se il tipo di azione specificato richiede una ricerca dall'inizio, ed in questo caso si chiama la funzione "JAWSTopOfFile ()", appena citata.

2. Il secondo controllo, nel caso in cui sia stato invece specificato di far partire la ricerca dalla fine, chiama la funzione nativa contraria, "JAWSBottomOfFile ()".

3. In ogni caso, si sospende l'esecuzione dello script per circa un decimo di secondo, così da dare modo alla funzione chiamata di svolgere il suo compito, in particolare nel caso di documenti lunghi.

Codice.

Void Function VaiEstremi (string sOggetto)
If sOggetto == PRIMO Then; se si è chiesta la prima occorrenza,
JAWSTopOfFile (); si porta all'inizio del documento
ElIf sOggetto == ULTIMO Then; se invece si è chiesta l'ultima occorrenza,
JAWSBottomOfFile (); si porta alla fine del documento
EndIf; fine controllo spostamento
Pause ()
EndFunction

Collaudo.

Come al solito, il collaudo per questo elemento di codice, e per quelli che seguiranno, sarà effettuato alla fine di questa procedura.

Esercizio 10.6.2. La versione di EsegueRicerca () per il file script Predefinito.

FileScript. Default.JSS

Nome. EsegueRicerca

Descrizione. Ricerca del testo tramite la relativa funzione dell'applicativo.

Ritorni. Di tipo Int. L'esito della ricerca: TRUE per la riuscita, FALSE per il fallimento.

Parametri.

1. sTesto. Per Riferimento. Il testo da cercare. Di tipo String.

2. sOggetto. Il tipo di ricerca da compiere. Di tipo String.

Note.

1. Per sfruttare in buona parte il lavoro già fatto, aprite il file "BloccoNote.JSS", il file script collegato, portatevi sulla funzione omonima, selezionatela con "Control+R" e copiatela.

2. Chiudete il file script, tornando così a quello Predefinito, ed incollate la funzione.

3. Da dentro il codice, aprite la schermata di Modifica, e aggiornate i dati mancanti.

4. Una volta tornati all'Editor, nelle dichiarazioni delle variabili all'interno del codice, inserite la seguente riga:

Int iStato, ; indica lo stato di attivazione della sintesi

5. Cancellate la prima istruzione, quella che spegne la sintesi, ed inserite la chiamata alla nostra apposita funzione:

Let iStato = ControllaSintesi (); verifica se spegnere la sintesi vocale, salvandone l'esito

6. Andate verso la fine del codice, all'istruzione che riattiva la sintesi, cancellatela, ed inserite il nostro comando relativo:

ControllaSintesi (iStato); verifica se riattivare la sintesi

7. Adesso provate a compilare, e per il collaudo come al solito lo faremo più avanti.

Codice.

Int Function EsegueRicerca (string ByRef sTesto, string sOggetto)
Var
Int iStato, ; indica lo stato di attivazione della sintesi
Int iErrore; esito della ricerca

Let iStato = ControllaSintesi (); verifica se spegnere la sintesi vocale, salvandone l'esito
ComandoTrova (); attiva la finestra di ricerca testo
Pause ()
If sTesto Then; se un qualche testo è stato specificato,
TypeString (sTesto); lo immette nel campo di ricerca
Pause ();
Else; altrimenti,
Let sTesto = GetObjectValue (); trasmette per riferimento la stringa da cercare
EndIf; fine controllo testo
; se si è richiesta la ricerca dall'inizio oppure in avanti,
If sOggetto == PRIMO || sOggetto == SUCCESSIVO Then
TypeKey (ALT_G); attiva la ricerca all'ingiù
Else; altrimenti,
TypeKey (ALT_S); attiva la ricerca all'insù
EndIf; fine controllo direzione indietro
EnterKey ();
EscapeKey ()
Delay (ATTESA); ritarda il flusso per i decimi di secondo impostati
If GetObjectSubTypeCode () == PULSANTE_RADIO Then; se si resta nella finestra,
EscapeKey (); ne esce,
Let iErrore = TRUE; e imposta la conclusione anomala
EndIf; fine controllo esito
ControllaSintesi (iStato); verifica se riattivare la sintesi
If !iErrore Then; se non si sono verificate anomalie,
Return TRUE; restituisce l'esito positivo
Else; altrimenti,
Return FALSE; restituisce un risultato nullo
EndIf; fine controllo esito
EndFunction

Esercizio 10.6.3. La funzione EstremiDocumento.

FileScript. Default.JSS

Nome. EstremiDocumento

Descrizione. Gestisce l'arrivo ad una delle estremità del documento, proponendo di continuare la ricerca dalla parte opposta dello stesso.

Ritorni. Di tipo Int. L'esito della funzione: TRUE per continuare la ricerca, FALSE per lo stop.

Parametri.

1. sTesto. L'eventuale stringa da ricercare. Di tipo String.

2. sOggetto. Per Riferimento. Il termine che identifica il tipo di ricerca da svolgere. Di tipo String.

Novità.

1. La nostra funzione "VaiEstremi ()".

2. Le costanti "_A" e "_O", equivalenti al relativo carattere, che servono per formattare il messaggio.

3. La variabile globale "gsPartenza", che registra il punto del documento, la fine o l'inizio, da cui comincia la nuova ricerca di un testo.

Fasi.

1. Come primo passo, si riattiva direttamente la sintesi vocale, senza la nostra funzione, perché non sarà necessario rispegnerla prima di uscire.

2. Se si è chiesta una ricerca all'occorrenza precedente o successiva, si impostano i relativi messaggi, da sottoporre poi ad una finestra di scelta.

3. Nel caso si sia confermato di continuare, prima si fa muovere il cursore chiamando la nostra funzione "VaiEstremi ()", quindi si attiva l'altra nostra funzione, "EsegueRicerca ()", per interpretarne l'esito.

Se invece si annulla la richiesta, il flusso s'interrompe, restituendo tale flusso alla funzione chiamante.

Note.

1. Il punto del documento da cui far eventualmente ripartire la ricerca, all'inizio o alla fine, viene registrato in una variabile globale perché potrebbe essere utilizzato anche dalla funzione chiamante.

Codice.

Int Function EstremiDocumento (string sTesto, string ByRef sOggetto)
Var
String sTitolo, ; intestazione della finestra di dialogo
String sMessaggio, ; testo per la finestra di dialogo
Int iTasto; valore premuto nella finestra di dialogo

SpeechOn (TRUE); riattiva la sintesi, con lo svuotamento del buffer
If sOggetto == SUCCESSIVO Then; se si era chiesta l'occorrenza seguente,
Let sTitolo = FormatString (ttlContinuaCerca, _A, msgFine); formatta il titolo
Let sMessaggio = FormatString (msgContinuaCerca, msgInizio); formatta anche la conferma
Let gsPartenza = PRIMO; si assegna al tipo di azione la ricerca dall'inizio
Else; se invece si era chiesta l'occorrenza precedente,
Let sTitolo = FormatString (ttlContinuaCerca, _O, msgInizio); formatta il titolo
Let sMessaggio = FormatString (msgContinuaCerca, msgFine); formatta anche la conferma
Let gsPartenza = ULTIMO; imposta il tipo di azione per la ricerca dalla fine
EndIf; fine controllo tipo richiesta
; propone se continuare o meno la ricerca dalla parte opposta
If ChiedeConferma (sTitolo, sMessaggio, FALSE, FALSE, TRUE) Then; se si conferma di proseguire,
VaiEstremi (gsPartenza); esegue lo spostamento per continuare la ricerca,
Return EsegueRicerca (sTesto, sOggetto);poi riprende la ricerca e ne restituisce l'esito
Else; se invece la ricerca è stata interrotta,
Return TRUE; restituisce comunque la prosecuzione del flusso
EndIf; fine controllo tasto
EndFunction

Esercizio 10.6.4. La funzione InizioDocumento.

FileScript. Default.JSS

Nome. InizioDocumento

Descrizione. Restituisce la prima posizione nel documento sulla base del tipo di gestione dell'applicativo corrente.

Ritorni. Di tipo Int. Il valore corrispondente alla prima posizione nel documento.

Note.

1. Nell'alternativa alla prima condizione, si dà per scontato che la finestra dell'applicativo sia gestito sulla base della posizione assoluta, in cui la prima posizione equivale al valore 0. Non si è voluto porre una seconda condizione costituita dalla nostra funzione "SiamoNellaFinestra ()", come sarebbe stato più giusto fare, solo per evitare di richiamarla inutilmente.

Codice.

Int Function InizioDocumento ()
If SiamoNellaFinestra (RIGHE) Then; se l'applicativo corrente funziona a righe,
Return TRUE; restituisce un'unità come prima posizione del file
Else; se invece l'applicativo funziona con la posizione assoluta,
Return FALSE; restituisce uno zero come prima posizione
EndIf; fine controllo finestra
EndFunction

Esercizio 10.6.5. La funzione MossoDaPrima.

FileScript. Default.JSS

Nome. MossoDaPrima

Descrizione. Verifica se il cursore si è mosso a seguito dell'azione svolta dall'applicativo.

Ritorni. Di tipo Int. L'esito del confronto: 1 o TRUE per una posizione diversa da quella di partenza, 0 o FALSE per nessun spostamento.

Parametri.

1. sOggetto. Il tipo di ricerca svolta, da cui si ricava la direzione in cui è stato effettuato il movimento. Di tipo String.

Novità.

1. La nostra funzione "InizioDocumento ()".

Note.

1. La funzione, costituita da un'unica struttura di controllo che verifica una serie di condizioni, serve soltanto a snellire il codice dell'elemento chiamante.

2. Nella prima condizione si utilizza nuovamente la variabile globale che avevamo impostato nell'ottavo capitolo per la procedura con le funzioni Evento.

Codice.

Int Function MossoDaPrima (string sOggetto)
Var Int iAttuale; posizione del cursore
Pause ()
Let iAttuale = PosizioneCursore (); memorizza la posizione corrente del cursore
If iAttuale == gnUltima ;se questa è uguale a quella memorizzata nell'ultimo contrassegno,
|| (sOggetto == PRIMO && iAttuale == InizioDocumento (); o, se si è partiti e rimasti all'inizio,
|| (sOggetto == ULTIMO && iAttuale == ValoreLunghezza ())) Then; o, partiti e rimasti alla fine,
Return FALSE; restituisce un risultato nullo
Else; altrimenti, in tutti gli altri casi,
Return TRUE; restituisce la conferma dello spostamento
EndIf; fine controllo cursore
EndFunction

Esercizio 10.6.6. La funzione CercaDato.

FileScript. Default.JSS

Nome. CercaDato

Descrizione. Gestisce la ricerca di un testo.

Ritorni. Di tipo Void. Nessuno.

Parametri.

1. sCategoria. Il tipo di ricerca da effettuare. Di tipo String.

2. sOggetto. L'oggetto della ricerca. Di tipo String.

3. iAiuto. Indica lo stato di attivazione dell'omonima fase. Di tipo Int.

Novità.

1. Le nostre funzioni "EstremiDocumento ()" e "MossoDaPrima ()".

Fasi.

1. Dopo aver casomai spento la sintesi, ed aver registrato la posizione di partenza, si chiama la nostra funzione "VaiEstremi ()", per spostarsi casomai all'inizio o alla fine del documento, qualora il tipo di ricerca impostato lo richieda.

2. Una struttura di controllo verifica poi se la categoria di ricerca impostata, che corrisponde al termine centrale nel nome dello script chiamante, preveda l'impostazione di un testo da cercare. Se così è, il flusso entra nel controllo ed imposta la stringa, altrimenti la variabile resta vuota e sarà ripetuta la ricerca precedente.

3. Una seconda struttura chiama la nostra funzione "EsegueRicerca ()",controllandone l'esito. Se questo è negativo, il flusso entra nella struttura operando la chiamata alla nostra funzione "EstremiDocumento ()". Se anche qui vi è un esito negativo, il flusso propone una schermata con un avviso che si può solo confermare, e l'oggetto dell'azione viene aggiornato con il punto del documento memorizzato nella variabile globale "gsPartenza".

4. Dopo aver casomai riattivato la sintesi, una terza struttura chiama in causa la nostra funzione "MossoDaPrima ()". Se questa ha un esito negativo, e la ricerca è stata effettuata da uno dei due estremi del documento, il flusso entra nella struttura facendo tornare il cursore alla posizione di partenza della ricerca.

5. In ogni caso, alla fine viene letta la riga corrente.

Codice.

Void Function CercaDato (string sCategoria, string sOggetto, int iAiuto)
Var
Int iStato, ; stato di attivazione della sintesi
String sTesto, ; stringa da cercare
Int iTasto; valore del tasto premuto

; verifica lo spegnimento della sintesi, azzerando il buffer
Let iStato = ControllaSintesi (FALSE, TRUE)
Let gnUltima = PosizioneCursore (); registra la posizione di partenza
VaiEstremi (sOggetto); effettua l'eventuale spostamento agli estremi del documento
If sCategoria == CODICE Then; se si è chiesto di cercare l'etichetta di inizio codice,
Let sTesto = INIZIO_PERSONALE; imposta la stringa relativa
EndIf; fine controllo categoria
If !EsegueRicerca (sTesto, sOggetto) Then; se la ricerca ha avuto un esito anomalo,
If !EstremiDocumento (sTesto, sOggetto) Then; se poi si è verificato un nuovo errore,
; si propone una finestra con un avviso da poter solo confermare, senza icone e suoni
ChiedeConferma (FormatString (msgNoTesto, sTesto), NULLO, OK, FALSE, TRUE)
Let sOggetto = gsPartenza; imposta l'ultima partenza come oggetto dello spostamento
EndIf; fine controllo estremi
EndIf; fine controllo ricerca
ControllaSintesi (iStato, TRUE); verifica l'eventuale riattivazione della sintesi
If !MossoDaPrima (sOggetto) ; se il cursore non si è spostato,
&& (sOggetto == PRIMO || sOggetto == ULTIMO) Then; e si è cercato dalle estremità del file,
SpostaCursore (gnUltima); ritorna al punto di partenza
EndIf; fine controlli esito ricerca
Refresh (); resetta la schermata
SayLine (); legge la riga corrente
EndFunction

Esercizio 10.6.7. Lo script CercaCodicePrimo.

FileScript. Default.JSS

Nome. CercaCodicePrimo

Sommario. Cerca l'inizio del codice personale.

Descrizione. Cerca l'eventuale prima etichetta di inizio codice Personale, presente nel documento aperto.

TastiAttivazione. Control+Windows+Home

Note.

1. Questo, come i tre script che lo seguono, ricalca il solito modello che si affida alla nostra funzione di gestione dei dati.

Codice.

Script CercaCodicePrimo ()
GestisceDato (); chiama la funzione generica
EndScript

Esercizio 10.6.8. Lo script CercaCodiceUltimo.

FileScript. Default.JSS

Nome. CercaCodiceUltimo

Sommario. Cerca la fine del codice personale.

Descrizione. Cerca l'ultima etichetta di inizio codice Personale, presente nel documento aperto.

TastiAttivazione. Control+Windows+Fine

Codice.

Script CercaCodiceUltimo ()
GestisceDato (); chiama la funzione generica
EndScript

Esercizio 10.6.9. Lo script CercaCodicePrecedente.

FileScript. Default.JSS

Nome. CercaCodicePrecedente

Sommario. Cerca il precedente codice personale.

Descrizione. Cerca la precedente etichetta di inizio codice Personale, presente nel documento aperto.

TastiAttivazione. Control+Windows+FrecciaSu

Codice.

Script CercaCodicePrecedente ()
GestisceDato (); chiama la funzione generica
EndScript

Esercizio 10.6.10. Lo script CercaCodiceSuccessivo.

FileScript. Default.JSS

Nome. CercaCodiceSuccessivo

Sommario. Cerca il successivo codice personale.

Descrizione. Cerca la successiva etichetta di inizio codice Personale, presente nel documento aperto.

TastiAttivazione. Control+Windows+FrecciaGiù

Codice.

Script CercaCodiceSuccessivo ()
GestisceDato (); chiama la funzione generica
EndScript

Collaudo della procedura di ricerca stringhe.

Quando avete compilato senza errori, provate a seguire questi passi:

1. Restando dentro all'Editor, premete "Control+Windows+Home". Se avete sempre seguito le nostre indicazioni, vi troverete all'inizio del nostro codice personale, sull'etichetta che precede le dichiarazioni "Include".

2. Provate ora a premere "Control+Windows+Fine". Se voi non avete aggiunto altre etichette al file script, dovreste posizionarvi sull'istruzione contenente la chiamata alla nostra funzione "GestisceDato ()", all'interno della funzione nativa "FocusChangedEvent ()".

3. Se ora premete "Control+Windows+FrecciaSu", tornerete all'etichetta iniziale , quindi con "Control+Windows+FrecciaGiù", scenderete nuovamente dentro alla funzione Evento modificata.

4. Se notate, gli spostamenti tra le etichette non sono velocissimi, più che altro perché bisogna andare dentro e fuori la finestra di ricerca testo. Nel caso aveste seguito i nostri consigli, ponendo varie etichette nel file script, potrete più velocemente scorrerle servendovi della funzione di ripetizione ricerca, con "Control+PaginaGiù" o "Control+PaginaSu", a seconda della direzione della ricerca stessa.

5. E ora, come promesso, usiamo questa procedura, e buona parte degli elementi suppletivi realizzati, per dotare anche il Blocco Note della funzionalità di ricerca in tutto il documento, con aggiornamento di un elemento già esistente, e la realizzazione ex novo dell'altro gemello.

Esercizio 10.6.11. La versione definitiva di CercaRipetiPrecedente () nel Blocco Note.

FileScript. Notepad.JSS

Nome. CercaRipetiPrecedente

Note.

1. La semplice modifica, già operata più volte sinora, prevede di cancellare tutto il contenuto della precedente versione, sostituendolo con l'ormai classica chiamata alla nostra funzione di gestione dati, come è riportato nel codice sottostante.

Codice.

Script CercaRipetiPrecedente ()
GestisceDato (); chiama l'apposita funzione
EndScript

Collaudo.

1. Per il momento limitatevi a compilare, perché il test di entrambi lo faremo quando avremo realizzato anche il secondo elemento di codice.

Esercizio 10.6.12. La versione di CercaRipetiSuccessivo () nel Blocco Note.

FileScript. Notepad.JSS

Nome. CercaRipetiSuccessivo

Sommario. Ripete l'ultima ricerca in avanti.

Descrizione. Cerca la successiva occorrenza del testo inserito nell'ultima ricerca effettuata.

TastiAttivazione. Control+PaginaGiù

Codice.

Script CercaRipetiSuccessivo ()
GestisceDato (); chiama l'apposita funzione
EndScript

Collaudo.

1. Dopo aver compilato, aprite il Blocco Note con un documento che abbia alcune occorrenze di un testo.

2. Avviate la ricerca con la normale funzione dell'applicativo, poi ripetetela premendo la combinazione "Control+PaginaGiù".

3. Continuate la ripetizione finché arrivate all'ultima occorrenza del testo, dopo della quale la pressione dei tasti vi proporrà un avviso che l'ulteriore ricerca è fallita, chiedendo se si vuole che la ricerca riprenda dall'inizio del documento. Annullate questa prima richiesta, ed il cursore resterà nella riga dove è stato trovato per l'ultima volta il testo, leggendone il contenuto.

4. Premete ora nuovamente "Control+PaginaGiù", ma stavolta confermate la richiesta. Il cursore dovrebbe ora spostarsi alla prima occorrenza del testo, partendo dall'inizio del documento.

5. Provate ora a fare il contrario, premendo la ricerca all'indietro con "Control+PaginaSu". Confermate ancora una volta la richiesta, ed il cursore tornerà dov'era prima, all'ultima occorrenza del testo.

***

10.7. Aggiungere altre ricerche, ed adattarle agli altri applicativi.

Il tipo di ricerca implementato, quello del codice di inizio personale, è probabile che abbiate modo di utilizzarlo dentro all'Editor di Script e, casomai, nel Blocco Note. In effetti, in questi due applicativi la procedura è già funzionante, senza altri aggiustamenti.

Lo scopo di questa sezione sarà invece allargare le occasioni d'utilizzo della procedura, e capire come poterla adattare ad altri applicativi.

In generale, oltre agli elementi di codice già realizzati, per far funzionare la procedura di ricerca testo, in ogni singolo applicativo, è necessario che:

1. Siano registrati i dati, comunque, per la finestra di tipo "Editing" e, a seconda dei casi, che sia configurato uno tra i tipi "Righe" o "Posizione", sulla base del fatto che l'applicativo sia gestito a righe o con la posizione nel documento virtuale.

2. La funzione del file script Predefinito "ComandoTrova ()" sia in grado di aprire la schermata di ricerca testo, oppure che tale compito sia svolto da una omonima funzione realizzata a livello locale.

3. Anche la nostra funzione "EsegueRicerca ()", possa gestire la scrittura ed il settaggio delle impostazioni dentro alla finestra "Trova", o che a maggior ragione essa sia integrata da una versione di tale elemento creata a livello locale.

Per quanto riguarda i punti 1 e 2, siamo a posto in tutti e quattro gli applicativi di nostro interesse, poiché erano condizioni necessarie per eseguire anche le precedenti funzionalità. Ci dedicheremo, dunque, a realizzare le versioni della funzione che richiama la finestra di ricerca negli altri due applicativi.

Esercizio 10.7.1. La versione di EsegueRicerca () per Word 2007.

FileScript. Word.JSS o WordClassic.JSS

Nome. EsegueRicerca

Descrizione. Ricerca del testo tramite la relativa funzione dell'applicativo.

Ritorni. Di tipo Int. L'esito della ricerca: TRUE per la riuscita, FALSE per il fallimento.

Parametri.

1. sTesto. Per Riferimento . Il testo da cercare. Di tipo String.

2. sOggetto. Il tipo di ricerca da compiere. Di tipo String.

Novità.

1. La funzione integrata"TabKey", (t), che simula la pressione dell'omonimo tasto.

2. Le costanti "ALT_C", "ALT_L", "ALT_A", "_G" e "_S", che servono tutte a simulare la pressione dei tasti cui si riferiscono.

3. La costante "OPZIONE_STANDARD", che equivale all'etichetta che nella finestra di ricerca corrisponde alle opzioni standard attivate.

4. La funzione integrata "GetObjectName ()", già citata parlando degli oggetti, ma che ora è giunta al suo primo utilizzo. Essa avrebbe due parametri, ma sono opzionali, e quindi non è importante specificarli.

5. La costante "BARRA_SPAZIO", che equivale al termine inglese "Space", il quale viene usato per simulare la pressione della barra spaziatrice.

6. La costante "OK_RICERCA", che corrisponde al nome del controllo su cui si ferma il cursore al termine di una ricerca positiva.

Note.

1. Questa funzione è sicuramente una delle meno performanti in quanto, oltre al solito tempo di entrata ed uscita dalla finestra, si è dovuto attingere spesso alla funzione "Pause ()" per consentire che il focus fosse stabile in un controllo che poi andava verificato. Pertanto, quando si chiede una ricerca in Word, è utile farlo solo in caso di occorrenze multiple, ricorrendo poi ai normali comandi word per la ripetizione della ricerca, "Control+PaginaGiù" o "Control+PaginaSu", anziché ripetere l'esecuzione del nostro script.

2. In ogni caso, al termine della ricerca si è previsto di lasciar gestire a Word l'eventuale ripetizione dall'altro estremo, e quindi è previsto sempre un ritorno positivo alla funzione chiamante.

3. Come specificato nel titolo, la versione è stata collaudata solo nell'Office 2007, e di sicuro non può valere per la versione 2016, che ha tutta un'altra interfaccia di ricerca. Sull'eventuale compatibilità con le versioni intermedie tra le due citate, lasciamo a voi l'onere della prova.

Codice.

Int Function EsegueRicerca (string sTesto, string sOggetto)
Var Int iStato; stato della sintesi
Let iStato = ControllaSintesi (); verifica se spegnere la sintesi, salvandone l'esito
ComandoTrova (); attiva la finestra di dialogo per la ricerca
Pause ()
If sTesto Then; se un qualche testo è stato specificato,
TypeString (sTesto); immette il testo da cercare
Pause ();
Else; altrimenti,
Let sTesto = GetObjectValue (); trasmette per riferimento la stringa da cercare
EndIf; fine controllo testo
TabKey (); si sposta al campo successivo
Pause ()
If GetObjectName () != OPZIONE_STANDARD Then; se non sono attivi i dettagli,
TypeKey (ALT_L); visualizza ulteriori opzioni
EndIf; fine controllo opzioni visualizzate
TypeKey (ALT_C); si porta sulla direzione della ricerca
If sOggetto == PRIMO ; se si è chiesta la prima occorrenza del testo,
|| sOggetto == SUCCESSIVO Then; o se ne è chiesto l'occorrenza successiva,
TypeKey (_G); imposta la ricerca in giù
ElIf sOggetto == ULTIMO ; se invece si è chiesto di andare all'ultima occorrenza,
|| sOggetto == PRECEDENTE Then; oppure se si vuole l'occorrenza precedente,
TypeKey (_S); imposta la ricerca in su
EndIf; fine controllo direzione ricerca
TypeKey (ALT_A); avvia la ricerca
Pause ()
ControllaSintesi (iStato); gestisce la riattivazione della sintesi
If GetObjectName () == OK_RICERCA Then; se la ricerca ha esito positivo,
EscapeKey (); esce dalla finestra
EndIf; fine controllo esito
Return TRUE; restituisce comunque l'esito positivo
EndFunction

Esercizio 10.7.2. La versione di EsegueRicerca () per Wordpad.

FileScript. Wordpad.JSS

Nome. EsegueRicerca

Descrizione. Ricerca del testo tramite la relativa funzione dell'applicativo.

Ritorni. Di tipo Int. L'esito della ricerca: TRUE per la riuscita, FALSE per il fallimento.

Parametri.

1. sTesto. Per Riferimento. Il testo da cercare. Di tipo String.

2. sOggetto. Il tipo di ricerca da compiere. Di tipo String.

Novità.

1. La costante "CAMPO_MAIUSCOLE", che equivale al valore 20, il quale è il numero di codice del controllo in cui rimane il cursore dopo un errore di ricerca.

Note.

1. Questa versione è più simile a quella presente nel file script Predefinito, anche perché la gestione degli errori torna di competenza della nostra procedura.

2. Come già detto negli script di ripetizione ricerca, Wordpad non ha la possibilità della ricerca all'indietro, anche se dopo non aver trovato l'occorrenza prima della fine del documento, una nuova ripetizione porterebbe comunque a riprendere la ricerca dall'inizio.

Codice.

Int Function EsegueRicerca (string ByRef sTesto, string sOggetto)
Var
Int iStato, ; indica lo stato di attivazione della sintesi
Int iErrore; esito della ricerca

Let iStato = ControllaSintesi (); verifica se spegnere la sintesi vocale, salvandone l'esito
ComandoTrova (); attiva la finestra di ricerca testo
Pause ()
If sTesto Then; se un qualche testo è stato specificato,
TypeString (sTesto); lo immette nel campo di ricerca
Pause ();
Else; altrimenti,
Let sTesto = GetObjectValue (); trasmette per riferimento la stringa da cercare
EndIf; fine controllo testo
EnterKey ();
EscapeKey ()
Delay (ATTESA); ritarda il flusso per i decimi di secondo impostati
If GetObjectSubTypeCode () == CAMPO_MAIUSCOLE Then; se si resta nella finestra,
EscapeKey (); ne esce,
Pause ()
Let iErrore = TRUE; e imposta la conclusione anomala
EndIf; fine controllo esito
ControllaSintesi (iStato); verifica se riattivare la sintesi
If !iErrore Then; se non si sono verificate anomalie,
Return TRUE; restituisce l'esito positivo
Else; altrimenti,
Return FALSE; restituisce un risultato nullo
EndIf; fine controllo esito
EndFunction

10.7.3. Aggiungere una ricerca preimpostata.

La ricerca di un testo predeterminato può avere anche altre applicazioni, non solo quella dell'etichetta di inizio codice. Nell'attesa di realizzare nel prossimo capitolo un nostro sistema di ricerca nel documento, che non utilizzi la funzione nativa, facciamo un esempio di cosa si dovrebbe fare per aggiungere una ricerca tramite la procedura che abbiamo già realizzato.

Tanto per rimanere nel campo della programmazione, ipotizziamo di dover cercare non un elemento di codice qualsiasi, bensì la successiva funzione. In questo caso, il testo da cercare sarebbe la parola chiave "Function", preceduta e seguita da uno spazio.

Di seguito, porremo i passi necessari per aggiungere questo tipo di ricerca alla procedura. Poi, starà a voi sostituire il termine da ricercare, e le relative impostazioni, con quello che più vi interessa.

1. Registrare il termine da ricercare in una costante, ed il nome della categoria, magari giocando con i plurali per evitare confusioni, come negli esempi di assegnazione seguente:

FUNZIONE = "Funzione", ; termine omonimo
CHIAVE_FUNZIONI = " Function ", ; parola chiave per le intestazioni delle funzioni

2. Aprire il file script Predefinito, portarsi sulla funzione "CercaDato ()", e scendere fino alla struttura di controllo in cui si verifica la categoria. Qui inserire un ulteriore controllo, facendo sì che la struttura abbia questo aspetto:

If sCategoria == CODICE Then; se si è chiesto di cercare l'etichetta di inizio codice,
Let sTesto = INIZIO_PERSONALE; imposta la stringa
ElIf sCategoria == FUNZIONE Then; se invece si è cercata l'intestazione delle funzioni,
Let sTesto = CHIAVE_FUNZIONI; si imposta il termine relativo
EndIf; fine controllo categoria

3. Creare uno o più script che abbiano come primi due termini l'azione di ricerca, e la categoria appena impostata, seguiti dal tipo di azione che si vuole ottenere, come negli esempi seguenti:

Script CercaFunzionePrimo ()
Script CercaFunzioneUltimo ()
Script CercaFunzionePrecedente ()
Script CercaFunzioneSuccessivo ()

4. Poi, la parte più difficile, trovare per ciascuno script che si vuole creare una combinazione tasti libera.

5. Tornati all'Editor, invece, la parte più facile: mettere un contenuto al nostro script, che sarà la solita chiamata alla nostra funzione, senza parametri, nella forma seguente:

GestisceDato (); chiama l'apposita funzione

10.10. Riepilogo.

Anche qui un bel po' di codice, che però stavolta ci ha permesso di chiudere le procedure ed i discorsi avviati anche da tempo. Come promesso, quindi, quello che c'è funziona tutto, e casomai l'aggiunta di qualcosa in un paio di elementi sarà necessaria solo se deciderete di proseguire il nostro viaggio assieme.

Nel prossimo capitolo, ad esempio, affronteremo il tema delle serie di script, creando una procedura che ce li scriverà per noi. Inizieremo però con il creare i contrassegni numerati, che sono paralleli a quelli che abbiamo usato sinora, ma del tutto indipendenti.

Soprattutto, sfrutteremo ancor più le potenzialità degli archivi in formato "INI", organizzandoli non più solo per applicativi e nomi di file, bensì aggiungendo la catalogazione per estensione. L'uso dei numeri come suffisso nei nomi di script, poi, ci amplierà le combinazioni a nostra disposizione, sempre mantenendo una logica nel loro utilizzo che ci aiuti a ricordarne le singole funzioni.

10.10.1. Elementi di Codice Personale.

ValoreRiga. File script: Predefinito. Funzione.
- Restituisce il numero della riga su cui è posizionato il cursore, chiamando la funzione nativa di Jaws.

ValoreColonna. File script: Predefinito. Funzione.
- Restituisce il numero della colonna su cui è posizionato il cursore, chiamando la funzione nativa di Jaws.

ValoreLunghezza. File script: Predefinito. Funzione.
- Restituisce il valore corrispondente alla lunghezza totale del documento corrente, utilizzando vari metodi sulla base del tipo di finestra aperta nell'applicativo.

PronunciaValoreRiga. File script: Predefinito. Control+J.
- Legge il numero di riga.

PronunciaValoreColonna. File script: Predefinito. Control+K.
- Legge il numero di colonna.

PronunciaValoreLunghezza. File script: Predefinito. Control+SemiColon.
- Legge la lunghezza del documento.

NumeroVersione. File script: Predefinito. Funzione.
- Restituisce un valore che identifica le prime due cifre della versione di Jaws.

NomeArchivio. File script: Predefinito. Funzione.
- Imposta il nome del file archivio da elaborare, sulla base del valore specificato come parametro, restituendolo con l'aggiunta dell'opportuna estensione.

PosizioneCursore. File script: Predefinito, Word, Wordpad. Funzione.
- Restituisce la posizione del cursore, sulla base del sistema usato dall'applicativo.

ScrivePuntatore. File script: Predefinito. Funzione.
- Trascrive il valore nell'archivio dei contrassegni, convertendolo in forma testuale e salvandolo nella chiave composta dal nome base casomai completato dal numero progressivo indicato.

LeggeSegni. File script: Predefinito. Funzione.
- Verifica il tipo di lettura da eseguire nell'archivio dei Contrassegni, se nell'elenco di quelli registrati oppure in quello dei Contrassegni numerati, sulla base dei parametri indicati.

PuntatoreSegni. File script: Predefinito. Funzione.
- Aggiorna il puntatore dei contrassegni, qualora il valore passato come parametro non sia negativo, mentre restituisce il numero del puntatore corrente, nel caso in cui il valore indicato sia inferiore a zero.

AggiornaSegni. File script: Predefinito. Funzione.
- Gestisce l'aggiornamento dei contrassegni, registrando con un numero progressivo quelli precedenti, fino ad un massimo di dieci. Dopo questo valore, viene cancellato man mano quello meno recente, così da far rimanere in memoria sempre le ultime dieci annotazioni sulla posizione del cursore.

SalvaDato. File script: Predefinito. Funzione.
- Gestisce la registrazione dei contrassegni nel documento aperto.

ScorreSegni. File script: Predefinito. Funzione.
- Gestisce lo spostamento al contrassegno indicato, all'interno dell'archivio di quelli già registrati.

MuoveAllaRiga. File script: Predefinito. Funzione.
- Richiama il comando locale di spostamento alla riga specificata, casomai spegnendo e riaccendendo la sintesi vocale.

SpostaCursore. File script: Predefinito. Funzione.
- Esegue lo spostamento del cursore, sulla base dell'applicativo corrente.

TornaDato. File script: Predefinito. Funzione.
- Gestisce il ritorno ad un contrassegno registrato.

GestisceDato. File script: Predefinito. Funzione.
- Raccoglie le richieste di azioni sui dati, verificandone la correttezza e smistando il flusso verso gli opportuni elementi di codice.

SalvaContrassegno. File script: Predefinito. Control+Windows+K.
- Contrassegna il punto desiderato.

TornaContrassegno. File script: Predefinito. Alt+Windows+K.
- Torna all'ultimo contrassegno.

TornaPrimo. File script: Predefinito. Alt+Windows+Home.
- Torna al contrassegno più vecchio.

TornaUltimo. File script: Predefinito. Alt+Windows+End.
- Torna all'ultimo contrassegno.

TornaPrecedente. File script: Predefinito, Word. Alt+Windows+UpArrow.
- Torna al contrassegno precedente.

TornaSuccessivo. File script: Predefinito, Word. Alt+Windows+DownArrow.
- Torna al contrassegno successivo.

ComandoTrova. File script: Predefinito, Word, Wordpad. Funzione.
- Attiva il comando di ricerca testo dell'applicativo.

TrovaTesto. File script: Predefinito, Word. Control+F.
- Attiva la ricerca di testo.

SostituisceTesto. File script: Predefinito. Control+H.
- Richiama il comando di sostituzione testo.

SelezionaDalContrassegno. File script: Predefinito. Shift+Control+Windows+K.
- Seleziona il testo dal punto registrato.

MetteMacroTesto3. File script: Predefinito. Shift+Control+3.
- Inserisce un testo nel documento.

MetteMacroTesto4. File script: Predefinito. Shift+Control+4.
- Inserisce un testo nel documento.

ScriveSegno. File script: Word. Funzione.
- Inizializza e chiama l'apposita funzione per il salvataggio dei contrassegni.

EsceProgramma. File script: Predefinito, Word. Alt+F4.
- Esce dall'applicazione.

ChiudeFinestra. File script: Predefinito, Blocco Note, Wordpad. Control+F4.
- Chiude la finestra attiva.

VaiEstremi. File script: Predefinito. Funzione.
- Porta all'inizio o alla fine del documento corrente, sulla base del tipo di ricerca passato come parametro.

EsegueRicerca. File script: Predefinito, Word, Wordpad. Funzione.
- Ricerca del testo tramite la relativa funzione dell'applicativo.

EstremiDocumento. File script: Predefinito. Funzione.
- Gestisce l'arrivo ad una delle estremità del documento, proponendo di continuare la ricerca dalla parte opposta dello stesso.

InizioDocumento. File script: Predefinito. Funzione.
- Restituisce la prima posizione nel documento sulla base del tipo di gestione dell'applicativo corrente.

MossoDaPrima. File script: Predefinito. Funzione.
- Verifica se il cursore si è mosso a seguito dell'azione svolta dall'applicativo.

CercaDato. File script: Predefinito. Funzione.
- Gestisce la ricerca di un testo.

CercaCodicePrimo. File script: Predefinito. Control+Windows+Home.
- Cerca l'inizio del codice personale.

CercaCodiceUltimo. File script: Predefinito. Control+Windows+End.
- Cerca la fine del codice personale.

CercaCodicePrecedente. File script: Predefinito. Control+Windows+UpArrow.
- Cerca il precedente codice personale.

CercaCodiceSuccessivo. File script: Predefinito. Control+Windows+DownArrow.
- Cerca il successivo codice personale.

CercaRipetiPrecedente. File script: Blocco Note. Control+PageUp.
- Ripete l'ultima ricerca all'indietro.

CercaRipetiSuccessivo. File script: Blocco Note. Control+PageDown.
- Ripete l'ultima ricerca in avanti.

10.10.2. Script, Funzioni e Comandi di Jaws.

GetCursorCol. (OttieniColonnaSulCursore).
- Determina la posizione orizzontale o la colonna in cui si trova il cursore attivo.

GetCurrentDocumentLength. (OttieniLunghezzaDocumentoCorrente).
- Restituisce il numero di caratteri nel documento virtuale.

GetJFWVersion. (OttieniVersioneJaws).
- Restituisce la versione corrente di Jaws.

GetUserSettingsDirectory. (OttieniCartellaImpostazioniUtente).
- Restituisce il percorso completo della cartella per le Impostazioni personali.

DeleteFile. (CancellaFile).
- Elimina il file di cui si specificano nome e percorso completo.

MoveToDocumentOffset. (MuoviAlDocumentoSlittato).
- Sposta il cursore alla posizione specificata del documento virtuale.

GetCurCharPos. (OttieniPosizioneCarattereCorrente).
- Restituisce il valore della posizione nel documento virtuale, all'interno di Microsoft Word.

SetCurrentDocumentMarkedPlace. (ImpostaContrassegnoDocumentoCorrente).
- Salva il valore specificato come la posizione dell'ultimo contrassegno registrato dentro a Microsoft Word.

SayPriorRow. (LeggiRigaPrecedente).
- Sposta il cursore alla riga precedente e la legge.

SayNextRow. (LeggiRigaSuccessiva).
- Sposta il cursore alla riga successiva e la legge.

GetDocumentPercentage. (OttieniPercentualeDocumento).
- Restituisce la posizione del cursore attivo sotto forma di valore percentuale rispetto al documento virtuale.

SelectFromTop. (SelezionaDallAlto).
- Seleziona dalla posizione del cursore PC all'inizio del documento corrente.

SelectToBottom. (SelezionaDalBasso).
- Seleziona dalla posizione del cursore PC alla fine del documento.

GetSelectedText. (OttieniTestoSelezionato).
- Restituisce sotto forma di stringa il testo selezionato.

JAWSTopOfFile. (InizioFileDiJaws).
- Sposta il cursore all'inizio del documento corrente.

TabKey. (TastoTab).
- Simula la pressione del tasto Tab.

10.10.3. Voci di Glossario.

PersonalizedSettings. (ImpostazioniPersonalizzate).
- Sottocartella delle impostazioni personali di Jaws, contenente dei file archivio di vario tipo.

JSI.
- Estensione dei file di inizializzazione di Jaws, collocati solitamente in una sottocartella nelle impostazioni personali, denominata PersonalizedSettings.

transient-session. (SessioneTransitoria).
- Sottocartella delle impostazioni personali di Jaws, contenente dei file che sono cancellati ad ogni avvio di Jaws.

***

Per ulteriori spiegazioni, scrivere a:

Abramo Volpato, oppure, a: Nunziante Esposito