Numero 09 del 2021
Titolo: Gli script di Jaws 13c. Le procedure guidate: controllo dei dati e funzioni hook.
Autore: Abramo Volpato.
Articolo:
Gli script di Jaws 13c. Le procedure guidate: controllo dei dati e funzioni hook.
Di Abramo Volpato.
13.3.2. Disabilitare il controllo di tutti gli altri tasti.
In questa forma degli elementi proposti, l'effetto della pressione dei tasti non legati ad uno script, come ad esempio le lettere o i numeri, rimarrebbe del tutto invariato. Questo succede perché, una volta attivata una funzione hook, non tutti i tasti premuti sono reindirizzati a tale funzione, che in questo caso abbiamo chiamato "NuovoEffetto ()", ma solo appunto quelli legati ad un qualche script.
Per evitare questo risultato, che potrebbe causare degli inconvenienti, è necessario servirsi di una terza funzione nativa, "TrapKeys", (INtrappolaTasti), che attiva e disattiva la modalità "Trapping". In tale modalità, infatti, la pressione di tutti i tasti che non sono abbinati ad uno script viene ignorata, senza dunque essere reindirizzata ad alcun elemento di codice.
Questa funzione nativa agisce come un interruttore, disabilitando gli altri tasti quando si pone nel suo primo parametro un valore "TRUE", e tornando ad analizzare tutti i tasti quando si ponga ad esso un valore "FALSE". La funzione avrebbe anche un secondo parametro, che però è opzionale e quindi possiamo anche non considerarlo.
Per concludere questa ampia parentesi sulle funzioni hook, proponiamo gli elementi di prima, ora aggiornati anche con la funzione "TrapKeys ()". Se volete, potrete casomai provare anche questa versione del codice, avendo comunque l'avvertenza di non farlo all'interno del file script predefinito.
Script ModoAlternativo ()
SayString ("Premere il tasto Home per tornare come prima"); avvisa sul modo di uscirne,
AddHook (HK_SCRIPT, "NuovoEffetto"); avvia la modalità speciale,
TrapKeys (TRUE); e indica a JAWS di ignorare qualsiasi tasto non collegato a script
EndScript
Void Function NuovoEffetto (string sNome)
If sNome == "JAWSHome" Then; se si preme il tasto Home,
SayString ("Ecco tornato tutto come prima!"); legge l'avviso,
RemoveHook (HK_SCRIPT, "NuovoEffetto"); interrompe la modalità speciale,
TrapKeys(FALSE) ; ritorna a far riconoscere a Jaws tutti i tasti,
Return TRUE; e restituisce un valore positivo per confermare l'interruzione
Else; altrimenti, in tutti gli altri casi,
SayString (sNome); legge il nome dello script collegato ai tasti premuti
EndIf; fine controllo nome script
EndFunction
Se avrete modo di provare questa forma aggiornata, una volta attivata la modalità alternativa, solo la pressione dei tasti abbinati a degli script avrà un effetto reale, restituendo come detto il nome inglese degli stessi script. Se si premeranno i tasti singoli, invece, nulla sarà restituito, appunto perché ogni altra pressione sarà ignorata.
13.3.3. Integrare l'effetto delle funzioni hook.
Nella premessa di questo argomento avevamo già accennato al fatto che, per quanto importanti, le funzioni hook coprono solo una parte del lavoro da svolgere. In questo blocco di elementi di codice, infatti, avremo bisogno di:
1. Attivare una nuova modalità di risposta ai tasti, individuando le volte in cui sono premuti quelli abbinati agli script, e disabilitando la pressione di tutti gli altri.
2. Intercettare, e registrare, la pressione di combinazioni tasti per attivare gli script a gestione personale.
3. Gestire la pressione dei tasti Invio, per la conferma dei tasti da assegnare agli script, Escape, per l'annullamento dell'immissione, ed Insert o Tasto Jaws assieme alla lettera T, per la lettura del titolo della finestra.
Tra questi, solo il primo obiettivo si può raggiungere tramite le funzioni hook, mentre per il secondo ed il terzo dovremo trovare un'altra via.
Per capire come fare, si deve analizzare il fatto che anche le funzioni hook, in qualche modo, devono riconoscere i tasti premuti, prima di decidere se gestirli oppure no. Tale compito è svolto da una funzione evento, incontrata nell'ottavo capitolo, che si chiama "PreProcessKeyPressedEvent ()".
Se ricordate, questa funzione si attiva appena un tasto viene premuto, restituendo alcuni parametri per riferimento, tra i quali nel secondo il nome per esteso, ed in inglese, di tale tasto. Il modo di sfruttarla sarà, dunque, inserire del codice nella prima parte della funzione nativa, che intercetti, e trasmetta, i dati necessari agli altri elementi della nostra procedura, tramite alcune variabili globali.
L'unico problema è che il nome dei tasti, così come restituito dalla funzione "PreProcessKeyPressedEvent ()", non è sempre uguale a quello che Jaws usa per abbinarlo ai nomi di script, all'interno dei file tasti con estensione "JKM". Per questo, di seguito produrremo anche una funzione che controlla, e casomai converte, il nome dei tasti, così da renderli compatibili con il resto della procedura.
Nel codice di questo gruppo, composto da altre otto funzioni ed uno speciale script, saranno inserite anche alcune delle istruzioni che abbiamo presentato negli esempi. Per rendere più comprensibili gli elementi proposti di seguito, tuttavia, abbiamo spezzettato in più parti il codice necessario, prevedendo nel dettaglio una funzione che inizializza il lavoro, una che lo avvia ed una che lo ferma, oltre ovviamente a quella che gestisce le varie pressioni, il cui nome è posto come parametro nelle istruzioni con "AddHook ()" e "RemoveHook ()".
L'aspetto importante da chiarire è che questa parte della procedura, la quale consente di specificare i tasti che dovranno attivare gli script a gestione personale, è completamente a sé stante. Questo significa, in altre parole, che per lanciarla bisogna di fatto uscire dalla procedura principale, avviare la modalità hook e le altre funzioni accessorie, quindi, al termine dell'inserimento dei tasti, rientrare nella procedura da cui si era usciti.
Esercizio 13.3.4. La funzione AvviaHook.
FileScript. Default.JSS
Nome. AvviaHook
Descrizione. Attiva il reindirizzamento alla funzione hook, il cui nome è registrato in una variabile globale, e resetta il contenuto dell'archivio temporaneo di cattura stringhe.
Ritorni. Di tipo Void. Nessuno.
Novità.
1. La funzione integrata "SetJcfOption", (ImpostaOpzioniDiJaws), la quale modifica le opzioni attive di Jaws sulla base dei valori specificati; ha due parametri obbligatori:
- Il tipo di opzione di cui cambiare il valore, usando una delle costanti presenti nel file predefinito di Jaws, che hanno il prefisso OPT_, per la sintesi vocale, e OPTBRL_, nel caso della barra Braille.
- Il valore numerico da impostare.
2. Le altre funzioni native "AddHook ()" e "TrapKeys ()",già illustrate.
3. La funzione integrata "IniRemoveSection", (CancellaSezioneFileIni), che elimina tutto il contenuto di una sezione di dati in un archivio in formato INI. Ha tre parametri, dei quali solo i primi due obbligatori:
- Il nome della sezione da cancellare.
- Il nome dell'archivio da elaborare.
4. La costante "TASTI_HOOK", che corrisponde alla nostra omonima funzione, e che va messa quindi in tutte le istruzioni dove tale nome deve essere un parametro.
5. La costante nativa "OPT_TYPING_ECHO",la quale ha valore 5, e che corrisponde al tipo di opzione da modificare nelle impostazioni per la sintesi vocale.
6. L'altra costante nativa "HK_SCRIPT", già presentata.
Note.
1. Questa funzione si occupa, come illustra il nome, di avviare la modalità hook, facendo sì che Jaws sospenda la normale risposta alla pressione dei tasti; essa perciò contiene soltanto l'elenco delle varie istruzioni che servono a tale scopo.
2. L'assenza di parametri, così come nelle altre occasioni, è permessa dal costante ricorso alle variabili globali.
Codice.
Void Function AvviaHook ()
Suona (INGRESSO_CAMPO); emette un suono di avvio editazione
SetJcfOption(OPT_TYPING_ECHO, 1); imposta l'echo di digitazione nello stato di Caratteri.
AddHook (HK_SCRIPT, TASTI_HOOK) ; attiva l'hook per la cattura dei tasti
SetLastScriptKey (NULLO); azzera i tasti appena premuti
TrapKeys (TRUE); indica a JAWS di ignorare qualsiasi tasto non collegato a script
; cancella la sezione con i dati nell'archivio temporaneo
IniRemoveSection (TASTI, NomeArchivio (TEMPORANEO))
Let gnConta = FALSE; resetta il valore
Let gnScriveTasto = TRUE; attiva la cattura dei tasti
; formatta e legge il messaggio che invita a premere i tasti di attivazione dello script
SayFormattedMessage (OT_HELP, msgAttivazione, NULLO, gsAttiva)
EndFunction
Esercizio 13.3.5. La funzione FermaHook.
FileScript. Default.JSS
Nome. FermaHook
Descrizione. Interrompe una modalità hook per l'intercettazione dei tasti di attivazione degli script, disattivando sia la funzione hook, sia il trapping dei tasti.
Ritorni. Di tipo Void. Nessuno.
Novità.
1. La funzione integrata "RemoveHook", già illustrata.
Note.
1. Questa funzione, in modo del tutto analogo alla precedente, contiene solo un elenco di istruzioni che servono, in questo caso, ad interrompere la modalità hook e a ripristinare la situazione originaria.
Codice.
Void Function FermaHook ()
Suona (USCITA_CAMPO); emette un suono di uscita dall'editazione
Let gnScriveTasto = FALSE; ferma la cattura dei tasti
RemoveHook (HK_SCRIPT, TASTI_HOOK) ; disattiva l'hook
TrapKeys(FALSE) ; ritorna a far riconoscere a Jaws tutti i tasti
SetJcfOption(OPT_TYPING_ECHO,gnEcoTastiera); ripristina l'eco tastiera originale
EndFunction
Esercizio 13.3.6. La funzione ConverteTasti.
FileScript. Default.JSS
Nome. ConverteTasti
Descrizione. Modifica la forma in cui sono stati registrati i tasti premuti, convertendoli nella versione inglese valida per i file JKM.
Ritorni. Di tipo String. I tasti di attivazione nella forma valida.
Parametri.
1. sTasti. La stringa da convertire. Di tipo String.
Novità.
1. Le costanti "FRECCIA_DESTRA" e "FRECCIA_SINISTRA", che equivalgono ai rispettivi nomi inglesi dei tasti, "RightArrow" e "LeftArrow".
Fasi.
1. Un primo ciclo analizza, una alla volta, le eventuali parti dei tasti da controllare, separate dal Segno Più.
2. Se la porzione di nome analizzata non è il nome inglese dei tasti "FrecciaDestra" o "FrecciaSinistra", tale stringa viene sottoposta ad un secondo ciclo, il quale verifica la presenza al suo inizio di prefissi errati, impostati nel relativo messaggio, e casomai li elimina.
3. Al termine del ciclo secondario, la stringa eventualmente modificata viene ricomposta, aggiungendovi di nuovo gli eventuali caratteri di separazione, e restituendone poi la forma definitiva al termine anche del ciclo principale.
Note.
1. Questa funzione si rende necessaria perché, come detto nella premessa, la forma in cui i nomi dei tasti vengono restituiti dalla funzione "PreProcessKeyPressedEvent ()" non è sempre uguale a quella utilizzata da Jaws per abbinare gli stessi nomi dei tasti agli eventuali nomi degli script che devono attivare. In particolare, in alcune occasioni, la forma originale prevede un prefisso, "Right", (Destra), oppure "Left", (Sinistra), davanti a qualche combinazione di tasti presente a destra e sinistra nella tastiera, per indicarne, appunto, la provenienza precisa; come anticipato nelle fasi, quindi, questi suffissi vanno eliminati, prima di passare il nome dei tasti al resto della procedura.
Codice.
String Function ConverteTasti (string sTasti)
Var
Int j, ; contatore del ciclo principale
Int k, ; contatore del secondo ciclo
String sTasto, ; singolo tasto
String sPrefisso, ; singolo prefisso
String sNuova; la combinazione tasti espressa nella forma valida
; scorre le parti del nome separate dal segno unificatore
For j = 1 To StringSegmentCount (sTasti, SEGNO_PIU)
Let sTasto = StringSegment (sTasti, SEGNO_PIU, j); estrae il singolo tasto
If sTasto != FRECCIA_DESTRA ; se quello estratto non è il tasto indicato,
&& sTasto != FRECCIA_SINISTRA Then; e neppure il tasto freccia speculare,
For k = 1 To 2; scorre i due possibili prefissi errati
Let sPrefisso = StringSegment (lstPrefissiTasti, PIPE, k); estrae il singolo prefisso
If StringStartsWith (sTasto, sPrefisso) Then; se il tasto inizia con il prefisso elaborato,
Let sTasto = StringChopLeft (sTasto, StringLength (sPrefisso)); elimina il prefisso dal tasto
EndIf; fine controllo presenza prefisso
EndFor; fine scansione prefissi
EndIf; fine controllo tasti
Let sNuova = CambiaCampo (sNuova, sTasto, ULTIMA, SEGNO_PIU); frappone un segno Più tra i tasti
EndFor; fine scansione tasti
Return sNuova; restituisce la stringa eventualmente modificata
EndFunction
Esercizio 13.3.7. La funzione OrigineScript.
FileScript. Default.JSS
Nome. OrigineScript
Descrizione. Controlla quale sia l'origine di uno script, restituendo un testo opportunamente formattato da proporre in una finestra di dialogo.
Ritorni. Di tipo String. Il titolo da proporre a video.
Parametri.
1. sNome. Il nome dello script rilevato. Di tipo String.
2. iTipo. Per Riferimento. Il tipo di script rilevato. Di tipo Int.
Novità.
1. Le costanti "NATIVO" e "GESTIONE", equivalenti nell'ordine ai valori 1 e 3, che servono ad indicare a quale tipo di script appartenga quello di cui si analizza il nome.
Fasi.
1. Dopo alcune impostazioni iniziali, una prima struttura di controllo aggiunge all'elenco dei file tasti da elaborare il nome di quello predefinito, qualora non vi sia già.
2. Un primo ciclo scorre i file tasti definiti, cercando dentro ad essi un'assegnazione che coinvolga i tasti abbinati allo script da cercare.
3. Un secondo ciclo scorre poi le sezioni predefinite per i file tasti, sempre arrestandosi nel caso si sia individuato lo script desiderato.
4. All'uscita dai cicli, o quando essi abbiano concluso la ricerca, qualora si sia trovato lo script richiesto, una struttura di controllo verifica innanzi tutto se sia uno di quelli a gestione personale, ed in tal caso componendo il suo nome reale, o se sia un altro di quelli creati dall'Utente, o infine uno di quelli nativi; in ciascuno di questi casi, la struttura assegna un valore che sarà trasmesso per riferimento.
5. All'uscita dall'ultimo controllo, viene infine restituito un testo formattato, nel quale si illustra il tipo di script rilevato, al fine di utilizzarlo come titolo in una finestra di dialogo.
Note.
1. Conoscere di quale tipo sia lo script, che Jaws ha individuato come abbinato ai tasti immessi, serve soprattutto per capire se confermare o meno i tasti premuti; più avanti capiremo anche un altro motivo dell'importanza di tale dato.
2. Tra i tipi rilevabili, bisogna fare attenzione a non confondere gli script a gestione personale, identificati dalla costante "GESTIONE", con valore 3, e tutti gli altri realizzati dall'Utente secondo il metodo tradizionale, che viene identificato dalla costante "PERSONALE", dal valore 2.
Codice.
String Function OrigineScript (string sNome, int ByRef iTipo)
Var
String sTasti, ; combinazione tasti che attiva lo script
String sFileOrigine, ; elenco dei file con le assegnazioni dei tasti
Int iFile, ; numero dei file tasti
String sArchivio, ; nome completo del file tasti da elaborare
Int iSezioni, ; numero delle sezioni predefinite per i file tasti
Int i, ; contatore del ciclo
Int k, ; numero progressivo della sezione elaborata
String sDato, ; dato temporaneo
String sChiave; suffisso numerico dello script
Let sTasti = GetScriptKeyName (sNome); rileva i tasti di attivazione dello script
; inizializza un elenco con il nome del file tasti per l'applicazione attiva
Let sFileOrigine = ApplicativoCorrente ()
If sFileOrigine != JAWS_FILE Then; se il nome non è quello dei file predefiniti di Jaws,
Let sFileOrigine = CambiaCampo (sFileOrigine, JAWS_FILE, ULTIMA); lo aggiunge all'elenco
EndIf; fine controllo nome archivio
Let iFile = StringSegmentCount (sFileOrigine, PIPE); conta gli elementi dell'elenco appena creato
Let iSezioni = StringSegmentCount (lstSezioniTasti, PIPE); conta anche le sezioni predefinite
Let i = PRIMA; inizializza il contatore dei file di origine dei tasti
While !sDato && i <= iFile ; continua finché non si trovi un dato, o vi siano file tasti da elaborare
; compone il nome del file tasti da leggere
Let sArchivio = StringSegment (sFileOrigine, PIPE, i) + JKM
Let k = PRIMA; inizializza il contatore delle sezioni
While !sDato && k < iSezioni; continua finché non si trovi un dato, o vi siano sezioni da elaborare
; tenta di leggere un dato dalla sezione estratta del file tasti nelle impostazioni personali
Let sDato = LeggeUtente (sArchivio, StringSegment (lstSezioniTasti, PIPE, k), sTasti)
Let k = k + 1; aggiorna il contatore delle sezioni
EndWhile; fine analisi sezioni
Let i = i +1; aggiorna il contatore dei file
EndWhile; fine analisi file tasti
If sDato Then; se un dato è stato trovato,
If ScriptPersonale (sNome, sChiave) Then; se si tratta di uno script a gestione personale,
Let iTipo = GESTIONE; imposta un valore che identifica il tipo di script
Let sNome = LeggeCampo (NULLO, PERSONALI, sChiave, PRIMA); e rileva il nome virtuale dello script
Else; altrimenti, negli altri script creati dall'Utente,
Let iTipo = PERSONALE; imposta il valore relativo
EndIf; fine controllo tipo personale
Else; altrimenti, se si tratta di uno script originale di Jaws
Let iTipo = NATIVO ; ne imposta il valore
EndIf; fine controllo ricerca
Return FormatString (ttlTastiUtilizzati, StringSegment (lstTipiScript, PIPE, iTipo), sNome)
EndFunction
Esercizio 13.3.8. La funzione TastiHook.
FileScript. Default.JSS
Nome. TastiHook
Descrizione. Gestisce i possibili tipi di risposta alla pressione dei tasti, quando si avvia l'attesa della combinazione tasti che attiva uno script.
Ritorni. Di tipo Void. Nessuno.
Parametri.
1. sNomeScript. Il nome dello script rilevato dalla funzione hook, trasmesso in modo predefinito alla funzione chiamante. Di tipo String. Parametro Opzionale.
Novità.
1. Le nostre funzioni "FermaHook ()", "AvviaHook ()", "OrigineScript ()" e "ConverteTasti ()".
2. La costante "ERRORE2", che contiene il nome di un file audio.
3. Le altre costanti "INSERT_T" e "JAWSKEY_T", che equivalgono entrambe alle omologhe combinazioni di tasti.
Fasi.
1. Nella principale struttura di controllo, la prima via intercetta la pressione del tasto Invio; al suo interno, un controllo iniziale interrompe il flusso nel caso si sia ad un secondo passaggio dopo una sola pressione; quindi, dopo aver preventivamente interrotto la modalità speciale, tramite la nostra funzione "FermaHook ()", si controlla se non siano stati premuti tasti, ed in questo caso si chiede conferma dell'abbandono, altrimenti si torna all'inserimento, grazie alla nostra "AvviaHook ()"; se, infine, tutto è regolare, si registra la penultima pressione dei tasti, che dovrebbe essere quella valida, e si fa proseguire il flusso.
2. La seconda via della struttura intercetta la pressione del tasto Escape; di diverso dai controlli della prima via, qui la conferma dell'abbandono viene proposta a prescindere dal fatto di aver immesso dei tasti, e comunque in caso di ripensamento si torna all'immissione.
3. La terza via della struttura intercetta la pressione del tasto Insert+T, oppure JAWSKey+T, producendo la lettura di un messaggio sulla fase di elaborazione. Dopo tale lettura, viene cancellata dalla memoria la pressione dei citati tasti, quindi si torna direttamente alla fase d'inserimento.
4. L'ultima via della struttura raccoglie tutti gli altri casi nei quali la funzione viene coinvolta, e cioè la pressione di tasti, o combinazioni di essi, che attivano un qualche script; dopo aver come al solito fermato l'hook, la nostra funzione "OrigineScript ()", individua il tipo di script rilevato e crea il messaggio per la finestra di dialogo; nel caso in cui lo script sia uno tradizionale, nostro o nativo, viene proposta la possibilità di sovrascrivere l'impostazione esistente; nel caso di script a gestione personale, invece, si sarà soltanto avvisati dell'impossibilità di utilizzare quei tasti, con l'invito a modificarli; in quest'ultimo caso, o se i tasti scelti non sono confermati negli altri due, si tornerà ad un nuovo inserimento, mentre, se la modifica viene confermata, saranno registrati i tasti premuti, lasciando proseguire il flusso.
5. Usciti da quella principale, una seconda struttura di controllo verifica se dei tasti siano stati rilevati; se così non è, la prima via della struttura intercetta il flusso e, se dei tasti non sono mai stati specificati neppure in precedenza, si torna alla schermata iniziale di scelta.
6. Se invece dei tasti sono validi, dapprima la nostra funzione "ConverteTasti ()" li rende compatibili con il formato usato per registrarne le assegnazioni nei file tasti "JKM"; quindi, se i tasti sono cambiati rispetto ad eventuali assegnazioni precedenti, si tenta di trascriverli nel file tasti e, se la scrittura riesce, si effettuano le impostazioni relative; in particolare, se si tratta di un nuovo inserimento, si imposta un valore per il passaggio diretto alla schermata successiva e, nel caso in cui si tratti comunque di una modifica, viene aggiunta la chiave attiva all'elenco di quelle a cui sono stati modificati i tasti di attivazione.
7. Terminati anche questi ulteriori controlli, si rientra in ogni caso alla procedura principale, dopo aver impostato il valore per il salto delle impostazioni iniziali.
***
Per ulteriori spiegazioni, scrivere a:
Abramo Volpato, oppure a: Nunziante Esposito
