GX-TXT Python Script Workspace: aiuto, accessibilità e risoluzione dei problemi
Il Python Script Workspace integra la modifica dei sorgenti, i comandi per i progetti e l’accesso alle funzioni di esecuzione e debugging. Un uso affidabile dell’interfaccia richiede di sapere dove trovare il manuale, come cercare un comando, come recuperare spazio per il codice e come distinguere un problema di interfaccia da una modifica del sorgente o dello stato scientifico.
Questa guida utilizza i nomi dei controlli esattamente come compaiono nell’interfaccia inglese. Le operazioni di navigazione, ricerca e presentazione non equivalgono a salvare, eseguire uno Script, avviare un Job o pubblicare un Dataset.
1. Riconoscere i tre livelli di lavoro
Nella stessa finestra possono comparire il sorgente Python, i pannelli del progetto e i comandi collegati alla Session. Editor, Script registrato, Job eseguito e Dataset pubblicato sono oggetti distinti: modificare una vista non crea automaticamente nessuno degli altri. Per una prima verifica, aprire uno Script già salvato e controllare che non compaia un indicatore di modifiche non registrate.
2. I tre punti di accesso all’assistenza
Il menu Help del Python Script Workspace contiene Script Bridge help, Viewer manual / Debugger guide… e About…. Il primo presenta le API del client Python; il secondo apre la documentazione consultabile; il terzo mostra informazioni identificative sul modulo. Non confondere questi strumenti con un comando che installa dipendenze o avvia un’analisi.
3. Aprire il menu Help
Selezionare Help nella barra superiore dell’editor. Le voci restano disponibili anche quando il sorgente è in sola lettura o non ha modifiche in sospeso. Questa è la via visiva alternativa alla scorciatoia F1 per consultare la guida del Viewer.

4. Richiamare il manuale con F1
Dare il focus alla finestra Python e premere F1, oppure scegliere Help → Viewer manual / Debugger guide…. Si apre Python Script — User Manual, una finestra separata che può rimanere visibile mentre si lavora sull’editor. Per chiuderla usare Close; il codice aperto non viene modificato.

5. Manual e Interactive Tutorial
La finestra della guida contiene le schede Manual e Interactive Tutorial, oltre ai controlli di navigazione e ricerca. La scheda Manual presenta il testo di riferimento; la scheda Interactive Tutorial ospita percorsi interattivi quando disponibili per il modulo. La disponibilità di una scheda non implica che ogni esercizio citato da documentazione storica sia operativo nella versione installata.
6. Cercare nel manuale
Digitare una parola o un’espressione nel campo Find e premere Find next o Invio. Il testo trovato viene evidenziato, e lo stato della finestra indica il risultato. Per esempio, cercando F10 focuses si raggiunge direttamente il paragrafo dedicato alla navigazione da tastiera.

7. Quando una parola non si trova
Se non esiste alcuna corrispondenza, il manuale segnala Text not found. e rimuove l’evidenziazione precedente. Provare una parola più breve, una diversa denominazione inglese o una sezione vicina. Questo messaggio non indica un errore del programma né un problema del sorgente Python.
8. Zoom del manuale: distinguere testo e HTML
Nel menu View del manuale compaiono Zoom in, Zoom out e Actual size (100%). Il servizio di zoom è destinato alle pagine HTML e ai tutorial che utilizzano il relativo visualizzatore. Sul testo del manuale mostrato come contenuto Markdown, il comando non costituisce un ingrandimento del font dell’editor Python: non assumere che selezionare Zoom in modifichi i caratteri del codice. Per l’ingrandimento dei caratteri occorre distinguere il visualizzatore della documentazione, le preferenze dell’interfaccia e le impostazioni dei font del desktop.
9. Aprire Script Bridge help
Con Help → Script Bridge help si apre una finestra che elenca le funzioni del client pubblico, con un esempio di importazione da gxtxt. È un riferimento rapido per comprendere i nomi delle chiamate, non un editor alternativo e non un pulsante di esecuzione.

