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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.