6.14.1 Funzioni

Il modulo curses definisce la seguente eccezione:

exception error: Eccezione sollevata quando una funzione di libreria curses restituisce un errore.

Note: Ogni volta che gli argomenti x o y di una funzione o metodo sono facoltativi, i loro valori predefiniti fanno riferimento alla posizione corrente del cursore. Ogni volta che attr è facoltativo, il suo valore predefinito è A_NORMAL.

Il modulo curses definisce le seguenti funzioni:

baudrate( ): Restituisce la velocità di output del terminale in bit al secondo. Sui software di emulazione di terminale avrà un alto valore fisso. Inclusa per ragioni storiche; nei primi tempi, veniva usata per scrivere cicli di output per ritardi di tempo, e occasionalmente per modificare le interfacce in fuzione della velocità di linea.

beep( ): Emette un breve suono di attenzione.

can_change_color( ): Restituisce vero o falso, a seconda del faccto che il programmatore possa o meno modificare i colori mostrati dal terminale.

cbreak( ): Entra in modalità cbreak. Nella modalità cbreak (a volte chiamata modalità ``rare'') il normale buffering di riga delle tty viene disattivato, ed i caratteri sono disponibili per essere letti uno per volta. Comunque, a differenza della modalità raw, i caratteri speciali (interruzione, uscita, sospensione, e controllo dil flusso) mantengono il loro effetto sul driver tty e sul programma chiamante. Chiamando prima raw() e quindi cbreak(), il terminale viene lasciato in modalità cbreak.

color_content( color_number): Restituisce l'intensità delle componenti di rosso, verde e blu (RGB) nel colore color_number, che deve essere compreso tra 0 e COLORS. Viene restituita una tupla di 3 elementi, contenente i valori di R, G, B per il colore dato, che sarà compreso tra 0 (nessun componente) e 1000 (massimo valore del singolo componente).

color_pair( color_number): Restituisce il valore dell'attributo utilizzato per mostrare il testo nel colore specificato. Questo valore d'attributo può venire combinato con A_STANDOUT, A_REVERSE, e con gli altri attributi A_*. pair_number() è la controparte di questa funzione.

curs_set( visibility): Imposta lo stato del cursore. visibility può venire impostato ai valori 0, 1 o 2, che indicano invisibile, normale, o molto visibile. Se il terminale supporta la visibilità richiesta, viene restituito lo stato precedente del cursore; altrimenti, viene sollevata un'eccezione. Su molti terminali, la modalità ``visibile'' consiste in una linea di sottolineatura (NdT: underline), e la modalità ``molto visibile'' consiste in un cursore a blocco.

def_prog_mode( ): Salva la modalità corrente del terminale come modalità ``programma'', la modalità impiegata quando il programma in esecuzione utilizza curses. (La sua controparte è la modalità ``shell'', impiegata quando il programma non utilizza curses.) Chiamate successive a reset_prog_mode() rispristineranno questa modalità.

def_shell_mode( ): Salva la modalità corrente del terminale come modalità ``shell'', la modalità impiegata quando il programma non utilizza curses. ( La sua controparte è la modalità ``programma'', impiegata quando il programma utilizza curses.) Chiamate successive a reset_shell_mode() rispristineranno questa modalità.

delay_output( ms): Inserisce una pausa di ms millisecondi nell'output.

doupdate( ): Aggiorna lo schermo fisico. La libreria curses mantiene due strutture dati, una rappresentante i contentuti dello schermo fisico corrente ed una lo schermo virtuale rappresentante il prossimo stato desiderato. La doupdate() aggiorna lo schermo fisico al corrispondente schermo virtuale.
Lo schermo virtuale può venire aggiornato da una chiamata a noutrefresh(), dopo che su una finestra sono state eseguite operazioni di scrittura come addstr(). La chiamata normale a refresh() è semplicemente noutrefresh() seguita da doupdate(); se dovete aggiornare finestre multiple, potete velocizzare le performance e forse ridurre l'instabilità dell'immagine dello schermo distribuendo chiamate a noutrefresh() su tutte le finestre, seguite da una singola doupdate().

