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.