10. Le funzioni pubbliche richiamate nell’aiuto
L’interfaccia documenta gxtxt_context() per il contesto dell’esecuzione, gxtxt_api_list() per l’elenco delle API dichiarate, gxtxt_api_has(api_id) per verificare la presenza di un’API, gxtxt_api_describe(api_id) per ispezionarne il contratto, gxtxt_api_require(declaration) per richiederne una disponibilità esplicita e gxtxt_api_call(api_id, operation, positional_args) per invocarne un’operazione pubblica.
Prima di chiamare una funzione, controllare l’identificativo completo e la versione del contratto, i parametri e i valori restituiti. L’elenco dei nomi non sostituisce la descrizione dell’API specifica.
11. Esempio informativo senza pubblicazione
Questo esempio è destinato a uno Script eseguito nel contesto appropriato, non alla finestra Help. Le chiamate consultano informazioni disponibili: non pubblicano un Dataset.
# Inspect public client information in the current execution context.
from gxtxt import gxtxt_api_list, gxtxt_context
context = gxtxt_context()
available_apis = gxtxt_api_list()
print("Public API entries:", len(available_apis))
print("Context type:", type(context).__name__)
Il Bridge non isola automaticamente il codice Python dalle risorse del sistema. Verificare sempre la provenienza di uno Script prima di eseguirlo.
12. Cercare nel sorgente Python
Per trovare una variabile o una funzione, selezionare l’editor e premere Ctrl+F, quindi inserire il termine cercato. F3 passa alla corrispondenza successiva e Shift+F3 a quella precedente. Nell’esempio viene individuato measurements: il testo viene evidenziato, ma il sorgente salvato resta invariato.

13. Ricerca nel codice e ricerca nella documentazione
Il campo Find del Viewer e quello del manuale sono separati. Se la ricerca sembra non funzionare, verificare quale finestra ha il focus e se si sta lavorando in una nota Markdown anziché nel codice Python. Un risultato assente in un campo non dimostra che la parola manchi dall’intero progetto.
14. Spostarsi a una riga e leggere l’indicatore
Con Ctrl+G si apre Go to line…. Inserire un numero intero positivo per portare il cursore alla riga fisica corrispondente; Cancel chiude senza spostamenti. I numeri nel margine appartengono al sorgente corrente, non necessariamente al file di una scheda storica o di un helper diverso.
15. Navigazione da tastiera essenziale
| Tasto o combinazione | Azione |
|---|---|
| F1 | Apre il manuale del Viewer |
| F10 | Porta alla navigazione dei menu |
| Alt+F, Alt+E, Alt+V, Alt+H | Accede ai relativi menu, secondo il focus |
| Ctrl+F | Cerca nel contesto di modifica corrente |
| F3 / Shift+F3 | Risultato successivo / precedente |
| Ctrl+G | Go to line… |
| Ctrl+S | Salva il sorgente modificato |
| Escape | Chiude o lascia il controllo di ricerca, secondo il contesto |
I comandi vengono gestiti dal widget che possiede il focus. Evitare di premere scorciatoie di modifica quando è attiva una finestra di dialogo o una scheda in sola lettura.
16. Ritrovare i comandi di layout nel menu View
Il menu View include Script Explorer / Registered scripts, GX-TXT Bridge Snippets, Focus source / restore panes e Reset editor layout. Sono strumenti di presentazione: aprono, chiudono o riposizionano componenti della finestra. È opportuno esaminare il menu prima di presumere che un pannello mancante sia stato eliminato dal progetto.

17. Ripristinare un layout disordinato
Se l’editor appare troppo stretto o alcuni pannelli non sono più facilmente raggiungibili, selezionare View → Reset editor layout. Il comando ripristina il layout laterale con Explorer e Snippets e le proporzioni principali dei divisori. Le righe opzionali Script properties, Parameters, Version e Additional required APIs conservano preferenze indipendenti: Reset non implica che vengano tutte mostrate.

18. Dedicare più spazio al codice
Quando non servono strumenti laterali, selezionare View → Focus source / restore panes. Il comando nasconde temporaneamente i pannelli laterali e amplia il sorgente. Usarlo nuovamente per ripristinare i pannelli precedentemente memorizzati. Questa operazione non esegue Python e non salva uno Script.