echo( ): Entra nella modalità echo. Nella modalità echo, ogni carattere in input viene mostrato sullo schermo così come viene immesso.

endwin( ): Deinizializza la libreria, e reimposta il terminale allo stato normale.

erasechar( ): Restituisce il carattere di cancellazione corrente dell'utente. Nei sistemi operativi Unix questa è una proprietà della tty che controlla il programma curses, e non viene impostato dalla libreria curses.

filter( ): La procedura filter(), se usata, deve essere chiamata prima di initscr(). L'effetto è che, durante queste chiamate, LINES viene impostato a 1; le proprietà lear, cup, cud, cud1, cuu1, cuu, vpa vengono disabilitate; e la stringa home viene impostata al valore di cr. L'effetto è quello di confinare il cursore alla riga corrente, ed effettuare gli aggiornamenti dello schermo. Tutto questo può venire usato per abilitare l'editing di riga di un carattere alla volta, senza toccare il resto dello schermo.

flash( ): Fa lampeggiare lo schermo. Di fatto, lo modifica a reverse-video e lo riporta indietro in un breve intervallo. Alcune persone preferiscono questo genere di `campanello visibile' al segnale di attenzione udibile prodotto da beep().

flushinp( ): Svuota tutti i buffer di input. Questo fa perdere ogni carattere digitato dall'utente che non è ancora stato elaborato dal programma.

getmouse( ): Dopo che getch() ha restituito KEY_MOUSE per segnalare un evento del mouse, questo metodo dovrebbe venire chiamato per recuperare l'evento del mouse accodato, rappresentato come una tupla di 5 elementi (id, x, y, z, bstate). id è un valore ID usato per distinguere dispositivi multipli, e x, y, z sono le coordinate dell'evento (z al momento non viene usato). bstate è un valore intero i cui bit verranno impostati per indicare il tipo di evento, ed indicherà l'OR bit per bit di una o più di queste costanti, dove n è il numero del pulsante da 1 a 4: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

getsyx( ): Restitusce le coordinate correnti del cursore dello schermo virtuale in y e x. Se leaveok è vera al momento, allora viene restituito -1,-1.

getwin( file): Legge i dati relativi alla finestra immagazzinati in file da una precedente chiamata a putwin(). La procedura quindi crea ed inizializza una nuova finestra usando quei dati, restituendo il nuovo oggetto window.

has_colors( ): Restituisce vero se il terminale può mostrare i colori; altrimenti, restituisce falso.

has_ic( ): Restituisce vero se il terminale ha le proprietà di inserire e cancellare i caratteri. Questa funzione viene inclusa solamente per ragioni storiche, visto che tutti i moderni software di emulazione di terminale possiedono queste proprietà.

has_il( ): Restituisce vero se il terminale ha la proprietà di cancellare ed inserire righe, o può simularle usando le regioni scorrevoli. Questa funzione viene inclusa solamente per ragioni storiche, visto che tutti i moderni software di emulazione di terminale possiedono queste proprietà.

has_key( ch): Prende un valore chiave ch, e restituisce vero se il tipo di terminale corrente riconosce una chiave con quel valore.

halfdelay( tenths): Usato per la modalità half-delay, che è simile alla modalità cbreak per il fatto che i caratteri digitati dall'utente vengono immediatamente resi disponibili al programma. Comunque, dopo essere rimasto bloccato per tenths (NdT: decimi) di secondo, se non è stato digitato niente, viene sollevata un'eccezione. Il valore di tenths deve essere un numero nell'intervallo tra 1 e 255. Usate nocbreak() per abbandonare la modalità half-delay.

init_color( color_number, r, g, b): Modifica la definizione di un colore, prendendo il numero del colore da modificare seguito da tre valori RGB (per le quantità dei componenti rosso, verde e blu). Il valore di color_number deve essere compreso tra 0 e COLORS. Ciascun valore di r, g e b deve essere compreso tra 0 e 1000. Quando viene utilizzata la funzione init_color(), tutte le occorrenze di quel colore sullo schermo vengono immediatamente cambiate alla nuova definizione. Questa funzione non ha alcun effetto sulla maggior parte dei terminali; risulta attiva solo se can_change_color() restituisce 1.

init_pair( pair_number, fg, bg): Modifica la definizione di una coppia di colori. Prende tre argomenti: il numero della coppia di colori da modificare, il numero del colore in primo piano ed numero del colore di sfondo. Il valore di pair_number deve essere compreso tra 1 e COLOR_PAIRS - 1 (la coppia dei colori 0 è contornata in bianco e nero e non può essere modificata). Il valore degli argomenti fg e bg deve essere compreso tra 0 e COLORS. Se la coppia dei colori è stata inizializzata precedentemente, lo schermo viene aggiornato e tutte le occorrenze di quella coppia di colori vengono modificate alla nuova definizione.

initscr( ): Inizializza la libreria. Restituisce un WindowObject che rappresenta l'intero schermo. Note: Se si verifica un errore durante l'apertura del terminale, la libreria curses sottostante può causare l'uscita dall'interprete.

isendwin( ): Restituisce vero se è stata chiamata endwin() (di fatto, la libreria curses è stata deinizializzata).

keyname( k): Restituisce il nome del tasto numerato k. Il nome di un tasto che genera un carattere ASCII stampabile è il carattere del tasto. Il nome di una combinazione control-tasto è una stringa di due caratteri che consiste in un carattere di omissione seguito dal carattere ASCII stampabile corrispondente. Il nome di una combinazione alt-tasto (128-255) è una stringa che consiste nel prefisso `M-' seguito dal nome del carattere ASCII corrispondente.

