Accessibilità, contrasto e risoluzione dei problemi

L’interfaccia di GX-TXT Octave Script Workspace permette di scrivere, verificare ed eseguire programmi GNU Octave anche quando si lavora con molte sorgenti e pannelli di supporto. Questa guida illustra come leggere più facilmente il codice, utilizzare la tastiera e interpretare i messaggi di errore senza modificare accidentalmente il sorgente o creare Job indesiderati.

Le procedure si riferiscono a GX-TXT DEV112-P005, Octave Script Workspace 1.8.3. I nomi dei controlli corrispondono alle etichette inglesi dell’applicazione. Gli esempi sono sintetici e non richiedono strumenti, Dataset o file scientifici esterni.

1. Verificare il contrasto effettivo dell’editor

L’opzione High Contrast Dark può essere scelta nelle impostazioni di aspetto dell’applicazione. La verifica visiva è importante: impostare un nome di tema non garantisce che ogni controllo, etichetta o finestra assuma automaticamente gli stessi colori.

Nell’editor Octave il testo principale ha sfondo nero (#000000) e primo piano bianco (#FFFFFF), con rapporto di contrasto 21:1. Questa misura riguarda la coppia bianco/nero; i colori delle diverse categorie della sintassi possono avere rapporti differenti.

Contrasto effettivo dell'editor Octave con Script Explorer e pannelli laterali aperti.
Figura 1 — Contrasto effettivo dell’editor Octave con Script Explorer e pannelli laterali aperti.

La GUI utilizza anche controlli Tk/ttk che conservano un aspetto chiaro. Non significa che il tema scuro dell’editor non sia attivo: il tema del sorgente e quello dei controlli esterni sono due livelli distinti.

2. Dare spazio al codice e valutarne la leggibilità

Nella configurazione mostrata il font del sorgente è DejaVu Sans Mono, 10 punti, con altezza di riga di circa 17 pixel. È un carattere monospaziato: allineamenti, indentazioni e numeri rimangono leggibili, ma su schermi ad alta risoluzione 10 punti possono risultare piccoli.

Quando lo spazio per il testo è limitato, scegliere View → Focus source / restore panes. L’area centrale si espande e nasconde temporaneamente i pannelli laterali, senza eliminare il loro contenuto. Per esempio, una finestra con codice largo 772 pixel può diventare larga 1367 pixel.

Modalità Focus source con codice più ampio e pannelli laterali nascosti.
Figura 2 — Modalità Focus source con codice più ampio e pannelli laterali nascosti.

Lo Workspace non presenta in questo menu un comando di zoom specifico del carattere del codice. Note panes and zoom riguarda i pannelli delle note, non equivale a ingrandire automaticamente il Source. Se il testo resta troppo piccolo, valutare la scala dei caratteri e del display attraverso le impostazioni dell’ambiente desktop, controllando poi il risultato reale.

3. Cercare nel codice con la tastiera

Con il sorgente aperto, Ctrl+F porta il focus nel campo Find. Digitare una parola, per esempio calibration, quindi utilizzare F3 per passare all’occorrenza successiva e Shift+F3 per tornare a quella precedente. L’occorrenza corrente viene evidenziata nel codice.

Ctrl+F e F3 evidenziano una corrispondenza nel sorgente Octave.
Figura 3 — Ctrl+F e F3 evidenziano una corrispondenza nel sorgente Octave.

Se la stringa cercata non compare nel testo, non rimane attiva una vecchia evidenziazione: questo aiuta a evitare di confondere un risultato precedente con una ricerca nuova.

Una ricerca senza corrispondenze rimuove l'evidenziazione precedente.
Figura 4 — Una ricerca senza corrispondenze rimuove l’evidenziazione precedente.

Premere Esc nel campo Find per riportare il focus al testo del programma. Queste operazioni sono di sola navigazione: non cambiano la revisione salvata.

4. Spostarsi a una riga e gestire i numeri non validi

Premere Ctrl+G oppure scegliere Edit → Go to line…. La finestra richiede un numero di riga positivo.

Finestra nativa Go to line per navigare al punto desiderato del sorgente.
Figura 5 — Finestra nativa Go to line per navigare al punto desiderato del sorgente.

Un valore non numerico o il numero 0 non produce alcuno spostamento: la finestra rimane aperta e il cursore resta nella posizione precedente. Un numero maggiore dell’ultima riga viene invece limitato all’ultima riga esistente. Il comando non aggiunge righe al programma.

5. Preparare un esempio di calibrazione con un parametro tipizzato

Aprire una Session di lavoro, scegliere File → New Script e salvare con File → Save questo esempio GNU Octave, i cui commenti sono in inglese:

% Synthetic calibration for GUI troubleshooting; no external files.
% Use saved code revision, explicit typed parameter, and a bounded result.
gxtxt_parameter_declare('gain', 'double', 'default', 1.0, ...
                       'min', 0.5, 'max', 3.0, ...
                       'description', 'Synthetic calibration multiplier');
ctx = gxtxt_context();
calibration = [1, 2, 3, 4];
gain = ctx.parameters.gain;
corrected = calibration .* gain;
assert(numel(corrected) == 4);
fprintf('O28_CALIBRATION_GAIN=%.2f\n', gain);
fprintf('O28_CALIBRATION_TOTAL=%.2f\n', sum(corrected));

gxtxt_parameter_declare dichiara al Runner il parametro gain: tipo double, valore predefinito 1.0, minimo 0.5, massimo 3.0. gxtxt_context() restituisce il contesto pubblico dell’invocazione e permette di leggere il valore convalidato. L’operatore .* applica il guadagno ai quattro elementi del vettore. assert verifica il numero di campioni; fprintf invia il risultato a stdout.

Il salvataggio registra la revisione del sorgente, ma non esegue il programma. L’avvio è una scelta separata nel Runner.

6. Interpretare gli errori di Validate review

Scegliere Run → Open Script Runner…. Il campo gain contiene inizialmente il valore dichiarato nello script. Prima di premere Run Job, utilizzare Validate review per individuare eventuali errori.

Inserendo testo dove è atteso un numero finito compare il messaggio Review needs attention: Enter a finite number.

Validate review rifiuta un valore testuale nel parametro numerico gain.
Figura 6 — Validate review rifiuta un valore testuale nel parametro numerico gain.

Un valore inferiore a 0.5 produce Value must be at least 0.5; uno superiore a 3.0 produce Value must be at most 3.0.

Con gain superiore al massimo, il Runner mostra il limite effettivo senza avviare il calcolo.
Figura 7 — Con gain superiore al massimo, il Runner mostra il limite effettivo senza avviare il calcolo.

I messaggi derivano dal controllo dei valori tipizzati. Validate review non crea un Job, anche quando la richiesta non è valida. Correggere prima il campo interessato e ripetere la verifica.

7. Utilizzare i tooltip per distinguere convalida ed esecuzione

Spostando il puntatore sul pulsante Validate review, appare una spiegazione: il comando controlla lo script, i parametri e le revisioni degli input senza sottoporre il programma all’esecuzione.

Tooltip del pulsante Validate review con testo descrittivo e sfondo opaco.
Figura 8 — Tooltip del pulsante Validate review con testo descrittivo e sfondo opaco.

I tooltip non sostituiscono gli errori del Runner: forniscono una descrizione dell’azione prima di eseguirla. Se un suggerimento non compare o disturba la lettura, i nomi dei controlli e le indicazioni di stato rimangono il riferimento principale. Nell’interfaccia illustrata i tooltip vengono disegnati con sfondo opaco.

8. Correggere il parametro e controllare la richiesta prima dell’avvio

Impostare gain = 1.5 e premere Validate review. La risposta diventa Review valid. No Job submitted; Run Job performs fresh admission checks.

Il Runner accetta gain = 1.5 e conferma che non è stato ancora sottomesso alcun Job.
Figura 9 — Il Runner accetta gain = 1.5 e conferma che non è stato ancora sottomesso alcun Job.

Questa frase merita attenzione: la richiesta è pronta ma il programma non è ancora stato eseguito. È possibile rivedere il sorgente, il valore del parametro e la Session prima di procedere.

9. Eseguire una sola volta e consultare il risultato vero

Premere Run Job una sola volta. Il programma passa al supervisore dei Job e, dopo il completamento, può essere ritrovato in Run → Script Jobs Manager… con stato COMPLETED e codice di uscita 0.

Lo storico identifica il Job scientifico terminato correttamente.
Figura 10 — Lo storico identifica il Job scientifico terminato correttamente.

Selezionare la riga, quindi Jobs → Open execution details. In Program output si leggono i risultati stampati realmente da GNU Octave:

O28_CALIBRATION_GAIN=1.50
O28_CALIBRATION_TOTAL=15.00
Program output mostra il risultato numerico del Job, distinto dal messaggio di convalida.
Figura 11 — Program output mostra il risultato numerico del Job, distinto dal messaggio di convalida.

Il vettore originale ha somma 10; con guadagno 1.5 la somma corretta diventa 15. Il risultato deriva da un’esecuzione reale della revisione salvata. In questo esempio non viene pubblicato nessun Dataset: lo stdout è un flusso del Job, non una tabella scientifica canonica.

10. Aprire e cercare nel manuale integrato con F1

Il tasto F1, o Help → Viewer manual / Debugger guide…, apre il manuale locale di Octave Script Workspace. Non serve cercare una copia online per consultarlo.

Manuale di Octave aperto nell'interfaccia GX-TXT.
Figura 12 — Manuale di Octave aperto nell’interfaccia GX-TXT.

Nel manuale utilizzare Ctrl+F, digitare una frase e scegliere Find next. Un risultato presente è segnalato da Found, mentre una ricerca senza risultati mostra Text not found.

Ricerca del comando Focus source nel manuale integrato.
Figura 13 — Ricerca del comando Focus source nel manuale integrato.

Lo zoom della documentazione dipende dal formato aperto. Nel manuale Markdown il comando View → Zoom in non risulta disponibile: è previsto per una guida HTML attiva. Non confondere questo controllo con la dimensione dei caratteri del codice Octave.

11. Navigare i menu principali senza utilizzare il mouse

Premere F10 mentre Octave Script Workspace è attivo. Il focus passa al menu File. Le frecce destra e sinistra permettono di passare tra i menu principali; Esc riporta il focus all’editor.

F10 rende accessibile dalla tastiera la barra dei menu dello Workspace.
Figura 14 — F10 rende accessibile dalla tastiera la barra dei menu dello Workspace.

Sono disponibili anche le scorciatoie dei comandi: Ctrl+F per Find, Ctrl+G per Go to line e F1 per la documentazione. Prima di usare una combinazione da tastiera su un sorgente modificabile, verificare quale widget ha il focus.

12. Ripristinare un layout affollato

Se la schermata contiene troppi pannelli o la disposizione è diventata scomoda, selezionare View → Reset editor layout. Il comando riporta i pannelli laterali alla disposizione di partenza.

Reset editor layout ripristina la vista con i pannelli laterali.
Figura 15 — Reset editor layout ripristina la vista con i pannelli laterali.

Per l’uso normale conviene poi tornare a View → Focus source / restore panes. È possibile nascondere Parameters e Version quando non servono e mantenere visibili soltanto le proprietà indispensabili. I pannelli restano recuperabili dallo stesso menu.

Layout focalizzato sul codice con Parameters e Version nascosti.
Figura 16 — Layout focalizzato sul codice con Parameters e Version nascosti.

Questi comandi modificano la presentazione, non la revisione dello script, la Session o lo storico delle esecuzioni.

13. Perché uno script non salvato non può essere eseguito

Se si apre File → New Script, si scrive codice e si prova immediatamente Run → Open Script Runner… senza aver registrato lo script, l’applicazione mostra un avviso che richiede di salvare o registrare esplicitamente il documento nell’ambito appropriato.

Avviso che richiede di registrare il sorgente prima di aprire il Runner.
Figura 17 — Avviso che richiede di registrare il sorgente prima di aprire il Runner.

Per questa procedura basta assegnare un identificativo, scegliere lo Scope corretto e usare File → Save nell’Octave Script Workspace. Non è necessario aprire altri Viewer. Il rifiuto evita di sottomettere un codice senza identità e revisione registrate.

Chiudendo una scheda con modifiche non salvate compare Unsaved source con Yes, No e Cancel.

Chiusura di una sorgente anonima modificata con le tre scelte esplicite.
Figura 18 — Chiusura di una sorgente anonima modificata con le tre scelte esplicite.

Yes richiede il salvataggio, No scarta soltanto le modifiche locali e Cancel mantiene aperta la scheda. La chiusura di una bozza anonima non deve eliminare uno script già registrato o un Job precedentemente concluso.

14. Risolvere problemi comuni senza perdere il lavoro

Alcuni comportamenti richiedono una distinzione fra codice, schede visibili e dati salvati:

  • Non trovo lo script dopo aver chiuso una scheda. Aprire Registered scripts e selezionare il documento per identificativo. In questa versione una scheda salvata può anche scomparire dalla barra in certe sequenze di navigazione, senza che sia stata cancellata la registrazione.
  • Ctrl+O sembra modificare il codice o lascia la scheda sporca dopo Cancel. Nella versione considerata il comportamento può verificarsi per il legame di tastiera con il controllo Text. Preferire File → Import .m…; se è stato inserito un ritorno a capo involontario, annullarlo con Ctrl+Z prima di salvare.
  • Il Runner segnala un valore errato. Controllare il tipo del parametro, i limiti dichiarati nello script e la differenza fra Validate review e Run Job.
  • Il calcolo sembra non produrre risultati. Controllare lo stato del Job e consultare separatamente Program output, Program stderr e Diagnostic log; non presumere che il solo messaggio di convalida rappresenti un’esecuzione.
  • Il codice è troppo stretto. Usare Focus source e nascondere i pannelli non necessari. Se il carattere è comunque piccolo, intervenire sulle impostazioni del display senza presumere che lo zoom della documentazione si applichi all’editor.
  • Un buffer appartiene a un’altra Session. Se compare Source owner changed, tornare alla Session proprietaria e riaprire il sorgente prima di salvare o rieseguire.
Ritorno al sorgente salvato, pulito e focalizzato dopo le prove di navigazione e le richieste non valide.
Figura 19 — Ritorno al sorgente salvato, pulito e focalizzato dopo le prove di navigazione e le richieste non valide.

Una procedura affidabile segue questa sequenza: verificare la Session, salvare la revisione, convalidare i parametri, eseguire una sola volta, leggere lo stato del Job e infine consultare l’output. Contrasto, tastiera e layout facilitano il lavoro, ma non sostituiscono i controlli sulla provenienza scientifica dei risultati.