19. Riattivare un singolo pannello
Se serve soltanto l’elenco dei file, attivare Script Explorer / Registered scripts; se occorrono i riferimenti rapidi, attivare GX-TXT Bridge Snippets. Tenere gli altri pannelli chiusi durante la modifica del codice evita di comprimere inutilmente l’area di lavoro. Aprire Debugger, Call Stack o Variables / Locals solo quando si segue effettivamente un Job di debugging.
20. Contrasto reale del sorgente
Il tema High Contrast Dark applica all’area di codice un fondo nero e testo principale bianco, con evidenziazioni sintattiche specifiche. Le barre, i menu e alcuni dialoghi Tk/ttk possono rimanere chiari: il tema del sorgente non ricolora necessariamente tutta la GUI. In Configuration → Appearance, la preferenza Source color theme governa la tavolozza del codice.
21. Dimensione dei caratteri e leggibilità
L’editor utilizza un font monospaziato della piattaforma. Prima di aumentare il numero di pannelli o ridurre la finestra, verificare se le righe, il cursore e le parentesi restano leggibili. Un comando di zoom presente nel manuale non è una prova che lo stesso comando ingrandisca il sorgente. Se servono caratteri più grandi, considerare le impostazioni font del desktop e controllare il risultato reale, senza confonderle con la palette di colore del codice.
22. Quando una voce è disabilitata
Una voce grigia può dipendere da tipo di documento, assenza di una Session, stato del debugger, selezione corrente o scheda storica in sola lettura. Ad esempio, i comandi relativi alle Notes possono richiedere una nota aperta; alcune azioni del Runner richiedono una revisione Script registrata; i comandi di esecuzione diventano limitati con sorgenti modificati o riferimenti obsoleti. Verificare prima il contesto anziché cercare di forzare il controllo.
23. Modifiche non salvate: non perdere il sorgente
Un buffer modificato non coincide con la revisione presente nel Registry. Prima di chiudere una scheda, distinguere Save, No e Cancel nel dialogo per il sorgente non salvato. No scarta il buffer corrente; Cancel annulla la chiusura. In presenza di un Project multifile, controllare quale scheda è sporca e se occorre Save All. Una vista storica aperta da un Job può invece essere intenzionalmente read_only.
24. Problemi di Save, scope e revisione
Se il salvataggio non riesce, controllare User/Session scope, identificativo, tipo di sorgente, campi obbligatori e revisione che si sta modificando. Due Script con lo stesso nome breve ma proprietari differenti possono essere distinti; una revisione registrata non si sostituisce implicitamente a un’altra. Conservare il testo modificato prima di tentare una nuova registrazione o una copia.
25. Problemi di Run e parametri
Aprire Script Runner non crea un Job: prima controllare lo Script salvato, il contesto Session e il riepilogo di Validate review. I parametri dichiarati nel codice hanno tipi, vincoli e valori di default; un Dataset di parametri può appartenere a una revisione differente. Un errore di validazione non va aggirato eseguendo uno Script non controllato.
26. Dataset e output: verificare cosa è stato creato
Il completamento di un Job e la presenza di testo su stdout non dimostrano che esista un Dataset scientifico. Distinguere fra stdout/stderr, documenti testuali pubblicati e Dataset numerici con schema, unità e provenienza. Se un input Dataset non viene accettato, controllare il namespace, l’identificativo e la revisione selezionata, quindi ripetere la validazione prima dell’esecuzione.
27. Debugging e problemi ricorrenti
Breakpoint, Pause, Step Into/Over/Out e Stop dipendono dallo stato dell’esecuzione nativa. Le condizioni COMPLETED, FAILED e CANCELLED non sono intercambiabili. Per un’eccezione Python leggere la traccia e il numero di riga in Program stderr; per diagnosi del sistema distinguere il log diagnostico; per uno Script eseguito in passato consultare la copia immutabile associata al Job. Evitare modifiche del sorgente durante una Session di debug in pausa.
28. Sequenza pratica di recupero
Se un comando non produce il risultato atteso, controllare prima il focus, poi la scheda attiva, il contenuto non salvato, il tipo di Session e lo stato del Job. Per l’interfaccia usare Help/F1, Find e View; per l’esecuzione aprire il Runner e convalidare i dati; per l’analisi di un risultato esaminare Job Details e la pubblicazione canonica. Eventuali istruzioni storiche su Viewer separati non costituiscono una procedura verificata per questa versione.
Terminata la consultazione, chiudere le finestre di aiuto non necessarie e tornare al sorgente in modalità High Contrast Dark con spazio di modifica ampio.