killchar( ): Restituisce il carattere di kill di riga corrente dell'utente. Nei sistemi operativi Unix questa è una proprietà della tty che controlla il programma curses, e non viene impostato della libreria curses.

longname( ): Restituisce una stringa contenente il campo terminfo che descrive il terminale corrente. La lunghezza massima di una descrizione prolissa è di 128 caratteri. Viene definita solo dopo la chiamata a initscr().

meta( yes): Se yes viene impostato ad 1, permette l'input di caratteri a 8-bit. Se yes viene impostato a 0, ammette solamente caratteri a 7-bit.

mouseinterval( interval): Imposta il tempo massimo in millisecondi che possono passare fra gli eventi di pressione e rilascio, in modo che vengano interpretati come click, e restituisce il valore dell'intervallo precedente. Il valore predefinito è 200 msec, o un quinto di secondo.

mousemask( mousemask): Imposta la notifica degli eventi del mouse, e restituisce una tupla (availmask, oldmask). availmask indica quali tra gli eventi del mouse specificati possono venire riportati; in caso di completo fallimento restituisce 0. oldmask è il valore precedente della maschera degli eventi del mouse della finesta specificata. Se questa funzione non viene mai chiamata, nessun evento del mouse viene mai notificato.

napms( ms): Rimane in attesa per ms millisecondi.

newpad( nlines, ncols): Crea e restituisce un puntatore ad una nuova struttura dati pad con il dato numero di righe e colonne. Viene restituito un pad come oggetto finestra.
Un pad è simile ad una finestra, con l'eccezione che non viene ristretto dalla dimensione dello schermo e non viene necessariamente associato ad una particolare parte dello schermo. I pad possono venire usati quando c'è bisogno di una finestra grande, e solo una parte della finestra deve trovarsi sullo schermo in un dato momento. L'aggiornamento automatico dei pad (come dallo scorrimento o dall'echo dell'input) non viene messo in atto. I metodi refresh() e noutrefresh() di un pad richiedono 6 argomenti per specificare la parte del pad da mostrare, e la locazione sullo schermo da usare per il display. Gli argomenti sono pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; gli argomenti p si riferiscono all'angolo in alto a sinistra della regione del pad che deve essere mostrata, e gli argomenti s definiscono il ritaglio sullo schermo nel quale deve essere mostrata la regione del pad.

newwin( [nlines, ncols,] begin_y, begin_x): Restituisce una nuova finestra, il cui angolo in alto a sinistra si trova a (begin_y, begin_x), e la cui altezza/larghezza è nlines/ncols.
In modo predefinito, la finestra si estenderà dalla posizione specificata fino all'angolo in basso a destra dello schermo.

nl( ): Entra nella modalità newline. Questa modalità traduce il tasto invio in un fine riga durante l'input, e traduce il carattere di fine riga in caratteri di invio e line-feed durante l'output. La modalità newline è inizialmente attiva.

nocbreak( ): Abbandona la modalità cbreak. Ritorna alla modalità normale ``cooked'' con il buffering di riga.

noecho( ): Abbandona la modalità echo. L'echo dei caratteri in input viene disattivato.

nonl( ): Abbandona la modalità newline. Disabilita la traduzione di invio in fine riga durante l'input, e disabilita la traduzione a basso livello del fine riga in line-feed/invio durante l'output (ma questa non cambia il comportamento di addch('\n'), che simula sempre l'equivalente dei caratteri di invio e line-feed sullo schermo virtuale). Con la traduzione disattivata, curses può saltuariamente accelerare un po' lo spostamento verticale; inoltre, sarà in grado di rilevare il tasto di invio in input.

noqiflush( ): Quando viene utilizzata la procedura noqiflush, non sarà effettuato il normale svuotamento delle code di input e output associate ai caratteri NTR, QUIT e SUSP. Potreste voler chiamare noqiflush() in un gestore dei segnali dopo la sua uscita, se volete che l'output continui come se l'interruzione non fosse avvenuta.

noraw( ): Abbandona la modalità raw. Ritorna alla modalità normale ``cooked'' con il buffering di riga.

pair_content( pair_number): Restituisce una tupla (fg, bg) contenente i colori per la coppia di colore richesta. Il valore di pair_number deve trovarsi fra 0 e COLOR_PAIRS - 1.

pair_number( attr): Restituisce il numero della coppia di colore impostata dal valore attributo attr. color_pair() è la controparte di questa funzione.

putp( string): Equivalente a tputs(str, 1, putchar); emette il valore di una specifica proprietà terminfo per il terminale corrente. Notate che l'ouput di putp viene sempre diretto allo standard output.

qiflush( [flag]): Se flag è False, l'effetto è lo stesso di chiamare noqiflush(). Se flag è True, o nessun argomento viene passato, le code verranno svuotate alla lettura di questi caratteri di controllo.

raw( ): Entra nella modalità raw. Nella modalità raw, il normale buffering di riga e l'elaborazione dei caratteri di interruzione, terminazione, sospensione, e gestione del flusso, vengono disabilitati; i caratteri vengono presentati alle funzioni di input di curses uno alla volta.

reset_prog_mode( ): Ripristina la modalità ``program'' del terminale, come salvata precedentemente dalla funzione def_prog_mode().

reset_shell_mode( ): Ripristina la modalità ``shell'' del terminale, come salvata precedentemente dalla funzione def_shell_mode().

setsyx( y, x): Imposta il cursone dello schermo virtule a y, x. Se y ed x valgono entrambi -1, viene impostata la leaveok.

setupterm( [termstr, fd]): Inizializza il terminale. termstr è una stringa che fornisce il nome del terminale; se omesso, verrà utilizzato il valore della variabile d'ambiente TERM. fd è il descrittore di file al quale verrà inviata ogni sequenza di inizializzazione; se non fornito, verrà usato il descritttore di file di sys.stdout.

start_color( ): Deve essere chiamata se il programmatore vuole usare i colori, e prima che venga chiamata ogni altra procedura di manipolazione dei colori. È buona norma chiamare questa procedura subito dopo initscr().
start_color() inizializza otto colori di base (nero, rosso, verde, giallo, blu, magenta, ciano e bianco), e due variabili globali nel modulo curses, COLORS e COLOR_PAIRS, contenenti rispettivamente il massimo numero di colori e coppie colore che il terminale è in grado di supportare. Inoltre ripristina i colori sul terminale ai valori che possedevano al momento della sua accensione.

termattrs( ): Restituisce un OR logico di tutti gli attributi video supportati dal terminale. Questa informazione è utile quando un programma curses necessita di un controllo completo sull'aspetto dello schermo.

termname( ): Restituisce il valore della variabile d'ambiente TERM, troncata a 14 caratteri.

tigetflag( capname): Restituisce il valore della proprietà booleana corrispondente al nome della proprietà terminfo capname. Il valore -1 viene restituito nel caso in cui capname non sia una proprietà booleana, o 0 se è cancellata o assente dalla descrizione del terminale.

tigetnum( capname): Restituisce il valore della proprietà numerica corrispondente al nome della proprietà terminfo capname. Il valore -2 viene restituito nel caso in cui capname non sia una proprietà numerica, o -1 se è cancellata o assente dalla descrizione del terminale.

tigetstr( capname): Restituisce il valore della proprietà stringa corrispondente al nome della proprietà terminfo capname. Viene restituito None nel caso in cui capname non sia una capability stringa, o se è cancellata o assente dalla descrizione del terminale.

tparm( str[,...]): Istanzia la stringa str con i parametri specificati, dove str dovrebbe essere una stringa parametrizzata, ottenuta dal database terminfo. Per esempio tparm(tigetstr("cup"), 5, 3) potrebbe risultare come '\033[6;4H', il risultato esatto dipende dal tipo del terminale.

typeahead( fd): Specifica che il descrittore di file fd deve venire usato per il controllo typeahead. Se fd ha valore -1, allora non viene effettuato alcun controllo typeahead.
La libreria curses effettua ``l'ottimizzazione line-breakout'' cercando periodicamente il typeahead mentre viene aggiornato lo schermo. Se viene trovato dell'input, ed esso proviene da una tty, l'aggiornamento corrente viene posticipato fino a che non venga chiamata di nuovo una refresh o una doupdate, permettendo una risposta più rapida a comandi digitati in anticipo. Questa funzione permette di specificare un differente descrittore di file per il controllo typeahead.

unctrl( ch): Restituisce una stringa che è la rappresentazione stampabile del carattere ch. I caratteri di controllo vengono mostrati come un carattere di omissione seguito dal carattere, per esempio come accde con ^C. I caratteri stampabili vengono lasciati come tali.

ungetch( ch): Accoda ch così da restituirlo alla prossima getch(). Note: Solo un ch può venire accodato prima che venga chiamata getch().

ungetmouse( id, x, y, z, bstate): Accoda un evento KEY_MOUSE sulla coda dell'input, associandogli il dato di stato fornito.

use_env( flag): Se usata, questa funzione dovrebbe essere chiamata prima di initscr() o newterm(). Quando flag è falso, verranno utilizzati i valori di righe e colonne specificati nel database terminfo, anche se sono impostate le variabili di ambiente LINES e COLUMNS (usate in modo predefinito), o se curses viene eseguito in una finestra (nel qual caso il comportamento predefinito utilizzerebbe la dimensione della finestra se LINES e COLUMNS non fossere impostate).

use_default_colors( ): Permette l'utilizzo dei colori predefiniti sui terminali che supportano questa possibilità. Usate questo metodo per supportare la trasperenza nella vostra applicazione. Il colore predefinito viene assegnato al colore numero -1. Dopo aver chiamato questa funzione, init_pair(x, curses.COLOR_RED, -1) inizializza, ad esempio, la coppia colore x ad un colore di primo piano rosso sullo sfondo predefinito.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.