GTK Tutorial <author>Ian Main <tt><htmlurl url="mailto:imain@gtk.org" name="<imain@gtk.org>"></tt>, Tony Gale <tt><htmlurl url="mailto:gale@gtk.org" name="<gale@gtk.org>"></tt> <date>April 6th, 1998 - Traduzione aggiornata al 1 Maggio 1998 <abstract>Tradotto da Michel Morelli, <tt><htmlurl url="mailto:ziobudda@chiara.dei.unipd.it" name="ziobudda@chiara.dei.unipd.it"></tt>, Daniele Canazza, <tt><htmlurl url="mailto:dcanazz@tin.it" name="dcanazz@tin.it"></tt> e Antonio Schifano, <tt><htmlurl url="mailto:schifano@cli.di.unipi.it" name="schifano@cli.di.unipi.it"></tt> </abstract>  <sect>Introduzione  GTK (GIMP Toolkit) è stato orginariamente sviluppato come toolkit per il programma GIMP (General Image Manipulation Program). GTK è costruito sulla base del kit di disegno di GIMP, il GDK (GIMP Drawing Kit) il quale è costruito a sua volta attorno alle funzioni della Xlib. E' chiamato ``toolkit di GIMP'' perché era inizialmente scritto per sviluppare GIMP, ma ora viene utilizzato nello sviluppo di molti progetti software ``free''. Gli autori sono <itemize> <item> Peter Mattis <tt><htmlurl url="mailto:petm@xcf.berkeley.edu" name="petm@xcf.berkeley.edu"></tt> <item> Spencer Kimball <tt><htmlurl url="mailto:spencer@xcf.berkeley.edu" name="spencer@xcf.berkeley.edu"></tt> <item> Josh MacDonald <tt><htmlurl url="mailto:jmacd@xcf.berkeley.edu" name="jmacd@xcf.berkeley.edu"></tt> </itemize> GTK è essenzialmente una API (application programmers interface) orientata agli oggetti. Anche se scritto completamente in C, è implementato usando l'idea delle classi e delle funzioni di callback (puntatori a funzioni). C'è anche una terza componente chiamata glib che contiene una serie di implementazioni differenti di alcune chiamate di funzioni standard e anche alcune funzioni aggiuntive, per esempio per la manipolazione delle liste collegate. Le funzioni sostitutive sono usate per migliorare la portabilità di GTK. Alcune delle funzioni implementate qui non sono disponibili o non sono standard, altre sono uniche come g_strerror(). Altre contengono miglioramenti alle stesse della libc come g_malloc che ha delle utility di debugging migliorate. Questo tutorial è un tentativo di documentare il meglio possibile la libreria gtk e non pretende di essere completo. Questo tutorial suppone una buona conoscenza del linugaggio C e di come creare programmi in C. Saranno facilitati i lettori che hanno una precedente esperienza nella programmazione in X. Se il GTK è il primo insieme di widget che studiate, vi prego di dirmi come avete trovato questo tutorial e che tipo di problemi avete avuto. Notate che c'è anche una versione per il C++ della libreria GTK (chiamata GTK--), quindi se preferite utilizzare questo linguaggio al posto del C potreste cercare questa versione al posto della GTK normale. Ci sono poi un ``wrapper'' Objective C e un collegamento a Guile, ma non ne seguo l'evoluzione. Mi farebbe molto piacere conoscere qualsiasi problema che abbiate avuto nell'imparare il GTK da questo documento e apprezzerei anche critiche sul come migliorarlo.  <sect>Iniziamo  La prima cosa da fare è certamente quella di scaricare il GTK e installarlo. Potete prendere l'ultima versione dal sito ftp.gtk.org in /pub/gtk. Un'altra possibile sorgente di informazioni è il sito <htmlurl url="http://www.gtk.org/" name="http://www.gtk.org/">. GTK usa il comando GNU autoconf per autoconfigurarsi. Una volta estratti i file dall'archivio tar, eseguite configure --help per vedere una lista delle opzioni del comando configure. Per iniziare la nostra introduzione a GTK, cominceremo con il più semplice programma possibile. Questo programma crea una finestra con dimensioni (in pixel) di 200x200 e l'unica possibilità di uscita è di ucciderlo usando la shell o il Window Manager. <tscreen><verb> #include <gtk/gtk.h> int main (int argc, char *argv[]) { GtkWidget *window; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen> Tutti i programmi GTK includeranno sicuramente <gtk/gtk.h> in cui vengono dichiarate le variabili, le funzioni, le strutture, etc. che saranno usate nella tua applicazione GTK. La linea seguente: <tscreen><verb> gtk_init (&argc, &argv); </verb></tscreen> invoca la funzione gtk_init(gint *argc, gchar ***argv) che sarà usata in tutte le applicazioni GTK. Questa funzione sistema alcune cose al posto nostro, come la visuale predefinita e la mappa dei colori, e procede poi chiamando gdk_init(gint *argc, gchar ***argv). Questa funzione inizializza la libreria per l'uso, setta il gestore predefinito dei segnali e guarda negli argomenti, passati via linea di comando alla vostra applicazione, alla ricerca di uno di questi argomenti: <itemize> <item> <tt/--display/ <item> <tt/--debug-level/ <item> <tt/--no-xshm/ <item> <tt/--sync/ <item> <tt/--show-events/ <item> <tt/--no-show-events/ </itemize> Rimuove poi questi argomenti dalla lista degli argomenti passati, lasciando quelli non riconosciuti a disposizione della vostra applicazione che potrà tenerne conto o ignorarli. In questo modo si crea un set di argomenti standard accettato da tutte le applicazioni GTK. Le seguenti 2 linee di codice creano e mostrano la finestra. <tscreen><verb> window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_widget_show (window); </verb></tscreen> L'argomento GTK_WINDOW_TOPLEVEL specifica che noi vogliamo che la nostra finestra si sottometta alle decorazioni del windows manager e alla posizione che quest'ultimo indicherà. Invece di creare una finestra avente dimensioni 0x0, la dimensione di una finestra senza figli (altri widget, come i bottoni, etc) è predefinita a 200x200 così che si possa manipolarla. La funzione gtk_widget_show() fa sì che GTK sappia che abbiamo finito di settare gli attributi di questo widget e che quindi quest'ultimo può essere visualizzato. L'ultima linea ci fa entrare nel ciclo principale del GTK. <tscreen><verb> gtk_main (); </verb></tscreen> gtk_main() è un'altra chiamata che vedrete in tutte le applicazioni GTK. Quando il controllo raggiunge questo punto, l'applicazione si metterà a dormire aspettando che si verifichino eventi di X (come la pressione di un bottone o di un tasto), timeout o notifiche di Input/Output dai file Nel nostro esempio, comunque, tutti gli eventi vengono ignorati.  <sect1>Hello World in GTK  Ok, ora un programma con un widget (un bottone). E' il classico ``Hello World'' alla GTK. <tscreen><verb> /* helloworld.c */ #include <gtk/gtk.h> /* E' una funzione di ritorno (callback). Gli argomenti passati sono ignorati in questo * esempio. * Piu' informazioni sulle callback in seguito. */ void hello (GtkWidget *widget, gpointer data) { g_print ("Hello World\n"); } gint delete_event(GtkWidget *widget, gpointer data) { g_print ("delete event occured\n"); /* Se si dà FALSE al gestore del segnale ``delete_event'', GTK emettera' il segnale * ``destroy''. Fornire TRUE significa non volere che la finestra sia distrutta. * Questo e' utile per far uscire delle finestre di dialogo del tipo: * 'sei sicuro di voler uscire ?' * Cambia TRUE in FALSE e la finestra principale sara' distrutta con un "delete_event" */ return (TRUE); } /* Un'altra callback */ void destroy (GtkWidget *widget, gpointer data) { gtk_main_quit (); } int main (int argc, char *argv[]) { /* GtkWidget e' il tipo di dato per i Widget */ GtkWidget *window; GtkWidget *button; /* Questa e' una chiamata presente in tutte le applicazioni GTK. Gli argomenti della linea di comando vengono scorsi e restituiti alla applicazione */ gtk_init (&argc, &argv); /* Crea una nuova finestra */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); /* Quando alla finestra viene passato il segnale ``delete_event'' (questo * segnale viene passato Windows Manager di solito con l'opzione 'close' * o con la barra del titolo (title bar)) noi chiediamo che la funzione * delete_event() (definita sopra) venga invocata. * Il dato passato come argomento alla funzione di ritorno é NULL * ed é ignorato dalla funzione stessa. */ gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (delete_event), NULL); /* Qui connettiamo l'evento ``destroy'' al gestore del segnale. * Questo evento accade quando noi chiamimo la funzione gtk_widget_destroy() * sulla finestra o se ritorniamo FALSE dalla callback ``delete_event''. */ gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (destroy), NULL); /* Setta il bordo interno della finestra */ gtk_container_border_width (GTK_CONTAINER (window), 10); /* Crea un nuovo bottone avente etichetta (label) uguale a ``Hello World'' */ button = gtk_button_new_with_label ("Hello World"); /* Quando il bottone riceve il segnale ``clicked'', invochera' la funzione * hello() passando NULL come argomento della funzione. La funzione * hello() é definita sopra. */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (hello), NULL); /* Questo farà sì che la finestra venga distrutta dalla chiamata * gtk_widget_destroy(window) quando il bottone verrà premuto. Ancora, * questo segnale (``destroy'') puo' arrivare da qui o dal windows * manager */ gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy), GTK_OBJECT (window)); /* Questo inserisce il bottone nella finestra * (un contenitore GTK) */ gtk_container_add (GTK_CONTAINER (window), button); /* Il passo finale é il mostrare questo nuovo widget appena creato */ gtk_widget_show (button); /* e la finestra */ gtk_widget_show (window); /* Tutte le applicazioni GTK devono avere la funzione gtk_main(). * Il controllo finisce qui e attende un evento (come la pressione * di un tasto o l'evento di un mouse). */ gtk_main (); return 0; } </verb></tscreen>  <sect1>Compilare hello World  Per compilare si utilizza : <tscreen><verb> gcc -Wall -g helloworld.c -o hello_world `gtk-config --cflags` \ `gtk-config --libs` </verb></tscreen> (N.d.T.: se lanciato da linea di comando, il precedente comando di compilazione va messo su di una unica linea eliminando il backslash) In questo modo, si usa il progamma <tt>gtk-config</>, che viene distribuito con gtk. Questo programma 'sa' che opzioni di compilatore sono necessarie per compilare i programmi che usano gtk. <tt>gtk-config --cflags</> dà come risultato una lista di directory in cui i file di include devono essere cercati, e <tt>gtk-config --libs</> fornisce invece la lista delle librerie che devono essere linkate con le directory in cui devono essere cercate. Le librerie che normalmente vengono linkate sono: <itemize> <item> la libreria glib (-lglib), contiene varie funzioni, ma solo g_print() é usato in questo esempio. GTK si appoggia a questa libreria, quindi essa viene sempre, comunque, linkata. Vedi comunque la sezione sulla <ref id="sec_glib" name="glib"> per altri dettagli. <item>La libreria GDK (-lgdk), la copertura della X11. <item>La libreria GTK (-lgtk), la libreria dei widget, basata sulla GDK. <item>La libreria Xlib(-lX11) la quale è usata dalla GDK. <item>La libreria Xext(-lXext). Questa contiene il codice per le pixmap a memoria condivisa e altre estensioni di X. <item>La libreria matematica (-lm). Questa é usata dalla GTK per vari scopi. </itemize>  <sect1>Teoria dei segnali e delle funzioni di ritorno (callback) Prima di guardare in dettaglio ``Hello World'', parleremo un po' degli eventi e delle funzioni di ritorno. GTK è un toolkit guidato dagli eventi, il che significa che se ne starà a dorimire in gtk_main finché non succede un evento ed il controllo viene passato alla funzione appropriata. Questo passaggio di controllo è basato sull'idea dei segnali. Quando si ha un evento, come la pressione di un bottone del mouse, verrà emesso il segnale appropriato, per esempio dal widget che é stato premuto. Questo è il modo in cui GTK fa molto del suo utile lavoro. Per far sì che un bottone esegua una azione, prepareremo un gestore del segnale che catturi questi segnali e chiami la funzione corretta. Questo viene fatto usando una funzione del tipo: <tscreen><verb> gint gtk_signal_connect (GtkObject *object, gchar *name, GtkSignalFunc func, gpointer func_data); </verb></tscreen> in cui il primo argomento è il widget che emetterà il segnale, il secondo è il nome del segnale che si vuole catturare, il terzo è la funzione che verrà invocata quando il segnale sarà catturato e il quarto è il dato che potrà essere passato a questa funzione. La funzione specificata come terzo argomento è chiamata ``funzione di ritorno (callback)'', e dovrebbe essere della forma: <tscreen><verb> void callback_func(GtkWidget *widget, gpointer *callback_data); </verb></tscreen> Dove il primo argomento sarà un puntatore al widget che emette il segnale e il secondo un puntatore al dato passato come ultimo argomento della funzione gtk_signal_connect() come descritto sopra. Un'altra chiamata usata nell'esempio Hello World è: <tscreen><verb> gint gtk_signal_connect_object (GtkObject *object, gchar *name, GtkSignalFunc func, GtkObject *slot_object); </verb></tscreen> gtk_signal_connect_object() è uguale a gtk_signal_connect() eccetto che la funzione di callback usa solo un argomento, un puntatore ad un'oggetto GTK. Così quando si usa questa funzione per connettere i segnali, la callback dovrebbe essere della forma : <tscreen><verb> void callback_func (GtkObject *object); </verb></tscreen> dove object è normalmente un widget. Generalmente, non si assegna una callback per gtk_signal_connect_object. Queste sono invocate, usualmente, per chiamare una funzione GTK che accetta un widget singolo o un oggetto come argomento, come nel caso dell'esempio Hello World. Lo scopo di avere due funzioni per connettere i segnali è semplicemente quello di permettere alla funzione di callback di avere un numero di argomenti diverso. Molte funzioni della libreria GTK accettano solo un singolo puntatore ad un widget GTK come argomento, così per queste si può usare la funzione gtk_signal_connect_object(), mentre per le vostre funzioni potreste aver bisogno di passare dati supplementari alle funzioni di ritorno. <sect1>Attraverso Hello World passo per passo Ora che conosciamo la teoria che vi è dietro, iniziamo ad essere più chiari camminando attraverso il programma di Hello World. Questa è la funzione di callback che sarà invocata quando il bottone viene cliccato. Noi, in questo esempio, ignoriamo sia il widget che i dati passati, ma non è difficile farci invece qualcosa. Il prossimo esempio userà l'argomento passato per dire quale bottone è stato premuto. <tscreen><verb> void hello (GtkWidget *widget, gpointer *data) { g_print ("Hello World\n"); } </verb></tscreen> Questa callback è un po' speciale. L'evento ``delete'' avviene quanto il Window Manager manda questo evento all'applicazione. Qui abbiamo una scelta da fare: cosa fare di questo evento. Possiamo ignorarlo, creare qualche tipo di risposta, o semplicemente terminare l'applicazione. Il valore che si restituisce in questa callback fa sì che la GTK sappia cosa fare. Restituire TRUE significa che non vogliamo che il segnale ``destroy'' sia emesso, quindi far sì che la nostra applicazione proceda normalmente. Ritornare FALSE vuole dire far emettere il segnale ``destroy'' il quale chiamerà la nostra funzione di callback che gestisce il segnale ``destroy''. <tscreen><verb> gint delete_event(GtkWidget *widget, gpointer data) { g_print ("delete event occured\n"); return (TRUE); } </verb></tscreen> Questa è un'altra funzione di callback la quale fa uscire dal programma chiamando gtk_main_quit(). Questa funzione dice a GTK che deve uscire da gtk_main quando gli viene restituito il controllo. <tscreen><verb> void destroy (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } </verb></tscreen> Ritengo che conosciate la funzione main()... si, come tutte le altre applicazioni anche le applicazioni GTK hanno questa funzione. <tscreen><verb> int main (int argc, char *argv[]) { </verb></tscreen> Questa parte dichiara un puntatore ad una struttura di tipo GtkWidget. Queste sono usate più sotto per creare una finestra ed un bottone. <tscreen><verb> GtkWidget *window; GtkWidget *button; </verb></tscreen> Qui vi è ancora la nostra gtk_init. Come prima questa inizializza il toolkit e analizza gli argomenti trovati nella linea di comando. Tutti gli argomenti riconosciuti nella linea di comando sono rimossi dalla lista degli argomenti e vengono così modificati argc e argv per far sì che sembri che questi non siano mai esisiti e permettere alla vostra applicazione di analizzare gli argomenti rimasti. <tscreen><verb> gtk_init (&argc, &argv); </verb></tscreen> Crea una nuova finestra. Questo viene spiegato abbastanza approfonditamente più avanti. Viene allocata la memoria per la struttura GtkWidget *window così che si punti ad una struttura valida. In questo modo si predispone la nuova finestra, ma non la si visualizza fino a sotto dove, quasi alla fine del nostro programma, invochiamo gtk_widget_show(window). <tscreen><verb> window = gtk_window_new (GTK_WINDOW_TOPLEVEL); </verb></tscreen> Questo è un esempio di come connettere un gestore dei segnali con un oggetto, in questo caso la finestra. Qui viene catturato il segnale ``destroy''. Questo viene emesso quando usiamo il Window Manager per uccidere la finestra (e noi restituiamo TRUE dal gestore di ``delete_event'') o quando emettiamo la chiamata gtk_widget_destroy() passando l'oggetto finestra come oggetto da distruggere. Sistemando le cose così, trattiamo entrambi i casi con una singola chiamata. Qui è giusto invocare la funzione destroy() definita sopra con NULL come argomento, la quale termina l'applicazione GTK per noi. Questo ci permetterà di utilizzare il Window Manager per uccidere il programma. GTK_OBJECT e GTK_SIGNAL_FUNC sono macro che interpretano il casting e il controllo di tipo per noi, così da rendere piu' leggibile il codice. <tscreen><verb> gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (destroy), NULL); </verb></tscreen> La prossima funzione è usata per settare un attributo di un oggetto contenitore. Questo sistema la finestra così da avere un'area vuota all'interno della finestrra larga 10 pixel dove non potrà andare nessun widget. Ci sono altre funzioni simili che vedremo nella sezione <ref id="sec_setting_widget_attributes" name="Settare gli attributi del Widget."> E ancora, GTK_CONTAINER è una macro per interpretare il casting di tipo. <tscreen><verb> gtk_container_border_width (GTK_CONTAINER (window), 10); </verb></tscreen> Questa chiamata crea un nuovo bottone. Alloca spazio in memoria per un nuovo GtkWidget, inizializzandolo e facendo sì che il puntatore a bottone punti ad esso. Quando sarà visualizzato, avrà etichetta ``Hello World''. <tscreen><verb> button = gtk_button_new_with_label ("Hello World"); </verb></tscreen> Qui prendiamo il bottone e gli facciamo fare qualcosa di utile. Gli colleghiamo un gestore di segnale in modo che quando emetterà il segnale ``clicked'', verrà invocata la nostra funzione hello(). Il dato passato alla funzione è ignorato, cosicché alla funzione di callback hello() passiamo semplicemente NULL. Evidentemente il segnale ``clicked'' viene emesso quando premiamo il bottone con il mouse. <tscreen><verb> gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (hello), NULL); </verb></tscreen> Usiamo questo bottone anche per uscire dal programma. Questo illustrerà come il segnale ``destroy'' può arrivare sia dal Window Manager che dal nostro programma. Quando il bottone viene cliccato come descritto sopra, chiamerà la funzione di callback hello() e poi quest'ultima nell'ordine in cui sono definite. Si possono cioé avere tante funzioni di callback quante sono necessarie, e saranno eseguite nell'ordine in cui sono connesse. Visto che la funzione gtk_widget_destroy() accetta come argomento solo un GtkWidget *widget, usiamo la funzione gtk_signal_connect_object() al posto della normale gtk_signal_connect(). <tscreen><verb> gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy), GTK_OBJECT (window)); </verb></tscreen> Questa é una chiamata di ``impacchettamento'' che sarà spiegata più avanti. Ma è molto facile da capire. Semplicemente dice alla libreria GTK che il bottone è da mettere nella finestra dove sarà visualizzato. <tscreen><verb> gtk_container_add (GTK_CONTAINER (window), button); </verb></tscreen> A questo punto abbiamo predisposto tutto quello che ci eravamo prefissati. Con tutti i gestori di segnale a posto e il bottone messo nella finestra in cui dovrebbe essere, possiamo dire a GTK di mostrare gli oggetti sullo schermo. L'oggetto finestra viene mostrato per ultimo così che la finestra completa di tutti i suoi oggetti verrà mostrata tutta in una volta, invece di vedere prima la finestra spoglia e poi la comparsa del bottone all'interno di essa. Per quanto, con questi semplici esempi, questo l'avrete già notato. <tscreen><verb> gtk_widget_show (button); gtk_widget_show (window); </verb></tscreen> E naturalmente chiamiamo gtk_main(), la quale aspetta l'arrivo degli eventi dal server X e chiama l'oggetto interessato per fargli emettere il segnale corrispondente. <tscreen><verb> gtk_main (); </verb></tscreen> E il return finale. Il controllo ritorna qui dopo che viene invocata gtk_quit(). <tscreen><verb> return 0; </verb></tscreen> Ora, quando premiamo il bottone del mouse su un bottone GTK, questo oggetto emette il segnale ``clicked''. Per poter utilizzare queste informazioni, il nostro programma predispone un gestore di segnale per catturare quel segnale, il quale avvia la funzione da noi scelta. Nel nostro esempio, quando il bottone creato viene cliccato, la funzione hello() viene invocata con argomento NULL, dopoodiché viene invocato il successivo gestore di questo segnale. Questo chiama la funziona gtk_widget_destroy(), passandole l'oggetto-finestra (window) come argomento, che distruggerà la finestra. Questo fa sì che la finestra emetta il segnale ``destroy'' che viene catturato e che fa invocare la funzione di ritorno destroy(), che semplicemente esce dal programma GTK. Un'altro modo in cui possono andare le cose è l'uso del window manager per uccidere la finestra. Questo causera' l'emissione del segnale ``delete_event'' che automaticamente chiamerà il gestore del segnale ``delete_event''. Se qui noi restituiamo il valore TRUE, la finestra non verrà toccata e tutto procederà come se nulla fosse successo. Dare invece il valore FALSE causerà l'emissione da parte di GTK del segnale ``destroy'' il quale, a sua volta, invocherà la callback ``destroy'', uscendo dall'applicazione. Nota che questi segnali non sono gli stessi del sistema Unix e che non sono implementati usando quei segnali, anche se la terminologia è praticamente identica.  <sect>Proseguiamo   <sect1>Tipi di Dato Ci sono alcune cose che avrete probabilmente notato nei precedenti esempi che hanno bisogno di una spiegazione. I gint, gchar ecc. che vedete sono tipi di dato (typedef) riferiti rispettivamente a int e char. Questo viene fatto per rimediare alle scomode dipendenze dalle dimensioni di semplici tipi di dato quando si fanno dei calcoli. Un buon esempio è ``gint32'' il quale sarà un tipo di dato riferito ad un intero a 32 bit per tutte le piattaforme, sia per gli x86 che per gli per gli alpha a 64 bit. I tipi di dato sono ben spiegati più avanti e molto intuitivi. Sono definiti in glib/glib.h (il quale viene incluso da gtk.h). Noterete anche la possibilità di utilizzare un GtkWidget quando la funzione richiede un GtkObject. GTK è una libreria orienta agli oggetti ed un widget è un oggetto.  <sect1>Altri Dettagli sui Segnali Diamo un'altra occhiata alla dichiarazione della funzione gtk_signal_connect. <tscreen><verb> gint gtk_signal_connect (GtkObject *object, gchar *name, GtkSignalFunc func, gpointer func_data); </verb></tscreen> Notate il valore di ritorno definito come gint? Questo è un identificatore per la vostra funzione di callback. Come detto sopra, si possono avere più funzioni di ritorno per ogni segnale e per ogni ogetto a seconda delle necessità, ed ognuna sarà eseguita in sequenza, nell'ordine in cui è stata collegata. Questo identificatore vi permette di rimuovere una funzione dalla lista delle funzioni di ritorno tramite la seguente chiamata <tscreen><verb> void gtk_signal_disconnect (GtkObject *object, gint id); </verb></tscreen> Così, passando il widget da cui si vuole rimuovere il gestore di segnale e l'identificativo restituito da una delle funzioni signal_connect, si può rimuovere il gestore di segnale che si desidera dal widget. Un'altra funzione, usata per rimuovere tutti i segnali di un widget in una volta sola è: <tscreen><verb> gtk_signal_handlers_destroy (GtkObject *object); </verb></tscreen> Questa chiamata è abbastanza auto esplicativa. Semplicemente rimuove tutti i segnali collegati al widget che si passa alla funzione come argomento.  <sect1>Miglioriamo Hello World Diamo un'occhiata ad una versione migliorata di Hello World con altri esempi sulle callback. Questo ci introdurrà anche al nostro prossimo argomento, l'impacchettamento dei widget. <tscreen><verb> /* helloworld2.c */ #include <gtk/gtk.h> /* La nostra funzione di callback migliorata. I dati passati a questa * vengono stampati su stdout. */ void callback (GtkWidget *widget, gpointer *data) { g_print ("Hello again - %s was pressed\n", (char *) data); } /* Un'altra callback */ void delete_event (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } int main (int argc, char *argv[]) { /* GtkWidget e' il tipo di dato per i widget */ GtkWidget *window; GtkWidget *button; GtkWidget *box1; /* Questa funzione e' invocata in tutte le applicazioni GTK, gli argomenti sono analizzati e restituiti all'applicazione. */ gtk_init (&argc, &argv); /* Crea una nuova finestra */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); /* Questa e' una nuova chiamata. Assegna "Hello Buttons" come titolo della nostra finestra */ gtk_window_set_title (GTK_WINDOW (window), "Hello Buttons!"); /* Qui settiamo il gestore per il segnale "delete_event" che immediatamente esce dalla applicazione. gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (delete_event), NULL); /* predispone il bordo della finestra */ gtk_container_border_width (GTK_CONTAINER (window), 10); /* creiamo una scatola dove mettere tutti i widget. Questa è descritta dettagliatamente nella sezione "packing". La scatola non è realmente visibile, è solamente usata per sistemare i widget. */ box1 = gtk_hbox_new(FALSE, 0); /* Inseriamo la scatola nella finestra */ gtk_container_add (GTK_CONTAINER (window), box1); /* Creiamo un nuovo bottone con etichetta "Button 1" */ button = gtk_button_new_with_label ("Button 1"); /* Quando il bottone e' premuto, noi invocheremo la funzione di callback, con un puntatore alla stringa "button 1" come proprio argomento) */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); /* invece di aggiungerlo alla finestra, lo inseriamo nella scatola invisibile, la quale e' stata inserita nella finstra. */ gtk_box_pack_start(GTK_BOX(box1), button, TRUE, TRUE, 0); /* Ricordati sempre questo passo. Dice a GTK che la preparazione di questo bottone e' finita e che quindi puo' essere mostrato. */ gtk_widget_show(button); /* Facciamo la stessa cosa per il secondo bottone. */ button = gtk_button_new_with_label ("Button 2"); /* Chiamiamo la stessa funzione ma passandogli un argomento differente, gli passiamo un puntatore alla stringa "button 2" */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 2"); gtk_box_pack_start(GTK_BOX(box1), button, TRUE, TRUE, 0); /* L'ordine nel quale i bottoni sono visualizzati non e' realmente importante, ma io ti raccomando di mostrare per ultima la finestra cosi' che tutto sia visualizzato in una volta sola */ gtk_widget_show(button); gtk_widget_show(box1); gtk_widget_show (window); /* e ora ci mettiamo in gtk_main e aspettiamo che il diverimento inizi. gtk_main (); return 0; } </verb></tscreen> Compilate questo programma usando gli stessi argomenti di link del nostro primo esempio. Noterete che questa volta non c'è un modo semplice per uscire dal programma, si deve usare il nostro window manager o la linea di comando per uccidere l'applicazione. Un buon esercizio per il lettore è quello di inserire un tezo bottone ``quit'' che faccia uscire dal programma. Potete anche divertirvi con le opzioni di gtk_box_pack_start() mentre leggete il prossimo capitolo. Provate a ridimensionare la finestra ed a osservare cosa succede. Solo una piccola nota: c'è un'altra definizione di gtk_window_new() - GTK_WINDOW_DIALOG. Questa interagisce con il window manager in un modo un po' diverso, e dovrebbe essere usata per finestre temporanee.  <sect>Come ``Impacchettare'' i Widget  Nel momento in cui si crea un'applicazione, normalmente si avrà la necessità di mettere più di un unico bottone all'interno di una finestra. Il nostro primo esempio ``Hello World'' usava un solo oggetto, cosicché abbiamo potuto usare semplicemente una chiamata a gtk_container_add per impacchettare il widget nella finestra. Quando invece si vuole inserire più di un unico widget in una finestra, come si fa a controllare dove vengono posizionati i propri oggetti? E' qui che entra in gioco il meccanismo dell'``impacchettamento''.  <sect1>Teoria delle Scatole per Impacchettamento La maggior parte dell'impacchettamento viene effettuata creando delle scatole come nell'esempio più sopra. Le scatole sono dei contenitori invisibili di widget che possiamo usare per imballarci i nostri oggetti e che esistono in due varietà: in particolare si possono avere scatole orizzontali (hbox) e verticali (vbox). Quando si impacchentano degli oggetti in una scatola orizzontale, gli oggetti vengono inseriti orizzontalmente da sinistra a destra oppure da destra a sinistra a seconda della chiamata di funzione che si usa. In una scatola verticale, gli oggetti vengono inseriti dall'alto in basso o viceversa. Si può usare qualsiasi combinazione di scatole all'interno o a fianco di altre scatole, fino ad ottenere l'effetto desiderato. Per creare una nuova scatola orizzontale, si usa una chiamata a gtk_hbox_new(), mentre per le scatole verticali si usa gtk_vbox_new(). Per inserire i widget all'interno di questi contenitori si usano le funzioni gtk_box_pack_start() e gtk_box_pack_end(). La funzione gtk_box_pack_start() comincerà dall'alto verso il basso in una vbox e da sinistra a destra in una hbox. gtk_box_pack_end() fa l'opposto, impacchettando dal basso verso l'alto in una vbox e da destra a sinistra in una hbox. Queste funzioni ci permettono di giustificare a destra o a sinistra i nostri widget, e possono essere mescolate in qualsiasi modo per ottenere l'effetto desiderato. Useremo gtk_box_pack_start() nella maggior parte dei nostri esempi. Un oggetto può essere costituito da un altro contenitore o da un oggetto grafico. Infatti, molti oggetti grafici sono a loro volta dei contenitori, compreso il bottone, anche se tipicamente all'interno del bottone mettiamo solo una etichetta. Usando queste chiamate, GTK riesce a capire dove si vogliono piazzare i propri widget, in modo di essere poi in grado di effettuare il ridimensionamento automatico e altre cose interessanti. Esiste poi un insieme di opzioni che riguardano il modo in cui i propri oggetti grafici dovrebbero essere impacchettati. Come si può immaginare, questo metodo dà una buona flessibilità nella creazione e nella disposizione dei propri widget.  <sect1>Dettagli sulle Scatole A causa di questa flessibilità, le scatole per impacchettamento del GTK possono, di primo acchito, creare un po' di disorientamento. Sono infatti disponibili molte opzioni, e non è immediato il modo in cui si combinano l'una con l'altra. Alla fine però, si possono ottenere essenzialmente cinque diversi stili. <? <CENTER> > <? <IMG SRC="gtk_tut_packbox1.gif" VSPACE="15" HSPACE="10" WIDTH="528" HEIGHT="235" ALT="Box Packing Example Image"> > <? </CENTER> > Ogni linea contiene una scatola orizzontale (hbox) con diversi bottoni. La chiamata a gtk_box_pack è una scorciatoia per la chiamata di impacchettamento di ognuno dei bottoni nella hbox. Ognuno dei bottoni viene impacchettato nella hbox nello stesso modo (cioè, con gli stessi argomenti per la funzione gtk_box_pack_start ()). Questa è la dichiarazione della funzione gtk_box_pack_start. <tscreen><verb> void gtk_box_pack_start (GtkBox *box, GtkWidget *child, gint expand, gint fill, gint padding); </verb></tscreen> Il primo argomento è la scatola nella quale si stanno inscatolando i widget, il secondo è il widget stesso. Gli oggetti per ora saranno bottoni, quindi quello che faremo sarà impacchettare bottoni in scatole. L'argomento ``expand'' in gtk_box_pack_start() o gtk_box_pack_end() controlla se gli oggetti devono essere sistemati nella scatola in modo da riempire tutto lo spazio in diponibile presente nella scatola, in modo che la scatola si espanda fino ad occupare tutta l'area assegnatale (valore TRUE). La scatola può anche essere rimpiciolita in modo da contenere esattamente i widget (valore FALSE). Assegnare a expand il valore FALSE permette di giustificare a destra o sinistra i propri oggetti. In caso contrario, tutti gli ogetti si espandono fino ad adattarsi alla scatola, e il medesimo effetto si può ottenere usando solo una delle funzioni gtk_box_pack_start o pack_end. L'argomento ``fill'' delle funzioni gtk_box_pack stabilisce se lo spazio disponibile nella scatola deve essere allocato agli oggetti (TRUE) o se deve essere mantenuto come riempimento attorno a questi oggetti (FALSE). Questo argomento ha effetto solo se a expand è assegnato il valore TRUE. Quando si crea una nuova scatola, la funzione ha questo aspetto: <tscreen><verb> GtkWidget * gtk_hbox_new (gint homogeneous, gint spacing); </verb></tscreen> L'argomento homogeneous di gtk_hbox_new (la stesso per gtk_vbox_new) determina se ogni oggetto nella scatola deve avere la stessa dimensione (cioè la stessa ampiezza in una hbox o la stessa altezza in una vbox). Se è settato, l'argomento expand delle routine gtk_box_pack è sempre attivato. Qual è la differenza fra la spaziatura (che è stabilita quando la scatola viene creata) e il riempimento (che viene stabilito quando gli elementi vengono impacchettati)? La spaziatura viene inserita fra gli oggetti, mentre il riempimento viene aggiuno a ciascuno dei lati dell'oggetti. La seguente figura dovrebbe chiarire meglio questo punto: <? <CENTER> > <? <IMG ALIGN="center" SRC="gtk_tut_packbox2.gif" WIDTH="509" HEIGHT="213" VSPACE="15" HSPACE="10" ALT="Box Packing Example Image"> > <? </CENTER> > Di seguito è riportato il codice usato per creare le immagini precedenti. L'ho commentato in modo piuttosto pesante, in modo che non dovreste avere problemi nel seguirlo. Compilatelo voi stessi e provate a giocarci un po'.  <sect1>Programma Dimostrativo di Impacchettamento <tscreen><verb> /* packbox.c */ #include "gtk/gtk.h" void delete_event (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } /* Costruisco una nuova hbox riempita con bottoni-etichette. Gli * argomenti per le varabili che ci interessano sono passati * in questa funzione. Non mostriamo la scatola, ma mostriamo * tutto quello che c'e' dentro. */ GtkWidget *make_box (gint homogeneous, gint spacing, gint expand, gint fill, gint padding) { GtkWidget *box; GtkWidget *button; char padstr[80]; /* costruisco una nuova hbox con i valori appropriati di * homogeneous e spacing */ box = gtk_hbox_new (homogeneous, spacing); /* costruisco una serie di bottoni con i valori appropriati */ button = gtk_button_new_with_label ("gtk_box_pack"); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); button = gtk_button_new_with_label ("(box,"); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); button = gtk_button_new_with_label ("button,"); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); /* costruisco un bottone con l'etichetta che dipende dal valore di * expand. */ if (expand == TRUE) button = gtk_button_new_with_label ("TRUE,"); else button = gtk_button_new_with_label ("FALSE,"); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); /* Questo e' la stessa cosa della creazione del bottone per "expand" * piu' sopra, ma usa la forma breve. */ button = gtk_button_new_with_label (fill ? "TRUE," : "FALSE,"); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); sprintf (padstr, "%d);", padding); button = gtk_button_new_with_label (padstr); gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding); gtk_widget_show (button); return box; } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *button; GtkWidget *box1; GtkWidget *box2; GtkWidget *separator; GtkWidget *label; GtkWidget *quitbox; int which; /* La nostra inizializzazione, non dimenticatela! :) */ gtk_init (&argc, &argv); if (argc != 2) { fprintf (stderr, "uso: packbox num, dove num è 1, 2, o 3.\n"); /* questo fa solo un po' di pulizia in GTK, ed esce con un valore 1. */ gtk_exit (1); } which = atoi (argv[1]); /* Creiamo la nostra finestra */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); /* Ci si dovrebbe sempre ricordare di connettere il segnale di destroy * alla finestra principale. Cio' e' molto importante per avere un funzionamento * corretto dal punto di vista intuitivo */ gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (delete_event), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* Creiamo una scatola verticale (vbox) in cui impacchettare quelle * orizzontali. Questo ci permette di impilare le scatole orizzontali * piene di bottoni una sull'altra in questa vbox. */ box1 = gtk_vbox_new (FALSE, 0); /* Decide quale esempio si deve mostrare. Corrispondono alle figure precedenti */ switch (which) { case 1: /* creare una nuova etichetta. */ label = gtk_label_new ("gtk_hbox_new (FALSE, 0);"); /* allineare l'etichetta al lato sinistro. Discuteremo questa e altre * funzioni nella sezione dedicata agli attributi degli oggetti grafici. */ gtk_misc_set_alignment (GTK_MISC (label), 0, 0); /* Impacchettare l'etichetta nella scatola verticale (vbox box1). * Ricordare che gli oggetti che vengono aggiunti in una vbox vengono * impacchettati uno sopra all'altro in ordine. */ gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0); /* mostrare l'etichetta */ gtk_widget_show (label); /* chiamare la nostra funzione make_box - homogeneous = FALSE, * spacing = 0, expand = FALSE, fill = FALSE, padding = 0 */ box2 = make_box (FALSE, 0, FALSE, FALSE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* chiamare la nostra funzione make_box - homogeneous = FALSE, spacing = 0, * expand = FALSE, fill = FALSE, padding = 0 */ box2 = make_box (FALSE, 0, TRUE, FALSE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (FALSE, 0, TRUE, TRUE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* Questo crea un separatore. Li conosceremo meglio in seguito, * comunque sono piuttosto semplici. */ separator = gtk_hseparator_new (); /* Impacchetta il separatore nella vbox. Ricordare che stiamo impacchettando * ognuno di questi oggetti in una vbox, cosicché essi verranno * impacchettati verticalmente. */ gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5); gtk_widget_show (separator); /* crea un'altra nuova etichetta e mostrala. */ label = gtk_label_new ("gtk_hbox_new (TRUE, 0);"); gtk_misc_set_alignment (GTK_MISC (label), 0, 0); gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0); gtk_widget_show (label); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (TRUE, 0, TRUE, FALSE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (TRUE, 0, TRUE, TRUE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* ancora un nuovo separatore. */ separator = gtk_hseparator_new (); /* Gli ultimi 3 argumenti per gtk_box_pack_start sono: expand, fill, padding. */ gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5); gtk_widget_show (separator); break; case 2: /* creare una nuova etichetta, ricordare che box1 e' la vbox creata * vicino all'inizio di main() */ label = gtk_label_new ("gtk_hbox_new (FALSE, 10);"); gtk_misc_set_alignment (GTK_MISC (label), 0, 0); gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0); gtk_widget_show (label); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (FALSE, 10, TRUE, FALSE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (FALSE, 10, TRUE, TRUE, 0); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); separator = gtk_hseparator_new (); /* Gli ultimi tre arcomenti di gtk_box_pack_start sono: expand, fill, padding. */ gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5); gtk_widget_show (separator); label = gtk_label_new ("gtk_hbox_new (FALSE, 0);"); gtk_misc_set_alignment (GTK_MISC (label), 0, 0); gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0); gtk_widget_show (label); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (FALSE, 0, TRUE, FALSE, 10); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* Gli argomenti sono: homogeneous, spacing, expand, fill, padding */ box2 = make_box (FALSE, 0, TRUE, TRUE, 10); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); separator = gtk_hseparator_new (); /* Gli ultimi tre argomenti di gtk_box_pack_start sono: expand, fill, padding. */ gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5); gtk_widget_show (separator); break; case 3: /* Questo dimostra la possibilita' di usare use gtk_box_pack_end() per * giustificare gli oggetti a destra. Per prima cosa creiamo una * nuova scatola come prima. */ box2 = make_box (FALSE, 0, FALSE, FALSE, 0); /* creiamo l'etichetta che sara' aggiunta alla fine. */ label = gtk_label_new ("end"); /* impacchettiamola usando gtk_box_pack_end(), cosa' che viene inserita * sul lato destro della hbox creata nella chiamata a the make_box(). */ gtk_box_pack_end (GTK_BOX (box2), label, FALSE, FALSE, 0); /* mostriamo l'etichetta. */ gtk_widget_show (label); /* impacchettiamo box2 in box1 (the vbox, ricordate? :) */ gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0); gtk_widget_show (box2); /* un separatore per il fondo */ separator = gtk_hseparator_new (); /* Questo assegna esplicitamente al separatore l'ampiezza di 400 pixel * e l'altezza di 5 pixel. Cio' fa si' che la hbox che abbiamo creato sia * anche essa larga 400 pixel, e che l'etichetta finale sia separata dalle * altre etichette nella hbox. In caso contrario, tutti gli oggetti nella * hbox sarebbero impacchettati il piu' vicino possibile. */ gtk_widget_set_usize (separator, 400, 5); /* impacchetta il separatore nella vbox (box1) creata vicino all'inizio * di main() */ gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5); gtk_widget_show (separator); } /* Creare un'altra nuova hbox.. ricordate che ne possiamo usare quante ne vogliamo! */ quitbox = gtk_hbox_new (FALSE, 0); /* Il nostro bottone di uscita. */ button = gtk_button_new_with_label ("Quit"); /* Configuriamo il segnale per distruggere la finestra. Ricordate che * ciò manderà alla finestra il segnale "destroy", che verrà catturato * dal nostro gestore di segnali che abbiamo definito in precedenza. */ gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (gtk_main_quit), GTK_OBJECT (window)); /* impacchetta il bottone in quitbox. * Gli ultimi tre argomenti di gtk_box_pack_start sono: expand, fill, padding. */ gtk_box_pack_start (GTK_BOX (quitbox), button, TRUE, FALSE, 0); /* impacchetta quitbox nella vbox (box1) */ gtk_box_pack_start (GTK_BOX (box1), quitbox, FALSE, FALSE, 0); /* impacchetta la vbox (box1), che ora contiene tutti i nostri oggetti, * nella finestra principale. */ gtk_container_add (GTK_CONTAINER (window), box1); /* e mostra tutto quel che rimane */ gtk_widget_show (button); gtk_widget_show (quitbox); gtk_widget_show (box1); /* Mostriamo la finestra alla fine in modo che tutto spunti fuori assieme. */ gtk_widget_show (window); /* E, naturalmente, la nostra funzione main. */ gtk_main (); /* Il controllo ritorna a questo punto quando viene chiamata gtk_main_quit(), * ma non quando si usa gtk_exit. */ return 0; } </verb></tscreen>  <sect1>Impacchettamento con uso di Tabelle Diamo ora un'occhiata ad un altro modo di impacchettare - le Tabelle. In certe situazioni, possono risultare estremamente utili. Usando le tabelle, creiamo una griglia in cui possiamo piazzare gli oggetti. Gli oggetti possono occupare tanti spazi quanti ne specifichiamo. Naturalmente, la prima cosa da vedere è la funzione gtk_table_new: <tscreen><verb> GtkWidget* gtk_table_new (gint rows, gint columns, gint homogeneous); </verb></tscreen> Il primo argomento rappresenta il numero di righe da mettere nella tabella, mentre il secondo è ovviamente il numero di colonne. L'argomento homogeneous ha a che fare con il modo in cui le caselle della tabella sono dimensionate. Se homogeneous ha il valore TRUE, le caselle sono ridimensionate fino alla dimensione del più grande oggetto contenuto nella tabelle. Se è FALSE, la dimensione delle caselleè decisa dal più alto oggetto in una certa riga e dal più largo oggetto in una stessa colonna. Le righe e le colonne sono disposte a partire da 0 fino a n, dove n è il numero che era stato specificato nella chiamata a gtk_table_new. Così, se specificate rows = 2 e columns = 2, lo schema avrà questo aspetto: <tscreen><verb> 0 1 2 0+----------+----------+ | | | 1+----------+----------+ | | | 2+----------+----------+ </verb></tscreen> Notate che il sistema di coordinate ha origine nel vertice in alto a sinistra. Per mettere un oggetto in una tabella, usate la seguente funzione: <tscreen><verb> void gtk_table_attach (GtkTable *table, GtkWidget *child, gint left_attach, gint right_attach, gint top_attach, gint bottom_attach, gint xoptions, gint yoptions, gint xpadding, gint ypadding); </verb></tscreen> In cui il primo argomento (``table'') è la tabella che avete creato e il secondo (``child'') è l'oggetto che volete piazzare nella tabella. Gli argomenti ``attach'' (right, left, top, bottom) specificano dove mettere l'oggetto e quante caselle adoperare. Se volete mettere un bottone nella casella in basso a destra nella nostra tabella 2x2, e volete che esso riempia SOLO quella casella, dovete porre left_attach = 1, right_attach = 2, top_attach = 1, bottom_attach = 2. Se invece volete che un oggetto si prenda tutta la riga più in alto nella nostra tabella 2x2, dovreste usare left_attach = 0, right_attach =2, top_attach = 0, bottom_attach = 1. Gli argomenti ``xoptions'' e ``yoptions'' sono usati per specificare le opzioni di impacchettamento; di essi si può fare l'OR in modo di ottenere opzioni multiple. Le opzioni sono: <itemize> <item>GTK_FILL - Se la parte di tabella in cui si vuole inserire il widget è più grande dell'oggetto, e se si specifica GTK_FILL, l'oggetto viene espanso fino ad occupare tutto lo spazio disponibile. <item>GTK_SHRINK - Se si alloca all'oggetto nella tabella meno spazio del necessario (di solito succede quando l'utente ridimensiona la finestra), allora normalmente l'oggetto verrebbe spinto fuori dal fondo della finestra fino a sparire. Se invece si specifica GTK_SHRINK is specified, gli oggetti si rimpiccioliscono assieme alla tabella. <item>GTK_EXPAND - Questo fa sì che la tabella si espanda fino ad occupare tutto lo spazio che rimane nella finestra. </itemize> Il riempimento funziona come nelle scatole, con la creazione di un'area vuota attorno all'oggetto la cui dimensione viene specificata in pixel. La funzione gtk_table_attach() ha UN MUCCHIO di opzioni. Quindi, ecco una scorciatoia: <tscreen><verb> void gtk_table_attach_defaults (GtkTable *table, GtkWidget *widget, gint left_attach, gint right_attach, gint top_attach, gint bottom_attach); </verb></tscreen> Le xoptions e yoptions vengono posti per difetto a GTK_FILL | GTK_EXPAND, e sia xpadding che ypadding vengono posti a 0. Il resto degli argomenti sono identici a quelli della funzione precedente. Ci sono poi le funzioni gtk_table_set_row_spacing() and gtk_table_set_col_spacing(). Queste mettono dello spazio fra le righe (o colonne)in corrispondenza di una specifica riga (o colonna). <tscreen><verb> void gtk_table_set_row_spacing (GtkTable *table, gint row, gint spacing); </verb></tscreen> e <tscreen><verb> void gtk_table_set_col_spacing (GtkTable *table, gint column, gint spacing); </verb></tscreen> Notate che per le colonne lo spazio viene posto alla destra della colonna, mentre per le righe lo spazio viene posto al di sotto della riga. Si può poi inserire una spaziatura identica fra tutte le righe e/o colonne usando: <tscreen><verb> void gtk_table_set_row_spacings (GtkTable *table, gint spacing); </verb></tscreen> e <tscreen><verb> void gtk_table_set_col_spacings (GtkTable *table, gint spacing); </verb></tscreen> Notate che con queste chiamate, all'ultima riga e all'ultima colonna non viene assegnata alcuna spaziatura.  <sect1>Esempio di Impacchettamento con Tabelle In questo esempio creiamo una finestra avente tre bottoni disposti in una tabella 2x2. I primi due bottoni li mettiamo nella riga superiore. Un terzo bottone, quit, lo mettiamo nella riga inferioe, in modo da comprendere entrambe le colonne. Ciò significa che dovremmo avere qualcosa di questo tipo: <? <CENTER> > <? <IMG SRC="gtk_tut_table.gif" VSPACE="15" HSPACE="10" ALT="Table Packing Example Image" WIDTH="180" HEIGHT="120"> > <? </CENTER> > Ecco il codice sorgente: <tscreen><verb> /* table.c */ #include <gtk/gtk.h> /* la nostra funzione di ritorno. * i dati passati a questa funzione vengono stampati su stdout */ void callback (GtkWidget *widget, gpointer *data) { g_print ("Hello again - %s was pressed\n", (char *) data); } /* questa funzione fa uscire dal programma */ void delete_event (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *button; GtkWidget *table; gtk_init (&argc, &argv); /* creiamo una nova finestra */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); /* predisponiamo il titolo per la finestra */ gtk_window_set_title (GTK_WINDOW (window), "Table"); /* creiamo un gestore per delete_event che esca immediatamente * da GTK. */ gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (delete_event), NULL); /* regoliamo la larghezza del bordo della finestra. */ gtk_container_border_width (GTK_CONTAINER (window), 20); /* creiamo una tabella 2x2 */ table = gtk_table_new (2, 2, TRUE); /* mettiamo la tabella nella finesta principale */ gtk_container_add (GTK_CONTAINER (window), table); /*creiamo il primo bottone */ button = gtk_button_new_with_label ("button 1"); /* quando viene premuto il bottone, chiamiamo la funzione di ritorno * con un puntatore a "button 1"come argomento */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); /* inseriamo il bottone 1 nel quadrante in alto a sinistra della tabella */ gtk_table_attach_defaults (GTK_TABLE(table), button, 0, 1, 0, 1); gtk_widget_show (button); /* creiamo il secondo bottone */ button = gtk_button_new_with_label ("button 2"); /* quando si preme il bottone, chiamamo la funzione di ritorno * con un puntatore a "button 2"come argomento */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 2"); /* inseriamo il secondo bottone nel quadrate in alto a destra della tbella */ gtk_table_attach_defaults (GTK_TABLE(table), button, 1, 2, 0, 1); gtk_widget_show (button); /* creiamo il botone "Quit" */ button = gtk_button_new_with_label ("Quit"); /* quando viene premuto questo bottone, chiamiamo la funzione "delete_event" * e si esce dal programma */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (delete_event), NULL); /* inseriamo il pulsante quit nelle due casele in basso della tabella */ gtk_table_attach_defaults (GTK_TABLE(table), button, 0, 2, 1, 2); gtk_widget_show (button); gtk_widget_show (table); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect>Panoramica sui Widget  La procedura generale di creazione di un widget in GTK prevede i seguenti passi: <enum> <item> gtk_*_new - una delle varie funzioni che servono per greare un nuovo widget. In questa sezione le vedremo tutte in dettaglio. <item> Connettere tutti i segnali che si vogliono usare alle funzione gestione appfropriate. <item> Assegnare gli attributi all'oggetto. <item> Impacchettare l'oggetto in un contenitore usando la chiamate appropriata, per esempio gtk_container_add() o gtk_box_pack_start(). <item> Mostrare l'oggetto con gtk_widget_show(). </enum> gtk_widget_show() fa sì che GTK sappia che abbiamo terminato di assegnare gli attributi dell'oggetto grafico, e che è pronto per essere visualizzato. Si può anche usare la funzione gtk_widget_hide per farlo sparire di nuovo. L'ordine in cui mostrate gli oggetti grafici non è importante, ma io suggerisco di mostrare per ultima la finestra, in modo che questa spunti fuori già completa, invece di vedere i singoli oggetti che arrivano sullo schermo a mano a mano che si formano. I figli di un oggetto grafico (anche una finestra è un oggetto grafico) non vengono infatti mostrati finché la finestra stessa non viene mostrata usando la funzione gtk_widget_show().  <sect1> Casting Noterete andando avanti che GTK usa un sistema di casting di tipo. Questa operazione viene sempre effettuata usando delle macro che allo stesso tempo controllano la possibilità di effettuare il cast sull'elemento dato e lo effettuano realmente. Alcune macro che avrete modo di incontrare sono: <itemize> <item> GTK_WIDGET(widget) <item> GTK_OBJECT(object) <item> GTK_SIGNAL_FUNC(function) <item> GTK_CONTAINER(container) <item> GTK_WINDOW(window) <item> GTK_BOX(box) </itemize> Tutte queste funzioni sono usate per fare il cast di argomenti di funzione. Le vedrete negli esempi, e capirete se è il caso di usarle semplicemente guardando alle dichiarazioni delle funzioni. Come potrete vedere più sotto nella gerarchia delle classi, tutti i GtkWidgets sono derivati dalla classe base GtkObject. Ciò significa che potete usare un widget in ogni posto in cui una funzione richiede un oggetto - semplicemente usate la macro GTK_OBJECT(). Per esempio: <tscreen><verb> gtk_signal_connect(GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC(callback_function), callback_data); </verb></tscreen> Questo fa il cast del bottone in un oggetto e fornisce alla chiamata di ritorno un cast al puntatore a funzione. Molti oggetti grafici sono anche contenitori. Se guardate alla gerarchia delle classi più sotto, vedrete che molti oggetti grafici sono derivati dalla classe GtkContainer. Ognuna di queste classi può essere usata, con la macro GTK_CONTAINER, come argomento per funzioni che richiedono un contenitore. Sfortunatamente, in questo tutorial non si parlerà in modo estensivo di queste macro, ma raccomando di dare un'occhiata ai file header di GTK. Può essere una cosa molto educativa. Infatti, non è difficile imparare come funziona un oggetto solo guardando le dichiarazioni delle funzioni.  <sect1>Gerarchia degli Oggetti Grafici Ecco, per vostro riferimento, la gerarchia delle classi usata per implementare gli oggetti grafici. <tscreen><verb> GtkObject +GtkData | +GtkAdjustment | `GtkTooltips `GtkWidget +GtkContainer | +GtkBin | | +GtkAlignment | | +GtkEventBox | | +GtkFrame | | | `GtkAspectFrame | | +GtkHandleBox | | +GtkItem | | | +GtkListItem | | | +GtkMenuItem | | | | `GtkCheckMenuItem | | | | `GtkRadioMenuItem | | | `GtkTreeItem | | +GtkViewport | | `GtkWindow | | +GtkColorSelectionDialog | | +GtkDialog | | | `GtkInputDialog | | `GtkFileSelection | +GtkBox | | +GtkButtonBox | | | +GtkHButtonBox | | | `GtkVButtonBox | | +GtkHBox | | | +GtkCombo | | | `GtkStatusbar | | `GtkVBox | | +GtkColorSelection | | `GtkGammaCurve | +GtkButton | | +GtkOptionMenu | | `GtkToggleButton | | `GtkCheckButton | | `GtkRadioButton | +GtkCList | +GtkFixed | +GtkList | +GtkMenuShell | | +GtkMenuBar | | `GtkMenu | +GtkNotebook | +GtkPaned | | +GtkHPaned | | `GtkVPaned | +GtkScrolledWindow | +GtkTable | +GtkToolbar | `GtkTree +GtkDrawingArea | `GtkCurve +GtkEditable | +GtkEntry | | `GtkSpinButton | `GtkText +GtkMisc | +GtkArrow | +GtkImage | +GtkLabel | | `GtkTipsQuery | `GtkPixmap +GtkPreview +GtkProgressBar +GtkRange | +GtkScale | | +GtkHScale | | `GtkVScale | `GtkScrollbar | +GtkHScrollbar | `GtkVScrollbar +GtkRuler | +GtkHRuler | `GtkVRuler `GtkSeparator +GtkHSeparator `GtkVSeparator </verb></tscreen>  <sect1>Oggetti senza Finestre Gli oggetti seguenti non hanno una finestra associata. Se volete catturare degli eventi, dovrete usare l'oggetto GtkEventBox. Vedete anche la sezione su <ref id="sec_The_EventBox_Widget" name="Il Widget EventBox"> <tscreen><verb> GtkAlignment GtkArrow GtkBin GtkBox GtkImage GtkItem GtkLabel GtkPixmap GtkScrolledWindow GtkSeparator GtkTable GtkAspectFrame GtkFrame GtkVBox GtkHBox GtkVSeparator GtkHSeparator </verb></tscreen> Proseguiremo la nostra esplorazione di GTK esaminando uno alla volta tutti gli oggetti, creando qualche semplice funzione per mostrarli. Un'altra buona sorgente è il programma testgtk.c che viene fornito con GTK. Potete trovarlo in gtk/testgtk.c.  <sect>Il Widget Bottone (Button)   <sect1>Bottoni Normali Ormai abbiamo visto tutto quello che c'è da vedere riguardo all'oggetto ``bottone''. E' piuttosto semplice, ma ci sono due modi per crare un bottone. Potete usare gtk_button_new_with_label() per creare un bottone con una etichetta, o usare gtk_button_new() per creare un bottone vuoto. In tal caso è poi vostro compito impacchettare un'etichetta o una pixmap sul bottone creato. Per fare ciò, create una nuova scatola, e poi impacchettateci i vostri oggetti usando la solita gtk_box_pack_start, e infine usate la funzione gtk_container_add per impacchettare la scatola nel bottone. Ecco un esempio di utilizzo di gtk_button_new per creare un bottone con un'immagine ed un'etichetta su di sè. Ho separato il codice usato per creare la scatola in modo che lo possiate usare nei vostri programmi. <tscreen><verb> /* buttons.c */ #include <gtk/gtk.h> /* crea una nuova hbox contenente un'immagine ed un'etichetta * e ritorna la scatola creata. */ GtkWidget *xpm_label_box (GtkWidget *parent, gchar *xpm_filename, gchar *label_text) { GtkWidget *box1; GtkWidget *label; GtkWidget *pixmapwid; GdkPixmap *pixmap; GdkBitmap *mask; GtkStyle *style; /* creare una scatola per una xpm ed una etichetta */ box1 = gtk_hbox_new (FALSE, 0); gtk_container_border_width (GTK_CONTAINER (box1), 2); /* ottengo lo stile del bottone. Penso che sia per avere il colore * dello sfondo. Se qualcuno sa il vero motivo, è pregato di dirmelo. */ style = gtk_widget_get_style(parent); /* e ora via con le faccende dell'xpm stuff. Carichiamo l'xpm*/ pixmap = gdk_pixmap_create_from_xpm (parent->window, &mask, &style->bg[GTK_STATE_NORMAL], xpm_filename); pixmapwid = gtk_pixmap_new (pixmap, mask); /* creiamo l'etichetta per il bottone */ label = gtk_label_new (label_text); /* impacchettiamo la pixmap e l'etichetta nella scatola */ gtk_box_pack_start (GTK_BOX (box1), pixmapwid, FALSE, FALSE, 3); gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 3); gtk_widget_show(pixmapwid); gtk_widget_show(label); return (box1); } /* la nostra solita funzione di callback */ void callback (GtkWidget *widget, gpointer *data) { g_print ("Hello again - %s was pressed\n", (char *) data); } int main (int argc, char *argv[]) { /* GtkWidget è il tipo per contenere gli oggetti */ GtkWidget *window; GtkWidget *button; GtkWidget *box1; gtk_init (&argc, &argv); /* creiamo una nuova finestra */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Pixmap'd Buttons!"); /* E' una buona idea fare questo per tutte le finestre. */ gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_exit), NULL); gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (gtk_exit), NULL); /* assegnamo lo spessore del bordo della finestra */ gtk_container_border_width (GTK_CONTAINER (window), 10); gtk_widget_realize(window); /* creiamo un nuovo bottone */ button = gtk_button_new (); /* Ormai dovreste esservi abituati a vedere la maggior parte di * queste funzioni */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "cool button"); /* questa chiama la nostra funzione di creazione di scatole */ box1 = xpm_label_box(window, "info.xpm", "cool button"); /* impacchetta e mostra tutti i nostri oggetti */ gtk_widget_show(box1); gtk_container_add (GTK_CONTAINER (button), box1); gtk_widget_show(button); gtk_container_add (GTK_CONTAINER (window), button); gtk_widget_show (window); /* mettiti in gtk_main e aspetta che cominci il divertimento! */ gtk_main (); return 0; } </verb></tscreen> La funzione xpm_label_box può essere usata per impacchettare delle xpm e delle etichette su qualsiasi oggetto che può essere un contenitore.  <sect1> Bottoni a Commutazione (Toggle Buttons) I bottoni a commutazione sono molto simili ai bottoni normali, tranne che per il fatto che essi si trovano sempre in uno di due stati, che si alternano ad ogni click. Possono trovarsi nello stato ``premuto'', e quando li si ripreme, tornano ad essere sollevati. Ri-clickandoli, torneranno giù. I bottoni a commutazione sono la base per i bottoni di controllo (check button) e per i radio-bottoni, e quindi molte delle chiamate disponibili per i bottoni a commutazione vengono ereditati dai radio-bottoni e dai bottoni di controllo. Ma vedremo questi aspetti nel momento in cui li incontreremo. Creare un nuovo bottone a commutazione: <tscreen><verb> GtkWidget* gtk_toggle_button_new (void); GtkWidget* gtk_toggle_button_new_with_label (gchar *label); </verb></tscreen> Come potete immaginare, queste funzioni lavorano in modo identico che per i bottoni normali. La prima crea un bottone a commutazione vuoto e la seconda un bottone con un'etichetta. Per ottenere lo stato dei widget a commutazione, compresi i radio-bottoni e i bottoni di controllo, si può usare una macro come mostrato nell'esempio più sotto. In questo modo lo stato dell'oggetto commutabile viene valutato in una funzione di ritorno. Il segnale emesso dai bottoni a commutazione (toggle button, il radio button o il check button) che ci interessa è il segnale ``toggled''. Per controllare lo stato di questi bottoni, create un gestore di segnali che catturi il ``toggled'', e usate la macro per determinare il suo stato. La funzione di callback avrà un aspetto più o meno così: <tscreen><verb> void toggle_button_callback (GtkWidget *widget, gpointer data) { if (GTK_TOGGLE_BUTTON (widget)->active) { /* Se il programma si è arrivato a questo punto, il bottone * a commutazione è premuto */ } else { /* il bottone è sollevato */ } } </verb></tscreen>  <tscreen><verb> void gtk_toggle_button_set_state (GtkToggleButton *toggle_button, gint state); </verb></tscreen> La chiamata qui sopra può essere usata per fare l'assegnazione dello stato del bottone a commutazione e dei suoi figli, il radio-bottone e il bottone di controllo. Passando come primo argomento a questa funzione il vostro bottone e come secondo argomento il valore TRUE o FALSE, si può specificare se il bottone deve essere sollevato (rilasciato) o abbassato (premuto). Il valore di difetto è sollevato, cioè FALSE. Notate che quando usate la funzione gtk_toggle_button_set_state(), e lo stato viene cambiato, si ha il risultato che il bottone emette il segnale ``clicked''. <tscreen><verb> void gtk_toggle_button_toggled (GtkToggleButton *toggle_button); </verb></tscreen> Questa funzione semplicemente commuta il bottone, ed emette il segnale ``toggled''.  <sect1> Bottoni di Controllo (Check Buttons) I bottoni di controllo ereditano molte proprietà e funzioni dal bottone a commutazione, ma hanno un aspetto un po' diverso. Invece di essere bottoni contenenti del testo, si tratta di quadratini con del testo alla propria destra. Questi bottoni sono spesso usati nelle applicazioni per commutare fra lo stato attivato e disattivato delle opzioni. Le due funzioni di creazione sono analoghe a quelle del bottone normale.. <tscreen><verb> GtkWidget* gtk_check_button_new (void); GtkWidget* gtk_check_button_new_with_label (gchar *label); </verb></tscreen> La funzione new_with_label crea un bottone di controllo con una etichetta a fianco di esso. Per controllare lo stato del check button si opera in modo identico al bottone a commutazione.  <sect1> Radio-Bottoni (Radio Buttons) I radio-bottoni sono simili ai bottoni di controllo, tranne che per il fatto che sono sempre raggruppati in modo che solo uno alla volta di essi può essere selezionato (premuto). Tornano utili quando nella propria applicazione si ha bisogno di selezionare una opzione da una breve lista. La creazione di un nuovo radio-bottone si fa con una di queste chiamate: <tscreen><verb> GtkWidget* gtk_radio_button_new (GSList *group); GtkWidget* gtk_radio_button_new_with_label (GSList *group, gchar *label); </verb></tscreen> Avrete notato l'argomento in più che c'è in queste chiamate. Queste hanno infatti bisogno dela specificazione di un ``gruppo'' per svolgere il loro compito. Per il primo bottone di un gruppo si deve passare come primo argomento il valore NULL. Dopodiché potete creare un gruppo usando la funzione: <tscreen><verb> GSList* gtk_radio_button_group (GtkRadioButton *radio_button); </verb></tscreen> La cosa importante da ricordare è che gtk_radio_button_group va chiamata ogni volta che si aggiunge un nuovo bottone al gruppo, con il preceente bottone passato come argomento. Il risultato viene poi passato nella chiamata a gtk_radio_button_new o a gtk_radio_button_new_with_label. Ciò permette di creare una catena di bottoni. L'esempio più sotto dovrebbe chiarire questo punto. E' poi una buona idea stabiire quale dev'essere il bottone premuto per difetto, usando: <tscreen><verb> void gtk_toggle_button_set_state (GtkToggleButton *toggle_button, gint state); </verb></tscreen> Questa funzione è descritta nella sezione sui bottoni a commutazione, e funziona nello stesso identico modo. Nel seguente esempio creiamo un gruppo di tre radio-bottoni. <tscreen><verb> /* radiobuttons.c */ #include <gtk/gtk.h> #include <glib.h> void close_application( GtkWidget *widget, gpointer *data ) { gtk_main_quit(); } main(int argc,char *argv[]) { static GtkWidget *window = NULL; GtkWidget *box1; GtkWidget *box2; GtkWidget *button; GtkWidget *separator; GSList *group; gtk_init(&argc,&argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC(close_application), NULL); gtk_window_set_title (GTK_WINDOW (window), "radio buttons"); gtk_container_border_width (GTK_CONTAINER (window), 0); box1 = gtk_vbox_new (FALSE, 0); gtk_container_add (GTK_CONTAINER (window), box1); gtk_widget_show (box1); box2 = gtk_vbox_new (FALSE, 10); gtk_container_border_width (GTK_CONTAINER (box2), 10); gtk_box_pack_start (GTK_BOX (box1), box2, TRUE, TRUE, 0); gtk_widget_show (box2); button = gtk_radio_button_new_with_label (NULL, "button1"); gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0); gtk_widget_show (button); group = gtk_radio_button_group (GTK_RADIO_BUTTON (button)); button = gtk_radio_button_new_with_label(group, "button2"); gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON (button), TRUE); gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0); gtk_widget_show (button); group = gtk_radio_button_group (GTK_RADIO_BUTTON (button)); button = gtk_radio_button_new_with_label(group, "button3"); gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0); gtk_widget_show (button); separator = gtk_hseparator_new (); gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 0); gtk_widget_show (separator); box2 = gtk_vbox_new (FALSE, 10); gtk_container_border_width (GTK_CONTAINER (box2), 10); gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, TRUE, 0); gtk_widget_show (box2); button = gtk_button_new_with_label ("close"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC(close_application), GTK_OBJECT (window)); gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0); GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT); gtk_widget_grab_default (button); gtk_widget_show (button); gtk_widget_show (window); gtk_main(); return(0); } </verb></tscreen> La cosa può essere accorciata un po' usando la seguente sintassi, che elimina la necessità di una variabile per contenere la lista di bottoni: <tscreen><verb> button2 = gtk_radio_button_new_with_label( gtk_radio_button_group (GTK_RADIO_BUTTON (button1)), "button2"); </verb></tscreen>  <sect> Alcuni Widget   <sect1> L'Etichetta (Label) Le etichette sono molto usate in GTK, e sono relativamente semplici. Le etichette non emettono segnali, dal momento che non hanno una finestra X a loro assegnata. Se avete la necessità di avere dei segnali o di fare delle operazioni di clipping, potete usare il widget EventBox. Per creare una nuova etichetta, si usa: <tscreen><verb> GtkWidget* gtk_label_new (char *str); </verb></tscreen> In cui l'unico argomento è la stringa che si vuole sia mostrata. Per cambiare il testo dell'etichetta dopo che è stata creata, si usa la funzione: <tscreen><verb> void gtk_label_set (GtkLabel *label, char *str); </verb></tscreen> in cui il primo argomento è l'etichetta creata in precedenza (di cui si fa il cast usando la macro GTK_LABEL()), mentre il secondo è la nuova stringa. Nel caso, lo spazio necessario per la nuova stringa verrà regolato automaticamente. Per ottenere la stringa corrente si usa: <tscreen><verb> void gtk_label_get (GtkLabel *label, char **str); </verb></tscreen> in cui il primo argomento è l'etichetta che avete creato, e il secondo è il valore di ritorno per la stringa.  <sect1>Il Widget Suggerimenti (Tooltips) I suggerimenti sono piccole stringhe di testo che spuntano quando lasciate il puntatore su un bottone o un altro widget per qualche secondo. Sono piuttosto semplici da usare, per cui ne darò la spiegazione senza corredarla di esempi. Se volede vedere un po' di codice, date un'occhiata al programma testgtk.c distribuito con GTK. Con alcuni widget (per esempio con l'etichetta) i suggerimenti non funzionano. La prima chiamata che si usa per creare un nuovo tooltip è la seguente. In una data funzione, è necessario chiamarla una sola volta: il GtkTooltip che viene ritornato da questa funzione può essere usato per creare suggerimenti multipli. <tscreen><verb> GtkTooltips *gtk_tooltips_new (void); </verb></tscreen> Una volta creato un nuovo suggerimento e il widget su cui lo volete usare, basta usare la seguente chiamata per fare l'assegnazione: <tscreen><verb> void gtk_tooltips_set_tips (GtkTooltips *tooltips, GtkWidget *widget, gchar *tips_text); </verb></tscreen> Il primo argomento è il suggerimento che era già stato creato, che è seguito dal widget da cui volete che spunti il suggerimento e dal testo che volete venga mostrato. Ecco un piccolo esempio: <tscreen><verb> GtkTooltips *tooltips; GtkWidget *button; ... tooltips = gtk_tooltips_new (); button = gtk_button_new_with_label ("button 1"); ... gtk_tooltips_set_tips (tooltips, button, "This is button 1"); </verb></tscreen> Ci sono anche altre funzioni che si usano con i suggerimenti. Eccone una lista con una breve descrizione di quello che fanno. <tscreen><verb> void gtk_tooltips_destroy (GtkTooltips *tooltips); </verb></tscreen> Distrugge un suggerimento esistente. <tscreen><verb> void gtk_tooltips_enable (GtkTooltips *tooltips); </verb></tscreen> Abilita un gruppo di suggerimenti disbilitato. <tscreen><verb> void gtk_tooltips_disable (GtkTooltips *tooltips); </verb></tscreen> Disabilita un gruppo di suggerimenti abilitato. <tscreen><verb> void gtk_tooltips_set_delay (GtkTooltips *tooltips, gint delay); </verb></tscreen> Stabilisce quanti millisecondi si deve mantenere il puntatore sopra al widget prima che venga mostrato il suggerimento. Il valore di difetto è di 1000 millisecondi. <tscreen><verb> void gtk_tooltips_set_tips (GtkTooltips *tooltips, GtkWidget *widget, gchar *tips_text); </verb></tscreen> Cambia il testo di un suggerimento già esistente. <tscreen><verb> void gtk_tooltips_set_colors (GtkTooltips *tooltips, GdkColor *background, GdkColor *foreground); </verb></tscreen> Assegna i colori di primo piano e di sfondo dei suggerimenti. (Non ho idea di come si specifichino i colori). E questo è tutto riguardo alle funzioni relative ai suggerimenti. Più di quanto avreste mai voluto sapere :)  <sect1> La Barra di Avanzamento (Progress Bar) Le barre di avanzamento sono usate per mostrare lo stato di una operazione. Come potete vedere nel frammento di codice qui sotto, sono piuttosto semplici da usare. Ma prima vediamo come cominciare con la chiamata per creare una nuova progress bar. <tscreen><verb> GtkWidget *gtk_progress_bar_new (void); </verb></tscreen> Ora che la barra di avanzamento è stata creata, possiamo usarla.. <tscreen><verb> void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage); </verb></tscreen> Il primo argomento è la barra di avanzamento su cui volete lavorare, e il secondo è la quantità 'completato', cioè la quantità di riempimento della progress bar fra 0 e 100% (un numero reale fra 0 e 1). Le barre di avanzamento sono usate di solito con funzioni di timeout o altre di questo tipo (vedi alla sezione <ref id="sec_timeouts" name="Timeouts, I/O and Idle Functions">) per dare l'illusione del multitasking. Tutte usano la funzione gtk_progress_bar_update nello stesso modo. Ecco un esempio di barra di avanzamento, in cui l'aggiornamento avviene usando dei timeout. Questo codice vi mostra anche come riinizializzare le barre di avanzamento. <tscreen><verb> /* progressbar.c */ #include <gtk/gtk.h> static int ptimer = 0; int pstat = TRUE; /* Questa funzione incrementa e aggiorna la barra di avanzamento, e la rimette a zero se pstat è FALSE */ gint progress (gpointer data) { gfloat pvalue; /* ottiene il valore corrente della status bar */ pvalue = GTK_PROGRESS_BAR (data)->percentage; if ((pvalue >= 1.0) || (pstat == FALSE)) { pvalue = 0.0; pstat = TRUE; } pvalue += 0.01; gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue); return TRUE; } /* Questa funzione segnala la riinizializzazione della barra di avanzamento */ void progress_r (void) { pstat = FALSE; } void destroy (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *button; GtkWidget *label; GtkWidget *table; GtkWidget *pbar; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (destroy), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); table = gtk_table_new(3,2,TRUE); gtk_container_add (GTK_CONTAINER (window), table); label = gtk_label_new ("Progress Bar Example"); gtk_table_attach_defaults(GTK_TABLE(table), label, 0,2,0,1); gtk_widget_show(label); /* Crea una nuova barra di avanzamento, impacchettala nella tabella e mostrala */ pbar = gtk_progress_bar_new (); gtk_table_attach_defaults(GTK_TABLE(table), pbar, 0,2,1,2); gtk_widget_show (pbar); /* Attiva un timeout che gestisca l'aggiornamento automatico della barra */ ptimer = gtk_timeout_add (100, progress, pbar); /* Questo bottone segnala alla barra che deve essere resettata */ button = gtk_button_new_with_label ("Reset"); gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (progress_r), NULL); gtk_table_attach_defaults(GTK_TABLE(table), button, 0,1,2,3); gtk_widget_show(button); button = gtk_button_new_with_label ("Cancel"); gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (destroy), NULL); gtk_table_attach_defaults(GTK_TABLE(table), button, 1,2,2,3); gtk_widget_show (button); gtk_widget_show(table); gtk_widget_show(window); gtk_main (); return 0; } </verb></tscreen> In questo programmino ci sono quattro aree che riguardano il modo di uso generale delle Barre di Avanzamento; le vediamo ora nell'ordine. <tscreen><verb> pbar = gtk_progress_bar_new (); </verb></tscreen> Questo codice crea una nuova barra ciamata pbar. <tscreen><verb> ptimer = gtk_timeout_add (100, progress, pbar); </verb></tscreen> Questo codice usa dei timeout per abilitare degli intervalli di tempo uguali. Per usare le barre di avanzamento non è però necessario servirsi di timeout. <tscreen><verb> pvalue = GTK_PROGRESS_BAR (data)->percentage; </verb></tscreen> Qui si assegna a pvalue il valore corrente della percentuale di avanzamento. <tscreen><verb> gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue); </verb></tscreen> Infine, questo codice aggiorna la barra di avanzamento con il valore di pvalue. Questo è tutto quanto c'è da sapere sulle barre di avanzamento, divertitevi.  <sect1> Dialoghi Il widget ``Dialogo'' è molto semplice: si tratta in realtà di una finestra con alcuni elementi pre-impacchettati. La struttura di un dialogo è la seguente: <tscreen><verb> struct GtkDialog { GtkWindow window; GtkWidget *vbox; GtkWidget *action_area; }; </verb></tscreen> Come potete vedere, crea semplicemente una finestra vi inserisce una vbox in cima, poi un separatore e infine una hbox come ``area di azione''. Un Dialogo può essere utilizzato per messaggi per l'utente e altri scopi simili. E' un widget molto essenziale, che ha una sola funzione, e precisamente: <tscreen><verb> GtkWidget* gtk_dialog_new (void); </verb></tscreen> Per cui, per creare una nuova finestra di dialogo, uate: <tscreen><verb> GtkWidget window; window = gtk_dialog_new (); </verb></tscreen> Questa funzione crea una finestra di dialogo, dopodiché sta a voi utilizzarla. Potete mettere un bottone nella action_area facendo qualcosa del tipo: <tscreen><verb> button = ... gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button, TRUE, TRUE, 0); gtk_widget_show (button); </verb></tscreen> Potreste anche aggiungere, ad esempio, un'etichetta all'area della vbox, con qualcosa di questo genere: <tscreen><verb> label = gtk_label_new ("Dialogs are groovy"); gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->vbox), label, TRUE, TRUE, 0); gtk_widget_show (label); </verb></tscreen> Per provare a usare una finestra di dialogo, potreste provare a mettere due bottoni nella action_area, per esempio un bottone ``Cancella'' ed un bottone ``OK'' e un'etichetta nella vbox che chieda qualcosa all'utente o segnali un errore. Poi potreste collegare un diverso segnale a ciascun bottone ed eseguire l'operazione che l'utente che viene scelta dall'utente.  <sect1> Le Pixmap Le Pixmap sono strutture dati che contengono immagini. Queste immagini possono poi essere utilizzate in varie occasioni, per esempio come icone sul desktop X-Window o come cusori. Una bitmap è una pixmap a due colori. Per usare una pixmap in GTK, dobbiamo in primo luogo creare una struttura GdkPixmap utilizzando le routine disponibili nello strato GDK. Una Pixmap può essere creata a partire da dati presenti in memoria o letti da un file. Vedremo ora una ad una le chiamate utilizzate per creare una pixmap. <tscreen><verb> GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window, gchar *data, gint width, gint height ); </verb></tscreen> Si usa questa routine per creare una pixmap ad un solo piano (2 colori) da dati disponibili in memoria. Ogni bit nei dati indica lo stato acceso o spento di un pixel. L'altezza (height) e la larghezza (width) sono espresse in pixel. GdkWindow è un puntatore alla finestra corrente, dal momento che le risorse di una pixmap hanno significato solo nel contesto dello schermo in cui deve essere mostrata. <tscreen><verb> GdkPixmap* gdk_pixmap_create_from_data( GdkWindow *window, gchar *data, gint width, gint height, gint depth, GdkColor *fg, GdkColor *bg ); </verb></tscreen> Questa è usata per creare una pixmap con la profondità data (depth, ossia numero di colori) usando i dati specificati. fg e bg indicano i colori da usare per il primo piano e per lo sfondo. <tscreen><verb> GdkPixmap* gdk_pixmap_create_from_xpm( GdkWindow *window, GdkBitmap **mask, GdkColor *transparent_color, const gchar *filename ); </verb></tscreen> Il formato XPM è una rappresentazione di pixmap leggibile per X Window. E' una rappresentazione molto diffusa, e sono disponibili parecchi programmi per creare immagini in questo formato. Il file specificato da ``filename'' deve contenere un'immagine in questo formato, che viene caricato nella struttura pixmap. La maschera (mask) specifica quali pixel della pixmap devono essere opachi. Tutti gli altri pixel sono colorati usando il colore specificato da transparent_color. Più sotto mostreremo un esempio di uso di questa funzione. <tscreen><verb> GdkPixmap* gdk_pixmap_create_from_xpm_d (GdkWindow *window, GdkBitmap **mask, GdkColor *transparent_color, gchar **data); </verb></tscreen> Si possono incorporare piccole immagini all'interno di un programma sotto forma di dati in formato XPM. In questo modo, invece di leggerli da un file, si possono usare questi dati per creare una pixmap. Un esempio di questo tipo di dati è <tscreen><verb> /* XPM */ static const char * xpm_data[] = { "16 16 3 1", " c None", ". c #000000000000", "X c #FFFFFFFFFFFF", " ", " ...... ", " .XXX.X. ", " .XXX.XX. ", " .XXX.XXX. ", " .XXX..... ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " ......... ", " ", " "}; </verb></tscreen> <tscreen><verb> void gdk_pixmap_destroy( GdkPixmap *pixmap ); </verb></tscreen> Quando abbiamo finito di usare una pixmap e pensiamo di non doverla riutilizzare presto, è una buona idea liberare queste risorse usando la funzione dk_pixmap_destroy. Le pixmap devono essere considerate una risorsa preziosa. Quando abbiamo creato una pixmap, possiamo mostrarla come un widget GTK. E' necessario creare un widget pixmap che contenga una pixmap GDK. Questa operazione viene compiuta usando <tscreen><verb> GtkWidget* gtk_pixmap_new( GdkPixmap *pixmap, GdkBitmap *mask ); </verb></tscreen> Le altre chiamate per i widget pixmap sono <tscreen><verb> guint gtk_pixmap_get_type( void ); void gtk_pixmap_set( GtkPixmap *pixmap, GdkPixmap *val, GdkBitmap *mask); void gtk_pixmap_get( GtkPixmap *pixmap, GdkPixmap **val, GdkBitmap **mask); </verb></tscreen> La funzione gtk_pixmap_set viene usata per cambiare la pixmap che viene gestita correntemente dal widget. gtk_pixmap_set is used to change the pixmap that the widget is currently managing. ``val'' è la pixmap che è stata creata usando il GDK. Segue un esempio di uso di una pixmap in un bottone. <tscreen><verb> /* pixmap.c */ #include <gtk/gtk.h> /* dat XPM dell'icona Apri File */ static const char * xpm_data[] = { "16 16 3 1", " c None", ". c #000000000000", "X c #FFFFFFFFFFFF", " ", " ...... ", " .XXX.X. ", " .XXX.XX. ", " .XXX.XXX. ", " .XXX..... ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " .XXXXXXX. ", " ......... ", " ", " "}; /* quando invocata (con il segnale delete_event), termina l'applicazione. */ void close_application( GtkWidget *widget, gpointer *data ) { gtk_main_quit(); } /* invocata se il bottone è clickato. Stampa semplicemente un messaggio */ void button_clicked( GtkWidget *widget, gpointer *data ) { printf( "button clicked\n" ); } int main( int argc, char *argv[] ) { /* i widget sono memorizzati nel tipo GtkWidget */ GtkWidget *window, *pixmapwid, *button; GdkPixmap *pixmap; GdkBitmap *mask; GtkStyle *style; /* crea la finestra principale, e collega il segnale delete_event alla terminazione dell'applicazione */ gtk_init( &argc, &argv ); window = gtk_window_new( GTK_WINDOW_TOPLEVEL ); gtk_signal_connect( GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (close_application), NULL ); gtk_container_border_width( GTK_CONTAINER (window), 10 ); gtk_widget_show( window ); /* la pixmap proviene da gdk */ style = gtk_widget_get_style( window ); pixmap = gdk_pixmap_create_from_xpm_d( window->window, &mask, &style->bg[GTK_STATE_NORMAL], (gchar **)xpm_data ); /* un widget pixmap per contenere la pixmap */ pixmapwid = gtk_pixmap_new( pixmap, mask ); gtk_widget_show( pixmapwid ); /* un bottone per contenere il widget pixmap */ button = gtk_button_new(); gtk_container_add( GTK_CONTAINER(button), pixmapwid ); gtk_container_add( GTK_CONTAINER(window), button ); gtk_widget_show( button ); gtk_signal_connect( GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC(button_clicked), NULL ); /* mostra la finestra */ gtk_main (); return 0; } </verb></tscreen> Per caricare una pixmap da un file XPM chiamato icon0.xpm che si trova nella direttorio corrente, avremmo creato la pixmap in questo modo: <tscreen><verb> /* carica una pixmap da un file */ pixmap = gdk_pixmap_create_from_xpm( window->window, &mask, &style->bg[GTK_STATE_NORMAL], "./icon0.xpm" ); pixmapwid = gtk_pixmap_new( pixmap, mask ); gtk_widget_show( pixmapwid ); gtk_container_add( GTK_CONTAINER(window), pixmapwid ); </verb></tscreen> Usare le Sagome Uno degli svantaggi di usare le pixmap è costituito dal fatto che l'oggetto mostrato è sempre rettangolare, a prescindere dall'immagine. Ci piacerebbe invece poter crare dei desktop e delle immagini con forme più naturali. Per esempio, per l'interfaccia di un gioco, potremmo volere avere dei pulsanti circolari. Il modo per ottenere questo effetto è di usare delle finestre sagomate. Una finestra sagomata è semplicemente una pixmap in cui i pixel dello sfondo sono trasparenti. In questo modo, se l'immagine di sfondo è multicolore, possiamo evitare di sovrascriverla con un bordo rettangolare attorno all'icona. Il prossimo esempio mostra una carriola sul desktop. <tscreen><verb> /* wheelbarrow.c */ #include <gtk/gtk.h> /* XPM */ static char * WheelbarrowFull_xpm[] = { "48 48 64 1", " c None", ". c #DF7DCF3CC71B", "X c #965875D669A6", "o c #71C671C671C6", "O c #A699A289A699", "+ c #965892489658", "@ c #8E38410330C2", "# c #D75C7DF769A6", "$ c #F7DECF3CC71B", "% c #96588A288E38", "& c #A69992489E79", "* c #8E3886178E38", "= c #104008200820", "- c #596510401040", "; c #C71B30C230C2", ": c #C71B9A699658", "> c #618561856185", ", c #20811C712081", "< c #104000000000", "1 c #861720812081", "2 c #DF7D4D344103", "3 c #79E769A671C6", "4 c #861782078617", "5 c #41033CF34103", "6 c #000000000000", "7 c #49241C711040", "8 c #492445144924", "9 c #082008200820", "0 c #69A618611861", "q c #B6DA71C65144", "w c #410330C238E3", "e c #CF3CBAEAB6DA", "r c #71C6451430C2", "t c #EFBEDB6CD75C", "y c #28A208200820", "u c #186110401040", "i c #596528A21861", "p c #71C661855965", "a c #A69996589658", "s c #30C228A230C2", "d c #BEFBA289AEBA", "f c #596545145144", "g c #30C230C230C2", "h c #8E3882078617", "j c #208118612081", "k c #38E30C300820", "l c #30C2208128A2", "z c #38E328A238E3", "x c #514438E34924", "c c #618555555965", "v c #30C2208130C2", "b c #38E328A230C2", "n c #28A228A228A2", "m c #41032CB228A2", "M c #104010401040", "N c #492438E34103", "B c #28A2208128A2", "V c #A699596538E3", "C c #30C21C711040", "Z c #30C218611040", "A c #965865955965", "S c #618534D32081", "D c #38E31C711040", "F c #082000000820", " ", " .XoO ", " +@#$%o& ", " *=-;#::o+ ", " >,<12#:34 ", " 45671#:X3 ", " +89<02qwo ", "e* >,67;ro ", "ty> 459@>+&& ", "$2u+ ><ipas8* ", "%$;=* *3:.Xa.dfg> ", "Oh$;ya *3d.a8j,Xe.d3g8+ ", " Oh$;ka *3d$a8lz,,xxc:.e3g54 ", " Oh$;kO *pd$%svbzz,sxxxxfX..&wn> ", " Oh$@mO *3dthwlsslszjzxxxxxxx3:td8M4 ", " Oh$@g& *3d$XNlvvvlllm,mNwxxxxxxxfa.:,B* ", " Oh$@,Od.czlllllzlmmqV@V#V@fxxxxxxxf:%j5& ", " Oh$1hd5lllslllCCZrV#r#:#2AxxxxxxxxxcdwM* ", " OXq6c.%8vvvllZZiqqApA:mq:Xxcpcxxxxxfdc9* ", " 2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ", " :,q-6MN.dfmZZrrSS:#riirDSAX@Af5xxxxxfevo", " +A26jguXtAZZZC7iDiCCrVVii7Cmmmxxxxxx%3g", " *#16jszN..3DZZZZrCVSA2rZrV7Dmmwxxxx&en", " p2yFvzssXe:fCZZCiiD7iiZDiDSSZwwxx8e*>", " OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ", " 3206Bwxxszx%et.eaAp77m77mmmf3&eeeg* ", " @26MvzxNzvlbwfpdettttttttttt.c,n& ", " *;16=lsNwwNwgsvslbwwvccc3pcfu<o ", " p;<69BvwwsszslllbBlllllllu<5+ ", " OS0y6FBlvvvzvzss,u=Blllj=54 ", " c1-699Blvlllllu7k96MMMg4 ", " *10y8n6FjvllllB<166668 ", " S-kg+>666<M<996-y6n<8* ", " p71=4 m69996kD8Z-66698&& ", " &i0ycm6n4 ogk17,0<6666g ", " N-k-<> >=01-kuu666> ", " ,6ky& &46-10ul,66, ", " Ou0<> o66y<ulw<66& ", " *kk5 >66By7=xu664 ", " <<M4 466lj<Mxu66o ", " *>> +66uv,zN666* ", " 566,xxj669 ", " 4666FF666> ", " >966666M ", " oM6668+ ", " *4 ", " ", " "}; /* quando invocata (con il segnale delete_event), termina l'applicazione. */ void close_application( GtkWidget *widget, gpointer *data ) { gtk_main_quit(); } int main (int argc, char *argv[]) { /* il tipo di dato per i widget è GtkWidget */ GtkWidget *window, *pixmap, *fixed; GdkPixmap *gdk_pixmap; GdkBitmap *mask; GtkStyle *style; GdkGC *gc; /* crea la finestra principale e collega il segnale delete_event per terminare l'applicazione. Notare che non mettiamo un titolo alla finestra. */ gtk_init (&argc, &argv); window = gtk_window_new( GTK_WINDOW_POPUP ); gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC (close_application), NULL); gtk_widget_show (window); /* ora occupiamoci della pixmap e del widget pixmap */ style = gtk_widget_get_default_style(); gc = style->black_gc; gdk_pixmap = gdk_pixmap_create_from_xpm_d( window->window, &mask, &style->bg[GTK_STATE_NORMAL], WheelbarrowFull_xpm ); pixmap = gtk_pixmap_new( gdk_pixmap, mask ); gtk_widget_show( pixmap ); /* Per mostrare la pixmap, usiamo un widget "fixed" in cui metterla */ fixed = gtk_fixed_new(); gtk_widget_set_usize( fixed, 200, 200 ); gtk_fixed_put( GTK_FIXED(fixed), pixmap, 0, 0 ); gtk_container_add( GTK_CONTAINER(window), fixed ); gtk_widget_show( fixed ); /* Questa maschera tutto tranne l'immagine stessa */ gtk_widget_shape_combine_mask( window, mask, 0, 0 ); /* mostra la finestra */ gtk_widget_set_uposition( window, 20, 400 ); gtk_widget_show( window ); gtk_main (); return 0; } </verb></tscreen> Per rendere sensibile l'immagine della carriola, potremmo collegare il segnale di pressione del bottone in modo che venga compiuta una certa azione. Le prossime linee renderebbero l'immagine sensibile alla pressione di un bottone del mouse che fa sì che l'applicazione termini. <tscreen><verb> gtk_widget_set_events( window, gtk_widget_get_events( window ) | GDK_BUTTON_PRESS_MASK ); gtk_signal_connect( GTK_OBJECT(window), "button_press_event", GTK_SIGNAL_FUNC(close_application), NULL ); </verb></tscreen>  <sect1>Righelli I widget righello vengono usati per indicare la posizione del pontatore del mouse in una certa finestra. Una finestra può cioé avere un righello orizzontale che si estende per tutta la sua ampiezza e un righello verticale che ne comprende l'altezza. Un piccolo triangolo sui rghelli indica la posizione esatta del puntatore relativamente ai righelli. I righelli devono essere in primo luogo creati. I righlli orizzontali e verticali vengono creati usando <tscreen><verb> GtkWidget *gtk_hruler_new(void); /* horizontal ruler */ GtkWidget *gtk_vruler_new(void); /* vertical ruler */ </verb></tscreen> Una volta che che si è creato il righello, si può l'unità di misura. Le unità di misura possono essere GTK_PIXELS, GTK_INCHES oppure GTK_CENTIMETERS. Ciò viene stabilito usando <tscreen><verb> void gtk_ruler_set_metric( GtkRuler *ruler, GtkMetricType metric ); </verb></tscreen> La misura predefinita è GTK_PIXELS. <tscreen><verb> gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS ); </verb></tscreen> Altre caratteritiche importanti di un righello sono il modo in cui vengono segnate le tacche delle unità di misura e dove viene posto inizialmente l'indicatore di posizione. Questi vengono stabiliti usando <tscreen><verb> void gtk_ruler_set_range (GtkRuler *ruler, gfloat lower, gfloat upper, gfloat position, gfloat max_size); </verb></tscreen> Gli argomenti lower e upper definiscono l'estensione del righello, e max_size rappresenta il numero massimo che verrà mostrato. Position definisce l posizione iniziale dell'indicatore del puntatore all'interno del righello. Quindi, un righello che può stare su una finestra di 800 pixel sarà: <tscreen><verb> gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800); </verb></tscreen> Sul righello saranno presenti dei segni da 0 a 800, con un numero ogni 100 pixel. Se avessimo invece voluto che il righello fosse andato da 7 a 16, avremmo scritto: <tscreen><verb> gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20); </verb></tscreen> L'indicatore sul righello è un piccolo segno triangolare che indica la posizione del puntatore rispetto al righello. Se il righello viene usato per seguire il movimento del mouse, il segnale di motion_notify_event dovrebbe venir connesso al metodo motion_notify_event del righello. Per seguire tutti i movimenti del mouse all'interno dell'area di una finestra, useremmo: <tscreen><verb> #define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event", (GtkSignalFunc)EVENT_METHOD(ruler, motion_notify_event), GTK_OBJECT(ruler) ); </verb></tscreen> L'esempio seguente crea un'area di disegno con un reghello orizzontale nella parte superiore e un righello verticale nella parte sinistra. Le dimensioni di questa area di disegno sono di 600 e 400 pixel risettivamente per la larghezza e per l'altezza. Il righello orizzontale va da 7 a 13 con una tacca ogni 100 pixel, mentre quello verticale va da 0 a 400, ancora con una tacca ogni 100 pixel. La sistemazione dell'area di disegno e dei righelli viene fatta usando una tabella. <tscreen><verb> /* rulers.c */ #include <gtk/gtk.h> #define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x #define XSIZE 600 #define YSIZE 400 /* il controllo raggiunge questa routine quando si preme il bottone close */ void close_application( GtkWidget *widget, gpointer *data ) { gtk_main_quit(); } /* la routine principale */ int main( int argc, char *argv[] ) { GtkWidget *window, *table, *area, *hrule, *vrule; /* inizializziamo gtk e creiamo la finestra principale */ gtk_init( &argc, &argv ); window = gtk_window_new( GTK_WINDOW_TOPLEVEL ); gtk_signal_connect (GTK_OBJECT (window), "delete_event", GTK_SIGNAL_FUNC( close_application ), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* creiamo una tabella in cui mettere righelli e area di disegno */ table = gtk_table_new( 3, 2, FALSE ); gtk_container_add( GTK_CONTAINER(window), table ); area = gtk_drawing_area_new(); gtk_drawing_area_size( (GtkDrawingArea *)area, XSIZE, YSIZE ); gtk_table_attach( GTK_TABLE(table), area, 1, 2, 1, 2, GTK_EXPAND|GTK_FILL, GTK_FILL, 0, 0 ); gtk_widget_set_events( area, GDK_POINTER_MOTION_MASK | GDK_POINTER_MOTION_HINT_MASK ); /* Il righello orizzontale va nella parte superiore. Quando il mouse si muove * nell'area di disegno, si passa un motion_notify_event al gestore appropriato * per il righello. */ hrule = gtk_hruler_new(); gtk_ruler_set_metric( GTK_RULER(hrule), GTK_PIXELS ); gtk_ruler_set_range( GTK_RULER(hrule), 7, 13, 0, 20 ); gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event", (GtkSignalFunc)EVENT_METHOD(hrule, motion_notify_event), GTK_OBJECT(hrule) ); /* GTK_WIDGET_CLASS(GTK_OBJECT(hrule)->klass)->motion_notify_event, */ gtk_table_attach( GTK_TABLE(table), hrule, 1, 2, 0, 1, GTK_EXPAND|GTK_SHRINK|GTK_FILL, GTK_FILL, 0, 0 ); /* Il righello verticale va nella parte sinistra. Quando il mouse si muove * nell'area di disegno, si passa un motion_notify_event al gestore appropriato * per il righello. */ vrule = gtk_vruler_new(); gtk_ruler_set_metric( GTK_RULER(vrule), GTK_PIXELS ); gtk_ruler_set_range( GTK_RULER(vrule), 0, YSIZE, 10, YSIZE ); gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event", (GtkSignalFunc) GTK_WIDGET_CLASS(GTK_OBJECT(vrule)->klass)-motion_notify_event, GTK_OBJECT(vrule) ); gtk_table_attach( GTK_TABLE(table), vrule, 0, 1, 1, 2, GTK_FILL, GTK_EXPAND|GTK_SHRINK|GTK_FILL, 0, 0 ); /* ora mostriamo tutto quanto */ gtk_widget_show( area ); gtk_widget_show( hrule ); gtk_widget_show( vrule ); gtk_widget_show( table ); gtk_widget_show( window ); gtk_main(); return 0; } </verb></tscreen>  <sect1>Barre di Stato (Statusbar) Le barre di stato sono dei semplici widget usati per mostrare messaggi di test. Hanno la caratteristica di mantenere uno stack dei messggi che vi vengono mostrati, cosiccheé rimuovendo il messaggio corrente fa sì che torni ad essere mostrato il messaggio precedente.. Per permettere a parti diverse di una stessa applicazione di usare la stessa barra di stato per mostrare messaggi, questo widget emette degli 'Identificatori di Contesto' che vengono usati per identificare i diversi 'utenti'. Quello che viene mostrato è sempre il messaggio che si trova in cima allo stack, a prescindere in quale contesto si trovi. I messaggi vengono immagazzinati secondo l'ordine LIFO, e non secondo l'ordine stabilito dal contesto. Una barra di stato viene creata con una chiamata a: <tscreen><verb> GtkWidget* gtk_statusbar_new (void); </verb></tscreen> Per richiedere un nuovo identificatore di contesto, si usa una chiamata alla seguente funzione con una breve descrizione testuale: <tscreen><verb> guint gtk_statusbar_get_context_id (GtkStatusbar *statusbar, const gchar *context_description); </verb></tscreen> Le seguenti sono tre funzioni che possono operare sulle barre di stato: <tscreen><verb> guint gtk_statusbar_push (GtkStatusbar *statusbar, guint context_id, gchar *text); void gtk_statusbar_pop (GtkStatusbar *statusbar) guint context_id); void gtk_statusbar_remove (GtkStatusbar *statusbar, guint context_id, guint message_id); </verb></tscreen> La prima, gtk_statusbar_push, viene usata per aggiungere un nuovo messaggio alla barra di stato. Questa restituisce un identificatore di messaggio, che può essere passato successivamente alla funzione gtk_statusbar_remove per rimuovere dallo stack il messggio con identificatore di messaggio e di contesto dati. La funzione gtk_statusbar_pop rimuove il messaggio che si trova in cima allo stack avente un dato identificatore di contesto. Nel seguente esempio si crea una barra di stato e due bottoni, uno per mettere elementi sulla barra di stato e l'altro per riuovere l'ultimo elemento.. <tscreen><verb> /* statusbar.c */ #include <gtk/gtk.h> #include <glib.h> GtkWidget *status_bar; void push_item (GtkWidget *widget, gpointer *data) { static int count = 1; char buff[20]; g_snprintf(buff, 20, "Item %d", count++); gtk_statusbar_push( GTK_STATUSBAR(status_bar), (guint) &data, buff); return; } void pop_item (GtkWidget *widget, gpointer *data) { gtk_statusbar_pop( GTK_STATUSBAR(status_bar), (guint) &data ); return; } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *vbox; GtkWidget *button; int context_id; gtk_init (&argc, &argv); /* creazione di una nuova finestra */ window = gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_widget_set_usize( GTK_WIDGET (window), 200, 100); gtk_window_set_title(GTK_WINDOW (window), "GTK Statusbar Example"); gtk_signal_connect(GTK_OBJECT (window), "delete_event", (GtkSignalFunc) gtk_exit, NULL); vbox = gtk_vbox_new(FALSE, 1); gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); status_bar = gtk_statusbar_new(); gtk_box_pack_start (GTK_BOX (vbox), status_bar, TRUE, TRUE, 0); gtk_widget_show (status_bar); context_id = gtk_statusbar_get_context_id( GTK_STATUSBAR(status_bar), "Statusbar example"); button = gtk_button_new_with_label("push item"); gtk_signal_connect(GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC (push_item), &context_id); gtk_box_pack_start(GTK_BOX(vbox), button, TRUE, TRUE, 2); gtk_widget_show(button); button = gtk_button_new_with_label("pop last item"); gtk_signal_connect(GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC (pop_item), &context_id); gtk_box_pack_start(GTK_BOX(vbox), button, TRUE, TRUE, 2); gtk_widget_show(button); /* la finestra va sempre mostrata come ultimo passo, in modo che venga * sullo schermo tutta in una volta. */ gtk_widget_show(window); gtk_main (); return 0; } </verb></tscreen>  <sect1>Inserimento di testo Questo widget permette diinserire e mostrare del testo in una casella contenente una sola linea. Il testo può essere assegnato con chiamate di funzione che permettono a nuovo testo di sostituire, seguire o precedere il contenuto corrente del widget di inserimento testo. Per la creazione di un inserimento di testo, sono disponibili due funzioni: <tscreen><verb> GtkWidget* gtk_entry_new (void); GtkWidget* gtk_entry_new_with_max_length (guint16 max); </verb></tscreen> La prima crea solamente un inserimento di testo, mentre la seconda lo crea imponendo un limite alla lunghezza del testo inseribile.. Per cambiaere il testo che si trova correntemente nel widget, sono disponibili diverse funzioni. <tscreen><verb> void gtk_entry_set_text (GtkEntry *entry, const gchar *text); void gtk_entry_append_text (GtkEntry *entry, const gchar *text); void gtk_entry_prepend_text (GtkEntry *entry, const gchar *text); </verb></tscreen> La funzione gtk_entry_set_text assegna il contenuto del widget di inserimento, sostituendo il contenuto corrente. Le funzioni gtk_entry_append_text e gtk_entry_prepend_text permettono di antemporre o posporre un testo al testo corrente.. La prossima funzione permette di stabilire il punto di inserimento. <tscreen><verb> void gtk_entry_set_position (GtkEntry *entry, gint position); </verb></tscreen> Usando la seguente funzione, è possibile estrarre il contenuto di un widget di inserimento. Ciò può essere utile nelle funzioni di ritorno come descritto più sotto. <tscreen><verb> gchar* gtk_entry_get_text (GtkEntry *entry); </verb></tscreen> Se non si vuole che qualcuno possa cambiare il contenuto di una entry sovrascrivendola, ne possiamo cambiare lo stato di "editabilità".. <tscreen><verb> void gtk_entry_set_editable (GtkEntry *entry, gboolean editable); </verb></tscreen> Questa funzine ci permette di far passare un widget di inserimento dallo sato di editabile a quello di non editabile passando con l'argomento editable i valori TRUE o FALSE. Se stiamo usando l'entry in un punto in cui non vogliamo che il testo sia visibile, per esempio quando si digita una password, possiamo usare la seguente funzione, che accetta un parametro booleano.. <tscreen><verb> void gtk_entry_set_visibility (GtkEntry *entry, gboolean visible); </verb></tscreen> Si può stabilire che una parte del testo risulti selezionata usado la seguente funzione. Si userà di solito questa possibilità dopo aver inserito nel widget un qualche valore predefinito, in modo che per l'utente sia semplice sostituirlo. <tscreen><verb> void gtk_entry_select_region (GtkEntry *entry, gint start, gint end); </verb></tscreen> Se vogliamo accorgerci del momento in cui l'utente ha inserito del testo, possiamo connettere il segnale <tt/activate/ o <tt/changed/. <tt/activate/ viene reso attivo quando l'utente preme il tasto Enter mentre si trova nel widget. <tt/changed/ viene invece emesso ogni volta che il testo cambia, per esempio ogni volta che viene inserito o rimosso un carattere. Il seguente codice mostra un esempio di utilizzo del widget di inserimento. . <tscreen><verb> /* entry.c */ #include <gtk/gtk.h> void enter_callback(GtkWidget *widget, GtkWidget *entry) { gchar *entry_text; entry_text = gtk_entry_get_text(GTK_ENTRY(entry)); printf("Entry contents: %s\n", entry_text); } void entry_toggle_editable (GtkWidget *checkbutton, GtkWidget *entry) { gtk_entry_set_editable(GTK_ENTRY(entry), GTK_TOGGLE_BUTTON(checkbutton)->active); } void entry_toggle_visibility (GtkWidget *checkbutton, GtkWidget *entry) { gtk_entry_set_visibility(GTK_ENTRY(entry), GTK_TOGGLE_BUTTON(checkbutton)->active); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *vbox, *hbox; GtkWidget *entry; GtkWidget *button; GtkWidget *check; gtk_init (&argc, &argv); /* creiamo una nuova finestra */ window = gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_widget_set_usize( GTK_WIDGET (window), 200, 100); gtk_window_set_title(GTK_WINDOW (window), "GTK Entry"); gtk_signal_connect(GTK_OBJECT (window), "delete_event", (GtkSignalFunc) gtk_exit, NULL); vbox = gtk_vbox_new (FALSE, 0); gtk_container_add (GTK_CONTAINER (window), vbox); gtk_widget_show (vbox); entry = gtk_entry_new_with_max_length (50); gtk_signal_connect(GTK_OBJECT(entry), "activate", GTK_SIGNAL_FUNC(enter_callback), entry); gtk_entry_set_text (GTK_ENTRY (entry), "hello"); gtk_entry_append_text (GTK_ENTRY (entry), " world"); gtk_entry_select_region (GTK_ENTRY (entry), 0, GTK_ENTRY(entry)->text_length); gtk_box_pack_start (GTK_BOX (vbox), entry, TRUE, TRUE, 0); gtk_widget_show (entry); hbox = gtk_hbox_new (FALSE, 0); gtk_container_add (GTK_CONTAINER (vbox), hbox); gtk_widget_show (hbox); check = gtk_check_button_new_with_label("Editable"); gtk_box_pack_start (GTK_BOX (hbox), check, TRUE, TRUE, 0); gtk_signal_connect (GTK_OBJECT(check), "toggled", GTK_SIGNAL_FUNC(entry_toggle_editable), entry); gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(check), TRUE); gtk_widget_show (check); check = gtk_check_button_new_with_label("Visible"); gtk_box_pack_start (GTK_BOX (hbox), check, TRUE, TRUE, 0); gtk_signal_connect (GTK_OBJECT(check), "toggled", GTK_SIGNAL_FUNC(entry_toggle_visibility), entry); gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(check), TRUE); gtk_widget_show (check); button = gtk_button_new_with_label ("Close"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC(gtk_exit), GTK_OBJECT (window)); gtk_box_pack_start (GTK_BOX (vbox), button, TRUE, TRUE, 0); GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT); gtk_widget_grab_default (button); gtk_widget_show (button); gtk_widget_show(window); gtk_main(); return(0); } </verb></tscreen>  <sect1> Selettori di Colore Il widget selettore di colore è chiaramente un widget che permtte di scegliere interattivamente dei colori. Questo widget composto permette all'utente di selezionare un colore agendo su terne RGB (Red, Green, Blue) e HSV (Hue, Saturation, Value). Questo lo si può fare o agendo sui singoli valori tramite degli slider o inserendoli da tastiera, oppure selezionando direttamente il colore da un cerchio (valori H e S) e da una barra (valore V). Opzionalmente, è possibile anche stabilire il grado di trasparenza del colore. Il widget di selezione di colore emette per ora un solo segnale, "color_changed", che viene generato ogni volta che il colore corrente nel widget cambia, sia quando è l'utente a cambiarlo, sia quando viene modificato esplicitamente tramite una chiamata a gtk_color_selection_set_color(). Diamo ora un'occhiata a cosa ha da offrirci il widget di selezione di colore. Il widget è disponibile in due versioni, gtk_color_selection e gtk_color_selection_dialog: <tscreen><verb> GtkWidget *gtk_color_selection_new(void); </verb></tscreen> E' probabile che non userete questo costruttore direttamente. Infatti esso crea un widget GtkColorSelection orfano a cui dovrete assegnare un genitore voi stessi. Il widget GtkColorSelection eredita dal widget GtkVBox. <tscreen><verb> GtkWidget *gtk_color_selection_dialog_new(const gchar *title); </verb></tscreen> Questo è il più comune fra i costruttori di selettori di colore. Esso crea un GtkColorSelectionDialog, che eredita da GtkDialog. Esso consiste di un GtkFrame che contiene un widget GtkColorSelection, un GtkHSeparator e un GtkHBox con tre bottoni, "Ok", "Cancel" e "Help". Si arriva a questi bottoni accedendo ai widget "ok_button", "cancel_button" e "help_button" nella struttura GtkColorSelectionDialog (cioè (GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button). <tscreen><verb> void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel, GtkUpdateType policy); </verb></tscreen> Questa funzione stabilisce la politica di aggiornamento. Quella predefinita è GTK_UPDATE_CONTINOUS, che significa che il colore viene aggiornato continuamente mano a mano che l'utente trascina gli slider o preme e trascina il mouse nel cerchio della hue-saturation o nella relativa barra. Se si hanno problemi di prestazioni, si può decidere di usare la politica GTK_UPDATE_DISCONTINOUS o GTK_UPDATE_DELAYED. <tscreen><verb> void gtk_color_selection_set_opacity(GtkColorSelection *colorsel, gint use_opacity); </verb></tscreen> Il widget di selezione di colore permette anche di variare l'opacità di un colore (conosciuta anche come canale alfa). Questa caratteristica è normalmente disabilitata. Chiamare la precedente funzione, con use_opacity uguale a TRUE abilita la manipolazione dell'opacità. Analogamente, mettendo use_opacity uguale a FALSE la disabiliterà. <tscreen><verb> void gtk_color_selection_set_color(GtkColorSelection *colorsel, gdouble *color); </verb></tscreen> Si può assegnare esplicitamente un colore chiamando questa funzione con un puntatore ad un vettore di colori (gdouble). La lunghezza del vettore dipende dall'attivazione o meno del controllo dell'opacità. La posizione 0 contiene la componente rossa, la 1 ` il verde, la 2 il blu e la 3 contiene l'opacità (se questa ` attivata, come si è detto per gtk_color_selection_set_opacity()). Tutti i valori sono compresi fra 0.0 e 1.0. <tscreen><verb> void gtk_color_selection_get_color(GtkColorSelection *colorsel, gdouble *color); </verb></tscreen> Questa funzione viene usata per ottenere il colore corrente, tipicamente quando si è ricevuto il segnale "color_changed". Color è un puntatore al vettore di colori da riempire. Vedi la descrizione di questo vettore nella funzione gtk_color_selection_set_color().  Ecco un semplice esempio che mostra l'uso di GtkColorSelectionDialog. Il programma mostra una finestra che contiene un'area di disegno. Cliccandoci sopra, si apre un dialogo di selezione di colore, e se si modifica il colore nella finestra di dialogo verrà cambiato anche il colore dello sfondo. <tscreen><verb> #include <glib.h> #include <gdk/gdk.h> #include <gtk/gtk.h> GtkWidget *colorseldlg = NULL; GtkWidget *drawingarea = NULL; /* gestore del cambiamento del colore */ void color_changed_cb (GtkWidget *widget, GtkColorSelection *colorsel) { gdouble color[3]; GdkColor gdk_color; GdkColormap *colormap; /* recupera la colormap dell'area di disegno */ colormap = gdk_window_get_colormap (drawingarea->window); /* recupera il colore corrente */ gtk_color_selection_get_color (colorsel,color); /* adattamento ad un intero unsigned di 16 bit (0..65535) * e inseriscili nella struttura GdkColor */ gdk_color.red = (guint16)(color[0]*65535.0); gdk_color.green = (guint16)(color[1]*65535.0); gdk_color.blue = (guint16)(color[2]*65535.0); /* Alloca il colore */ gdk_color_alloc (colormap, &gdk_color); /* assegna il colore di sfondo della finestra */ gdk_window_set_background (drawingarea->window, &gdk_color); /* pulisce la finestra */ gdk_window_clear (drawingarea->window); } /* gestore per l'area di disegno */ gint area_event (GtkWidget *widget, GdkEvent *event, gpointer client_data) { gint handled = FALSE; GtkWidget *colorsel; /* controlliamo se abbiamo ricevuto un evento di pressione di pulsante */ if (event->type == GDK_BUTTON_PRESS && colorseldlg == NULL) { /* Si , c'e' l'evento e ancora non c'e' alcun colorseldlg! */ handled = TRUE; /* Creiamo una finestra di dialogo per la selezione del colore */ colorseldlg = gtk_color_selection_dialog_new("Select background color"); /* Otteniamo il widget GtkColorSelection */ colorsel = GTK_COLOR_SELECTION_DIALOG(colorseldlg)->colorsel; /* Facciamo la connessione al segnale "color_changed", * ed assegnamo i dati-utente al widget di selezione di colore */ gtk_signal_connect(GTK_OBJECT(colorsel), "color_changed", (GtkSignalFunc)color_changed_cb, (gpointer)colorsel); /* Mostriamo il dialogo */ gtk_widget_show(colorseldlg); } return handled; } /* Chiusura ed uscita dal getore */ void destroy_window (GtkWidget *widget, gpointer client_data) { gtk_main_quit (); } /* Main */ gint main (gint argc, gchar *argv[]) { GtkWidget *window; /* Inizialliziamo il toolkit, remuoviamo gli argomenti sulla linea di * comando legati a gtk */ gtk_init (&argc,&argv); /* creiamo la finestra base, con titolo e politiche */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW(window), "Color selection test"); gtk_window_set_policy (GTK_WINDOW(window), TRUE, TRUE, TRUE); /* colleghiamo gli eventi "delete" e "destroy" per poter uscire */ gtk_signal_connect (GTK_OBJECT(window), "delete_event", (GtkSignalFunc)destroy_window, (gpointer)window); gtk_signal_connect (GTK_OBJECT(window), "destroy", (GtkSignalFunc)destroy_window, (gpointer)window); /* crea un'area di disegna, stabilisce le dimensioni e raccogli * gli eventi */ drawingarea = gtk_drawing_area_new (); gtk_drawing_area_size (GTK_DRAWING_AREA(drawingarea), 200, 200); gtk_widget_set_events (drawingarea, GDK_BUTTON_PRESS_MASK); gtk_signal_connect (GTK_OBJECT(drawingarea), "event", (GtkSignalFunc)area_event, (gpointer)drawingarea); /* aggiungi l'area di disegno alla finestra e mostrale entrambe */ gtk_container_add (GTK_CONTAINER(window), drawingarea); gtk_widget_show (drawingarea); gtk_widget_show (window); /* entra nel ciclo principale di gtk (che non cede mai il controllo */ gtk_main (); /* soddisfa i compilatori brontoloni */ return 0; } </verb></tscreen>  <sect1> Selezione di File (File Selections) Il widget Selezione di File è un modo rapido e semplice per mostrare una finestra di dialogo `File'. Questa si presenta completa di bottoni Ok, Cancel e Help, un buon modo per tagliare i tempi di programmazione. Per creare una nuova finestra di selezione file usate: <tscreen><verb> GtkWidget* gtk_file_selection_new (gchar *title); </verb></tscreen> Per assegnare il nome del file, ad esempio per predisporre una certa directory o per dare un certo nome di file per difetto, usate la seguente funzione: <tscreen><verb> void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename); </verb></tscreen> Per recuperare il testo che l'utente ha inserito o che ha selezionato con il mouse, si usa la funzione: <tscreen><verb> gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel); </verb></tscreen> Ci sono anche dei puntatori ai widget che sono contenuti all'interno del widget di selezione file. Si tratta di: <itemize> <item>dir_list <item>file_list <item>selection_entry <item>selection_text <item>main_vbox <item>ok_button <item>cancel_button <item>help_button </itemize> Molto probabilmente potreste voler usare i puntatori a ok_button, cancel_button e help_button per segnalarne l'uso. Ecco un esempio rubato da testgtk.c, nodificato per essere eseguito da solo. Come potrete vedere, non c'è molto più che la creazione di un widget di selezione file. In questo esempio, il bottone Help non fa nulla mentre è mostrato allo schermo, dal momento che non c'è alcun segnale collegato con esso. <tscreen><verb> /* filesel.c */ #include <gtk/gtk.h> /* Recupera il nome di file selezionato e stampalo a console */ void file_ok_sel (GtkWidget *w, GtkFileSelection *fs) { g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs))); } void destroy (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } int main (int argc, char *argv[]) { GtkWidget *filew; gtk_init (&argc, &argv); /* Crea un nuovo widget di selezione file */ filew = gtk_file_selection_new ("File selection"); gtk_signal_connect (GTK_OBJECT (filew), "destroy", (GtkSignalFunc) destroy, &filew); /* Connette ok_button alla funzione file_ok_sel */ gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button), "clicked", (GtkSignalFunc) file_ok_sel, filew ); /* Connette cancel_button alla funzione di distruzione del widget */ gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button), "clicked", (GtkSignalFunc) gtk_widget_destroy, GTK_OBJECT (filew)); /* Preassegnamo un nome di file, come se stessimo dando un valore per difetto in dialogo di tipo `` salva con nome '' */ gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew), "penguin.png"); gtk_widget_show(filew); gtk_main (); return 0; } </verb></tscreen>  <sect> Widget Contenitore   <sect1> Il widget Blocco Note (Notebook) Il widget Blocco note è un insieme di pagine sovrapposte l'una con l'altra, ognuna contente cose diverse. Questo widget è diventato molto comune nella programmazione delle interfacce utente ed è un buon metodo per mostrare informazioni tra loro correlate ma che debbano essere mostrate separatamente. La prima funzione da invocare che si deve conoscere, come si può intuire, è usata per creare un nuovo Blocco Note. <tscreen><verb> GtkWidget* gtk_notebook_new (void); </verb></tscreen> Una volta che il notebook è sato creato, ci sono 12 funzioni che possono operare sul widget notebook. Guardiamole individualmente. La prima che vediamo riguarda come posizionare l'indicatore di pagina. Questi inidicatori di pagina o ``linguette'' (come possono anche essere chiamati) possono essere posizionati in quattro posti: alto, basso, sinistra.destra. <tscreen><verb> void gtk_notebook_set_tab_pos (GtkNotebook *notebook, GtkPositionType pos); </verb></tscreen> GtkPositionType sarà uno dei seguenti valori (molto autoesplicativi) <itemize> <item> GTK_POS_LEFT <item> GTK_POS_RIGHT <item> GTK_POS_TOP <item> GTK_POS_BOTTOM </itemize> GTK_POS_TOP e' il valore predefinito. Ora vediamo come aggiugere le pagine al Blocco Note. Ci sono 3 modi per farlo. Diamo un'occhiata ai primi due insieme, viste che sono molto simili. <tscreen><verb> void gtk_notebook_append_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label); void gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label); </verb></tscreen> Queste funzioni aggiungono pagine al notebook inserendole rispettivamente alla fine (append) o all'inizio (prepend). *child è il widget che è posto nella pagina del notebook e *tab_label e la intestazione della pagina stessa. L'ultima funzione per aggiungere una pagina al notebook contiene tutte le proprietà delle precedenti due, ma permette di specificare dove posizionare la pagina che si vuole inserire. <tscreen><verb> void gtk_notebook_insert_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, gint position); </verb></tscreen> I parametri sono gli stessi di _append_ e _prepend_ tranne che per il parametro in più: ``position''. Questo parametro viene usato per specificare in che posizione ineserire la pagina. Ora che conosciamo come aggiungere le pagine, vediamo come poter toglierne una. <tscreen><verb> void gtk_notebook_remove_page (GtkNotebook *notebook, gint page_num); </verb></tscreen> Questa funzione prende il numero della pagina specificata dal campo page_num e rimuove la pagina corrispondente dal Blocco Note. Per trovare qual'è la pagina corrente nel notebook bisogna usare la funzione: <tscreen><verb> gint gtk_notebook_current_page (GtkNotebook *notebook); </verb></tscreen> Le prossime due funzioni sono semplicemente delle chiamate che muovono la pagina del notebook avanti o indietro. Semplicemente forniscono le chiamate alle rispettive funzioni del widget notebook su si può operare. NB: quando un notebook è correntemente sull'ultima pagina e viene invocata la funzione gtk_notebook_next_page, il notebook ritornerà automaticamente alla prima pagina. Logicamente succede anche il contrario quando invochi gtk_notebook_prev_page e ti trovi sulla prima pagina. <tscreen><verb> void gtk_notebook_next_page (GtkNoteBook *notebook); void gtk_notebook_prev_page (GtkNoteBook *notebook); </verb></tscreen> La prossima funzione stabilisce la pagina ``attiva''. Se si vuole che la pagina principale del notebook sia per esempio la 5 (ad esempio) si può usare questa funzione. Se non si usa questa funzione la pagina principale sarà la 1. <tscreen><verb> void gtk_notebook_set_page (GtkNotebook *notebook, gint page_num); </verb></tscreen> Le prossime due funzioni aggiungono o rimuovono, rispettivamente, le intestazioni e i bordi delle pagine. <tscreen><verb> void gtk_notebook_set_show_tabs (GtkNotebook *notebook, gint show_tabs); void gtk_notebook_set_show_border (GtkNotebook *notebook, gint show_border); </verb></tscreen> show_tabs e show_border posso avere come valore TRUE o FALSE (0 or 1). Diamo ora una occhiata ad un esempio. Si tratta di una espansione del codice preso dal file testgtk.c che è compreso in tutte le distribuzioni, e mostra tutte le 13 funzioni. Questo piccolo programma crea una finestra con un notebook e 6 bottoni. Il notebook contiene 11 pagine, aggiunte nei 3 modi differenti (alla fine, all'inizio o in qualsiasi posizione). I bottoni permettono di girare le intestazioni, aggiungere/rimuovere le intestazioni e i bordi, rimuovere una pagina, cambiare la pagina avanti e indietro e uscire dal programma. <tscreen><verb> /* notebook.c */ #include <gtk/gtk.h> /* Queta funzione ruota le posizione delle linguette delle pagine */ void rotate_book (GtkButton *button, GtkNotebook *notebook) { gtk_notebook_set_tab_pos (notebook, (notebook->tab_pos +1) %4); } /* Aggiunge e rimuove le linguette e i bordi */ void tabsborder_book (GtkButton *button, GtkNotebook *notebook) { gint tval = FALSE; gint bval = FALSE; if (notebook->show_tabs == 0) tval = TRUE; if (notebook->show_border == 0) bval = TRUE; gtk_notebook_set_show_tabs (notebook, tval); gtk_notebook_set_show_border (notebook, bval); } /* Rimuove una pagina */ void remove_book (GtkButton *button, GtkNotebook *notebook) { gint page; page = gtk_notebook_current_page(notebook); gtk_notebook_remove_page (notebook, page); /* E' necessario fare un refresh del widget -- Questo forza il widget a ridisegnarsi. */ gtk_widget_draw(GTK_WIDGET(notebook), NULL); } void delete (GtkWidget *widget, gpointer *data) { gtk_main_quit (); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *button; GtkWidget *table; GtkWidget *notebook; GtkWidget *frame; GtkWidget *label; GtkWidget *checkbutton; int i; char bufferf[32]; char bufferl[32]; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (destroy), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); table = gtk_table_new(2,6,TRUE); gtk_container_add (GTK_CONTAINER (window), table); /* Crea un nuovo notebook, e tabilisce la posizione delle linguette */ notebook = gtk_notebook_new (); gtk_notebook_set_tab_pos (GTK_NOTEBOOK (notebook), GTK_POS_TOP); gtk_table_attach_defaults(GTK_TABLE(table), notebook, 0,6,0,1); gtk_widget_show(notebook); /* appende una parte delle pagine */ for (i=0; i < 5; i++) { sprintf(bufferf, "Append Frame %d", i+1); sprintf(bufferl, "Page %d", i+1); frame = gtk_frame_new (bufferf); gtk_container_border_width (GTK_CONTAINER (frame), 10); gtk_widget_set_usize (frame, 100, 75); gtk_widget_show (frame); label = gtk_label_new (bufferf); gtk_container_add (GTK_CONTAINER (frame), label); gtk_widget_show (label); label = gtk_label_new (bufferl); gtk_notebook_append_page (GTK_NOTEBOOK (notebook), frame, label); } /* Ora aggiungiamo una pagina in una certa posizione */ checkbutton = gtk_check_button_new_with_label ("Check me please!"); gtk_widget_set_usize(checkbutton, 100, 75); gtk_widget_show (checkbutton); label = gtk_label_new ("Add spot"); gtk_container_add (GTK_CONTAINER (checkbutton), label); gtk_widget_show (label); label = gtk_label_new ("Add page"); gtk_notebook_insert_page (GTK_NOTEBOOK (notebook), checkbutton, label, 2); /* Ora finalmente aggiungiamo le pagine all'inizio */ for (i=0; i < 5; i++) { sprintf(bufferf, "Prepend Frame %d", i+1); sprintf(bufferl, "PPage %d", i+1); frame = gtk_frame_new (bufferf); gtk_container_border_width (GTK_CONTAINER (frame), 10); gtk_widget_set_usize (frame, 100, 75); gtk_widget_show (frame); label = gtk_label_new (bufferf); gtk_container_add (GTK_CONTAINER (frame), label); gtk_widget_show (label); label = gtk_label_new (bufferl); gtk_notebook_prepend_page (GTK_NOTEBOOK(notebook), frame, label); } /* Stabilisce quale sarà la prima pagina che sarà visualizzata. */ gtk_notebook_set_page (GTK_NOTEBOOK(notebook), 3); /* Crea un set di bottoni */ button = gtk_button_new_with_label ("close"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (delete), NULL); gtk_table_attach_defaults(GTK_TABLE(table), button, 0,1,1,2); gtk_widget_show(button); button = gtk_button_new_with_label ("next page"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) gtk_notebook_next_page, GTK_OBJECT (notebook)); gtk_table_attach_defaults(GTK_TABLE(table), button, 1,2,1,2); gtk_widget_show(button); button = gtk_button_new_with_label ("prev page"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) gtk_notebook_prev_page, GTK_OBJECT (notebook)); gtk_table_attach_defaults(GTK_TABLE(table), button, 2,3,1,2); gtk_widget_show(button); button = gtk_button_new_with_label ("tab position"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) rotate_book, GTK_OBJECT(notebook)); gtk_table_attach_defaults(GTK_TABLE(table), button, 3,4,1,2); gtk_widget_show(button); button = gtk_button_new_with_label ("tabs/border on/off"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) tabsborder_book, GTK_OBJECT (notebook)); gtk_table_attach_defaults(GTK_TABLE(table), button, 4,5,1,2); gtk_widget_show(button); button = gtk_button_new_with_label ("remove page"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) remove_book, GTK_OBJECT(notebook)); gtk_table_attach_defaults(GTK_TABLE(table), button, 5,6,1,2); gtk_widget_show(button); gtk_widget_show(table); gtk_widget_show(window); gtk_main (); return 0; } </verb></tscreen> E speriamo che questo vi aiuti a creare i Blocco Note per le vostre applicazioni GTK!  <sect1> Finestre Scorribili (Scrolled Windows) Le Finestre Scorribili sono usate per creare areee scorribili in una vera finestra. Si può inserire qualsiasi tipo di widget in questo tipo di finestra, e possono poi essere accessibili a prescindere dalle dimensioni usando le barre di scorrimento. La funzione seguente è usata per creare una nuova scrolled window. <tscreen><verb> GtkWidget* gtk_scrolled_window_new (GtkAdjustment *hadjustment, GtkAdjustment *vadjustment); </verb></tscreen> Il primo argomento è l'aggiustamento (di quanto scendere ogni volta) orizzontale e il secondo è quello verticale. A questi si assegna quasi sempre il valore NULL. <tscreen><verb> void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy); </verb></tscreen> Questa funzione stabilisce la politica da usare nella barra di scorrimento. Il primo argomento è la finestra scorribile interessata. Il secondo stabilisce la politica per la barra di scorrimento orizzontale e il terzo è quello per la politca verticale. La politica può essere GTK_POLICY AUTOMATIC o GTK_POLICY_ALWAYS. GTK_POLICY_AUTOMATIC decide automaticamente se la barra di scorrimento deve essere visualizzata, mentre con GTK_POLICY_ALWAYS la barra verrà sempre mostrata. <tscreen><verb> /* scrolledwin.c */ #include <gtk/gtk.h> void destroy(GtkWidget *widget, gpointer *data) { gtk_main_quit(); } int main (int argc, char *argv[]) { static GtkWidget *window; GtkWidget *scrolled_window; GtkWidget *table; GtkWidget *button; char buffer[32]; int i, j; gtk_init (&argc, &argv); /* Crea una nuove finestra di dialogo in cui la scrolled window sarà inserita. Una finestra di dialogo è semplicemente come una finestra normale, ma ha anche un vbox e un separatore orizzontale già inseriti per difetto. E'un modo semplice per creare finestre di dialogo. */ window = gtk_dialog_new (); gtk_signal_connect (GTK_OBJECT (window), "destroy", (GtkSignalFunc) destroy, NULL); gtk_window_set_title (GTK_WINDOW (window), "dialog"); gtk_container_border_width (GTK_CONTAINER (window), 0); gtk_widget_set_usize(window, 300, 300); /* crea una nuova finestra scorribile. */ scrolled_window = gtk_scrolled_window_new (NULL, NULL); gtk_container_border_width (GTK_CONTAINER (scrolled_window), 10); /* la politica è GTK_POLICY AUTOMATIC per lo scorrimento orizzontale e GTK_POLICY_ALWAYS per quello verticale. */ gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window), GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS); /* La finestra di dialogo è creata con un vbox già inserito.*/ gtk_box_pack_start (GTK_BOX (GTK_DIALOG(window)->vbox), scrolled_window, TRUE, TRUE, 0); gtk_widget_show (scrolled_window); /* crea una tablella di10 x 10. */ table = gtk_table_new (10, 10, FALSE); /* setta lo spazio tra ogni cella di 10 pixel sia verticale sia orizzontale*/ gtk_table_set_row_spacings (GTK_TABLE (table), 10); gtk_table_set_col_spacings (GTK_TABLE (table), 10); /* inserisce la tabella nella finestra scorribile*/ gtk_container_add (GTK_CONTAINER (scrolled_window), table); gtk_widget_show (table); /* questo semplicemente crea una griglia di bottoni nella tabelle per dimostrare il comportamento della finestra scorribile */ for (i = 0; i < 10; i++) for (j = 0; j < 10; j++) { sprintf (buffer, "button (%d,%d)\n", i, j); button = gtk_toggle_button_new_with_label (buffer); gtk_table_attach_defaults (GTK_TABLE (table), button, i, i+1, j, j+1); gtk_widget_show (button); } /* Aggiunge un bottone "close" alla fine della finestra */ button = gtk_button_new_with_label ("close"); gtk_signal_connect_object (GTK_OBJECT (button), "clicked", (GtkSignalFunc) gtk_widget_destroy, GTK_OBJECT (window)); /* questo fa sì che questo bottone sia quello predefinito */ GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT); gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button, TRUE, TRUE, 0); /* Questo ottiene il bottone predefinito. Premendo semplicemente l'"enter" il bottone si avvierà */ gtk_widget_grab_default (button); gtk_widget_show (button); gtk_widget_show (window); gtk_main(); return(0); } </verb></tscreen> Prova a giocare con il ridemensionamento della finestra. Noterete la reazione della barra di scorrimento. Potete anche usare la funzione gtk_widget_set_usize() per assegnare la dimensione predefinita della finestra o di un widget.   <sect1> Il widget "Finestra Frazionata" (Paned Window) Le finestre frazionate tornano utili quando si vuole dividere un'area in due parti, le cui dimensioni relative siano sotto il controllo dell'utente. Fra le due zone viene disgnato un separatore dotato di una maniglia che l'utente può trascinare per cambiare la proporzione fra le aree. La divisione può essere sia di tipo orizzontale (HPaned) che verticale (VPaned). Per creare una finestra frazionata, si chiama una delle seguenti: <tscreen><verb> GtkWidget* gtk_hpaned_new (void) GtkWidget* gtk_vpaned_new (void) </verb></tscreen> Dopo aver creato il widget della finestra frazionata, si devono aggiungere dei widget figli alle due parti. Per farlo, si usano le funzioni: <tscreen><verb> void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child) void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child) </verb></tscreen> <tt/gtk_paned_add1()/ inserisce il widget figlo alla parte di sinistra o superiore della finestra. <tt/gtk_paned_add2()/ lo inserisce invece nella parte destra o inferore. Per fare un esempio, creeremo una parte dell'interfaccia utente di un immaginario programma di email. Si divide una finestra in due verticalmente,  con la parte superiore in cui si mette la lista dei messaggi, e quella inferiore con il testo. La maggior parte del programma è piuttosto banale. Un paio di punti da notare sono: Non si può scrivere su un widget di testo prima che esso venga "realizato". Questa operazione può essere fatta con una chiamata alla funzione <tt/gtk_widget_realize()/, ma per far vedere un metodo alternativo, connetteremo una funzione al segnale "realize" per aggiungere il testo. Inoltre, dobbiamo aggiungere l'opzione <tt/GTK_SHRINK/ ad alcuni degli elementi della tabella che contiene la finestra del testo e le barre di scorrimento, in modo che quando si riducono le dimensioni della parte inferiore, le parti coinvolte risultino proporzionalmente rimpicciolite invece di venir spinte fuori dal fondo della finestra. <tscreen><verb> /* paned.c */ #include <gtk/gtk.h> /*Creiamo la lista dei "messaggi" */ GtkWidget * create_list (void) { GtkWidget *scrolled_window; GtkWidget *list; GtkWidget *list_item; int i; char buffer[16]; /* Creiamo una nuova finestra scorribile con barre di scorrimento solo * se necessarie */ scrolled_window = gtk_scrolled_window_new (NULL, NULL); gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC); /* Creiamo una nuova lista e la mettiamo nella finestra scorribile */ list = gtk_list_new (); gtk_container_add (GTK_CONTAINER(scrolled_window), list); gtk_widget_show (list); /* Aggiungiamo un po' di messaggi alla fiestra */ for (i=0; i<10; i++) { sprintf(buffer,"Message #%d",i); list_item = gtk_list_item_new_with_label (buffer); gtk_container_add (GTK_CONTAINER(list), list_item); gtk_widget_show (list_item); } return scrolled_window; } /* Aggiungiamo un po' di testo al nostro widget di testo - questa e' una funzione di callback che viene invocata quando la finestra viene "realizzata". Potremmo anche forzare la finestra ad essere realizzata con la funzione gtk_widget_realize, ma dovrebbe prima essere parte di una certa cerarchia */ void realize_text (GtkWidget *text, gpointer data) { gtk_text_freeze (GTK_TEXT (text)); gtk_text_insert (GTK_TEXT (text), NULL, &text->style->black, NULL, "From: pathfinder@nasa.gov\n" "To: mom@nasa.gov\n" "Subject: Made it!\n" "\n" "We just got in this morning. The weather has been\n" "great - clear but cold, and there are lots of fun sights.\n" "Sojourner says hi. See you soon.\n" " -Path\n", -1); gtk_text_thaw (GTK_TEXT (text)); } /* Creiamo un'area di testo scorribile che mostra un "messaggio" */ GtkWidget * create_text (void) { GtkWidget *table; GtkWidget *text; GtkWidget *hscrollbar; GtkWidget *vscrollbar; /*Creiamo una tabella in cui mettere il widget di testo e le barre di scorrimento */ table = gtk_table_new (2, 2, FALSE); /* Mettiamo un widget di testo nella parte superiore destra. Notate l'uso di * GTK_SHRINK nella direzione y */ text = gtk_text_new (NULL, NULL); gtk_table_attach (GTK_TABLE (table), text, 0, 1, 0, 1, GTK_FILL | GTK_EXPAND, GTK_FILL | GTK_EXPAND | GTK_SHRINK, 0, 0); gtk_widget_show (text); /* Mettiamo una HScrollbar nella parte in basso a sinistra */ hscrollbar = gtk_hscrollbar_new (GTK_TEXT (text)->hadj); gtk_table_attach (GTK_TABLE (table), hscrollbar, 0, 1, 1, 2, GTK_EXPAND | GTK_FILL, GTK_FILL, 0, 0); gtk_widget_show (hscrollbar); /* Aggiungiamo una VScrollbar in alto a sinistra */ vscrollbar = gtk_vscrollbar_new (GTK_TEXT (text)->vadj); gtk_table_attach (GTK_TABLE (table), vscrollbar, 1, 2, 0, 1, GTK_FILL, GTK_EXPAND | GTK_FILL | GTK_SHRINK, 0, 0); gtk_widget_show (vscrollbar); /* Aggiungiamo un gestore per mettere un messaggio nel wiget di testo * viene reaizzato */ gtk_signal_connect (GTK_OBJECT (text), "realize", GTK_SIGNAL_FUNC (realize_text), NULL); return table; } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *vpaned; GtkWidget *list; GtkWidget *text; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Paned Windows"); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_main_quit), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* Creiamo un widget frazionato verticalmente e aggiungiamolo alla * finestra di piu' alto livello */ vpaned = gtk_vpaned_new (); gtk_container_add (GTK_CONTAINER(window), vpaned); gtk_widget_show (vpaned); /* Creiamo il contenuto delle de parti della finestra */ list = create_list (); gtk_paned_add1 (GTK_PANED(vpaned), list); gtk_widget_show (list); text = create_text (); gtk_paned_add2 (GTK_PANED(vpaned), text); gtk_widget_show (text); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect1> Cornici ad aspetto fisso (Aspect Frames) Il widget aspect frame ` analogo al widget "cornice", tranne che per il fatto che è in grado di forzare le finestre figlie ad avere un certo aspetto, cioè un certo rapporto fra altezza e larghezza, aggiungendo se necessario dello spazio in più. Ciò può tornare utile se per esempio si vuole fare l'anteprima di un'immagine: le dimensioni dell'anteprima devono variare se l'utente ridimensiona la finestra, ma le proporzioni devono essere sempre quelle dell'immagine originale. Per creare una nuova cornice ad aspetto fisso, si usa: <tscreen><verb> GtkWidget* gtk_aspect_frame_new (const gchar *label, gfloat xalign, gfloat yalign, gfloat ratio, gint obey_child) </verb></tscreen> <tt/xalign/ e <tt/yalign/ specificano l'allineamento come si fa con il widget di allineamento. Se <tt/obey_child/ è TRUE, le proporzioni di una finestra figlia saranno le stesse delle misure ideali richieste. In caso contrario, vengono stabilite da <tt/ratio/. Per cambiare le opzioni di una finestra esistente, si può usare: To change the options of an existing aspect frame, you can use: <tscreen><verb> void gtk_aspect_frame_set (GtkAspectFrame *aspect_frame, gfloat xalign, gfloat yalign, gfloat ratio, gint obey_child) </verb></tscreen> Per fare un esempio, il seguente programma usa un Aspect Frame per rendere disponibile un'area disegnabile che sia sempre di proporzioni 2:1, in quasiasi modo l'utente ridimensioni la finestra di base. <tscreen><verb> /* aspectframe.c */ #include <gtk/gtk.h> int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *aspect_frame; GtkWidget *drawing_area; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame"); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_main_quit), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* Creiamo aspect_frame e lo mettiamo nella finestra di base */ aspect_frame = gtk_aspect_frame_new ("2x1", /* etichetta */ 0.5, /* x del centro */ 0.5, /* y del centro */ 2, /* xsize/ysize = 2 */ FALSE /* ignora le proporzioni del figlio */); gtk_container_add (GTK_CONTAINER(window), aspect_frame); gtk_widget_show (aspect_frame); /* Aggiungamo un widget figlio alla nostra cornice */ drawing_area = gtk_drawing_area_new (); /* Chiediamo una finestra 200x200, anche se l'AspectFrame ce ne dara' una * di 200x100 perche' forziamo l'aspetto 2:1 */ gtk_widget_set_usize (drawing_area, 200, 200); gtk_container_add (GTK_CONTAINER(aspect_frame), drawing_area); gtk_widget_show (drawing_area); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>   <sect> Il Widgets Lista  Il widget GtkList serve come contenitore verticale per altri widget che devono essere di tipo GtkListItem. Un widget GtkList possiede una sua propria finestra per ricevere eventi e un suo proprio colore di sfondo che di solito è bianco. Dal momento che è direttamente derivato dal widget GtkContainer, può essere trattato come tale usando la macro GTK_CONTAINER(List); si veda il widget GtkContainer per ulteriori dettagli. Per usare il widget GtkList in tutte le sue potenzialità, si dovrebbe essere già familiari con l'uso della GList e delle relative funzioni g_list_*(). All'interno della definizione della struttura del widget GtkList c'è un campo che sarà per noi di grande interesse, cioè: <tscreen><verb> struct _GtkList { ... GList *selection; guint selection_mode; ... }; </verb></tscreen> Il campo ``selection'' in un GtkList punta a una lista collegata di tutti gli elementi che sono selezionati correntemente, oppure a NULL se la selezione è vuota. Quindi, per avere informazioni sulla selezione corrente, leggiamo il campo GTK_LIST()->selection, senza però modificarlo dal momento che i campi interni debbono essere gestiti dalle funzioni gtk_list_*(). Le modalità di selezione in una GtkList, e quindi il contenuto di GTK_LIST()->selection, sono determinate dal campo selection_mode: selection_mode può assumere uno dei seguenti valori: <itemize> <item> GTK_SELECTION_SINGLE - La selezione può essere o NULL oppure un puntatore GList* per un singolo elemento selezionato. <item> GTK_SELECTION_BROWSE - La selezione è null se la lista non contiene alcun widget o se ha solo widget non sensibili, oppure può contenere un puntatore a una struttura GList, e quindi esattamente un elemento di lista. <item> GTK_SELECTION_MULTIPLE - La selezione è ``NULL'' se non è selezionato alcun elemento di lista, oppure un puntatore GList al primo elemento selezionato. Quello, a sua volta, punta a una struttura GList per il secondo elemento selezionato e così via. <item> GTK_SELECTION_EXTENDED - La selezione è sempre NULL. </itemize> Il valore per difetto è GTK_SELECTION_MULTIPLE.  <sect1> Segnali <tscreen><verb> void selection_changed (GtkList *LIST) </verb></tscreen> Questo segnale verrà invocato ogni volta che il campo di selezione di una GtkList è cambiato. Questo accade quando un figlio della GtkList viene selezionato o deselezionato. <tscreen><verb> void select_child (GtkList *LIST, GtkWidget *CHILD) </verb></tscreen> Questo segnale viene invocato quando un fuglio di una GtkList sta per essere selezionato. Questo accade principalmente in occasione di chiamate a gtk_list_select_item() e gtk_list_select_child(), di pressioni di bottoni e a volte può venir fatto scattare indirettamente in altre occasioni, in cui vengono aggiunti o rimossi dei figli dalla GtkList. <tscreen><verb> void unselect_child (GtkList *LIST, GtkWidget *CHILD) </verb></tscreen> Questo segnale viene invocato quando un figlio della GtkList sta per essere deselezionato. Ciò accade principalmente in occasione di chiamate a gtk_list_unselect_item() e gtk_list_unselect_child(), di pressioni di bottoni, e a volte può venir fatto scattare indirettamente in altre occasioni, in cui vengono aggiunti o rimossi dei figli dalla GtkList.  <sect1> Funzioni <tscreen><verb> guint gtk_list_get_type (void) </verb></tscreen> Restituisce l'identificatore di tipo `GtkList'. <tscreen><verb> GtkWidget* gtk_list_new (void) </verb></tscreen> Crea un nuovo oggetto `GtkList'. Il nuovo widget viene restituito sotto forma di un puntoatore ad un oggetto `GtkWidgetì'. In caso di fallimento, viene ritornato NULL. <tscreen><verb> void gtk_list_insert_items (GtkList *LIST, GList *ITEMS, gint POSITION) </verb></tscreen> Inserisce degli elementi di lista nella LIST, a partire da POSITION. ITEMS ITEMS è una lista doppiamente collegata, in cui ci si aspetta che i puntatori di ogni nodo puntino a un GtkListItem appena creato. I nodi GList di ITEMS vengono assunti dalla LIST. <tscreen><verb> void gtk_list_append_items (GtkList *LIST, GList *ITEMS) </verb></tscreen> Inserisce elementi di lista proprio come gtk_list_insert_items(), ma alla fine della LIST. I nodi GList di ITEMS vengono assunti dalla LIST. <tscreen><verb> void gtk_list_prepend_items (GtkList *LIST, GList *ITEMS) </verb></tscreen> Inserisce elementi di lista proprio come gtk_list_insert_items(), ma al principio della LIST. I nodi GList di ITEMS vengono assunti dalla LIST. <tscreen><verb> void gtk_list_remove_items (GtkList *LIST, GList *ITEMS) </verb></tscreen> Rimuove degli elementi di lista dalla LIST. ITEMS è una lista doppiamente collegata in cui ci si aspetta che i puntatori di ogni nodo puntino a un figlio diretto di LIST. E' poi responsabilità del chiamante di fare una chiamata a g_list_free(ITEMS). E' anche necessario che il chiamante distrugga lui stesso gli elementi della lista. <tscreen><verb> void gtk_list_clear_items (GtkList *LIST, gint START, gint END) </verb></tscreen> Rimuove e distrugge elementi di lista da LIST. Un widget ne è interessato se la sua posizione corrente all'interno di LIST è compreso fra START ed END. <tscreen><verb> void gtk_list_select_item (GtkList *LIST, gint ITEM) </verb></tscreen> Invoca il segnale select_child per un elemento di lista specificato dalla sua posizione corrente all'interno di LIST. <tscreen><verb> void gtk_list_unselect_item (GtkList *LIST, gint ITEM) </verb></tscreen> Invoca il segnale unselect_child per un elemento di lista specificato dalla sua posizione corrente all'interno di LIST. <tscreen><verb> void gtk_list_select_child (GtkList *LIST, GtkWidget *CHILD) </verb></tscreen> Invoca il segnale select_child per uno specifico CHILD. <tscreen><verb> void gtk_list_unselect_child (GtkList *LIST, GtkWidget *CHILD) </verb></tscreen> Invoca il segnale unselect_child per uno specifico CHILD. <tscreen><verb> gint gtk_list_child_position (GtkList *LIST, GtkWidget *CHILD) </verb></tscreen> Restituisce la posizione di CHILD all'interno di LIST. In caso di fallimento, viene restituito `-1'. <tscreen><verb> void gtk_list_set_selection_mode (GtkList *LIST, GtkSelectionMode MODE) </verb></tscreen> Assegna a LIST il modo di selezione MODE, che può essere uno fra GTK_SELECTION_SINGLE, GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE o GTK_SELECTION_EXTENDED. <tscreen><verb> GtkList* GTK_LIST (gpointer OBJ) </verb></tscreen> Fa il cast di un generico puntatore a `GtkList*'. Per maggiori informazioni vedere Standard Macros::. <tscreen><verb> GtkListClass* GTK_LIST_CLASS (gpointer CLASS) </verb></tscreen> Fa il cast di un generico puntatore a `GtkListClass*'. Per maggiori informazioni vedere Standard Macros::. <tscreen><verb> gint GTK_IS_LIST (gpointer OBJ) </verb></tscreen> Determina se un generico puntatore si riferisce ad un oggetto `GtkList'. Per maggiori informazioni vedere Standard Macros::.  <sect1> Esempio Diamo di seguito un programma di esempio che stamperà i campbiamenti della selezione di una GtkList, e vi lascia ``imprigionare'' gli elementi di una lista selezionandoli con il pulsante destro del mouse: <tscreen><verb> /* list.c */ /* includiamo i file header di gtk+ * includiamo stdio.h, ne abbiamo bisogno per printf() */ #include <gtk/gtk.h> #include <stdio.h> /* Questa e' la nostra stringa di identificazione dei dati per assegnarli * ad elementi di lista */ const gchar *list_item_data_key="list_item_data"; /* prototipi per i gestori di segnale che connetteremo * al widget GtkList */ static void sigh_print_selection (GtkWidget *gtklist, gpointer func_data); static void sigh_button_event (GtkWidget *gtklist, GdkEventButton *event, GtkWidget *frame); /* funzione main per predisporre l'interfaccia utente */ gint main (int argc, gchar *argv[]) { GtkWidget *separator; GtkWidget *window; GtkWidget *vbox; GtkWidget *scrolled_window; GtkWidget *frame; GtkWidget *gtklist; GtkWidget *button; GtkWidget *list_item; GList *dlist; guint i; gchar buffer[64]; /* inizializza gtk+ (e di conseguenza gdk) */ gtk_init(&argc, &argv); /* crea una finestra in cui mettere tutti i widget * connette gtk_main_quit() al segnale "destroy" della finestra * per gestire le richieste di chiusura finestra del window manager */ window=gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_window_set_title(GTK_WINDOW(window), "GtkList Example"); gtk_signal_connect(GTK_OBJECT(window), "destroy", GTK_SIGNAL_FUNC(gtk_main_quit), NULL); /* all'interno della finestra abbiamo bisogno di una scatola * in cui mettere i widget verticalmente */ vbox=gtk_vbox_new(FALSE, 5); gtk_container_border_width(GTK_CONTAINER(vbox), 5); gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); /* questa è la finestra scorribile in cui mettere il widget GtkList */ scrolled_window=gtk_scrolled_window_new(NULL, NULL); gtk_widget_set_usize(scrolled_window, 250, 150); gtk_container_add(GTK_CONTAINER(vbox), scrolled_window); gtk_widget_show(scrolled_window); /* crea il widget GtkList * connette il gestore di segnale sigh_print_selection() * al segnale "selection_changed" della GtkList, per stampare * gli elementi selezionati ogni volta che la selezione cambia */ gtklist=gtk_list_new(); gtk_container_add(GTK_CONTAINER(scrolled_window), gtklist); gtk_widget_show(gtklist); gtk_signal_connect(GTK_OBJECT(gtklist), "selection_changed", GTK_SIGNAL_FUNC(sigh_print_selection), NULL); /* creiamo una "Prigione" (Prison) in cui mettere gli elementi di lista ;) */ frame=gtk_frame_new("Prison"); gtk_widget_set_usize(frame, 200, 50); gtk_container_border_width(GTK_CONTAINER(frame), 5); gtk_frame_set_shadow_type(GTK_FRAME(frame), GTK_SHADOW_OUT); gtk_container_add(GTK_CONTAINER(vbox), frame); gtk_widget_show(frame); /* connette il gestore di segnale sigh_button_event() alla GtkList * il quale gestira' l'"imprigionamento" degli elementi di lista */ gtk_signal_connect(GTK_OBJECT(gtklist), "button_release_event", GTK_SIGNAL_FUNC(sigh_button_event), frame); /* crea un separatore */ separator=gtk_hseparator_new(); gtk_container_add(GTK_CONTAINER(vbox), separator); gtk_widget_show(separator); /* infine creiamo un bottone e connettiamone il segnale "clicked" * alla distruzione della finestra */ button=gtk_button_new_with_label("Close"); gtk_container_add(GTK_CONTAINER(vbox), button); gtk_widget_show(button); gtk_signal_connect_object(GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC(gtk_widget_destroy), GTK_OBJECT(window)); /* a questo punto creiamo 5 elementi di lista, ognuno con la * propria etichetta, e li aggiungiamo alla GtkList usando * gtk_container_add(). Inoltre, recuperiamo la stringa di testo * dall'etichetta e la associamo, per ogni elemento, a * list_item_data_key */ for (i=0; i<5; i++) { GtkWidget *label; gchar *string; sprintf(buffer, "ListItemContainer with Label #%d", i); label=gtk_label_new(buffer); list_item=gtk_list_item_new(); gtk_container_add(GTK_CONTAINER(list_item), label); gtk_widget_show(label); gtk_container_add(GTK_CONTAINER(gtklist), list_item); gtk_widget_show(list_item); gtk_label_get(GTK_LABEL(label), &string); gtk_object_set_data(GTK_OBJECT(list_item), list_item_data_key, string); } /* qui creiamo altre 5 etichette, questa volta usando * per la creazione gtk_list_item_new_with_label(). * Non possiamo recuperare la stringa di testo dall'etichetta * dal momento che non disponiamo di puntatori alle etichette, * quindi associamo semplicemente il list_item_data_key di ogni * elemento di lista con la medesima stringa di testo. * Per aggiungere elementi di lista, li mettiamo tutti in una lista * doppiamente collegata (GList), e quindi li aggiungiamo con una * unica chiamata a gtk_list_append_items(). * Dal momento che usiamo g_list_prepend() per mettere gli elementi * nella lista doppiamente collegata, il loro ordine sara' discendente * (invece che ascendente come sarebbe se usassimo g_list_append()) */ dlist=NULL; for (; i<10; i++) { sprintf(buffer, "List Item with Label %d", i); list_item=gtk_list_item_new_with_label(buffer); dlist=g_list_prepend(dlist, list_item); gtk_widget_show(list_item); gtk_object_set_data(GTK_OBJECT(list_item), list_item_data_key, "ListItem with integrated Label"); } gtk_list_append_items(GTK_LIST(gtklist), dlist); /* e finalmente vogliamo vedere la finestra, non e' vero? ;) */ gtk_widget_show(window); /* lancia il ciclo principale di gtk */ gtk_main(); /* si arriva a questo punto dopo la chiamata di gtk_main_quit(), * il che accade quando viene distrutta la finestra principale */ return 0; } /* questo e' il gestore di segnale che e' stato connesso all'evento di * pressione/rilascio del bottone della GtkList */ void sigh_button_event (GtkWidget *gtklist, GdkEventButton *event, GtkWidget *frame) { /* facciamo qualcosa solo nel caso di rilascio del terzo bottone * (quello piu' a destra) */ if (event->type==GDK_BUTTON_RELEASE && event->button==3) { GList *dlist, *free_list; GtkWidget *new_prisoner; /* recuperiamo l'elemento di lista selezionato correntemente, * che sara' il nostro prossimo prigioniero ;) */ dlist=GTK_LIST(gtklist)->selection; if (dlist) new_prisoner=GTK_WIDGET(dlist->data); else new_prisoner=NULL; /* cerchiamo elementi di lista gia' imprigionati, * li rimetteremo nella lista. * Ricordare di liberare la lista doppiamente collegata * che viene restituita da gtk_container_children() */ dlist=gtk_container_children(GTK_CONTAINER(frame)); free_list=dlist; while (dlist) { GtkWidget *list_item; list_item=dlist->data; gtk_widget_reparent(list_item, gtklist); dlist=dlist->next; } g_list_free(free_list); /* se abbiamo un nuovo prigioniero, lo rimuoviamo * dalla GtkList e lo mettiamo nella cornice della * "Prigione". Dobbiamo prima deselezionare l'elemento */ if (new_prisoner) { GList static_dlist; static_dlist.data=new_prisoner; static_dlist.next=NULL; static_dlist.prev=NULL; gtk_list_unselect_child(GTK_LIST(gtklist), new_prisoner); gtk_widget_reparent(new_prisoner, frame); } } } /* questo e' il gestore di segnaleche viene chiamato de la * GtkList emette il segnale "selection_changed" */ void sigh_print_selection (GtkWidget *gtklist, gpointer func_data) { GList *dlist; /* recuperiamo la lista doppiamente collegata degli * elementi selezionati della GtkList, ricordate di * trattarla come sola lettura */ dlist=GTK_LIST(gtklist)->selection; /* se non ci sono elementi selezionati non c'e' altro da * fare che dirlo all'utente */ if (!dlist) { g_print("Selection cleared\n"); return; } /* ok, abbiamo una selezione e quindi lo scriviamo */ g_print("The selection is a "); /* ottieniamo l'elemento di lista dalla lista doppiamente * collegata e poi richiediamo i dati associati con * list_item_data_key. Poi semplicemente li stampiamo */ while (dlist) { GtkObject *list_item; gchar *item_data_string; list_item=GTK_OBJECT(dlist->data); item_data_string=gtk_object_get_data(list_item, list_item_data_key); g_print("%s ", item_data_string); dlist=dlist->next; } g_print("\n"); } </verb></tscreen>  <sect1> Il Widget Elemento di Lista (List Item) Il widget GtkListItem è progettato allo scopo di essere un contenitore collegato ad un figlio, per fornire le funzioni per la selezione e deselezione allo stesso modo in cui il widget GtkList ne ha bisogno per i propri figli. Un GtkListItem ha la sua propria finestra per ricevere eventi, e ha il suo proprio colore di sfondo, che di solito è bianco. Dal momento che questo widget deriva direttamente da GtkItem, può essere trattato come tale usando la macro GTK_ITEM(ListItem), vedere il widget GtkItem per ulteriori informazioni. Di solito un GtkListItem ha solo un'etichetta per identificare per esempio un nome di file all'interno di una GtkList -- per cui viene fornita la funzione appropriata gtk_list_item_new_with_label(). Si può ottenere lo stesso effetto creando una GtkLabel da sola, assegnando al suo allineamento i valori xalign=0 e yalign=0.5, aggiungendo successivamente un contenitore alla GtkListItem. Dal momento che non si è obbligati a mettere una GtkLabel, si può anche aggiungere una GtkVBox una GtkArrow ecc. alla GtkListItem.  <sect1> Segnali Un GtkListItem non crea alcun nuovo segnale di per se, ma eredita i segnali di GtkItem. Per ulteriori informazioni, vedere GtkItem::.  <sect1> Funzioni <tscreen><verb> guint gtk_list_item_get_type (void) </verb></tscreen> Restituisce l'identificatore di tipo `GtkListItem'. <tscreen><verb> GtkWidget* gtk_list_item_new (void) </verb></tscreen> Crea un nuovo oggetto `GtkListItem'. Il nuovo widget viene restituito sottoforma di un puntatore ad un oggetto `GtkWidget'. In caso di fallimento, viene restituito `NULL'. <tscreen><verb> GtkWidget* gtk_list_item_new_with_label (gchar *LABEL) </verb></tscreen> Cre un nuovo oggetto `GtkListItem', avente come unico figlio un GtkLabel. Il nuovo widget viene restituito sottoforma di un puntatore ad un oggetto `GtkWidget'. In caso di fallimento, viene restituito `NULL'. <tscreen><verb> void gtk_list_item_select (GtkListItem *LIST_ITEM) </verb></tscreen> Questa funzione è essenzialmente un wrapper per una chiamata a gtk_item_select (GTK_ITEM (list_item)) che emetterà il segnale select. Vedere GtkItem:: per maggiori informazioni. <tscreen><verb> void gtk_list_item_deselect (GtkListItem *LIST_ITEM) </verb></tscreen> Questa funzione è essenzialmente un wrapper per una chiamata a gtk_item_deselect (GTK_ITEM (list_item)) che emetterà il segnale deselect. Vedere GtkItem:: per maggiori informazioni. <tscreen><verb> GtkListItem* GTK_LIST_ITEM (gpointer OBJ) </verb></tscreen> Effettua il cast di un puntatore generico a `GtkListItem*'. Vedere Standard Macros:: per maggiorni informazioni. <tscreen><verb> GtkListItemClass* GTK_LIST_ITEM_CLASS (gpointer CLASS) </verb></tscreen> Effettua il cast di un puntatore generico a `GtkListItemClass*'. Vedere Standard Macros:: per maggiorni informazioni. <tscreen><verb> gint GTK_IS_LIST_ITEM (gpointer OBJ) </verb></tscreen> Determina se un puntatore generico si riferisce ad un oggetto `GtkListItem'. Vedere Standard Macros:: per maggiorni informazioni.  <sect1> Esempio Come esempio su questo argomento, si veda quello relativo alla GtkList, che riguarda anche l'uso del GtkListItem.  <sect>Il Widget Menù (Menu Widgets)  Ci sono due modi per creare dei menù, quello facile e quello difficile. Ognuno è più adatto per certe circostanze, ma di solito si può usare il modo semplice, cioé menu_factory (la ``fabbrica dei menù''). Il modo ``difficile'' è di crearsi tutti i menù usando direttamente le chiamate. Quello semplice è di usare le chiamate di tipo gtk_menu_factory. Anche se è un modo molto più semplice, ci sono svantaggi e vantaggi per ciascuno dei due approcci. La menu_factory è molto più semplice da usare e per aggiungere dei nuovi menù, anche se scriversi un po' di funzioni per creare dei menù con il metodo manuale può dare risultati molto migliori dal punto di vista dell'usabilità. Con la menufactory, non è possibile mettere immagini o caratteri '/' nei menù.  <sect1>Creazione Manuale di Menù Seguendo la tradizionale arte dell'insegnamento, partiamo dal modo difficile. <tt>:)</> I widget che hanno a che fare con la creazione di una barra di menù e di sottomenù sono tre: <itemize> <item>un elemento di menù, che ` quello che l'utente poi selezionerà, per esempio 'Salva' <item>un menù, che fa la parte di contenitore per gli elementi di menù, e <item>una barra dei menù, che è un contenitore per ciascuno dei menù </itemize> La cosa viene un po' complicata dal fatto che i widget elemento di menù vngono usati per due scopi diversi. Essi sono sia i widget che vengono impacchettati nei menù, che quelli che vengono impacchettati nella barra dei menù che, quando selezonati, attivano i menù. Diamo un'occhiata alle funzioni usate per creare i menù e le barre di menù. Con questa prima funzione si crea un nuova barra di menù: <tscreen><verb> GtkWidget *gtk_menu_bar_new(void); </verb></tscreen> Questa funzione crea una nuova barra di menù. Per impacchettarla in una finestra o si usa la funzione gtk_container_add, oppure, per impacchettarla in una scatola, le funzioni box_pack - come con i bottoni. <tscreen><verb> GtkWidget *gtk_menu_new(); </verb></tscreen> Questa funzione restituisce un puntatore ad un nuovo menù, non viene mai realmente mostrato (con gtk_widget_show), serve solo per contenere gli elementi del menù. Spero che il tutto risulti più chiaro quando daremo un'occhiata all'esempio più sotto. Le prossime due chiamate sono usate per creare degli elementi che poi vengono impacchettati nei menù e nelle barre dei menù.. <tscreen><verb> GtkWidget *gtk_menu_item_new(); </verb></tscreen> e <tscreen><verb> GtkWidget *gtk_menu_item_new_with_label(const char *label); </verb></tscreen> Queste chiamate sono usate per creare gli elementi di menù che devono poi essere mostrati. Ricordate la differenza che esiste fra un ``menù'' come quelli creati con gtk_menu_new e un ``elemento di menù'' (menu item) come quelli creati con la funzione gtk_menu_item_new. L'elemento di menù sarà un bottone vero e proprio con una azione associata, mentre un menù è solo un contenitore che li raccoglie. Le funzioni gtk_menu_new_with_label e gtk_menu_new sono esattamente come vi aspettereste che siano dopo aver conosciuto i bottoni. Una crea un nuovo elemento di menù con un'etichetta già impacchettata, mentre l'altra crea un elemento di menù vuoto. Una volta che si ` creato un elemento di menù, è necessario piazzarlo su di un menù. Per fare ciò si usa la funzione gtk_menu_append. Per determinare quando l'utente ha selezionato un elemento, abbiamo bisogno di connettere il segnale <tt/activate/ nel solito modo. Quindi, se volessimo creare un normale menù <tt/File/, con le opzioni <tt/Open/, <tt/Save/ e <tt/Quit/, il codice avrebbe più o meno il seguente aspetto: <tscreen><verb> file_menu = gtk_menu_new(); /* Non e' necessario mostrare i menu' */ /* Creiamo gli elementi del menu' */ open_item = gtk_menu_item_new_with_label("Open"); save_item = gtk_menu_item_new_with_label("Save"); quit_item = gtk_menu_item_new_with_label("Quit"); /* Aggiungiamoli al menu' */ gtk_menu_append( GTK_MENU(file_menu), open_item); gtk_menu_append( GTK_MENU(file_menu), save_item); gtk_menu_append( GTK_MENU(file_menu), quit_item); /* Colleghiamo le funzioni di callback al segnale activate */ gtk_signal_connect_object( GTK_OBJECT(open_items), "activate", GTK_SIGNAL_FUNC(menuitem_response), (gpointer) "file.open"); gtk_signal_connect_object( GTK_OBJECT(save_items), "activate", GTK_SIGNAL_FUNC(menuitem_response), (gpointer) "file.save"); /* Possiamo collegare l'elemento Quit alla nostra funzione di uscita */ gtk_signal_connect_object( GTK_OBJECT(quit_items), "activate", GTK_SIGNAL_FUNC(destroy), (gpointer) "file.quit"); /* Abbiamo bisogno di mostrare gli elementi di menu' */ gtk_widget_show( open_item ); gtk_widget_show( save_item ); gtk_widget_show( quit_item ); </verb></tscreen> A questo punto abbiamo il nostro menù Adesso abbiamo bisogno di creare una barra dei menù e un elemento di menù per <tt/File/, a cui aggiungeremo il nostro menù. Il codice è questo: <tscreen><verb> menu_bar = gtk_menu_bar_new(); gtk_container_add( GTK_CONTAINER(window), menu_bar); gtk_widget_show( menu_bar ); file_item = gtk_menu_item_new_with_label("File"); gtk_widget_show(file_item); </verb></tscreen> Ora dobbiamo associare il menù con <tt/file_item/. Lo si può fare con la funzione <tscreen> void gtk_menu_item_set_submenu( GtkMenuItem *menu_item, GtkWidget *submenu); </tscreen> Quindi, il nostro esempio continuerebbe con <tscreen><verb> gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu); </verb></tscreen> Ciò che manca a questo punto è di collegare il menù alla barra, cosa che si può ottenere tramite la funzione <tscreen> void gtk_menu_bar_append( GtkMenuBar *menu_bar, GtkWidget *menu_item); </tscreen> che nel nostro caso è: <tscreen><verb> gtk_menu_bar_append( menu_bar, file_item ); </verb></tscreen> Se volessimo il menù giustificato a dstra, come sono spesso i menù di aiuto, potremm usare la seguente funzioe (di nuovo su <tt/file_item/ in questo esempio) prima di fare il collegamento alla barra. <tscreen><verb> void gtk_menu_item_right_justify (GtkMenuItem *menu_item); </verb></tscreen> Ecco un riassunto dei passi necessari per creare una barra con i relativi menù collegati: <itemize> <item> Create un nuovo menù con gtk_menu_new() <item> Usate delle chiamate multiple a gtk_menu_item_new() per ognuno degli elementi che volete mettere nel vostro menù. Usate inoltre gtk_menu_item_append() per mettere ciascuno di questi nuovi elementi sul menù.. <item> Create un elemento di menù usando gtk_menu_item_new(). Questo rappresenta l'elemento di base delmenù, e il testo relativo sarà il testo mostrato sulla barra dei menù stessa. <item> Usate gtk_menu_item_set_submenu() per collegare i menù all'elemento base del menù (cioè quello creato al passaggio precedente). <item> Create una nuova barra di menù usando gtk_menu_bar_new. Questo passo necessita di essere effettuato una sola volta quando si crea una serie di menù su una sola barra. <item> Usate gtk_menu_bar_append per mettere il menù base sulla barra dei menù. </itemize> Creare un menù a comparsa è più o meno la stessa cosa. La differenza è che il il menù non viene attivato ``automaticamente'' da una barra, bensì per esempio con la chiamata espicita alla funzione gtk_menu_popup() da parte di un evento di pressione di un pulsante. Seguite questi passaggi: <itemize> <item>Create una funzione di gestione di un evento. Essa deve seguire il prototipo <tscreen> static gint handler(GtkWidget *widget, GdkEvent *event); </tscreen> e usare l'evento per scoprire dove il menu deve essere fatto comparire. <item>Nel gestore di evento, se questo è la pressione di un bottone, trattate <tt>event</tt> come l'evento relativo ad un bottone (cosa che in effetti è) e usatelo come mostrato nel codice di esempio per passare informazioni a gtk_menu_popup(). <item>Collegate il gestore di evento a un widget con <tscreen> gtk_signal_connect_object(GTK_OBJECT(widget), "event", GTK_SIGNAL_FUNC (handler), GTK_OBJECT(menu)); </tscreen> in cui <tt>widget</tt> è il widget a cui state effettuando il collegamento, e <tt>handler</tt> è la funzione di gestione, mentre <tt>menu</tt> è un menù creato con gtk_menu_new(). Quest'ultimo può essere un menù che viene anche attivato da una barra di menù, come mostrato nel codice di esempio. </itemize>  <sect1>Esempio di Menù Manuale Per la teoria dovrebbe essere abbastanza. Diamo un'occhiata ad un esempio che ci aiuti a chiarire le cose. <tscreen><verb> /* menu.c */ #include <gtk/gtk.h> static gint button_press (GtkWidget *, GdkEvent *); static void menuitem_response (gchar *); int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *menu; GtkWidget *menu_bar; GtkWidget *root_menu; GtkWidget *menu_items; GtkWidget *vbox; GtkWidget *button; char buf[128]; int i; gtk_init (&argc, &argv); /* crea una nuova finestra */ window = gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_widget_set_usize( GTK_WIDGET (window), 200, 100); gtk_window_set_title(GTK_WINDOW (window), "GTK Menu Test"); gtk_signal_connect(GTK_OBJECT (window), "delete_event", (GtkSignalFunc) gtk_main_quit, NULL); /* Inizializziamo il menù, e ricordate: mai applicare * gtk_show_widget() al widget menù!! * Questo è il menù che contiene gli elementi, quello che * spunta quando si fa click sul "Menù radice" nell'applicazione */ menu = gtk_menu_new(); /* Ora creiamo un ciclo che crea tre elementi di menu per "test-menu". * Notete la chiamata a gtk_menu_append. In questo punto aggiungiamo una * lista di elementi al nostro menù. Normalmente, dovremmo poi catturare * il segnale di attivazione per ognuno degli elementi del menu, e creare * una funzione di ritorno per ciascuno di essi, ma qui non li mettiamo per * brevità. */ for(i = 0; i < 3; i++) { /* Copia i nomi in buf. */ sprintf(buf, "Test-undermenu - %d", i); /* Crea un nuovo elemento di menù con un nome... */ menu_items = gtk_menu_item_new_with_label(buf); /* ...e aggiungilo al menù. */ gtk_menu_append(GTK_MENU (menu), menu_items); /* Fa qualcosa di interessante quando si seleziona l'elemento */ gtk_signal_connect_object(GTK_OBJECT(menu_items), "activate", GTK_SIGNAL_FUNC(menuitem_response), (gpointer) g_strdup(buf)); /* Mostra il widget */ gtk_widget_show(menu_items); } /* Questo è il menù radice, e l'etichetta sarà il nome del menù che * verrà mostrato sulla barra dei menù. Non ci sarà alcun gestore di * segnale collegato, dal momento che non fa altro che mostrare il resto * del menù quando viene premuto. */ root_menu = gtk_menu_item_new_with_label("Root Menu"); gtk_widget_show(root_menu); /* Ora specifichiamo che vogliamo che il menù che abbiamo appena creato * sia il menù radice *// gtk_menu_item_set_submenu(GTK_MENU_ITEM (root_menu), menu); /* Una vbox in cui mettere un menù ed un bottone: */ vbox = gtk_vbox_new(FALSE, 0); gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); /* Crea una barra dei menù per metterci i menù e l'aggiunge alla finestra principale */ menu_bar = gtk_menu_bar_new(); gtk_box_pack_start(GTK_BOX(vbox), menu_bar, FALSE, FALSE, 2); gtk_widget_show(menu_bar); /* Crea un bottone a cui collegare un menù */ button = gtk_button_new_with_label("press me"); gtk_signal_connect_object(GTK_OBJECT(button), "event", GTK_SIGNAL_FUNC (button_press), GTK_OBJECT(menu)); gtk_box_pack_end(GTK_BOX(vbox), button, TRUE, TRUE, 2); gtk_widget_show(button); /* E finalmente attacchiamo l'elemento di menù alla barra dei menù -- questo * è l'elemento di menù "radice" di cui parlavo */ gtk_menu_bar_append(GTK_MENU_BAR (menu_bar), root_menu); /* La finestra va mostrata sempre come ultimo passo in modo che sia già * completa di tutti i suoi elementi. */ gtk_widget_show(window); gtk_main (); return 0; } /* Risponde alla pressione di un bottone impostando un menù che * viene passato come widget. * Notate che l'argomento "widget" si riferisce al menù impostato * e NON al bottone premuto. */ static gint button_press (GtkWidget *widget, GdkEvent *event) { if (event->type == GDK_BUTTON_PRESS) { GdkEventButton *bevent = (GdkEventButton *) event; gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL, bevent->button, bevent->time); /* Riferisce al codice chiamante che abbiamo trattato l'evento; * la faccenda finisce qui. */ return TRUE; } /* Riferisce al codice chiamante che abbiamo trattato l'evento; passa avanti. */ return FALSE; } /* Stampa una stringa quando viene selezionato un elemento di menù */ static void menuitem_response (gchar *string) { printf("%s\n", string); } </verb></tscreen> Si può anche fare in modo che un elemento di menù sia insensibile e, usando una tabella di acelleratori, collegare dei tasti a delle funzioni di menù.  <sect1>Usare GtkMenuFactory Ora che vi abbiamo mostrato il modo difficile, ecco invece come si fa usando le chiamate di gtk_menu_factory.  <sect1>Esempio di Menu Factory Ecco un esempio di utilizzo della ``Fabbrica'' di Menù di GTK (Menu Factory). Questo è il primo file, menufactoy.h. Teniemo dei file menufactory.c e main.c separati a causa delle variabili globali usate nel file menufactory.c. <tscreen><verb> /* menufactory.h */ #ifndef __MENUFACTORY_H__ #define __MENUFACTORY_H__ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ void get_main_menu (GtkWidget **menubar, GtkAcceleratorTable **table); void menus_create(GtkMenuEntry *entries, int nmenu_entries); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __MENUFACTORY_H__ */ </verb></tscreen> Ed ecco il file menufactory.c. <tscreen><verb> /* menufactory.c */ #include <gtk/gtk.h> #include <strings.h> #include "mfmain.h" static void menus_remove_accel(GtkWidget * widget, gchar * signal_name, gchar * path); static gint menus_install_accel(GtkWidget * widget, gchar * signal_name, gchar key, gchar modifiers, gchar * path); void menus_init(void); void menus_create(GtkMenuEntry * entries, int nmenu_entries); /* Questa è la struttuta GtkMenuEntry, che viene usata per creare dei nuovi * menù. Il primo membro à la stringa di definizione del menù. Il secondo * è il tasto acceleratore predefinito, usato per accedere a questa funzione * con la tastiera. Il terzo è la funzione di ritorno che viene chiamata * quando si seleziona con la tastiera o il mouse questo elemento di menù. * L'ultimo membro costituisce il dato che viene passato alla funzione di * ritorno. */ static GtkMenuEntry menu_items[] = { {"<Main>/File/New", "<control>N", NULL, NULL}, {"<Main>/File/Open", "<control>O", NULL, NULL}, {"<Main>/File/Save", "<control>S", NULL, NULL}, {"<Main>/File/Save as", NULL, NULL, NULL}, {"<Main>/File/<separator>", NULL, NULL, NULL}, {"<Main>/File/Quit", "<control>Q", file_quit_cmd_callback, "OK, I'll quit"}, {"<Main>/Options/Test", NULL, NULL, NULL} }; /* calcola il numero di menu_item */ static int nmenu_items = sizeof(menu_items) / sizeof(menu_items[0]); static int initialize = TRUE; static GtkMenuFactory *factory = NULL; static GtkMenuFactory *subfactory[1]; static GHashTable *entry_ht = NULL; void get_main_menu(GtkWidget ** menubar, GtkAcceleratorTable ** table) { if (initialize) menus_init(); if (menubar) *menubar = subfactory[0]->widget; if (table) *table = subfactory[0]->table; } void menus_init(void) { if (initialize) { initialize = FALSE; factory = gtk_menu_factory_new(GTK_MENU_FACTORY_MENU_BAR); subfactory[0] = gtk_menu_factory_new(GTK_MENU_FACTORY_MENU_BAR); gtk_menu_factory_add_subfactory(factory, subfactory[0], "<Main>"); menus_create(menu_items, nmenu_items); } } void menus_create(GtkMenuEntry * entries, int nmenu_entries) { char *accelerator; int i; if (initialize) menus_init(); if (entry_ht) for (i = 0; i < nmenu_entries; i++) { accelerator = g_hash_table_lookup(entry_ht, entries[i].path); if (accelerator) { if (accelerator[0] == '\0') entries[i].accelerator = NULL; else entries[i].accelerator = accelerator; } } gtk_menu_factory_add_entries(factory, entries, nmenu_entries); for (i = 0; i < nmenu_entries; i++) if (entries[i].widget) { gtk_signal_connect(GTK_OBJECT(entries[i].widget), "install_accelerator", (GtkSignalFunc) menus_install_accel, entries[i].path); gtk_signal_connect(GTK_OBJECT(entries[i].widget), "remove_accelerator", (GtkSignalFunc) menus_remove_accel, entries[i].path); } } static gint menus_install_accel(GtkWidget * widget, gchar * signal_name, gchar key, gchar modifiers, gchar * path) { char accel[64]; char *t1, t2[2]; accel[0] = '\0'; if (modifiers & GDK_CONTROL_MASK) strcat(accel, "<control>"); if (modifiers & GDK_SHIFT_MASK) strcat(accel, "<shift>"); if (modifiers & GDK_MOD1_MASK) strcat(accel, "<alt>"); t2[0] = key; t2[1] = '\0'; strcat(accel, t2); if (entry_ht) { t1 = g_hash_table_lookup(entry_ht, path); g_free(t1); } else entry_ht = g_hash_table_new(g_str_hash, g_str_equal); g_hash_table_insert(entry_ht, path, g_strdup(accel)); return TRUE; } static void menus_remove_accel(GtkWidget * widget, gchar * signal_name, gchar * path) { char *t; if (entry_ht) { t = g_hash_table_lookup(entry_ht, path); g_free(t); g_hash_table_insert(entry_ht, path, g_strdup("")); } } void menus_set_sensitive(char *path, int sensitive) { GtkMenuPath *menu_path; if (initialize) menus_init(); menu_path = gtk_menu_factory_find(factory, path); if (menu_path) gtk_widget_set_sensitive(menu_path->widget, sensitive); else g_warning("Impossibile assegnare sensibilità a menù inesistente: %s", path); } </verb></tscreen> Ed ecco mfmain.h <tscreen><verb> /* mfmain.h */ #ifndef __MFMAIN_H__ #define __MFMAIN_H__ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ void file_quit_cmd_callback(GtkWidget *widget, gpointer data); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __MFMAIN_H__ */ </verb></tscreen> E mfmain.c <tscreen><verb> /* mfmain.c */ #include <gtk/gtk.h> #include "mfmain.h" #include "menufactory.h" int main(int argc, char *argv[]) { GtkWidget *window; GtkWidget *main_vbox; GtkWidget *menubar; GtkAcceleratorTable *accel; gtk_init(&argc, &argv); window = gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_signal_connect(GTK_OBJECT(window), "destroy", GTK_SIGNAL_FUNC(file_quit_cmd_callback), "WM destroy"); gtk_window_set_title(GTK_WINDOW(window), "Menu Factory"); gtk_widget_set_usize(GTK_WIDGET(window), 300, 200); main_vbox = gtk_vbox_new(FALSE, 1); gtk_container_border_width(GTK_CONTAINER(main_vbox), 1); gtk_container_add(GTK_CONTAINER(window), main_vbox); gtk_widget_show(main_vbox); get_main_menu(&menubar, &accel); gtk_window_add_accelerator_table(GTK_WINDOW(window), accel); gtk_box_pack_start(GTK_BOX(main_vbox), menubar, FALSE, TRUE, 0); gtk_widget_show(menubar); gtk_widget_show(window); gtk_main(); return(0); } /* Questo è per mostrare come si usano le funzioni di ritorno quando * si utilizza la MenuFactory. Spesso, si mettono tutte le funzioni di * callback in un file separato, e le si fanno chiamare le funzioni * appropriate da lì. Così le cose sono più organizzate. */ void file_quit_cmd_callback (GtkWidget *widget, gpointer data) { g_print ("%s\n", (char *) data); gtk_exit(0); } </verb></tscreen> Ed infine un bel makefile per semplificare la compilazione. <tscreen><verb> # Makefile.mf CC = gcc PROF = -g C_FLAGS = -Wall $(PROF) -L/usr/local/include -DDEBUG L_FLAGS = $(PROF) -L/usr/X11R6/lib -L/usr/local/lib L_POSTFLAGS = -lgtk -lgdk -lglib -lXext -lX11 -lm PROGNAME = menufactory O_FILES = menufactory.o mfmain.o $(PROGNAME): $(O_FILES) rm -f $(PROGNAME) $(CC) $(L_FLAGS) -o $(PROGNAME) $(O_FILES) $(L_POSTFLAGS) .c.o: $(CC) -c $(C_FLAGS) $< clean: rm -f core *.o $(PROGNAME) nohup.out distclean: clean rm -f *~ </verb></tscreen> Per il momento, accontentatevi di questo esempio. Più avanti aggiungeremo una spiegazione ed un bel po' di commenti.  <sect> Widget "Testo" (Text Widget)  Il widget di testo permette di mostrare e modificare del testo disposto su più linee. Questo widget supporta sia la presenza di diversi colori che di diversi font contemporaneamente, permettendo di mischiarli nel modo in cui si desidera. Mette poi a disposizione un ampio gruppo di comandi basati sulla tastiera, che sono compatibili con Emacs. Il widget di testo dà la possibilità di fare taglia e incolla in modo completo, compreso l'uso del doppio e triplo click per selezionare un'intera parola o un'intera linea.  <sect1>Creazione e configurazione di una casella di testo Esiste un'unica funzione per la creazione di un nuovo widget di testo: <tscreen><verb> GtkWidget* gtk_text_new (GtkAdjustment *hadj, GtkAdjustment *vadj); </verb></tscreen> Gli argomenti di questa chiamata ci permettono di assegnare dei puntatori a dei valori che stabiliscono il punto di vista del widget. Passare dei valori NULL all'uno o all'altro o ad entrambi questi argomenti, fà sì che gtk_text_new li crei automaticamente. <tscreen><verb> void gtk_text_set_adjustments (GtkText *text, GtkAdjustment *hadj, GtkAdjustment *vadj); </verb></tscreen> La funzione precedente permette di cambiare gli aggiustamenti orizzontale e verticale di un widget di testo i ogni momento. Il widget di testo non ` di creare delle barre di scorrimento quando la quantità è troppo grande per la finestra. Dobbiamo quindi crearle e aggiungerle alla finestra noi stessi. <tscreen><verb> vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj); gtk_box_pack_start(GTK_BOX(hbox), vscrollbar, FALSE, FALSE, 0); gtk_widget_show (vscrollbar); </verb></tscreen> Il pezzetto di codice precedente crea una nuova barra di scorrimento verticale e la collega all'aggiustamento verticale del widget di testo, <tt/text/, dopodiché la impacchetta nella hbox al solito modo. Ci sono due modi principali di utilizzo di un widget di testo: per permettere all'utente di editare del testo, oppure per permettere a noi di mostrare all'utente del testo disposto su più righe. Per passare dall'una all'altra di queste modalità, il widget di testo ci mette a disposizione la seguente funzione: <tscreen><verb> void gtk_text_set_editable (GtkText *text, gint editable); </verb></tscreen> L'argomento <tt/editable/ è un valore TRUE o FALSE che specifica se l'utente può modificare o meno il contenuto del widgte. Quando il widget è modificabile, mostrerà un cursore nel punto di inserimento corrente. Niente però vi obbliga ad usare il widget di testo in questi due soli modi. Si può passare dall'una all'altra delle due modalità in qualsiasi momento, e si può inserire del testo in ogni momento. Il widget di testo è in grado di andare a capo automaticamente quando delle linee di testo sono troppo lunghe per stare su una sola linea della finestra. Il comportamento predefinito è di andare a capo automaticamente al termine della linea. Questo può essere cambiato con la seguente funzione: <tscreen><verb> void gtk_text_set_word_wrap (GtkText *text, gint word_wrap); </verb></tscreen> L'uso di questa funzione ci permette di specificare se il widget di testo deve spezzare o no le linee lunghe ai bordi della finestra. L'argomento <tt/word_wrap/ è un valore di tipo TRUE o FALSE.  <sect1>Manipolazione del testo Il punto di inserimento corrente del widget può essere stabilito usando <tscreen><verb> void gtk_text_set_point (GtkText *text, guint index); </verb></tscreen> in cui <tt/index/ è la posizione in cui mettere il punto di inserimento. La funzione per ottenere la posizione di inserimento corrente è analoga: <tscreen><verb> guint gtk_text_get_point (GtkText *text); </verb></tscreen> Una funzione che è utile in combinazione con le precedenti due è <tscreen><verb> guint gtk_text_get_length (GtkText *text); </verb></tscreen> la quale restituisce la lunghezza corrente del widget di testo. La lunghezza è definita come il numero di caratteri che si trovano nel blocco di testo della finestra, compresi i caratteri tipo CR, che marcano la fine delle linee. Per inserire del testo alla posizione corrente del widget di testo, si usa la funzione gtk_text_insert, che permette anche di specificare i colori di primo piano e di sfondo per il testo, oltre al font da usare. <tscreen><verb> void gtk_text_insert (GtkText *text, GdkFont *font, GdkColor *fore, GdkColor *back, const char *chars, gint length); </verb></tscreen> Passare un valore di NULL come valore per il colore di primo piano (fore), di sfondo (back) o per il font, farà sì che vengano usati i valori che sono specifici dello stile del widget. Usare un valore di <tt/-1/ per il parametro lunghezza (length) avrà come risultato l'inserzione dell'intera stringa di testo. Il widget di testo è uno dei pochi in GTK che vengono disegnati dinamicamente, fuori dalla funzione gtk_main. Ciò significa che tutti i cambiamenti al suo contenuto avranno effetto immediato. Questo può essere un comportamento indesiderabile quando si stanno facendo delle modifiche multiple al contenuto del widget. Per permettere di operare cambiamenti multipli sul widget senza che esso si ridisegni continuamente, si può congelare il contenuto della finestra, in modo che esso interrompa temporaneamente di ridisegnarsi. Potremo poi sbloccare il widget una volta che tutte le modifiche sono state completate. Le due seguenti funzioni fanno il congelamento e lo sbloccaggio (thaw) del widget: <tscreen><verb> void gtk_text_freeze (GtkText *text); void gtk_text_thaw (GtkText *text); </verb></tscreen> Il testo può essere cancellato nel widget di testo a partire dal punto di inserimento corrente usando le seguenti due funzioni, andando all'indietro (backward) o all'avanti (forward): <tscreen><verb> gint gtk_text_backward_delete (GtkText *text, guint nchars); gint gtk_text_forward_delete (GtkText *text, guint nchars); </verb></tscreen> Quando si vuole recuperare il contenuto del widget di testo, è disponibile la macro <tt/GTK_TEXT_INDEX(t, index)/, che permette di ottenere il crattere alla posizione <tt/index/ all'interno del widget <tt/t/. Per ecuperare un blocco di testo più ampio, si usa la funzione: <tscreen><verb> gchar *gtk_editable_get_chars (GtkEditable *editable, gint start_pos, gint end_pos); </verb></tscreen> Questa è una funzione della classe madre del widget di testo. Un valore di -1 per <tt/end_pos/, sta ad indicare la fine del testo. L'indice per il testo parte da 0. Questa funzione alloca una nuova porzione di memoria per il blocco di testo, per cui non dimenticate di liberarla con una chiamata a g_free quando non ne avete più bisogno.  <sect1>Keyboard Shortcuts Il widget di testo mette a disposizione un certo numero di scorciatoie da tastiera per le più comuni operazioni di modifica, movimento e selezione. Si possono utilizzare con delle combinazioni che comprendono i tasti Control e Alt. Oltre a queste, mantenendo premuto il pulsante Control mentre si usano i tasti di movimento del cursore, causerà lo spostamento parola per parola invece che carattere per carattere. Mantenere invece premuto il tasto Shift mentre si sposta il cursore, causerà l'estensione della selezione. <sect2>Scorciatoie per il movimento <itemize> <item> Ctrl-A Inizio della linea <item> Ctrl-E Fine della linea <item> Ctrl-N Prossima linea <item> Ctrl-P Linea precedente <item> Ctrl-B Indietro di un carattere <item> Ctrl-F Avanti di un carattere <item> Alt-B Indietro di una parola <item> Alt-F Avanti di una parola </itemize> <sect2>Scorciatoie per la modifica <itemize> <item> Ctrl-H Cancella il carattere precedente (Backspace) <item> Ctrl-D Cancella il carattere successivo (Delete) <item> Ctrl-W Cancella la parola precedente <item> Alt-D Cancella la parola successiva <item> Ctrl-K Cancella fino alla fine della linea <item> Ctrl-U Cancella la linea </itemize> <sect2>Scorciatoie per la selezione <itemize> <item> Ctrl-X Taglia <item> Ctrl-C Copia <item> Ctrl-V Incolla </itemize>  <sect> Widget non documentati  Per questi sarebbe utile il contributo degli autori! :) Prendete in considerazione la possibilità di contribuire al nostro tutorial. Se dovete usare uno di questi widget non documentati, vi suggeriamo caldamente di dare un'occhiata ai loro rispettivi file header nella distribuzione di GTK. I nomi delle funzioni di GTK sono molto descrittivi. Non appena si capisce come funzionano le cose, non è difficile dedurre il modo d'uso di un widget semplicemente guardando la dichiarazione di funzione ad esso associata. Aggiungendo a questo qualche spunto tratto dal codice di altri non dovrebbero esserci problemi. Quando avrete raggiunto una comprensione globale di tutte le funzioni di un widget non documentato, considerate la possibilità di scrivere un tutorial su di esso, in modo che altri possano beneficiare del vostro lavoro.  <sect1> Controlli di intervallo (Range Controls)  <sect1> Anteprime  Le anteprime servono a un certo numero di cose in GIMP/GTK. La più importante è questa: a risoluzioni molto alte le immagini possono facilmente occupare diverse decine di megabyte di memoria; ogni operazione su immagini così grosse può richiedere molto tempo. Se per la scelta di una data modifica vi occorrono 5-10 tentativi (cioè 10-20 passi, poiché è necessario ripristinare l'originale se si è commesso un errore), possono volerci letteralmente delle ore per fare quella giusta - se non si rimane a corto di memoria prima! Coloro che hanno passato ore in camera oscura conoscono la sensazione. In questi casi le anteprime sono utilissime! Ma la seccatura dell'attesa non è l'unico caso. Spesso è utile confrontare la versione precedente con la successiva affiancandole, o almeno alternandole. Se si sta lavorando con grandi immagini e ritardi di una decina di secondi un confronto efficace è quantomeno difficile da fare. Per immagini di 30 mega (4 pollici per 6 pollici, 600 punti per pollice, 24 bit) tale confronto risulta impraticabile per la maggior parte degli utenti. In questo caso le anteprime sono di grande aiuto! Ma c'è di più. Con le anteprime è possibile scrivere plug-in per ottenere addirittura anteprime di anteprime (per esempio, la simulazione del pacchetto di filtri). Questi plug-in possono così fornire un certo numero di anticipazioni di quel che si otterrebbe applicando certe opzioni. Un simile approccio funziona come una tavolozza di anteprime, ed è molto efficace per piccoli cambiamenti! Non è finita. Per alcuni plug-in può essere necessario un intervento umano in tempo reale specifico per ogni immagine. Nel plug-in SuperNova, ad esempio, vengono chieste le coordinate del centro della futura supernova. Il modo più semplice per fare questo è senza dubbio quello di mostrare un'anteprima all'utente chiedendogli di selezionare interattivamente il centro. Infine, un paio di applicazioni tipiche. Le anteprime possono essere usate anche quando non si sta lavorando con grandi immagini. Per esempio, sono utili quando si stanno calcolando dei pattern complicati (date un'occhiata al venerabile plug in ``Diffraction'' e a molti altri!). Altro esempio: date un'occhiata al plug-in di rotazione della mappa dei colori (in allestimento). Le anteprime possono anche essere usate per visualizzare in un plug-in piccoli logo o, addirittura, l'immagine dell'Autore! Quando non usare le anteprime Le anteprime non vanno usate per grafici, disegni ecc., poiché per queste cose GDK è molto più veloce. Le anteprime vanno usate solo per immagini derivate da un'elaborazione! Le anteprime possono essere inserite dappertutto. In un vbox, in un hbox, in una tabella, in un bottone, ecc. Sicuramente però hanno il loro look migliore se bordate con delle cornici (frame). Le anteprime non hanno bordi propri e appaiono piatte senza (naturalmente, se quel che si vuole è proprio un aspetto piatto...). I bordi possono essere creati con delle cornici. [Image][Image] Le anteprime sono per molti aspetti simili agli altri widget in GTK (con tutto ciò che questo implica), con l'eccezione di avere una caratteristica in più: è necessario che siano riempite con qualche tipo di immagine! Inizialmente parleremo solo dell'aspetto GTK delle anteprime e successivamente discuteremo di come riempirle. Semplicemente: <tscreen><verb> /* Crea un widget di anteprima, inizializzane le dimensioni e visualizzalo */ GtkWidget *preview; preview=gtk_preview_new(GTK_PREVIEW_COLOR) /* Alternativamente: GTK_PREVIEW_GRAYSCALE);*/ gtk_preview_size (GTK_PREVIEW (preview), WIDTH, HEIGHT); gtk_widget_show(preview); my_preview_rendering_function(preview); </verb></tscreen> Come già detto, le anteprime hanno un buon aspetto dentro le cornici, quindi: <tscreen><verb> GtkWidget *create_a_preview(int Width, int Height, int Colorfulness) { GtkWidget *preview; GtkWidget *frame; frame = gtk_frame_new(NULL); gtk_frame_set_shadow_type (GTK_FRAME (frame), GTK_SHADOW_IN); gtk_container_border_width (GTK_CONTAINER(frame),0); gtk_widget_show(frame); preview=gtk_preview_new (Colorfulness?GTK_PREVIEW_COLOR :GTK_PREVIEW_GRAYSCALE); gtk_preview_size (GTK_PREVIEW (preview), Width, Height); gtk_container_add(GTK_CONTAINER(frame),preview); gtk_widget_show(preview); my_preview_rendering_function(preview); return frame; } </verb></tscreen> Questa è una semplice anteprima. Questa funzione restituisce la cornice ``madre'', in modo che sia possibile metterla in qualche altro posto nella vostra interfaccia. Naturalmente è possibile passare alla routine la cornice madre come parametro. In molte situazioni, comunque, il contenuto di un'anteprima viene aggiornato continuamente dall'applicazione; in questi casi potreste preferire passare alla funzione ``create_a_preview()'' un puntatore all'anteprima, ottenendone così il controllo dopo. Un'avvertimento più importante che potrebbe un giorno risparmiarvi tanto tempo perso: a volte è preferibile etichettare le anteprime; ad esempio, è possibile etichettare l'anteprima contenente l'immagine originale come ``Originale'' e quella contenente l'immagine modificata come ``Modificata''. Potrebbe capitarvi di impacchettare in un vbox l'anteprima insieme con l'etichetta associata. L'insidia inattesa sta nel fatto che se l'etichetta è più ampia dell'anteprima (cosa che può accadere per una varietà di motivi da voi non prevedibili, come il fatto che la dimensione dell'anteprima viene decisa dinamicamente, o la dimensione del font), la cornice si espande e non risulta più perfettamente aderente all'anteprima. Questo stesso problema probabilmente può verificarsi anche in altre situazioni. [Image] La soluzione è quella di mettere l'anteprima e l'etichetta in una tabella 2x1 e di legarle insieme chiamando la funzione gtk_table_attach con i seguenti parametri (questa è una delle varianti possibili, naturalmente; l'importante è che non ci sia GTK_FILL nella seconda gtk_table_attach): <tscreen><verb> gtk_table_attach(GTK_TABLE(table),label,0,1,0,1, 0, GTK_EXPAND|GTK_FILL, 0,0); gtk_table_attach(GTK_TABLE(table),frame,0,1,1,2, GTK_EXPAND, GTK_EXPAND, 0,0); </verb></tscreen> Ed ecco il risultato: [Image] Altri suggerimenti La maniera più semplice per rendere cliccabile un'anteprima è quella di metterla dentro un bottone. Questo ha anche l'effetto di aggiungere un bel bordo attorno all'anteprima, il che rende superfluo metterla in una cornice. Questo è tutto per quel che riguarda GTK. Completare un'anteprima Per impratichirci con le basi del completamento delle anteprime, creiamo il seguente disegno (trovato per tentativi): [Image] <tscreen><verb> void my_preview_rendering_function(GtkWidget *preview) { #define SIZE 100 #define HALF (SIZE/2) guchar *row=(guchar *) malloc(3*SIZE); /* 3 bits per dot */ gint i, j; /* Coordinates */ double r, alpha, x, y; if (preview==NULL) return; /* Di solito aggiungo questo per */ /* evitare piantamenti stupidi. */ /* Probabilmente bisognerebbe */ /* assicurarsi che tutto sia stato*/ /* inizializzato con successo */ for (j=0; j < ABS(cos(2*alpha)) ) { /* Siamo dentro la sagoma? */ /* glib.h contiene ABS(x). */ row[i*3+0] = sqrt(1-r)*255; /* Definisce il Rosso */ row[i*3+1] = 128; /* Definisce il Verde */ row[i*3+2] = 224; /* Definisce il Blu */ } /* "+0" è per allineamento */ else { row[i*3+0] = r*255; row[i*3+1] = ABS(sin((float)i/SIZE*2*PI))*255; row[i*3+2] = ABS(sin((float)j/SIZE*2*PI))*255; } } gtk_preview_draw_row( GTK_PREVIEW(preview),row,0,j,SIZE); /* Inserisce "row" in "preview" a partire del punto avente */ /* coordinate (0,j) prima colonna, j-esima riga, per SIZE */ /* pixel verso destra */ } free(row); /* libera un po' di memoria */ gtk_widget_draw(preview,NULL); /* indovina cosa fa questo? */ gdk_flush(); /* e questo? */ } </verb></tscreen> Coloro che non usano GIMP probabilmente hanno già visto abbastanza per fare molte cose. Per gli utenti GIMP c'è ancora qualcosa da aggiungere. Anteprima dell'immagine Probabilmente è opportuno tenere pronta una versione ridotta dell'immagine, grande quanto basta per riempire l'anteprima. Questo può essere fatto selezionando un pixel ogni n, dove n è il rapporto tra la dimensione dell'immagine e la dimensione dell'anteprima. Tutte le operazioni successive (compreso il riempimento dell'anteprima) sono fatte solo sul ridotto numero di pixel selezionati. Di seguito è riportata un'implementazione della riduzione dell'immagine (si tenga presente che ho preso solo lezioni basilari di C!). (ATTENZIONE: CODICE NON VERIFICATO!!!) <tscreen><verb> typedef struct { gint width; gint height; gint bbp; guchar *rgb; guchar *mask; } ReducedImage; enum { SELECTION_ONLY, SELCTION_IN_CONTEXT, ENTIRE_IMAGE }; ReducedImage *Reduce_The_Image(GDrawable *drawable, GDrawable *mask, gint LongerSize, gint Selection) { /* Questa funzione riduce l'immagine alla dimens. scelta per l'anteprima */ /* La dimensione dell'anteprima è determinata da LongerSize, cioè la più */ /* grande delle dimensioni. Funziona solo per immagini RGB! */ gint RH, RW; /* Altezza ridotta e larghezza ridotta */ gint width, height; /* Larghezza e altezza dell'area da ridurre */ gint bytes=drawable->bpp; ReducedImage *temp=(ReducedImage *)malloc(sizeof(ReducedImage)); guchar *tempRGB, *src_row, *tempmask, *src_mask_row,R,G,B; gint i, j, whichcol, whichrow, x1, x2, y1, y2; GPixelRgn srcPR, srcMask; gint NoSelectionMade=TRUE; /* Assumiamo di trattare l'intera immagine */ gimp_drawable_mask_bounds (drawable->id, &x1, &y1, &x2, &y2); width = x2-x1; height = y2-y1; /* Se c'è una SELEZIONE, ne abbiamo avuto gli estremi! */ if (width != drawable->width && height != drawable->height) NoSelectionMade=FALSE; /* Controlliamo se l'utente ha una selezione attiva. Questo */ /* diventerà importante dopo, alla creazione di una maschera ridotta */ /* Se si vuole l'anteprima dell'immagine intera, annulla quanto sopra */ /* Naturalmente, in assenza di una selezione, questo non cambia nulla */ if (Selection==ENTIRE_IMAGE) { x1=0; x2=drawable->width; y1=0; y2=drawable->height; } /* Se si vuole l'anteprima di una selezione con parte dell'area */ /* circostante bisogna espanderla un po'. */ if (Selection==SELECTION_IN_CONTEXT) { x1=MAX(0, x1-width/2.0); x2=MIN(drawable->width, x2+width/2.0); y1=MAX(0, y1-height/2.0); y2=MIN(drawable->height, y2+height/2.0); } /* Così si determinano larghezza e altezza dell'area da ridurre. */ width = x2-x1; height = y2-y1; /* Le linee seguenti determinano quale dimensione deve essere il */ /* lato più lungo. L'idea è presa dal plug-in supernova. Ritengo */ /* che avrei potuto pensarci da solo, ma la verità va detta. */ /* Brutta cosa il plagio! */ if (width>height) { RW=LongerSize; RH=(float) height * (float) LongerSize/ (float) width; } else { RH=LongerSize; RW=(float)width * (float) LongerSize/ (float) height; } /* L'intera immagine viene "stirata" in una stringa! */ tempRGB = (guchar *) malloc(RW*RH*bytes); tempmask = (guchar *) malloc(RW*RH); gimp_pixel_rgn_init (&srcPR, drawable, x1, y1, width, height, FALSE, FALSE); gimp_pixel_rgn_init (&srcMask, mask, x1, y1, width, height, FALSE, FALSE); /* Prendine abbastanza da contenere una riga di immagine e una di maschera */ src_row = (guchar *) malloc (width*bytes); src_mask_row = (guchar *) malloc (width); for (i=0; i < RH; i++) { whichrow=(float)i*(float)height/(float)RH; gimp_pixel_rgn_get_row (&srcPR, src_row, x1, y1+whichrow, width); gimp_pixel_rgn_get_row (&srcMask, src_mask_row, x1, y1+whichrow, width); for (j=0; j < RW; j++) { whichcol=(float)j*(float)width/(float)RW; /* Nessuna selezione = tutti i punti sono completamente selezionati */ if (NoSelectionMade) tempmask[i*RW+j]=255; else tempmask[i*RW+j]=src_mask_row[whichcol]; /* Aggiungi la riga alla lunga stringa che ora contiene l'immagine */ tempRGB[i*RW*bytes+j*bytes+0]=src_row[whichcol*bytes+0]; tempRGB[i*RW*bytes+j*bytes+1]=src_row[whichcol*bytes+1]; tempRGB[i*RW*bytes+j*bytes+2]=src_row[whichcol*bytes+2]; /* Mantieni anche la trasparenza (alpha) */ if (bytes==4) tempRGB[i*RW*bytes+j*bytes+3]=src_row[whichcol*bytes+3]; } } temp->bpp=bytes; temp->width=RW; temp->height=RH; temp->rgb=tempRGB; temp->mask=tempmask; return temp; } </verb></tscreen> La seguente è una funzione di anteprima che usa lo stesso tipo ReducedImage! Si noti che usa una finta trasparenza - se ne è presente una, tramite fake_transparency che è definita come segue: <tscreen><verb> gint fake_transparency(gint i, gint j) { if ( ((i%20)- 10) * ((j%20)- 10)>0 ) return 64; else return 196; } </verb></tscreen> E adesso la funzione per l'anteprima: <tscreen><verb> void my_preview_render_function(GtkWidget *preview, gint changewhat, gint changewhich) { gint Inten, bytes=drawable->bpp; gint i, j, k; float partial; gint RW=reduced->width; gint RH=reduced->height; guchar *row=malloc(bytes*RW);; for (i=0; i < RH; i++) { for (j=0; j < RW; j++) { row[j*3+0] = reduced->rgb[i*RW*bytes + j*bytes + 0]; row[j*3+1] = reduced->rgb[i*RW*bytes + j*bytes + 1]; row[j*3+2] = reduced->rgb[i*RW*bytes + j*bytes + 2]; if (bytes==4) for (k=0; k<3; k++) { float transp=reduced->rgb[i*RW*bytes+j*bytes+3]/255.0; row[3*j+k]=transp*a[3*j+k]+(1-transp)*fake_transparency(i,j); } } gtk_preview_draw_row( GTK_PREVIEW(preview),row,0,i,RW); } free(a); gtk_widget_draw(preview,NULL); gdk_flush(); } Funzioni Applicabili guint gtk_preview_get_type (void); /* No idea */ void gtk_preview_uninit (void); /* No idea */ GtkWidget* gtk_preview_new (GtkPreviewType type); /* Descritta precedentemente */ void gtk_preview_size (GtkPreview *preview, gint width, gint height); /* Permette di ridimensionare un'anteprima esistente */ /* Pare che un bug in GTK renda disordinato questo */ /* processo. Un modo di rimettere le cose a posto */ /* è quello di ridimensionare manualmente */ /* la finestra contenente l'anteprima dopo aver */ /* ridimensionato l'anteprima. */ void gtk_preview_put (GtkPreview *preview, GdkWindow *window, GdkGC *gc, gint srcx, gint srcy, gint destx, gint desty, gint width, gint height); /* No idea */ void gtk_preview_put_row (GtkPreview *preview, guchar *src, guchar *dest, gint x, gint y, gint w); /* No idea */ void gtk_preview_draw_row (GtkPreview *preview, guchar *data, gint x, gint y, gint w); /* Descritta nel testo */ void gtk_preview_set_expand (GtkPreview *preview, gint expand); /* No idea */ /* Nessun indizio per le seguenti, ma dovrebbero */ /* essere standard per la maggior parte dei widget */ void gtk_preview_set_gamma (double gamma); void gtk_preview_set_color_cube (guint nred_shades, guint ngreen_shades, guint nblue_shades, guint ngray_shades); void gtk_preview_set_install_cmap (gint install_cmap); void gtk_preview_set_reserved (gint nreserved); GdkVisual* gtk_preview_get_visual (void); GdkColormap* gtk_preview_get_cmap (void); GtkPreviewInfo* gtk_preview_get_info (void); E' tutto! </verb></tscreen>  <sect1> Curve  <sect>Il Widget EventBox<label id="sec_The_EventBox_Widget">  Alcuni widget gtk non sono associati a finestre X, sicché semplicemente disegnano sui loro genitori. Per questo motivo essi non possono ricevere eventi e se sono sovradimensionati non vengono troncati, ma rischiano di sovrapporsi, generando confusione. Se si vuole di più da questi widget si può ricorrere agli EventBox. A prima vista il widget EventBox potrebbe sembrare completamente inutile. Non disegna nulla sullo schermo e non risponde a nessun evento. Tuttavia ha una funzione: fornire una finestra X al suo widget figlio. Ciò è importante in quanto molti widget GTK non hanno una finestra X associata. Se questo da una parte risparmia memoria e migliora le prestazioni, dall'altra introduce degli svantaggi: un widget senza una finestra X non può ricevere eventi, e non taglia in alcun modo il suo contenuto. Sebbene il nome ``EventBox'' (casella di eventi) enfasizzi la funzione di gestione degli eventi, il widget può essere usato anche per limitare la dimensione dei widget figli (ma anche per altro: si veda l'esempio seguente). Per creare un widget di tipo EventBox: <tscreen><verb> GtkWidget* gtk_event_box_new (void); </verb></tscreen> All'EventBox si può aggiungere un widget figlio: <tscreen><verb> gtk_container_add (GTK_CONTAINER(event_box), widget); </verb></tscreen> The following example demonstrates both uses of an EventBox - a label is created that clipped to a small box, and set up so that a mouse-click on the label causes the program to exit. Il seguente esempio mostra entrambi gli usi di un EventBox - si crea un'etichetta limitata da un rettangolo piccolo, fatta in modo che cliccando con il mouse su di essa il programma termina. <tscreen><verb> /* eventbox.c */ #include <gtk/gtk.h> int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *event_box; GtkWidget *label; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Event Box"); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_exit), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* Crea un EventBox e lo aggiunge alla finestra principale */ event_box = gtk_event_box_new (); gtk_container_add (GTK_CONTAINER(window), event_box); gtk_widget_show (event_box); /* Crea una etichetta lunga */ label = gtk_label_new ("Click here to quit, quit, quit, quit, quit"); gtk_container_add (GTK_CONTAINER (event_box), label); gtk_widget_show (label); /* Limitane le dimensioni */ gtk_widget_set_usize (label, 110, 20); /* E collega ad essa una azione */ gtk_widget_set_events (event_box, GDK_BUTTON_PRESS_MASK); gtk_signal_connect (GTK_OBJECT(event_box), "button_press_event", GTK_SIGNAL_FUNC (gtk_exit), NULL); /* Un'altra cosa per cui si ha bisogno di una finestra X ... */ gtk_widget_realize (event_box); gdk_window_set_cursor (event_box->window, gdk_cursor_new (GDK_HAND1)); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect>Selezionare gli Attributi dei Widget<label id="sec_setting_widget_attributes">  Qui si descrivono le funzioni per la gestione dei widget. Esse possono essere usate per impostarne lo stile, il padding, le dimensioni, ... (Forse andrebbe fatta un'intera sezione sugli acceleratori). <tscreen><verb> void gtk_widget_install_accelerator (GtkWidget *widget, GtkAcceleratorTable *table, gchar *signal_name, gchar key, guint8 modifiers); void gtk_widget_remove_accelerator (GtkWidget *widget, GtkAcceleratorTable *table, gchar *signal_name); void gtk_widget_activate (GtkWidget *widget); void gtk_widget_set_name (GtkWidget *widget, gchar *name); gchar* gtk_widget_get_name (GtkWidget *widget); void gtk_widget_set_sensitive (GtkWidget *widget, gint sensitive); void gtk_widget_set_style (GtkWidget *widget, GtkStyle *style); GtkStyle* gtk_widget_get_style (GtkWidget *widget); GtkStyle* gtk_widget_get_default_style (void); void gtk_widget_set_uposition (GtkWidget *widget, gint x, gint y); void gtk_widget_set_usize (GtkWidget *widget, gint width, gint height); void gtk_widget_grab_focus (GtkWidget *widget); void gtk_widget_show (GtkWidget *widget); void gtk_widget_hide (GtkWidget *widget); </verb></tscreen>  <sect>Funzioni periodiche, di I/O e di attesa<label id="sec_timeouts">   <sect1>Funzioni periodiche Probabilmente vi sarete chiesti come far fare qualcosa di utile a GTK durante la chiamata alla gtk_main(). Ci sono diverse possibilità. Usando le seguenti funzioni si possono creare funzioni che vengono chiamate periodicamente. <tscreen><verb> gint gtk_timeout_add (guint32 interval, GtkFunction function, gpointer data); </verb></tscreen> Il primo argomento è il numero di millisecondi tra le chiamate alla funzione. Il secondo è la funzione periodica, mentre il terzo rappresenta i dati che vengono passati alla funzione. Il valore restituito è un'etichetta che può essere utilizzata per fermare la chiamata periodica, passandolo alla funzione: <tscreen><verb> void gtk_timeout_remove (gint tag); </verb></tscreen> La chiamata periodica si ferma anche se la funzione periodica ritorna zero o FALSE. Naturalmente questo vuol dire che se si vuole che la funzione periodica continui ad essere richiamata, essa deve restituire un valore non nullo, cioè TRUE. La dichiarazione della funzione periodica dovrebbe essere come questa: <tscreen><verb> gint timeout_callback (gpointer data); </verb></tscreen>  <sect1>Controllo dell'I/O Un'altra utile caratteristica di GTK è la possibilità di fargli controllare che siano verificate certe condizioni su un descrittore di file (come quelli restituiti da open(2) o socket(2)). Questo è utile in particolar modo per le applicazioni di rete. La funzione è la seguente: <tscreen><verb> gint gdk_input_add (gint source, GdkInputCondition condition, GdkInputFunction function, gpointer data); </verb></tscreen> Il primo argomento è il descrittore che si desidera venga controllato, mentre il secondo specifica quale condizione si vuole che GDK controlli. Questa può essere una tra: GDK_INPUT_READ - Chiama la funzione quando ci sono dati pronti per la lettura nel descrittore di file. GDK_INPUT_WRITE - Chiama la funzione quando il descrittore di file è pronto per la scrittura. Come sicuramente avrete già intuito, il terzo parametro è la funzione da chiamare quando la condizione specificata è soddisfatta, mentre il quarto rappresenta i dati da passare a questa funzione. Il valore di ritorno è un etichetta che può essere usata per fermare il controllo di GDK sul descrittore di file, usando la seguente funzione: <tscreen><verb> void gdk_input_remove (gint tag); </verb></tscreen> La funzione da richiamare va dichiarata così: <tscreen><verb> void input_callback (gpointer data, gint source, GdkInputCondition condition); </verb></tscreen>  <sect1>Funzioni di attesa (``Idle'') Cosa fare se si ha una funzione che si vuole venga chiamata quando non sta accadendo nient'altro? <tscreen><verb> gint gtk_idle_add (GtkFunction function, gpointer data); </verb></tscreen> Questa fa si che GDK chiami la funzione specificata quando non c'è nessuna altra operazione in corso. <tscreen><verb> void gtk_idle_remove (gint tag); </verb></tscreen> Non ci soffermeremo sul significato dei parametri in quanto del tutto analoghi ai precedenti. La funzione puntata dal primo argomento della gtk_idle_add viene chiamata non appena se ne presenta l'opportunità; come negli altri casi, se essa restituisce FALSE non viene più chiamata.  <sect>La gestione delle selezioni   <sect1> Overview Le selezioni sono un tipo di comunicazione tra processi supportato da GTK. Una selezione identifica un frammento di dati; per esempio, una porzione di testo selezionata dall'utente in qualche modo, magari con il mouse. Su un display solo un'applicazione alla volta (il proprietario) puó essere proprietaria di una particolare selezione, sicché quando un'applicazione richiede una selezione il precedente proprietario deve comunicare all'utente che la selezione è stata ceduta. Altre applicazioni possono richiedere il contenuto di una selezione in diverse forme, chiamate obiettivi. Ci può essere un numero qualsiasi di selezioni, ma la maggior parte delle applicazioni X può gestirne solo una, la selezione primaria. Nella maggior parte dei casi per una applicazione GTK non è necessario gestire esplicitamente le selezioni. I widget standard, come quello di Ingresso, hanno già la capacità di chiedere la selezione se necessario (p. e., quando l'utente seleziona sul testo), e di recuperare il contenuto di una selezione di un altro widget o di un'altra applicazione (p. e., quando l'utente clicca il tasto centrale del mouse). Ci possono comunque essere dei casi nei quali si vuole dare ad altri widget la capacità di fornire la selezione, o si vogliono recuperare degli obiettivi non supportati direttamente. Un concetto fondamentale necessario per comprendere la gestione delle selezioni è quello di atomo. Un atomo è un intero che identifica univocamente una stringa (su un certo display). Certi atomi sono predefiniti dal server X, e in alcuni casi in <tt>gtk.h</tt> ci sono costanti corrispondenti a questi atomi. Per esempio, la costante <tt>GDK_PRIMARY_SELECTION</tt> corrisponde alla stringa ``PRIMARY''. Negli altri casi bisogna usare le funzioni <tt>gdk_atom_intern()</tt> per ottenere l'atomo corrispondente ad una stringa, e <tt>gdk_atom_name()</tt> per ottenere il nome di un atomo. Sia le selezioni sia gli obiettivi sono identificati da atomi.  <sect1> Recuperare le selezioni Il recupero di una selezione è un processo asincrono. Per iniziare il processo, si chiama: <tscreen><verb> gint gtk_selection_convert (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint32 time) </verb</tscreen> Questo converte la selezione nella forma specificata dall'obiettivo <tt/target/. Se possibile, il campo <tt/time/ dovrebbe essere il tempo dell'evento che ha attivato la selezione. Questo aiuta a far si che gli eventi avvengano nell'ordine in cui l'utente li ha richiesti. Se comunque non fosse disponibile (per esempio, se la conversione è stata attivata da un segnale di ``cliccato''), allora si può usare la costante <tt>GDK_CURRENT_TIME</tt>. Quando il proprietario di una selezione risponde ad una richiesta, un segnale ``selection_received'' (selezione ricevuta) viene inviato alla vostra applicazione. Il gestore di questo segnale riceve un puntatore ad una struttura <tt>GtkSelectionData</tt>, che è definita nel modo seguente: <tscreen><verb> struct _GtkSelectionData { GdkAtom selection; GdkAtom target; GdkAtom type; gint format; guchar *data; gint length; }; </verb></tscreen> <tt>selection</tt> e <tt>target</tt> sono i valori da voi specificati nella chiamata <tt>gtk_selection_convert()</tt>. <tt>type</tt> è un atomo che identifica il tipo di dati restituiti dal proprietario della selezione. Alcuni valori possibili sono ``STRING'', una stringa di caratteri latin-1, ``ATOM'', una serie di atomi, ``INTEGER'', un intero, ecc. La maggior parte degli obiettivi può restituire solo un tipo. <tt/format/ ci dà la lunghezza delle unità (per esempio caratteri) in bit. Di solito, quando si ricevono i dati non ci si cura di questo. <tt>data</tt> è un puntatore ai dati restituiti, e <tt>length</tt> è la lunghezza dei dati restituiti, in byte. Se <tt>length</tt> è negativo allora si è verificato un errore e non è stato possibile recuperare la selezione. Questo può avvenire se nessuna applicazione era proprietaria della selezione, o se si è richiesto un obiettivo non supportato dall'applicazione. Viene garantito che il buffer sia un byte più lungo di <tt>length</tt>; il byte in più sarà sempre zero, in modo che non sia necessario ricopiare le stringhe solo per farle terminare con zero. Nell'esempio che segue viene recuperato l'obiettivo speciale ``TARGETS'', che è una lista di tutti gli obiettivi in cui può essere convertita la selezione. <tscreen><verb> /* gettargets.c */ #include <gtk/gtk.h> void selection_received (GtkWidget *widget, GtkSelectionData *selection_data, gpointer data); /* Gestore di segnale chiamato quando l'utente clicca nel bottone */ /* "Get Targets" */ void get_targets (GtkWidget *widget, gpointer data) { static GdkAtom targets_atom = GDK_NONE; /* Prende l'atomo corrispondente alla stringa "TARGETS" */ if (targets_atom == GDK_NONE) targets_atom = gdk_atom_intern ("TARGETS", FALSE); /* E richiede l'obiettivo "TARGETS" per la selezione primaria */ gtk_selection_convert (widget, GDK_SELECTION_PRIMARY, targets_atom, GDK_CURRENT_TIME); } /* Gestore di segnale chiamato quando il proprietario della selezione */ /* restituisce i dati */ void selection_received (GtkWidget *widget, GtkSelectionData *selection_data, gpointer data) { GdkAtom *atoms; GList *item_list; int i; /* **** IMPORTANTE **** Controlla che il recupero sia riuscito */ if (selection_data->length < 0) { g_print ("Selection retrieval failed\n"); return; } /* Make sure we got the data in the expected form */ if (selection_data->type != GDK_SELECTION_TYPE_ATOM) { g_print ("Selection \"TARGETS\" was not returned as atoms!\n"); return; } /* Stampa gli atomi ricevuti */ atoms = (GdkAtom *)selection_data->data; item_list = NULL; for (i=0; i<selection_data->length/sizeof(GdkAtom); i++) { char *name; name = gdk_atom_name (atoms[i]); if (name != NULL) g_print ("%s\n",name); else g_print ("(bad atom)\n"); } return; } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *button; gtk_init (&argc, &argv); /* Create the toplevel window */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Event Box"); gtk_container_border_width (GTK_CONTAINER (window), 10); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_exit), NULL); /* Crea un bottone che l'utente può cliccare per ottenere gli obiettivi */ button = gtk_button_new_with_label ("Get Targets"); gtk_container_add (GTK_CONTAINER (window), button); gtk_signal_connect (GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC (get_targets), NULL); gtk_signal_connect (GTK_OBJECT(button), "selection_received", GTK_SIGNAL_FUNC (selection_received), NULL); gtk_widget_show (button); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect1> Fornire una selezione Fornire la selezione è un po' più complicato. Bisogna registrare i gestori che verranno chiamati quando viene richiesta la propria selezione. Per ogni coppia selezione/obiettivo che si gestirà occorre una chiamata a: <tscreen><verb> void gtk_selection_add_handler (GtkWidget *widget, GdkAtom selection, GdkAtom target, GtkSelectionFunction function, GtkRemoveFunction remove_func, gpointer data); </verb></tscreen> <tt/widget/, <tt/selection/, e <tt/target/ identificano le richieste che questo gestore soddisferà. <tt/remove_func/, se non è NULL, verrà chiamato quando il gestore di segnale viene rimosso. Questo è utile, per esempio, per linguaggi interpretati ai quali serve di tener traccia di un conteggio di riferimento per <tt/data/. La funzione di richiamo ha la forma: <tscreen><verb> typedef void (*GtkSelectionFunction) (GtkWidget *widget, GtkSelectionData *selection_data, gpointer data); </verb></tscreen> La GtkSelectionData è la stessa di prima, ma stavolta siamo responsabili di riempire i campi <tt/type/, <tt/format/, <tt/data/, e <tt/length/. (Il campo <tt/format/ qui è effettivamente importante - il server X lo usa per capire se occorre che i byte dei dati vengano scambiati o no. Di solito sarà 8 - cioè un carattere - o 32 - cioè un intero.) Questo viene fatto chiamando la funzione: <tscreen><verb> void gtk_selection_data_set (GtkSelectionData *selection_data, GdkAtom type, gint format, guchar *data, gint length); </verb></tscreen> Questa funzione si prende cura di fare propriamente una copia dei dati in modo che non ci si debba preoccupare di conservarli (è opportuno evitare di riempire a mano i campi della struttura GtkSelectionData). Quando richiesto dall'utente, richiederete la proprietà della selezione chiamando: <tscreen><verb> gint gtk_selection_owner_set (GtkWidget *widget, GdkAtom selection, guint32 time); </verb></tscreen> Se un'altra applicazione richiede la proprietà della selezione, riceverete un evento di azzeramento della selezione (``selection_clear_event''). Come esempio di fornitura della selezione, il programma seguente aggiunge la funzionalità di selezione a un bottone di attivazione. Quando il bottone viene premuto, il programma richiede la selezione primaria. L'unico obiettivo supportato (oltre a certi obiettivi come ``TARGETS'' fornito dalla stessa GTK) è l'obiettivo ``STRING''. Quando viene richiesto questo obiettivo, viene restituita una rappresentazione stringa del tempo. <tscreen><verb> /* setselection.c */ #include <gtk/gtk.h> #include <time.h> /* Richiamata quando l'utente attiva la selezione */ void selection_toggled (GtkWidget *widget, gint *have_selection) { if (GTK_TOGGLE_BUTTON(widget)->active) { *have_selection = gtk_selection_owner_set (widget, GDK_SELECTION_PRIMARY, GDK_CURRENT_TIME); /* se il richiamo della selezione è fallito, si riporta il bottone nello stato non premuto */ if (!*have_selection) gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON(widget), FALSE); } else { if (*have_selection) { /* Prima di annullare la selezione mettendone a NULL il proprietario, controlliamo se siamo i veri proprietari */ if (gdk_selection_owner_get (GDK_SELECTION_PRIMARY) == widget->window) gtk_selection_owner_set (NULL, GDK_SELECTION_PRIMARY, GDK_CURRENT_TIME); *have_selection = FALSE; } } } /* Chiamata quando un'altra applicazione richiede la selezione */ gint selection_clear (GtkWidget *widget, GdkEventSelection *event, gint *have_selection) { *have_selection = FALSE; gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON(widget), FALSE); return TRUE; } /* Fornisce come selezione il tempo attuale */ void selection_handle (GtkWidget *widget, GtkSelectionData *selection_data, gpointer data) { gchar *timestr; time_t current_time; current_time = time (NULL); timestr = asctime (localtime(&current_time)); /* Quando si restituisce una singola stringa, non occorre che finisca con NULL. Questo verrà fatto automaticamente */ gtk_selection_data_set (selection_data, GDK_SELECTION_TYPE_STRING, 8, timestr, strlen(timestr)); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *selection_button; static int have_selection = FALSE; gtk_init (&argc, &argv); /* Crea la finestra di livello superiore */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Event Box"); gtk_container_border_width (GTK_CONTAINER (window), 10); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_exit), NULL); /* Crea un bottone a commutazione che agisce come la selezione */ selection_button = gtk_toggle_button_new_with_label ("Claim Selection"); gtk_container_add (GTK_CONTAINER (window), selection_button); gtk_widget_show (selection_button); gtk_signal_connect (GTK_OBJECT(selection_button), "toggled", GTK_SIGNAL_FUNC (selection_toggled), &have_selection); gtk_signal_connect (GTK_OBJECT(selection_button), "selection_clear_event", GTK_SIGNAL_FUNC (selection_clear), &have_selection); gtk_selection_add_handler (selection_button, GDK_SELECTION_PRIMARY, GDK_SELECTION_TYPE_STRING, selection_handle, NULL); gtk_widget_show (selection_button); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect>La glib<label id="sec_glib">  La glib fornisce molte funzioni e definizioni utili pronte all'uso quando si creano applicazioni GDK e GTK. Qui verranno elencate tutte, con una breve spiegazione. Molte sono duplicati delle funzioni standard della libc, e quindi per queste non si scenderà nei dettagli. Questa vuole essere una lista di riferimento, in modo che si sappia cosa è possibile usare.  <sect1>Definizioni Le definizioni per gli estremi di molti dei tipi standard sono: <tscreen><verb> G_MINFLOAT G_MAXFLOAT G_MINDOUBLE G_MAXDOUBLE G_MINSHORT G_MAXSHORT G_MININT G_MAXINT G_MINLONG G_MAXLONG </verb></tscreen> Ci sono anche le seguenti definizioni di tipo. Quelle rimaste non specificate sono dipendenti dall'architettura. Si ricordi di evitare di fare affidamento sulla dimensione di un puntatore se si vuole la portabilità! P.e., un puntatore su un Alpha è lungo 8 byte, ma 4 su un Intel. <tscreen><verb> char gchar; short gshort; long glong; int gint; char gboolean; unsigned char guchar; unsigned short gushort; unsigned long gulong; unsigned int guint; float gfloat; double gdouble; long double gldouble; void* gpointer; gint8 guint8 gint16 guint16 gint32 guint32 </verb></tscreen>  <sect1>Liste a doppio collegamento le seguenti funzioni sono usate per creare, gestire e distruggere liste a doppio collegamento. Si assume che il lettore sappia già cosa sono le liste collegate (linked list), poiché descriverle è fuori dagli scopi di questo documento. Naturalmente non è necessario conoscerle per l'uso generale di GTK, per quanto conoscerle sia comunque interessante. <tscreen><verb> GList* g_list_alloc (void); void g_list_free (GList *list); void g_list_free_1 (GList *list); GList* g_list_append (GList *list, gpointer data); GList* g_list_prepend (GList *list, gpointer data); GList* g_list_insert (GList *list, gpointer data, gint position); GList* g_list_remove (GList *list, gpointer data); GList* g_list_remove_link (GList *list, GList *link); GList* g_list_reverse (GList *list); GList* g_list_nth (GList *list, gint n); GList* g_list_find (GList *list, gpointer data); GList* g_list_last (GList *list); GList* g_list_first (GList *list); gint g_list_length (GList *list); void g_list_foreach (GList *list, GFunc func, gpointer user_data); </verb></tscreen>  <sect1>Liste a collegamento singolo Molte delle funzioni per le liste a collegamento singolo sono identiche alle precedenti. Eccone una lista completa: <tscreen><verb> GSList* g_slist_alloc (void); void g_slist_free (GSList *list); void g_slist_free_1 (GSList *list); GSList* g_slist_append (GSList *list, gpointer data); GSList* g_slist_prepend (GSList *list, gpointer data); GSList* g_slist_insert (GSList *list, gpointer data, gint position); GSList* g_slist_remove (GSList *list, gpointer data); GSList* g_slist_remove_link (GSList *list, GSList *link); GSList* g_slist_reverse (GSList *list); GSList* g_slist_nth (GSList *list, gint n); GSList* g_slist_find (GSList *list, gpointer data); GSList* g_slist_last (GSList *list); gint g_slist_length (GSList *list); void g_slist_foreach (GSList *list, GFunc func, gpointer user_data); </verb></tscreen>  <sect1>Gestione della memoria <tscreen><verb> gpointer g_malloc (gulong size); </verb></tscreen> Questa è una sostituta di malloc(). Non occorre controllare il valore restituito, in quanto lo fa già questa funzione. <tscreen><verb> gpointer g_malloc0 (gulong size); </verb></tscreen> Come la precedente, ma la memoria viene azzerata prima di restituire un puntatore ad essa. <tscreen><verb> gpointer g_realloc (gpointer mem, gulong size); </verb></tscreen> Riloca ``size'' byte di memoria che inizia a ``mem''. Ovviamente, la memoria dovrebbe essere stata allocata precedentemente. <tscreen><verb> void g_free (gpointer mem); </verb></tscreen> Libera la memoria. Facile! <tscreen><verb> void g_mem_profile (void); </verb></tscreen> Emette un profilo della memoria usata, ma occorre ricompilare e reinstallare la libreria aggiungendo #define MEM_PROFILE all'inizio del file glib/gmem.c. <tscreen><verb> void g_mem_check (gpointer mem); </verb></tscreen> Controlla che una locazione di memoria sia valida. Occorre ricompilare e reinstallare la libreria aggiungendo #define MEM_CHECK all'inizio del file gmem.c.  <sect1>Timer Funzioni legate ai timer... <tscreen><verb> GTimer* g_timer_new (void); void g_timer_destroy (GTimer *timer); void g_timer_start (GTimer *timer); void g_timer_stop (GTimer *timer); void g_timer_reset (GTimer *timer); gdouble g_timer_elapsed (GTimer *timer, gulong *microseconds); </verb></tscreen>  <sect1>Gestione delle stringhe Un'accozzaglia di funzioni per la gestione delle stringhe. Sembrano tutte molto interessanti, e probabilmente migliori per molte caratteristiche delle funzioni standard del C per le stringhe, ma necessitano di documentazione. <tscreen><verb> GString* g_string_new (gchar *init); void g_string_free (GString *string, gint free_segment); GString* g_string_assign (GString *lval, gchar *rval); GString* g_string_truncate (GString *string, gint len); GString* g_string_append (GString *string, gchar *val); GString* g_string_append_c (GString *string, gchar c); GString* g_string_prepend (GString *string, gchar *val); GString* g_string_prepend_c (GString *string, gchar c); void g_string_sprintf (GString *string, gchar *fmt, ...); void g_string_sprintfa (GString *string, gchar *fmt, ...); </verb></tscreen>  <sect1>Funzioni d'utilità e di errore <tscreen><verb> gchar* g_strdup (const gchar *str); </verb></tscreen> Funzione sostitutiva della strdup. Copia i contenuti originari delle stringhe in memoria appena allocata, restituendo un puntatore ad essa. <tscreen><verb> gchar* g_strerror (gint errnum); </verb></tscreen> Si raccomanda di usare questa gunzione per tutti i messaggi di errore. E' molto più graziosa, e più portabile di perror() o di altre. L'output di solito ha la forma: <tscreen><verb> nome programma:funzione fallita:file o altre descrizioni:strerror </verb></tscreen> Di seguito un esempio di una chiamata di questo tipo usata nel nostro programma Hello World: <tscreen><verb> g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno)); </verb></tscreen> <tscreen><verb> void g_error (gchar *format, ...); </verb></tscreen> Visualizza un messaggio di errore. Il formato è come quello di printf, ma prepone ``** ERROR **: '' al messaggio e termina il programma. Da usare solo per errori gravi. <tscreen><verb> void g_warning (gchar *format, ...); </verb></tscreen> Come la precedente, ma prepone ``** WARNING **: '' e non termina il programma. <tscreen><verb> void g_message (gchar *format, ...); </verb></tscreen> Visualizza ``message: '' e poi il messaggio. <tscreen><verb> void g_print (gchar *format, ...); </verb></tscreen> Sostituta di printf(). L'ultima funzione: <tscreen><verb> gchar* g_strsignal (gint signum); </verb></tscreen> Visualizza il nome del messaggio del sistema Unix associato al numero di segnale. Utile nelle funzioni generiche di gestione dei segnali. Tutte le funzioni elencate sono più o meno prese da glib.h. Se qualcuno volesse documentare qualche funzione, mandi una email all'autore!  <sect>I file rc di GTK  GTK ha un suo modo di trattare le preferenze delle applicazioni, usando i file rc. Questi possono essere usati per scegliere i colori di quasi tutti i widget, e possono anche essere usati per inserire delle pixmap nello sfondo di alcuni widget.  <sect1>Funzioni per i file rc All'inizio della vostra applicazione dovrebbe esserci una chiamata a <tscreen><verb> void gtk_rc_parse (char *filename); </verb></tscreen> passando come parametro il nome del vostro file rc. Questo farà si che GTK analizzi tale file e usi le impostazioni di stile per i tipi di widget ivi definite. Se si desidera avere un insieme speciale di widget che abbia uno stile diverso dagli altri, o qualsiasi altra divisione logica dei widget, si chiami <tscreen><verb> void gtk_widget_set_name (GtkWidget *widget, gchar *name); </verb></tscreen> passando un widget appena creato come primo argomento, e il nome che gli si vuole dare come secondo. Questo consentirà di cambiare gli attributi di questo widget per nome tramite il file rc. Effettuando una chiamata come questa: <tscreen><verb> button = gtk_button_new_with_label ("Special Button"); gtk_widget_set_name (button, "special button"); </verb></tscreen> allora a questo bottone viene dato il nome ``special button'' ed esso può essere riferito per nome nel file rc come ``special button.GtkButton''. [<--- Verificatemi!] Il seguente esempio di file rc imposta le proprietà della finestra principale, e fa si che tutti i figli di questa finestra ereditino lo stile descritto dallo stile ``main button''. Il codice usato nell'applicazione è: <tscreen><verb> window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_widget_set_name (window, "main window"); </verb></tscreen> Lo stile viene definito nel file rc usando: <tscreen><verb> widget "main window.*GtkButton*" style "main_button" </verb></tscreen> che assegna a tutti i widget GtkButton nella finestra principale lo stile ``main_buttons'' secondo la definizione data nel file rc. Come si può vedere, questo sistema è molto potente e flessibile. Usate la vostra immaginazione per trarre il massimo vantaggio da esso.  <sect1>Il formato dei file rc di GTK Nell'esempio che segue viene illustrato il formato del file GTK. Si tratta del file testgkrc dalla distribuzione del GTK, a cui sono stati aggiunti vari commenti e varie cose. Potete includere questa spiegazione nella vostra applicazione per consentire all'utente di personalizzarla finemente. There are several directives to change the attributes of a widget. Ci sono diverse direttive per cambiare gli attributi di un widget. <itemize> <item>fg - Assegna il colore di primo piano di un widget. <item>bg - Assegna il colore di sfondo di un widget. <item>bg_pixmap - Inserisce nello sfondo di un widget una pixmap. <item>font - Sceglie il font da usarsi con il dato widget. </itemize> Inoltre ci sono diversi stati in cui può trovarsi un widget, e si possono assegnare diversi colori, pixmap e font per ogni stato. Essi sono: <itemize> <item>NORMAL - Lo stato normale di un widget, quando il mouse non si trova su di esso, quando non è premuto, ecc. <item>PRELIGHT (evidenziato)- Quando il mouse si trova sopra al widget verranno usati i colori assegnati per questo stato. <item>ACTIVE (attivo) - Quando il widget è premuto o cliccato esso sarà attivo, e verranno usati gli attributi assegnati da questa etichetta. <item>INSENSITIVE (insensibile)- Quando un widget viene reso insensibile, e non può essere attivato, prenderà questi attributi. <item>SELECTED (selezionato) - Quando un oggetto viene selezionato, prende questi attributi. </itemize> Quando si usano le parole chiave ``fg'' e ``bg'' per assegnare i colori dei widget il formato è: <tscreen><verb> fg[<STATE>] = { Rosso, Verde, Blu } </verb></tscreen> Dove STATE è uno degli stati visti prima (PRELIGHT, ACTIVE ecc.), e Rosso, Verde e Blu sono valori nell'intervallo 0 - 1.0; { 1.0, 1.0, 1.0 } rappresenta il bianco. Devono essere in formato float, o verranno visti come 0, sicché un ``1'' diretto non funziona, deve essere ``1.0''. Uno ``0'' diretto va invece bene, poiché poco importa se non viene riconosciuto: valori non riconosciuti vengono considerati 0. bg_pixmap è molto simile al precedente, tranne per i colori che vengono sostituiti dal nome di un file. pixmap_path è una lista di percorsi separati da ``:''. In questi percorsi vengono cercate le pixmap specificate. La direttiva font è semplicemente: <tscreen><verb> font = "" </verb></tscreen> dove l'unica parte complicata è immaginare la stringa del font. Allo scopo può servire usare xfontsel o una utilità analoga. ``widget_class'' assegna lo stile di una classe di widget. Queste classi sono elencate nell'introduzione ai widget sulla gerarchia delle classi. La direttiva ``widget'' assegna un insieme di widget dal nome specificato ad un dato stile, annullando qualsiasi stile assegnato per la data classe di widget. Questi widget vengono registrati nell'applicazione usando la chiamata gtk_widget_set_name(). Questo consente di specificare gli attributi di un widget singlarmente, piuttosto che assegnando gli attributi di un'intera classe di widget. E' opportuno documentare tutti questi widget speciali in modo che gli utenti possano personalizzarli. Quando la parola chiave ``<tt>parent</>'' viene usata come un attributo, il widget erediterà gli attributi del suo genitore nell'applicazione. Quando si definisce uno stile si possono assegnare gli attributi di uno stile definito precedentemente a quello nuovo. <tscreen><verb> style "main_button" = "button" { font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*" bg[PRELIGHT] = { 0.75, 0, 0 } } </verb></tscreen> Questo esempio prende lo stile ``button'' e crea un nuovo stile semplicemente cambiando il font e il colore di sfondo dello stato ``prelight'' nello stile ``button''. Naturalmente, molti di questi attributi non sono applicabili a tutti i widget. E' veramente un semplice problema di buon senso. Tutto quello che potrebbe applicarsi, dovrebbe.  <sect1>Esempio di file rc <tscreen><verb> # pixmap_path "<dir 1>:<dir 2>:<dir 3>:..." # pixmap_path "/usr/include/X11R6/pixmaps:/home/imain/pixmaps" # # style <name> [= <name>] # { # <option> # } # # widget <widget_set> style <style_name> # widget_class <widget_class_set> style <style_name> # Ecco una lista di tutti gli stati possibili. Si noti che alcuni non sono # applicabili a certi widget. # # NORMAL - Lo stato normale di un widget, quando il mouse non si trova su # di esso, quando non è premuto, ecc. # # PRELIGHT (evidenziato)- Quando il mouse si trova sopra al widget # verranno usati i colori assegnati per questo stato. # # ACTIVE (attivo) - Quando il widget è premuto o cliccato esso sarà attivo, # e verranno usati gli attributi assegnati da questa etichetta. # # INSENSITIVE (insensibile)- Quando un widget viene reso insensibile, # e non può essere attivato, prenderà questi attributi. # # SELECTED (selezionato) - Quando un oggetto viene selezionato, prende # questi attributi. # # Dati questi stati, è possibile assegnare gli attributi dei widget in # ognuno di questi stati usando le seguenti direttive. # # fg - Assegna il colore di primo piano di un widget. # bg - Assegna il colore di sfondo di un widget. # bg_pixmap - Inserisce nello sfondo di un widget una pixmap. # font - Sceglie il font da usarsi con il dato widget. # # Questo è uno stile chiamato "button". Il nome non è veramente importante, # in quanto viene assegnato ai veri widget alla fine del file. style "window" { # Questo inserisce nella spaziatura attorno alla finestra la pixmap # specificata. #bg_pixmap[<STATE>] = "<pixmap filename>" bg_pixmap[NORMAL] = "warning.xpm" } style "scale" { # Mette il colore di primo piano (il colore del font) a rosso nello # stato "NORMAL". fg[NORMAL] = { 1.0, 0, 0 } # Inserisce nello sfondo del gadget la stessa pixmap usata dal suo genitore. bg_pixmap[NORMAL] = "<parent>" } style "button" { # Questo mostra tutti i possibili stati per un bottone. L'unico che # non è applicabile è lo stato "SELECTED". fg[PRELIGHT] = { 0, 1.0, 1.0 } bg[PRELIGHT] = { 0, 0, 1.0 } bg[ACTIVE] = { 1.0, 0, 0 } fg[ACTIVE] = { 0, 1.0, 0 } bg[NORMAL] = { 1.0, 1.0, 0 } fg[NORMAL] = { .99, 0, .99 } bg[INSENSITIVE] = { 1.0, 1.0, 1.0 } fg[INSENSITIVE] = { 1.0, 0, 1.0 } } # In questi esempio ereditiamo gli attributi dello stile "button" e poi # alteriamo il font e il colore di sfondo quando evidenziato per creare # un nuovo stile "main_button". style "main_button" = "button" { font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*" bg[PRELIGHT] = { 0.75, 0, 0 } } style "toggle_button" = "button" { fg[NORMAL] = { 1.0, 0, 0 } fg[ACTIVE] = { 1.0, 0, 0 } # Questo seleziona come pixmap di sfondo per il toggle_button quella del # suo widget genitore (definita nell'applicazione). bg_pixmap[NORMAL] = "<parent>" } style "text" { bg_pixmap[NORMAL] = "marble.xpm" fg[NORMAL] = { 1.0, 1.0, 1.0 } } style "ruler" { font = "-adobe-helvetica-medium-r-normal--*-80-*-*-*-*-*-*" } # pixmap_path "~/.pixmaps" # Queste assegnano ai tipi di widget gli stili definiti prima. # I tipi di widget sono elencati nella gerarchia delle classi, ma probabilmente # dovrebbero essere elencati in questo documento come riferimento per l'utente. widget_class "GtkWindow" style "window" widget_class "GtkDialog" style "window" widget_class "GtkFileSelection" style "window" widget_class "*Gtk*Scale" style "scale" widget_class "*GtkCheckButton*" style "toggle_button" widget_class "*GtkRadioButton*" style "toggle_button" widget_class "*GtkButton*" style "button" widget_class "*Ruler" style "ruler" widget_class "*GtkText" style "text" # Questo assegna lo stile main_button a tutti i bottoni che sono figli della # "main window" (finestra principale). Questi devono essere documenati per # potersene avvantaggiare. widget "main window.*GtkButton*" style "main_button" </verb></tscreen>  <sect>Scrivere un proprio Widget   <sect1> Panoramica Anche se la distribuzione GTK contiene molto tipi di widget che possono coprire molte necessità basilari, può essere necessario costruirsi un proprio widget. GTK usa molto l'ereditarietà tra i vari widget e, di solito, vi è un widget che si avvicina a quello che ti servirebbe, ed è spesso possibile creare un nuovo widget con poche linee di codice. Ma prima di iniziare il lavoro su un nuovo widget, vediamo se qualcuno non lo ha già creato. Questo eviterà un duplicazione di lavoro e farà sì che i widget non-GTK puri siano minimi, così da aiutare sia chi crea il codice che chi l'interfaccia per applicazioni GTK molto grosse. D'altra parte, quando hai finito di scrivere un widget, annuncialo a tutto il mondo così che le altre persone ne possano beneficiare. Il miglioro modo dove farlo è la <tt>gtk-list</tt>. I sorgenti completi per i widget di esempio possono essere presi dallo stesso sito da cui avete scaricato questo tutorial, oppure da: <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial" name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">  <sect1> L'anatomia di un widget Per creare un nuovo widget è importante aver capito come gli ogetti di GTK lavorano. Questa sezione è solo una breve spiegazione. Guarda la documentazione di riferimento per maggiori dettagli. I widget GTK sono implementati in un modo orientato agli oggetti, anche se usando il C standard. Questo aumenta notevolmente la portabilità e la stabilità, specialmente per le correnti generazioni di compilatori C++; comunque questo significa che chi scrive un widget deve fare attenzione ad alcuni dettagli di implementazione. L'informazione comune a tutte le istanze di una classe di widget (ad esempio: a tutti i bottoni) è memorizzata class structure. C'e' solamente una copia di questo in cui sono memorizzate le informazioni riguardanti i segnali della classe (assomiglia ad una funzione virtuale in C). Per supportare l'ereditarietà il primo campo della struttura di una classe deve essere una copia della struttura della classe genitore. La dichiarazione della struttura della classe GtkButton è: <tscreen><verb> struct _GtkButtonClass { GtkContainerClass parent_class; void (* pressed) (GtkButton *button); void (* released) (GtkButton *button); void (* clicked) (GtkButton *button); void (* enter) (GtkButton *button); void (* leave) (GtkButton *button); }; </verb></tscreen> Quando un bottone viene trattato come un contenitore (ad esempio quando viene ridimensionato) si può fare il cast della struttura della sua classe con la GtkContainerClass, e usare i campi rilevanti per gestire i segnali. C'è anche una struttura per ogni widget che viene creata ad ogni istanza. Questa struttura ha campi per memorizzare le informazioni che sono differenti per ogni volta che il widget viene istanziato. Chiameremo questa struttura la struttura oggetto. Per la classe Bottone, questa ha l'aspetto: <tscreen><verb> struct _GtkButton { GtkContainer container; GtkWidget *child; guint in_button : 1; guint button_down : 1; }; </verb></tscreen> Si noti che, similmente alla struttura della classe, il primo campo è la struttura dell'oggetto della classe madre, così che, se necessario, si può fare il cast di questa struttura con quella dell'oggetto della classe madre.  <sect1> Creare un Widget composto  <sect2> Introduzione Un tipo di widget a cui potreste essere interessati è un widget che è semplicemnte un aggregato di altri widget GTK. Questo tipo di widget non fa nulla che non possa essere fatto creando un nuovo widget, ma fornisce un modo conveniente per inscatolare elementi dell'interfaccia utente per poi riutilizzarli. I widget FileSelection e ColorSelection della ditribuzione standard sono esempi di questo tipo di widget. Il widget di esempio che creeremo in questo capitolo è il Tictactoe, un vettore 3x3 di bottoni a commutazione il quale emette un segnale quando tutti e 3 i bottoni di una riga, colonna o di una diagonale sono premuti.  <sect2> Scegliere la classe madre La classe madre per un widget composto e' tipicamente la classe contenitrice che racchiude tutti gli elementi del widget composto. Per esempio, la classe madre del widget FileSelection è la classe Dialog. Visto che i nostri bottoni sono inseriti in una tabella, è naturale pensare che la nostra classe madre possa essere la GtkTable. Sfortunatamente, così non è. La creazione di un widget è diviso tra 2 funzioni : la funzione <tt/WIDGETNAME_new()/ che viene invocata dall'utente, e la funzione <tt/WIDGETNAME_init()/ che ha il compito principale di inizializzare il widget che è indipendente dai valori passati alla funzione <tt/_new()/. Widget figli o discendenti possono chiamare, solamente, la funzione del loro widget genitore. Ma questa divisione del lavoro non funziona bene per la tabella, la quale, quando creata, necessita di conoscere il numero di righe e colonne che la comporrà. A meno che non vogliamo duplicare molte delle fuinzionalità della <tt/gtk_table_new()/ nel nostro widget Tictactoe, faremmo meglio a evitare di derivarlo dalla GtkTable. Per questa ragione lo deriviamo invece da GtkVBox, e uniamo la nostra tabella dentro il VBox.  <sect2> Il File Header Ogni classe di widget ha un file header il quale dichiara l'oggetto e la struttura della classe del widget, comprese le funzioni pubbliche. Per prevenire duplicati di definizioni, noi includiamo l'intero file header fra: <tscreen><verb> #ifndef __TICTACTOE_H__ #define __TICTACTOE_H__ . . . #endif /* __TICTACTOE_H__ */ </verb></tscreen> E per far felici i programmi in C++ che includono il nostro file header, in: <tscreen><verb> #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ . . . #ifdef __cplusplus } #endif /* __cplusplus */ </verb></tscreen> Insieme alle funzioni e alle strutture, dichiariamo tre macro standard nel nostro file header, <tt/TICTACTOE(obj)/, <tt/TICTACTOE_CLASS(klass)/, e <tt/IS_TICTACTOE(obj)/, i quali rispettivamente fanno il cast di un puntatore ad un puntatore ad un ogetto od ad una struttura di classe, e guarda se un oggetto è un widget Tictactoe. Qui vi è il file header completo: <tscreen><verb> /* tictactoe.h */ #ifndef __TICTACTOE_H__ #define __TICTACTOE_H__ #include <gdk/gdk.h> #include <gtk/gtkvbox.h> #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #define TICTACTOE(obj) GTK_CHECK_CAST (obj, tictactoe_get_type (), Tictactoe) #define TICTACTOE_CLASS(klass) GTK_CHECK_CLASS_CAST (klass, tictactoe_get_type (), TictactoeClass) #define IS_TICTACTOE(obj) GTK_CHECK_TYPE (obj, tictactoe_get_type ()) typedef struct _Tictactoe Tictactoe; typedef struct _TictactoeClass TictactoeClass; struct _Tictactoe { GtkVBox vbox; GtkWidget *buttons[3][3]; }; struct _TictactoeClass { GtkVBoxClass parent_class; void (* tictactoe) (Tictactoe *ttt); }; guint tictactoe_get_type (void); GtkWidget* tictactoe_new (void); void tictactoe_clear (Tictactoe *ttt); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __TICTACTOE_H__ */ </verb></tscreen>  <sect2> La funzione <tt/_get_type()/ Continuiamo ora con l'implementazione del nostro widget. Una funzione basilare di ogni widget è la funzione <tt/WIDGETNAME_get_type()/. Questa funzione, quando chiamata la prima volta, comunica a GTK la classe del widget, e ottiene un identificativo univoco per la classe del widget. Chiamate successive restituiscono semplicemente l'identificativo. <tscreen><verb> guint tictactoe_get_type () { static guint ttt_type = 0; if (!ttt_type) { GtkTypeInfo ttt_info = { "Tictactoe", sizeof (Tictactoe), sizeof (TictactoeClass), (GtkClassInitFunc) tictactoe_class_init, (GtkObjectInitFunc) tictactoe_init, (GtkArgSetFunc) NULL, (GtkArgGetFunc) NULL }; ttt_type = gtk_type_unique (gtk_vbox_get_type (), &ttt_info); } return ttt_type; } </verb></tscreen> La struttura GtkTypeInfo ha la seguente definizione: <tscreen><verb> struct _GtkTypeInfo { gchar *type_name; guint object_size; guint class_size; GtkClassInitFunc class_init_func; GtkObjectInitFunc object_init_func; GtkArgSetFunc arg_set_func; GtkArgGetFunc arg_get_func; }; </verb></tscreen> I campi di questa struttura sono abbastanza auto-esplicativi. Ignoreremo, per ora, i campi <tt/arg_set_func/ e <tt/arg_get_func/: hanno un ruolo importante, ma ancora largamente non implementato, nel permettere ai linguaggi interpretati di settare convenientemente le opzioni del widget. Una volta che il GTK ha completato correttamente una copia di questa struttura, sa come creare un oggetto di un particolare widget.  <sect2> La funzione <tt/_class_init()/ La funzione <tt/WIDGETNAME_class_init()/ inizialiazza i campi della struttura della classe del widget, e setta ogni segnale della classe. Per il nostro widget Tictactoe ha il seguente aspetto: <tscreen><verb> enum { TICTACTOE_SIGNAL, LAST_SIGNAL }; static gint tictactoe_signals[LAST_SIGNAL] = { 0 }; static void tictactoe_class_init (TictactoeClass *class) { GtkObjectClass *object_class; object_class = (GtkObjectClass*) class; tictactoe_signals[TICTACTOE_SIGNAL] = gtk_signal_new ("tictactoe", GTK_RUN_FIRST, object_class->type, GTK_SIGNAL_OFFSET (TictactoeClass, tictactoe), gtk_signal_default_marshaller, GTK_TYPE_NONE, 0); gtk_object_class_add_signals (object_class, tictactoe_signals, LAST_SIGNAL); class->tictactoe = NULL; } </verb></tscreen> Il nostro widget ha semplicemente il segnale ``tictactoe'' che è invocato quando una riga, colonna o diagonale è completamente premuta. Non tutti i widget composti necessitano di segnali, quindi se stai leggendo questo per la prima volta, puoi anche saltare alla prossima sezione, dal momento che a questo punto le cose diventano un po' complicate. La funzione: <tscreen><verb> gint gtk_signal_new (const gchar *name, GtkSignalRunType run_type, GtkType object_type, gint function_offset, GtkSignalMarshaller marshaller, GtkType return_val, guint nparams, ...); </verb></tscreen> crea un nuovo segnale. I parametri sono: <itemize> <item> <tt/name/: Il nome del segnale. <item> <tt/run_type/: Se il segstore predefinito viene eseguito prima o dopo di quello dell'utente. Di norma questo sarà <tt/GTK_RUN_FIRST/, o <tt/GTK_RUN_LAST/, anche se ci sono altre possibilità. <item> <tt/object_type/: l'identificativo dell'oggetto a cui questo segnale si riferisce. Esso sarà anche applicato agli oggetti discendenti. <item> <tt/function_offset/: L'offset nella struttura della classe di un puntatore al gestore predefinito. <item> <tt/marshaller/: una funzione che è usata per invocare il gestore del segnale. Per gestori di segnali che non hanno argomenti oltre all'oggetto che emette il segnale e i dati dell'utente, possiamo usare la funzione predefinita <tt/gtk_signal_default_marshaller/ <item> <tt/return_val/: Il tipo del valore di ritorno. <item> <tt/nparams/: Il numero di parametri del gestore di segnali (oltre ai due predefiniti menzionati sopra) <item> <tt/.../: i tipi dei parametri </itemize> Quando si specificano i tipi, si usa l'enumerazione <tt/GtkType/: <tscreen><verb> typedef enum { GTK_TYPE_INVALID, GTK_TYPE_NONE, GTK_TYPE_CHAR, GTK_TYPE_BOOL, GTK_TYPE_INT, GTK_TYPE_UINT, GTK_TYPE_LONG, GTK_TYPE_ULONG, GTK_TYPE_FLOAT, GTK_TYPE_DOUBLE, GTK_TYPE_STRING, GTK_TYPE_ENUM, GTK_TYPE_FLAGS, GTK_TYPE_BOXED, GTK_TYPE_FOREIGN, GTK_TYPE_CALLBACK, GTK_TYPE_ARGS, GTK_TYPE_POINTER, /* sarebbe bello poter togliere alla fine i prossimi due */ GTK_TYPE_SIGNAL, GTK_TYPE_C_CALLBACK, GTK_TYPE_OBJECT } GtkFundamentalType; </verb></tscreen> <tt/gtk_signal_new()/ restituisce un identificatore unico intero per il segnale, che memorizziamo nel vettore <tt/tictactoe_signals/, che indicizzeremo usando una enumerazione. (Convenzionalmente, gli elementi dell'enumerazione sono i nomi dei segnali, in maiuscolo, ma qui ci potrebbe essere un conflitto con la macro <tt/TICTACTOE()/, quindi l'abbiamo chiamato <tt/TICTACTOE_SIGNAL/ Dopo aver creato un nostro segnale, abbiamo bisogno di dire a GTK di associare il nostro segnale alla classe Tictactoe. Lo facciamo invocando <tt/gtk_object_class_add_signals()/. Settiamo quindi a NULL il puntatore che punta al gestore predefinito per il segnale ``tictactoe'' a NULL, indicando che non ci sono azioni predefinite.  <sect2> La funzione <tt/_init()/ Ogni classe di Widget necessita anche di una funzione per inizializzare la struttura dell'oggetto. Usualmente questa funzione ha il ruolo abbastanza limitato di assegnare ai campi della struttura i valori predefiniti. Per widget composti, comunque, questa funzione crea, anche, i widget componenti del widget composto. <tscreen><verb> static void tictactoe_init (Tictactoe *ttt) { GtkWidget *table; gint i,j; table = gtk_table_new (3, 3, TRUE); gtk_container_add (GTK_CONTAINER(ttt), table); gtk_widget_show (table); for (i=0;i<3; i++) for (j=0;j<3; j++) { ttt->buttons[i][j] = gtk_toggle_button_new (); gtk_table_attach_defaults (GTK_TABLE(table), ttt->buttons[i][j], i, i+1, j, j+1); gtk_signal_connect (GTK_OBJECT (ttt->buttons[i][j]), "toggled", GTK_SIGNAL_FUNC (tictactoe_toggle), ttt); gtk_widget_set_usize (ttt->buttons[i][j], 20, 20); gtk_widget_show (ttt->buttons[i][j]); } } </verb></tscreen>  <sect2> E il resto... C'è un'altra funzione che ogni widget (eccetto i Widget di base come GtkBin che non possono essere instanziati) deve avere : la funzione che l'utente invoca per creare un oggetto di quel tipo. Questa è convenzionalmente chiamata <tt/WIDGETNAME_new()/. In alcuni widget, non nel caso del nostro Tictactoe, questa funzione richiede degli argomenti, e fa alcune operazioni basandosi su di essi. Le altre due funzioni sono specifiche del widget Tictactoe. <tt/tictactoe_clear()/ è una funzione pubblica che resetta tutti i bottoni, nel widget, allo stato iniziale (non premuto). Notate l'uso di <tt/gtk_signal_handler_block_by_data()/ per impedire che il nostro gestore dei segnali venga attivato quando non ce n'è bisogno. <tt/tictactoe_toggle()/ è il gestore del segnale che viene invocato quando l'utente preme il bottone. Esso guarda se vi è qualche combinazione vincente che coinvolge i bottoni premuti, e nel caso ci fosse, emette il segnale ``tictactoe''. <tscreen><verb> GtkWidget* tictactoe_new () { return GTK_WIDGET ( gtk_type_new (tictactoe_get_type ())); } void tictactoe_clear (Tictactoe *ttt) { int i,j; for (i=0;i<3;i++) for (j=0;j<3;j++) { gtk_signal_handler_block_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt); gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON (ttt->buttons[i][j]), FALSE); gtk_signal_handler_unblock_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt); } } static void tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt) { int i,k; static int rwins[8][3] = { { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 }, { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 } }; static int cwins[8][3] = { { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 }, { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 }, { 0, 1, 2 }, { 2, 1, 0 } }; int success, found; for (k=0; k<8; k++) { success = TRUE; found = FALSE; for (i=0;i<3;i++) { success = success && GTK_TOGGLE_BUTTON(ttt->buttons[rwins[k][i]][cwins[k][i]])->active; found = found || ttt->buttons[rwins[k][i]][cwins[k][i]] == widget; } if (success && found) { gtk_signal_emit (GTK_OBJECT (ttt), tictactoe_signals[TICTACTOE_SIGNAL]); break; } } } </verb></tscreen> E finalmente un programma di esempio che usa il nostro widget Tictactoe: <tscreen><verb> #include <gtk/gtk.h> #include "tictactoe.h" /* Invocato quando una riga, colonna o diagonale e' completata. */ void win (GtkWidget *widget, gpointer data) { g_print ("Yay!\n"); tictactoe_clear (TICTACTOE (widget)); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *ttt; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame"); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (gtk_exit), NULL); gtk_container_border_width (GTK_CONTAINER (window), 10); /* Crea un nuovo widget Tictactoe. */ ttt = tictactoe_new (); gtk_container_add (GTK_CONTAINER (window), ttt); gtk_widget_show (ttt); /* E gli aggancia il segnale "tictactoe" */ gtk_signal_connect (GTK_OBJECT (ttt), "tictactoe", GTK_SIGNAL_FUNC (win), NULL); gtk_widget_show (window); gtk_main (); return 0; } </verb></tscreen>  <sect1> Creare un widget a partire da zero  <sect2> Introduzione In questa sezione impareremo meglio come i widget si mostrano sullo schermo e interagiscono con gli eventi. Come esempio, creeremo un widget di quadrante analogico con un puntatore che l'utente può trascinare per assegnare il valore.  <sect2> Mostrare un widget sullo schermo Ci sono alcuni passi che sono necessari nella visualizzazione sullo schermo. Dopo che il widget è stato creato con una chiamata a <tt/WIDGETNAME_new()/, sono necessarie alcune altre funzioni: <itemize> <item> <tt/WIDGETNAME_realize()/ è responsabile della creazione di una finestra X per il widget se ne ha una. <item> <tt/WIDGETNAME_map()/ è invocata dopo che l'utente ha chiamato <tt/gtk_widget_show()/. E' responsabile di vedere se il widget è attualmente disegnato sullo schermo (<em/mappato/). Per una classe contenitore, essa deve anche creare chiamate alle funzioni <tt/map()/> per ogni widget figlio. <item> <tt/WIDGETNAME_draw()/ è invocata quando <tt/gtk_widget_draw()/ viene chiamata per il widget o per uno dei suoi predecessori. Esso fa sì che l'attuale chiamata alla funzione di disegno del widget disegni il widget sullo schermo. Per la classe contenitore, questa funzione deve eseguire le chiamate alla funzioni <tt/gtk_widget_draw()/ di ogni suo widget figlio. <item> <tt/WIDGETNAME_expose()/ è un gestore per l'evento di esposizione per il widget. Esso crea le chiamate necessarie alle funzioni di disegno per disegnare la porzione che si è resa visibile. Per le classi contenitore, questa funzione deve generare gli eventi di ``expose'' per tutti i widget figli che non hanno una propria finestra (se essi hanno una loro finestra, sarà X che genererà i necessari eventi di expose). </itemize> Potete notare che le ultime due funzioni sono molto simili, ognuna è responsabile per il disegno del widget sullo schermo. Infatti molti tipi di widget non sanno relamente la differenza tra le due. La funzione di predefinita <tt/draw()/ nella classe widget, semplicemente genera un sintetico evento di ``expose'' per l'area da ridisegnare. Comunque, alcuni tipi di widget possono risparmiare tempo distinguendo le due funzioni. Per esempio, se un widget ha piu' finestre X, allora visto che l'evento ``expose'' identifica solo la finestra esposta, esso può ridisegnare solo la finestra interessata, cosa che non è possibile per chiamate a <tt/draw()/. I widget contenitori, anche se essi non farebbero differenze, non possono semplicemente usare la funzione <tt/draw()/ perchè per i loro widget figli la differenza potrebbere essere importante. Comunque, sarebbe uno spreco duplicare il codice di disegno nelle due funzioni. La convenzione è che questi widget abbiano una funzione chiamata <tt/WIDGETNAME_paint()/ che disegna il widget, che è poi chiamata dalle funzioni <tt/draw()/ e <tt/expose()/ Nell'approccio del nostro esempio, visto che il widget, ha una sola finestra, possiamo utilizzare il modo piu' semplice ed usare la funzione predefinita <tt/draw()/ e implementare solamente la funzione <tt/expose()/.  <sect2> Le origini del widget Dial Come tutti gli animali terresti sono semplicemente varianti del primo amfibio, i widget Gtk tendono ad essere varianti di altri widget, precedentemente scritti. Così, anche se questa sezione è intitolata ``Creare un widget a partire da zero", il nostro widget inizia in realtà con il codice sorgente del widget Range. Questo è stato preso come punto d'inizio perche' sarebbe carino se il nostro widget avesse la stessa interfaccia del widget Scale il quale è semplicemente una specializzazione del widget Range. Così, sebbene il codice sorgente e' presentato sotto in forma definitiva, non si deve pensare che sia stato scritto deus ex machina in questo modo. Se poi non avete familiarità con il funzionamento del widget Scale dal punto di vista di chi scrive un'applicazione, potrebbe essere una buona idea guardare indietro prima di continuare.  <sect2> Le basi Una parte del nostro widget potrebbe essere simile al widget Tictactoe. In primo luogo, abbiamo il file header: <tscreen><verb> /* GTK - The GIMP Toolkit * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ #ifndef __GTK_DIAL_H__ #define __GTK_DIAL_H__ #include <gdk/gdk.h> #include <gtk/gtkadjustment.h> #include <gtk/gtkwidget.h> #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #define GTK_DIAL(obj) GTK_CHECK_CAST (obj, gtk_dial_get_type (), GtkDial) #define GTK_DIAL_CLASS(klass) GTK_CHECK_CLASS_CAST (klass, gtk_dial_get_type (), GtkDialClass) #define GTK_IS_DIAL(obj) GTK_CHECK_TYPE (obj, gtk_dial_get_type ()) typedef struct _GtkDial GtkDial; typedef struct _GtkDialClass GtkDialClass; struct _GtkDial { GtkWidget widget; /* Politica di update (GTK_UPDATE_[CONTINUOUS/DELAYED/DISCONTINUOUS]) */ guint policy : 2; /* Bottone correntemente premuto o 0 altrimenti */ guint8 button; /* Dimensione della componente Dial. */ gint radius; gint pointer_width; /* ID del timer di update, o 0 altrimenti */ guint32 timer; /* Angolo corrente. */ gfloat angle; /* Vecchi valori dell'aggiustamento così sappiamo quando * qualcosa cambia */ gfloat old_value; gfloat old_lower; gfloat old_upper; /* L'oggetto adjustament che memorizza i dati per questo dial */ GtkAdjustment *adjustment; }; struct _GtkDialClass { GtkWidgetClass parent_class; }; GtkWidget* gtk_dial_new (GtkAdjustment *adjustment); guint gtk_dial_get_type (void); GtkAdjustment* gtk_dial_get_adjustment (GtkDial *dial); void gtk_dial_set_update_policy (GtkDial *dial, GtkUpdateType policy); void gtk_dial_set_adjustment (GtkDial *dial, GtkAdjustment *adjustment); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __GTK_DIAL_H__ */ </verb></tscreen> Essendoci più cose da fare con questo widget, rispetto al precedente, abbiamo più cambi nella struttura dati, ma le altre cose sono abbastamza simili. Dopo aver incluso i file di header e aver dichiarato alcune costanti, dobbiamo fornire alcune funzioni circa il widget e la sua inizializzazione. <tscreen><verb> #include <math.h> #include <stdio.h> #include <gtk/gtkmain.h> #include <gtk/gtksignal.h> #include "gtkdial.h" #define SCROLL_DELAY_LENGTH 300 #define DIAL_DEFAULT_SIZE 100 /* Dichiarazioni di funzioni successive */ [ omesse per salvare spazio ] /* variabili locali. */ static GtkWidgetClass *parent_class = NULL; guint gtk_dial_get_type () { static guint dial_type = 0; if (!dial_type) { GtkTypeInfo dial_info = { "GtkDial", sizeof (GtkDial), sizeof (GtkDialClass), (GtkClassInitFunc) gtk_dial_class_init, (GtkObjectInitFunc) gtk_dial_init, (GtkArgSetFunc) NULL, (GtkArgGetFunc) NULL, }; dial_type = gtk_type_unique (gtk_widget_get_type (), &dial_info); } return dial_type; } static void gtk_dial_class_init (GtkDialClass *class) { GtkObjectClass *object_class; GtkWidgetClass *widget_class; object_class = (GtkObjectClass*) class; widget_class = (GtkWidgetClass*) class; parent_class = gtk_type_class (gtk_widget_get_type ()); object_class->destroy = gtk_dial_destroy; widget_class->realize = gtk_dial_realize; widget_class->expose_event = gtk_dial_expose; widget_class->size_request = gtk_dial_size_request; widget_class->size_allocate = gtk_dial_size_allocate; widget_class->button_press_event = gtk_dial_button_press; widget_class->button_release_event = gtk_dial_button_release; widget_class->motion_notify_event = gtk_dial_motion_notify; } static void gtk_dial_init (GtkDial *dial) { dial->button = 0; dial->policy = GTK_UPDATE_CONTINUOUS; dial->timer = 0; dial->radius = 0; dial->pointer_width = 0; dial->angle = 0.0; dial->old_value = 0.0; dial->old_lower = 0.0; dial->old_upper = 0.0; dial->adjustment = NULL; } GtkWidget* gtk_dial_new (GtkAdjustment *adjustment) { GtkDial *dial; dial = gtk_type_new (gtk_dial_get_type ()); if (!adjustment) adjustment = (GtkAdjustment*) gtk_adjustment_new (0.0, 0.0, 0.0, 0.0, 0.0, 0.0); gtk_dial_set_adjustment (dial, adjustment); return GTK_WIDGET (dial); } static void gtk_dial_destroy (GtkObject *object) { GtkDial *dial; g_return_if_fail (object != NULL); g_return_if_fail (GTK_IS_DIAL (object)); dial = GTK_DIAL (object); if (dial->adjustment) gtk_object_unref (GTK_OBJECT (dial->adjustment)); if (GTK_OBJECT_CLASS (parent_class)->destroy) (* GTK_OBJECT_CLASS (parent_class)->destroy) (object); } </verb></tscreen> Notate che questa funzione <tt/init()/ fa meno rispetto all'analoga del widget Tictactoe, essendo questo un widget non composto, e la funzione <tt/new()/ fa di più, essendoci un argomento. Inoltre, notate che quando memorizziamo un puntatore all'oggetto Adjustment, incrementiamo il conteggio dei suoi riferimenti(e corrispondentemente lo decrementato quando non lo usiamo più) così che GTK può tener traccia di quando è possibile distruggerlo senza causare guai. Inoltre, ci sono alcune funzioni per manipolare le opzioni del widget: <tscreen><verb> GtkAdjustment* gtk_dial_get_adjustment (GtkDial *dial) { g_return_val_if_fail (dial != NULL, NULL); g_return_val_if_fail (GTK_IS_DIAL (dial), NULL); return dial->adjustment; } void gtk_dial_set_update_policy (GtkDial *dial, GtkUpdateType policy) { g_return_if_fail (dial != NULL); g_return_if_fail (GTK_IS_DIAL (dial)); dial->policy = policy; } void gtk_dial_set_adjustment (GtkDial *dial, GtkAdjustment *adjustment) { g_return_if_fail (dial != NULL); g_return_if_fail (GTK_IS_DIAL (dial)); if (dial->adjustment) { gtk_signal_disconnect_by_data (GTK_OBJECT (dial->adjustment), (gpointer) dial); gtk_object_unref (GTK_OBJECT (dial->adjustment)); } dial->adjustment = adjustment; gtk_object_ref (GTK_OBJECT (dial->adjustment)); gtk_signal_connect (GTK_OBJECT (adjustment), "changed", (GtkSignalFunc) gtk_dial_adjustment_changed, (gpointer) dial); gtk_signal_connect (GTK_OBJECT (adjustment), "value_changed", (GtkSignalFunc) gtk_dial_adjustment_value_changed, (gpointer) dial); dial->old_value = adjustment->value; dial->old_lower = adjustment->lower; dial->old_upper = adjustment->upper; gtk_dial_update (dial); } </verb></tscreen>  <sect2> <tt/gtk_dial_realize()/ Abbiamo ora raggiunto alcuni nuovi tipi di funzione. In primo luogo, abbiamo una funzione che crea la finestra di X. Noterete che viene passata alla funzione <tt/gdk_window_new()/ una maschera che specifica quali campi della struttura GdkWindowAttr non sono vuoti (ai rimanenti campi può essere dato il valore predefinito). Anche il modo con cui la maschera degli eventi del widget creata non è complicato. Chiameremo <tt/gtk_widget_get_events()/ per sapere la maschera degli eventi che l'utente ha specificato per questo widget (con <tt/gtk_widget_set_events()/) e aggiungeremo gli eventi che ci possono interessare. Dopo aver creato la finestra, settiamo lo stile e lo sfondo, e creiamo un puntatore al widget nel campo dei dati utente (user data) del GdkWindow. Quest'ultimo passo permette a GTK di mandare gli eventi della finestra al widget corretto. <tscreen><verb> static void gtk_dial_realize (GtkWidget *widget) { GtkDial *dial; GdkWindowAttr attributes; gint attributes_mask; g_return_if_fail (widget != NULL); g_return_if_fail (GTK_IS_DIAL (widget)); GTK_WIDGET_SET_FLAGS (widget, GTK_REALIZED); dial = GTK_DIAL (widget); attributes.x = widget->allocation.x; attributes.y = widget->allocation.y; attributes.width = widget->allocation.width; attributes.height = widget->allocation.height; attributes.wclass = GDK_INPUT_OUTPUT; attributes.window_type = GDK_WINDOW_CHILD; attributes.event_mask = gtk_widget_get_events (widget) | GDK_EXPOSURE_MASK | GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK | GDK_POINTER_MOTION_MASK | GDK_POINTER_MOTION_HINT_MASK; attributes.visual = gtk_widget_get_visual (widget); attributes.colormap = gtk_widget_get_colormap (widget); attributes_mask = GDK_WA_X | GDK_WA_Y | GDK_WA_VISUAL | GDK_WA_COLORMAP; widget->window = gdk_window_new (widget->parent->window, &attributes, attributes_mask); widget->style = gtk_style_attach (widget->style, widget->window); gdk_window_set_user_data (widget->window, widget); gtk_style_set_background (widget->style, widget->window, GTK_STATE_ACTIVE); } </verb></tscreen>  <sect2> Negoziazione della dimensione Prima di visualizzare per la prima volta la finestra, e se il layout della finestra cambia, GTK chiede ad ogni widget, incluso nella finestra, la propria dimensione. Questa richiesta è fatta dalla funzione <tt/gtk_dial_size_request()/. Non essendo il nostro widget un contenitore, e non avendo dei veri limiti per la propria dimensione, restituiamo semplicemnte un valore ragionevole. <tscreen><verb> static void gtk_dial_size_request (GtkWidget *widget, GtkRequisition *requisition) { requisition->width = DIAL_DEFAULT_SIZE; requisition->height = DIAL_DEFAULT_SIZE; } </verb></tscreen> Dopo che tutti i widget hanno restituito una dimensione ideale, viene calcolata la disposizione della finestra e ad ogni widget figlio è notificata la propria dimensione attuale . Usualmente, questo sarà almeno quanto richiesto, ma occasionalmente può essere più piccolo. La notifica della dimensione viene fatta dalla funzione <tt/gtk_dial_size_allocate()/. Notate che questa funzione è utilizzata anche quando la finestra X del widget è spostata o modificata come dimensione. <tscreen><verb> static void gtk_dial_size_allocate (GtkWidget *widget, GtkAllocation *allocation) { GtkDial *dial; g_return_if_fail (widget != NULL); g_return_if_fail (GTK_IS_DIAL (widget)); g_return_if_fail (allocation != NULL); widget->allocation = *allocation; if (GTK_WIDGET_REALIZED (widget)) { dial = GTK_DIAL (widget); gdk_window_move_resize (widget->window, allocation->x, allocation->y, allocation->width, allocation->height); dial->radius = MAX(allocation->width,allocation->height) * 0.45; dial->pointer_width = dial->radius / 5; } } </verb></tscreen>.  <sect2> <tt/gtk_dial_expose()/ Come menzionato sopra, tutto il lavoro di questo widget viene fatto nella gestione dell'evento ``expose''. Non c'è molto da notare su questo eccetto l'uso della funzione <tt/gtk_draw_polygon/ per disegnare il puntatore con un'ombreggiatura a tre dimensioni in accordo con il colore memorizzato nello stile del wiget. <tscreen><verb> static gint gtk_dial_expose (GtkWidget *widget, GdkEventExpose *event) { GtkDial *dial; GdkPoint points[3]; gdouble s,c; gdouble theta; gint xc, yc; gint tick_length; gint i; g_return_val_if_fail (widget != NULL, FALSE); g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE); g_return_val_if_fail (event != NULL, FALSE); if (event->count > 0) return FALSE; dial = GTK_DIAL (widget); gdk_window_clear_area (widget->window, 0, 0, widget->allocation.width, widget->allocation.height); xc = widget->allocation.width/2; yc = widget->allocation.height/2; /* Draw ticks */ for (i=0; i<25; i++) { theta = (i*M_PI/18. - M_PI/6.); s = sin(theta); c = cos(theta); tick_length = (i%6 == 0) ? dial->pointer_width : dial->pointer_width/2; gdk_draw_line (widget->window, widget->style->fg_gc[widget->state], xc + c*(dial->radius - tick_length), yc - s*(dial->radius - tick_length), xc + c*dial->radius, yc - s*dial->radius); } /* Draw pointer */ s = sin(dial->angle); c = cos(dial->angle); points[0].x = xc + s*dial->pointer_width/2; points[0].y = yc + c*dial->pointer_width/2; points[1].x = xc + c*dial->radius; points[1].y = yc - s*dial->radius; points[2].x = xc - s*dial->pointer_width/2; points[2].y = yc - c*dial->pointer_width/2; gtk_draw_polygon (widget->style, widget->window, GTK_STATE_NORMAL, GTK_SHADOW_OUT, points, 3, TRUE); return FALSE; } </verb></tscreen>  <sect2> Gestione degli eventi Il resto del codice del widget manipola vari tipi di eventi, e non è differente da quello che può essere trovato in molte applicazione GTK. Due tipi di eventi possono verificarsi: l'utente può clickare sul widget con il mouse e trascinare per muovere il puntatore, o il valore dell'oggetto Adjustmente può cambiare a causa di alcune circostanze esterne. Quando l'utente clicka sul widget, noi vediamo se la pressione era veramente vicina al puntatore, e se così, memorizziamo il bottone premuto dall'utente con il campo <tt/button/ della struttura del widget, e prendiamo tutti gli eventi del mouse con una chiamata alla funzione <tt/gtk_grab_add()/. Successivi movimenti del mouse causano il ricalcolo dei valori di controllo (fatto dalla funzione <tt/gtk_dial_update_mouse/). Dipendentemente dalla politica che abbiamo stabilito, gli eventi ``value_changed'' possono essere generati istantaneamente (<tt/GTK_UPDATE_CONTINUOUS/), dopo un certo tempo aggiunto con la funzione <tt/gtk_timeout_add()/ (<tt/GTK_UPDATE_DELAYED/), o solamente quando il bottone del mouse e' rilasciato (<tt/GTK_UPDATE_DISCONTINUOUS/). <tscreen><verb> static gint gtk_dial_button_press (GtkWidget *widget, GdkEventButton *event) { GtkDial *dial; gint dx, dy; double s, c; double d_parallel; double d_perpendicular; g_return_val_if_fail (widget != NULL, FALSE); g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE); g_return_val_if_fail (event != NULL, FALSE); dial = GTK_DIAL (widget); /* Determina se il bottone premuto era dentro la regione del puntatore: lo facciamo calcolando la distanza parallela e perpendicolare dal punto dove il bottone del mouse e' stato premuto alla linea passante per il puntatore. */ dx = event->x - widget->allocation.width / 2; dy = widget->allocation.height / 2 - event->y; s = sin(dial->angle); c = cos(dial->angle); d_parallel = s*dy + c*dx; d_perpendicular = fabs(s*dx - c*dy); if (!dial->button && (d_perpendicular < dial->pointer_width/2) && (d_parallel > - dial->pointer_width)) { gtk_grab_add (widget); dial->button = event->button; gtk_dial_update_mouse (dial, event->x, event->y); } return FALSE; } static gint gtk_dial_button_release (GtkWidget *widget, GdkEventButton *event) { GtkDial *dial; g_return_val_if_fail (widget != NULL, FALSE); g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE); g_return_val_if_fail (event != NULL, FALSE); dial = GTK_DIAL (widget); if (dial->button == event->button) { gtk_grab_remove (widget); dial->button = 0; if (dial->policy == GTK_UPDATE_DELAYED) gtk_timeout_remove (dial->timer); if ((dial->policy != GTK_UPDATE_CONTINUOUS) && (dial->old_value != dial->adjustment->value)) gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed"); } return FALSE; } static gint gtk_dial_motion_notify (GtkWidget *widget, GdkEventMotion *event) { GtkDial *dial; GdkModifierType mods; gint x, y, mask; g_return_val_if_fail (widget != NULL, FALSE); g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE); g_return_val_if_fail (event != NULL, FALSE); dial = GTK_DIAL (widget); if (dial->button != 0) { x = event->x; y = event->y; if (event->is_hint || (event->window != widget->window)) gdk_window_get_pointer (widget->window, &x, &y, &mods); switch (dial->button) { case 1: mask = GDK_BUTTON1_MASK; break; case 2: mask = GDK_BUTTON2_MASK; break; case 3: mask = GDK_BUTTON3_MASK; break; default: mask = 0; break; } if (mods & mask) gtk_dial_update_mouse (dial, x,y); } return FALSE; } static gint gtk_dial_timer (GtkDial *dial) { g_return_val_if_fail (dial != NULL, FALSE); g_return_val_if_fail (GTK_IS_DIAL (dial), FALSE); if (dial->policy == GTK_UPDATE_DELAYED) gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed"); return FALSE; } static void gtk_dial_update_mouse (GtkDial *dial, gint x, gint y) { gint xc, yc; gfloat old_value; g_return_if_fail (dial != NULL); g_return_if_fail (GTK_IS_DIAL (dial)); xc = GTK_WIDGET(dial)->allocation.width / 2; yc = GTK_WIDGET(dial)->allocation.height / 2; old_value = dial->adjustment->value; dial->angle = atan2(yc-y, x-xc); if (dial->angle < -M_PI/2.) dial->angle += 2*M_PI; if (dial->angle < -M_PI/6) dial->angle = -M_PI/6; if (dial->angle > 7.*M_PI/6.) dial->angle = 7.*M_PI/6.; dial->adjustment->value = dial->adjustment->lower + (7.*M_PI/6 - dial->angle) * (dial->adjustment->upper - dial->adjustment->lower) / (4.*M_PI/3.); if (dial->adjustment->value != old_value) { if (dial->policy == GTK_UPDATE_CONTINUOUS) { gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed"); } else { gtk_widget_draw (GTK_WIDGET(dial), NULL); if (dial->policy == GTK_UPDATE_DELAYED) { if (dial->timer) gtk_timeout_remove (dial->timer); dial->timer = gtk_timeout_add (SCROLL_DELAY_LENGTH, (GtkFunction) gtk_dial_timer, (gpointer) dial); } } } } </verb></tscreen> Cambiamenti esterni all'Adjustment sono comunicati al nostro widget dai segnali ``changed'' e ``value_changed''. Il gestore per queste funzioni chiama <tt/gtk_dial_update()/ per validare gli argomenti, calcolare il nuovo angolo del puntatore e ridisegnare il widget (chiamando <tt/gtk_widget_draw()/). <tscreen><verb> static void gtk_dial_update (GtkDial *dial) { gfloat new_value; g_return_if_fail (dial != NULL); g_return_if_fail (GTK_IS_DIAL (dial)); new_value = dial->adjustment->value; if (new_value < dial->adjustment->lower) new_value = dial->adjustment->lower; if (new_value > dial->adjustment->upper) new_value = dial->adjustment->upper; if (new_value != dial->adjustment->value) { dial->adjustment->value = new_value; gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed"); } dial->angle = 7.*M_PI/6. - (new_value - dial->adjustment->lower) * 4.*M_PI/3. / (dial->adjustment->upper - dial->adjustment->lower); gtk_widget_draw (GTK_WIDGET(dial), NULL); } static void gtk_dial_adjustment_changed (GtkAdjustment *adjustment, gpointer data) { GtkDial *dial; g_return_if_fail (adjustment != NULL); g_return_if_fail (data != NULL); dial = GTK_DIAL (data); if ((dial->old_value != adjustment->value) || (dial->old_lower != adjustment->lower) || (dial->old_upper != adjustment->upper)) { gtk_dial_update (dial); dial->old_value = adjustment->value; dial->old_lower = adjustment->lower; dial->old_upper = adjustment->upper; } } static void gtk_dial_adjustment_value_changed (GtkAdjustment *adjustment, gpointer data) { GtkDial *dial; g_return_if_fail (adjustment != NULL); g_return_if_fail (data != NULL); dial = GTK_DIAL (data); if (dial->old_value != adjustment->value) { gtk_dial_update (dial); dial->old_value = adjustment->value; } } </verb></tscreen>  <sect2> Possibili Miglioramenti Il widget Dial, da come l'abbiamo costruito, è lungo circa 670 linee di codice C. Anche se questo potrebbe sembrare un po' troppo, abbiamo realmente fatto un bel po' con quel tanto di codice, specialmente considerando che molta della lunghezza è costituita da file header e commmenti. Comunque ci sono alcuni miglioramenti che potrebbero essere fatti a questo widget: <itemize> <item> Se tu provate questo widget, troverete che ci sono alcuni lampeggiamenti quando il puntatore viene trascinato in giro. Questo perchè l'intero widget è cancellato ogni volta che il puntatore viene mosso, prima di essere ridisegnato. Spesso, il modo migliore per gestire questo tipo di problema è il disegnare il tutto su una pixmap non visibile, poi copiare il risultato finale sullo schermo in una passata sola (il widget ProgressBar viene disegnato in questo modo). <item> L'utente potrebbe essere abilitato ad usare le frecce su e giu per incrementare e diminuire il valore. <item> Potrebbe essere carino se il widget avesse i bottoni per incrementare e decrementare il valore di step. Anche se potrebbe essere possibile usare dei widget Bottone incorporati per questo, possiamo anche far sì che il bottone sia auto-ripentente quando premuto, come le frecce in una barra di scorrimento. Molto del codice per implementare questo tipo di comportamento può essere trovato nel widget GtkRange. <item> il widget Dial potrebbe essere fatto/creato dentro un widget contenitore con un singolo widget figlio posizionato all'inizio tra i 2 bottoni menzionati prima. L'utente potrebbe poi aggiungere o una etichetta o un widget ``entry'' per mostrare il valore corrente del dial. </itemize>  <sect1> Impararne di più Fin qui abbiamo esposto solo una piccola parte di tutto quello che serve per creare un widget. Se volete davvero scrivere un vostro widget, la miglior risorsa di esempi è lo stesso codice sorgente GTK. Chiedete a voi stessi alcune cose su come deve essere il widget che volete scrivere: è un widget contenitore? dovrà avere una propria finestra? è una modifica di un widget precedente? Trovate poi un widget simile e iniziate a fargli delle modifiche. Buone Fortuna.  <sect>Scribble, Un semplice esempio di Programma di Disegno   <sect1> Panoramica In questa sezione, creeremo un semplice programma di disegno. Durante questo processo, esamineremo come gestire gli eventi generati dal mouse, come disegnare all'interno di una finestra e come disegnare in modo migliore usando una pixmap di supporto. Dopo averlo creato, lo amplieremo aggiungendo il supporto per i dispositivi XInput, per esempio le tavolette grafiche. Il GTK fornisce delle routine di supporto grazie alle quali risulta piuttosto semplice ottenere informazioni estese, come la pressione o l'inclinazione.  <sect1> Gestione degli Eventi I segnali di GTK che abbiamo discusso finora si riferivano ad azioni di alto livello, ad esempio la selezione di un elemento di un menù. Però, a volte è utile sapere qualcosa su cose che si svolgono a livello più basso livello, come possono essere il movimento del mouse o la pressione di un tasto. Ci sono segnali di GTK anche per questi eventi di basso livello. I gestori di questo tipo di segnali hanno un parametro caratteristico in più, che è il puntatore ad una struttura che contiene informazioni riguardo all'evento. Per esempio, ai gestori di eventi che riguardano dei movimenti, si passa un puntatore ad una struttura GdkEventMotion, che è fatta (in parte) così: <tscreen><verb> struct _GdkEventMotion { GdkEventType type; GdkWindow *window; guint32 time; gdouble x; gdouble y; ... guint state; ... }; </verb></tscreen> <tt/type/ avrà il valore del tipo di evento, in questo caso <tt/GDK_MOTION_NOTIFY/, <tt/window/ rappresenta la finestra in cui l'evento si è verificato. <tt/x/ e <tt/y/ forniscono le coordinate dell'evento e <tt/state/ specifica lo stato dei modificatori nel momento in cui l'evento si è verificato (cioè, specifica quali tasti modificatori e tasti del mouse erano premuti in quel momento). E' un OR bit per bit dei seguenti valori: <tscreen><verb> GDK_SHIFT_MASK GDK_LOCK_MASK GDK_CONTROL_MASK GDK_MOD1_MASK GDK_MOD2_MASK GDK_MOD3_MASK GDK_MOD4_MASK GDK_MOD5_MASK GDK_BUTTON1_MASK GDK_BUTTON2_MASK GDK_BUTTON3_MASK GDK_BUTTON4_MASK GDK_BUTTON5_MASK </verb></tscreen> Come succede per gli altri segnali, per determinare cosa deve accadere in corrispondenza di un evento, si chiama <tt>gtk_signal_connect()</tt>. Ma è anche necessario far sì che GTK sappia di quali eventi vogliamo essere informati. A questo fine, chiamiamo la funzione: <tscreen><verb> void gtk_widget_set_events (GtkWidget *widget, gint events); </verb></tscreen> Il secondo campo specifica gli eventi che ci interessano. Si tratta dell'OR bit per bit delle costanti che identificano i diversi tipi di eventi. La lista dei tipi di eventi è la seguente: <tscreen><verb> GDK_EXPOSURE_MASK GDK_POINTER_MOTION_MASK GDK_POINTER_MOTION_HINT_MASK GDK_BUTTON_MOTION_MASK GDK_BUTTON1_MOTION_MASK GDK_BUTTON2_MOTION_MASK GDK_BUTTON3_MOTION_MASK GDK_BUTTON_PRESS_MASK GDK_BUTTON_RELEASE_MASK GDK_KEY_PRESS_MASK GDK_KEY_RELEASE_MASK GDK_ENTER_NOTIFY_MASK GDK_LEAVE_NOTIFY_MASK GDK_FOCUS_CHANGE_MASK GDK_STRUCTURE_MASK GDK_PROPERTY_CHANGE_MASK GDK_PROXIMITY_IN_MASK GDK_PROXIMITY_OUT_MASK </verb></tscreen> Per chiamare <tt/gtk_widget_set_events()/, si devono fare alcune osservazioni sottili. In primo luogo, la si deve chiamare prima che sia stata creata la finestra X per il widget GTK. In pratica, ciò significa che la si deve chiamare subito dopo aver creato il widget. In secondo luogo, il widget deve avere una finestra X associata. Molti widget, per ragioni di efficienza, non hanno una propria finetra, e vengono mostrati nella finestra madre. Questi widget sono: <tscreen><verb> GtkAlignment GtkArrow GtkBin GtkBox GtkImage GtkItem GtkLabel GtkPixmap GtkScrolledWindow GtkSeparator GtkTable GtkAspectFrame GtkFrame GtkVBox GtkHBox GtkVSeparator GtkHSeparator </verb></tscreen> Per catturare degli eventi per questo tipo di widget, si deve fare uso del widget EventBox. Si veda a questo proposito la sezione su <ref id="sec_The_EventBox_Widget" name="The EventBox Widget">. Per il nostro programma di disegno, vogliamo sapere quando il pulsante del mouse è premuto e quando viene mosso, quindi specificheremo <tt/GDK_POINTER_MOTION_MASK/ e <tt/GDK_BUTTON_PRESS_MASK/. Vogliamo anche essere informati su quando è necessario ridisegnare la nostra finestra, quindi specifichiamo <tt/GDK_EXPOSURE_MASK/. Anche se vogliamo essere avvertiti con un evento ``Configure'' se la dimensione della nostra finestra cambia, non è necessario specificare il flag <tt/GDK_STRUCTURE_MASK/, dal momento che questo viene specificato automaticamente per tutte le finestre. Risulta, conunque, che specificando semplicemente <tt/GDK_POINTER_MOTION_MASK/ si crea un problema. Ciò infatti fa sì che il server aggiunga nella coda un un nuovo evento di movimento ogni volta che l'utente muovoe il mouse. Immaginate che ci vogliano 0.1 secondi per gestire uno di questi eventi, e che il server X metta in coda un nuovo evento ogni 0.05 secondi. Rimarremo ben presto indietro rispetto al disegno dell'utente. Se l'utente disegna per 5 secondi, ci metteremmo altri 5 secondi prima di finire dopo che l'utente ha rilasciato il pulsante del mouse! Vorremmo quindi che venga notificato un solo evento di movimento per ogni evento che processiamo. Il modo per farlo è di specificare <tt/GDK_POINTER_MOTION_HINT_MASK/. Quando specifichiamo <tt/GDK_POINTER_MOTION_HINT_MASK/, il server ci notifica un evento di movimento la prima volta che il puntatore si muove dopo essere entrato nella nostra finestra, oppure dopo ogni rilascio di un pulsante del mouse. Gli altri eventi di movimento verranno soppressi finché non richiediamo esplicitamente la posizione del puntatore con la funzione: <tscreen><verb> GdkWindow* gdk_window_get_pointer (GdkWindow *window, gint *x, gint *y, GdkModifierType *mask); </verb></tscreen> (c'è anche un'altra funzione, <tt>gtk_widget_get_pointer()</tt>, che ha un'interfaccia più semplice, ma che non risulta molto utile dal momento che restituisce solo la posizione del puntatore, senza dettagli sullo sato dei pulsanti.) Quindi, il codice per assegnare gli eventi per la nostra finestra, avrà l'aspetto: <tscreen><verb> gtk_signal_connect (GTK_OBJECT (drawing_area), "expose_event", (GtkSignalFunc) expose_event, NULL); gtk_signal_connect (GTK_OBJECT(drawing_area),"configure_event", (GtkSignalFunc) configure_event, NULL); gtk_signal_connect (GTK_OBJECT (drawing_area), "motion_notify_event", (GtkSignalFunc) motion_notify_event, NULL); gtk_signal_connect (GTK_OBJECT (drawing_area), "button_press_event", (GtkSignalFunc) button_press_event, NULL); gtk_widget_set_events (drawing_area, GDK_EXPOSURE_MASK | GDK_LEAVE_NOTIFY_MASK | GDK_BUTTON_PRESS_MASK | GDK_POINTER_MOTION_MASK | GDK_POINTER_MOTION_HINT_MASK); </verb></tscreen> Teniamo per dopo i gestori di ``expose_event'' e ``configure_event''. Quelli di ``motion_notify_event'' e ``button_press_event'' sono piuttosto semplici: <tscreen><verb> static gint button_press_event (GtkWidget *widget, GdkEventButton *event) { if (event->button == 1 && pixmap != NULL) draw_brush (widget, event->x, event->y); return TRUE; } static gint motion_notify_event (GtkWidget *widget, GdkEventMotion *event) { int x, y; GdkModifierType state; if (event->is_hint) gdk_window_get_pointer (event->window, &x, &y, &state); else { x = event->x; y = event->y; state = event->state; } if (state & GDK_BUTTON1_MASK && pixmap != NULL) draw_brush (widget, x, y); return TRUE; } </verb></tscreen>  <sect1> Il widget Area di Disegno (DrawingArea) e il procedimento per Disegnare Vediamo ora il procedimento per disegnare sullo schermo. Il widget da usare è l'Area di Disegno (DrawingArea). Essenzialmente si tratta di una finestra X e nient'altro. E' una tela bianca su cui possimo disegnare tutto quello che vogliamo. Per crearne una usiamo la chiamata: <tscreen><verb> GtkWidget* gtk_drawing_area_new (void); </verb></tscreen> Per specificare una dimensione predefinita, si puo fare: <tscreen><verb> void gtk_drawing_area_size (GtkDrawingArea *darea, gint width, gint height); </verb></tscreen> Come è vero per tutti i widget, si può modificare questa dimensione predefinita, tramite la chamata a <tt>gtk_widget_set_usize()</tt>, e questa a sua volta può essere modificata dall'utente ridimensionando manualmente la finestra che contiene l'area di disegno. Si deve notare che nel momento in cui creiamo un widget DrawingArea, siamo completamente responsabili di disegnarne il contenuto. Se ad esempio la nostra finestra viene prima nascosta e poi dinuovo portata in primo piano, otteniamo un evento di ``esposizione'' e doppiamo ridisegnare ciò che era stato precedente nascosto. Dover ricordare tutto quello che era disegnato sulla finestra in modo da poterlo ridisegnare successivamente, può essere, come minimo, noioso. In più, può essere spiacevole dal punto di vista visivo, se delle porzioni dello schermo vengono prima cancellate e poi ridisegnate passo per passo. La soluzione per questo problema è di usare una pixmap di supporto. Invece di disegnare direttamente sullo schermo, disegnamo su un'iimagine conservata nella memoria del server ma che non viene mostrata; quindi, quando l'immagine cambia o ne vengono mostrate nuove porzioni, copiamo sullo schermo le parti corrispondenti. Per creare una ppixmap fuori dallo schermo, usiamo la funzione: <tscreen><verb> GdkPixmap* gdk_pixmap_new (GdkWindow *window, gint width, gint height, gint depth); </verb></tscreen> Il parametro <tt>window</tt>specifica una finestra GDK dalla quale questa pixmap prende alcune delle sue proprietà. <tt>width</tt> e <tt>height</tt> specificano le dimensioni della pixmap. <tt>depth</tt> specifica la profondità di colore, cioè il numero di bit per ogni pixel, per la nuova pixmap. Se alla profondità è assegnato il valore <tt>-1</tt>, questa verrà posta identica a quella di <tt>window</tt>. Creiamo la pixmap all'interno del gestore di ``configure_event''. Questo evento è generato ogni volta che la finestra cambia di dimensione, compreso il momento in cui viene creata per la prima volta. <tscreen><verb> /* Pixmap di supporto per l'area di disegno */ static GdkPixmap *pixmap = NULL; /* Creare una pixmap della dimensione appropriata */ static gint configure_event (GtkWidget *widget, GdkEventConfigure *event) { if (pixmap) { gdk_pixmap_destroy(pixmap); } pixmap = gdk_pixmap_new(widget->window, widget->allocation.width, widget->allocation.height, -1); gdk_draw_rectangle (pixmap, widget->style->white_gc, TRUE, 0, 0, widget->allocation.width, widget->allocation.height); return TRUE; } </verb></tscreen> La chiamata a <tt>gdk_draw_rectangle()</tt> inizialmente rende bianca l'intera pixmap. Fra un momento ne riparleremo. Il gestore dell'evento ``esposizione'', copia quindi la porzione appropriata della pixmap sullo schermo (determiniamo qual è l'area da ridisegnare usando il campo event->area dell'evento di esposizione): <tscreen><verb> /* Ridisegna sullo schermo a partire dalla pixmap di supporto */ static gint expose_event (GtkWidget *widget, GdkEventExpose *event) { gdk_draw_pixmap(widget->window, widget->style->fg_gc[GTK_WIDGET_STATE (widget)], pixmap, event->area.x, event->area.y, event->area.x, event->area.y, event->area.width, event->area.height); return FALSE; } </verb></tscreen> Abbiamo quindi visto come tenete aggiornato lo schermo con la nostra pixmap, ma come facciamo per disegnare delle cose interessanti sulla pixmap? Ci sono un bel po' di funzioni nella libreria GDK di GTK che servono per disegnare su superfici disegnabili. Una superficie disegnabile è semplicemente qualcosa su cui si può disegnare un'immagine. Può essere una finestra, una pixmap o una bitmap (un'immagine in bianco e nero). Abbiamo già visto sopra due di chiamate, <tt>gdk_draw_rectangle()</tt> and <tt>gdk_draw_pixmap()</tt>. La lista completa è la seguente: <tscreen><verb> gdk_draw_line () gdk_draw_rectangle () gdk_draw_arc () gdk_draw_polygon () gdk_draw_string () gdk_draw_text () gdk_draw_pixmap () gdk_draw_bitmap () gdk_draw_image () gdk_draw_points () gdk_draw_segments () </verb></tscreen> Per ulteriori dettagli su queste funzioni, vedete la documentazione di riferimento nei file header <tt><gdk/gdk.h></tt>. Tutte queste funzioni hanno i medesimi primi due argomenti. Il primo è la superficie disegnabili su cui disegnare, il secondo è un contesto grafico (GC). Un contesto grafico incapsula delle informazioni riguardo a cose come il colore di sfondo e di primo piano e lo spessore della linea. GDK ha un ampio insieme di funzioni per crare e modificare contesti grafici, ma per tenere le cose semplici useremo solo dei contesti grafici predefiniti. Ogni widget ha uno stile associato (che può essere modificato agendo su un file gtkrc). Questo, fra le altre cose, contiene un certo numero di contesti grafici. Alcuni esempi di come accedere a questi contesti grafici sono i seguenti: <tscreen><verb> widget->style->white_gc widget->style->black_gc widget->style->fg_gc[GTK_STATE_NORMAL] widget->style->bg_gc[GTK_WIDGET_STATE(widget)] </verb></tscreen> I campi <tt>fg_gc</tt>, <tt>bg_gc</tt>, <tt>dark_gc</tt>, e <tt>light_gc</tt> sono indicizzati tramite un parametri di tipo <tt>GtkStateType</tt>, che può assumere i valori: <tscreen><verb> GTK_STATE_NORMAL, GTK_STATE_ACTIVE, GTK_STATE_PRELIGHT, GTK_STATE_SELECTED, GTK_STATE_INSENSITIVE </verb></tscreen> Per esempio, per <tt/GTK_STATE_SELECTED/ il colore di sfondo predefinito è blu scuro e quello di primo piano bianco. La nostra funzione <tt>draw_brush()</tt>, che efettivamente disegna sullo schermo, diventa quindi: <tscreen><verb> /* Disegna un rettangolo sullo schermo */ static void draw_brush (GtkWidget *widget, gdouble x, gdouble y) { GdkRectangle update_rect; update_rect.x = x - 5; update_rect.y = y - 5; update_rect.width = 10; update_rect.height = 10; gdk_draw_rectangle (pixmap, widget->style->black_gc, TRUE, update_rect.x, update_rect.y, update_rect.width, update_rect.height); gtk_widget_draw (widget, &update_rect); } </verb></tscreen> Dopo aver disegnato il rettangolo sulla pixmap, chiamiamo la funzione: <tscreen><verb> void gtk_widget_draw (GtkWidget *widget, GdkRectangle *area); </verb></tscreen> che notifica a X che l'area data dal parametro <tt>area</tt> deve essere aggiornata. X poi genererà un evento di esposizione (che può essere combinato con le aree passate da diverse chiamate a <tt>gtk_widget_draw()</tt>) che farà sì che il nostro gestore dell'evento di esposizione, copi le porzioni rilevanti sullo schermo. Abbiamo a questo punto creato tutto il programma di disegno, tranne che per qualche dettaglio irrilevante come la creazione della finestra principale. Il codice sorgente completo è reperibile dove avete ottenuto questo tutorial, oppure da: <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial" name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">  <sect1> Aggiungere il supporto per XInput Al giorno d'oggi è possibile acquistare dei dispositivi abbastanza a buon mercato, come tavolette grafice, che permettono di disegnare con una espressività artistica molto semplificata rispetto ad un mouse. Il modo più semplice per usare questi dispositivi è di sostituirli semplicemente al mouse, ma in questo modo si perdono molti dei loro vantaggi, come: <itemize> <item> Sensibilità alla pressione <item> Sensibilità all'inclinazione <item> Posizionamento infra-pixel <item> Ingressi multipli (per esempio, uno stilo che contiene sia una ``matita'' sia una ``gomma'') </itemize> Per ulteriori informazioni sulle estensioni XInput, vedere l'<htmlurl url="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html" name="XInput-HOWTO">. Se esaminiamo, per esempio, la definizione completa della struttura GdkEventMotion, possiamo vedere che contiene dei campi per il supporto delle informazioni estese dai dispositivi. <tscreen><verb> struct _GdkEventMotion { GdkEventType type; GdkWindow *window; guint32 time; gdouble x; gdouble y; gdouble pressure; gdouble xtilt; gdouble ytilt; guint state; gint16 is_hint; GdkInputSource source; guint32 deviceid; }; </verb></tscreen> <tt/pressure/ fornisce la pressione sotto forma di un numero decimale compreso fra 0 e 1. <tt/xtilt/ e <tt/ytilt/ possono assumere valori compresi fra -1 e 1, corrispondenti al grado di inclinazione in ciascuna direzione. <tt/source/ e <tt/deviceid/ specificano il dispositivo per il quale si è verificato l'evento in due modi distinti. <tt/source/ da alcune semplici informazioni sul tipo di dispositivo, e può assumere i valori: <tscreen><verb> GDK_SOURCE_MOUSE GDK_SOURCE_PEN GDK_SOURCE_ERASER GDK_SOURCE_CURSOR </verb></tscreen> <tt/deviceid/ specifica invece un identificativo numerico univoco per il dispositivo. Questo può essere a sua volta utilizzato per avere ulteriori informazioni sul dispositivo tramite la chiamata a <tt/gdk_input_list_devices()/ (vedi sotto). Il valore speciale <tt/GDK_CORE_POINTER/ viene usato per identificare il dispositivo di puntamento principale (di solito il mouse). <sect2> Abilitare le informazioni estese Per far sì che GTK sappia che ci interessano le informazioni estese dai dispositivi, basta aggiungere un'unica linea al nostro programma: <tscreen><verb> gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR); </verb></tscreen> Dando il valore <tt/GDK_EXTENSION_EVENTS_CURSOR/, diciamo che ci interessano gli eventi relativi alle estensioni, ma solo se non dobbiamo disegnare da noi il nostro cursore. Si veda più sotto alla sezione <ref id="sec_Further_Sophistications" name="Ulteriori Sofisticazioni"> per ulteriori informazioni sul modo si disegnare i cursori. Potremmo anche dare i valori <tt/GDK_EXTENSION_EVENTS_ALL/ se vogliamo disegnare il nostro cursore o <tt/GDK_EXTENSION_EVENTS_NONE/ se vogliamo tornare alle condizioni predefinite. Comunque, non finisce tutto qui. Non ci sono estensioni abilitate per difetto. Abbiamo bisogno di un meccanismo per permettere agli utenti l'abilitazione e la configurazione delle estensioni dei loro dispositivi, GTK fornisce il widget InputDialog per automatizzare questo processo. La seguente procedura mostra come gestire un widget InputDialog. Crea la finestra di dialogo nel caso non sia presente, mentre la porta in primo piano in caso contrario. <tscreen><verb> void input_dialog_destroy (GtkWidget *w, gpointer data) { *((GtkWidget **)data) = NULL; } void create_input_dialog () { static GtkWidget *inputd = NULL; if (!inputd) { inputd = gtk_input_dialog_new(); gtk_signal_connect (GTK_OBJECT(inputd), "destroy", (GtkSignalFunc)input_dialog_destroy, &inputd); gtk_signal_connect_object (GTK_OBJECT(GTK_INPUT_DIALOG(inputd)->close_button), "clicked", (GtkSignalFunc)gtk_widget_hide, GTK_OBJECT(inputd)); gtk_widget_hide ( GTK_INPUT_DIALOG(inputd)->save_button); gtk_widget_show (inputd); } else { if (!GTK_WIDGET_MAPPED(inputd)) gtk_widget_show(inputd); else gdk_window_raise(inputd->window); } } </verb></tscreen> (Notate come gestiamo questo dialogo. Con la connessione del segnale ``destroy'' ci assicuriamo di non tenerci in giro il puntatore al dialogo dopo che lo abbiamo distrutto, cosa che potrebbe portare ad un errore di segmentazione.) L'InputDialog ha due pulsanti, ``Close'' e ``Save'', i quali non hanno alcuna azione predefinita assegnata ad essi. Nella funzione precedente, abbiamo fatto in modo che ``Close'' nasconda la finestra di dialogo, e abbiamo nascosto il pulsante ``Save'' dal momento che in questo programma non implementiamo il salvataggio delle opzioni di XInput. <sect2> Usare le informazioni estese Una volta abilitato il dipositivo, possiamo usare le informazioni estese che si trovano nei corrispondenti campi delle strutture che descrivono gli eventi. A dire il vero, l'utilizzo di questi campi è sempre sicuro, perché sono tutti posti per difetto a valori ragionevoli ancje quando la gestione degli eventi estesi non è abilitata. Un cambiamento che dobbiamo fare è di chiamare <tt/gdk_input_window_get_pointer()/ invece di <tt/gdk_window_get_pointer/. Ciò si rende necessario perché <tt/gdk_window_get_pointer/ non restituisce le informazioni esetese. <tscreen><verb> void gdk_input_window_get_pointer (GdkWindow *window, guint32 deviceid, gdouble *x, gdouble *y, gdouble *pressure, gdouble *xtilt, gdouble *ytilt, GdkModifierType *mask); </verb></tscreen> Quando chiamiamo questa funzione, dobbiamo specificare l'identificativo del dispositivo e la finestra. Normalmente questo identificativo lo si ottiene dal campo <tt/deviceid/ della struttura dell'evento. Questa funzione restituirà valori ragionevoli nel caso che la gestione degli eventi estesi non sia attivata (in questo caso, <tt/event->deviceid/ avrà il valore <tt/GDK_CORE_POINTER/). Quindi, la struttura di base dei gestori degli eventi relativi alla pressione di bottoni e ai movomenti non cambia molto - abbiamo solo bisogno di aggiungere il codice necessario per tenere conto delle informazioni estese. <tscreen><verb> static gint button_press_event (GtkWidget *widget, GdkEventButton *event) { print_button_press (event->deviceid); if (event->button == 1 && pixmap != NULL) draw_brush (widget, event->source, event->x, event->y, event->pressure); return TRUE; } static gint motion_notify_event (GtkWidget *widget, GdkEventMotion *event) { gdouble x, y; gdouble pressure; GdkModifierType state; if (event->is_hint) gdk_input_window_get_pointer (event->window, event->deviceid, &x, &y, &pressure, NULL, NULL, &state); else { x = event->x; y = event->y; pressure = event->pressure; state = event->state; } if (state & GDK_BUTTON1_MASK && pixmap != NULL) draw_brush (widget, event->source, x, y, pressure); return TRUE; } </verb></tscreen> Avremo anche bisogno di fare qualcosa con queste nuove informazioni. La nostra nuova funzione <tt/draw_brush/ disegna con un colore diverso per ogni <tt/event->source/ e cambia la dimensione della linea in funzione della pressione. <tscreen><verb> /* Disegna un rettangolo sullo schermo, con la dimensione dipendente dalla pressione e il colore dipendente dal tipo di dispositivo */ static void draw_brush (GtkWidget *widget, GdkInputSource source, gdouble x, gdouble y, gdouble pressure) { GdkGC *gc; GdkRectangle update_rect; switch (source) { case GDK_SOURCE_MOUSE: gc = widget->style->dark_gc[GTK_WIDGET_STATE (widget)]; break; case GDK_SOURCE_PEN: gc = widget->style->black_gc; break; case GDK_SOURCE_ERASER: gc = widget->style->white_gc; break; default: gc = widget->style->light_gc[GTK_WIDGET_STATE (widget)]; } update_rect.x = x - 10 * pressure; update_rect.y = y - 10 * pressure; update_rect.width = 20 * pressure; update_rect.height = 20 * pressure; gdk_draw_rectangle (pixmap, gc, TRUE, update_rect.x, update_rect.y, update_rect.width, update_rect.height); gtk_widget_draw (widget, &update_rect); } </verb></tscreen> <sect2> Trovare ulteriori informazioni su di un dispositivo Come esempio del modo di trovare altre informazioni su di un dispositivo, il nostro programma stamperà il nome di ogni dispositivo che genera un evento di pressione di un pulsante. Per avere il nome di un dispositivo, chiamiamo la funzione <tscreen><verb> GList *gdk_input_list_devices (void); </verb></tscreen> che restituisce una GList (un tipo di lista collegata che si trova nella libreria glib) di strutture di tipo GdkDeviceInfo. La definizione di GdkDeviceInfo è la seguente: <tscreen><verb> struct _GdkDeviceInfo { guint32 deviceid; gchar *name; GdkInputSource source; GdkInputMode mode; gint has_cursor; gint num_axes; GdkAxisUse *axes; gint num_keys; GdkDeviceKey *keys; }; </verb></tscreen> La maggior parte di questi campi rappresentano informazioni di configurazione che potete ignorare a meno che non implementiate il salvataggio della configurazione di un XInput. Quelle che ci interessano sono <tt/name/, che è semplicemente il nome che X assegna al dispositivo, e <tt/has_cursor/. Anche <tt/has_cursor/ non è informazione di configurazione, e indica, nel caso abbia valore ``falso'', che dobbiamo disegnare da soli il nostro cursore. Ma dal momento che abbiamo specificato <tt/GDK_EXTENSION_EVENTS_CURSOR/, possiamo anche non preoccuparcene. La nostra funzione <tt/print_button_press()/ scorre semplicemente la lista che è stata restituita finché non trova il valore corretto, e poi stampa il nome del dispositivo. <tscreen><verb> static void print_button_press (guint32 deviceid) { GList *tmp_list; /* gdk_input_list_devices restituisce una lista interna, così poi non dobbiamo liberarla */ tmp_list = gdk_input_list_devices(); while (tmp_list) { GdkDeviceInfo *info = (GdkDeviceInfo *)tmp_list->data; if (info->deviceid == deviceid) { printf("Button press on device '%s'\n", info->name); return; } tmp_list = tmp_list->next; } } </verb></tscreen> Questo completa i cambiamenti necessari per usare gli XInput nel nostro programma. Come per la prima versione, i sorgenti completi sono prelevabili da dove avete prelevato questo tutorial, oppure da: <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial" name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial"> <sect2> Ulteriori sofisticazioni <label id="sec_Further_Sophistications"> Anche se ora il nostro programma supporta XInput pittosto bene, gli mancano alcune caratteristiche che probabilmente vorremmo mettere in una applicazione completa. In primo luogo, probabilmente all'utente non farà piacere dover configurare i propri dispositivi ogni volta che lanciano il programma, per cui dovremmo dare la possibilità di salvare la configurazione dei dispositivi. Ciò può essere fatto scorrendo la lista restituita da <tt/gdk_input_list_devices()/ e scrivendo la configurazione su di un file. Per tornare allo stato salvato la prossima volta che il programma viene eseguito, GDK mette a disposizione delle funzioni per cambiare la configurazione dei dispositivi: <tscreen><verb> gdk_input_set_extension_events() gdk_input_set_source() gdk_input_set_mode() gdk_input_set_axes() gdk_input_set_key() </verb></tscreen> (La lista restituita da <tt/gdk_input_list_devices()/ non dovrebbe essere modificata direttamente.) Un esempio di come fare può essere trovato nel programma di disegno gsumi (disponibile da <htmlurl url="http://www.msc.cornell.edu/~otaylor/gsumi/" name="http://www.msc.cornell.edu/~otaylor/gsumi/">). Sarebbe bello avere alla fine un modo standard di recuperare le informazioni per tutte le applicazioni. Questo probabilmente appartiene ad un livello un po' più elevato ripetto a GTK, forse alla libreria GNOME. Un'altra notevole omissione a cui abbiamo accennato precedentemente è il fatto di non disegnare il cursore direttamente. Piattaforme diverse da XFree86 non permettono in questo momento di usare contemporaneamente un dispositivo sia come puntatore principale sia direttamente da una applicazione. Vedere <url url="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html" name="XInput-HOWTO"> per ulteriori informazioni. Ciò significa che le applicazioni che vogliono rivolgersi al pubblico più ampio dovranno prevedere di disegnare esse stesse il proprio cursore. Un'applicazione che voglia disegnare il proprio cursore dovrà fare due cose: determinare se il dispositivo corrente necessita che venga disegnato un cursore, e determinare se il dispositivo corrente è in prossimità. (Se il dispositivo è una tavoletta grafica, un tocco di finezza è fare sparire il puntatore quando lo stilo viene sollevato dalla tavoletta. Quando c'è contatto fra lo stilo e la tavoletta, si dice che il dispositivo è ``in prossimità".) La prima cosa viene fatta scorrendo la lista dei dispositivi, come abbiamo fatto per trovare il nome del dispositivo. La seconda cosa viene ottenuta selezionando gli eventi ``proximity_out''. Un esempio di disegno del proprio cursore si trova nel programma 'testinput' incluso nella distribuzione di GTK.  <sect>Consigli per scrivere Applicazioni GTK  Questa sezione è semplicemente una raccolta di saggezza, una guida di stile e un aiuto per creare buone applicazioni GTK. E' totalmente inutile per ora perché è solamente un appunto. Usa autoconf e automake! Sono tuoi amici :) Ho intenzione di fare una piccola introduzione su di loro qui.  <sect>Contributi  Questo documento, come molti altri grandi software là fuori, è stato creato da volontari. Se sai tutto quello che c'è da sapere su GTK e non lo hai trovato qui allora considera la possibilità di contribuire a questo documento. Se decidi di contribuire, ti prego di trasmettere il tuo lavoro a Tony Gale, <tt><htmlurl url="mailto:gale@gtk.org" name="gale@gtk.org"></tt>. Inoltre, ricorda che l'intero documento è ``free'', e che ogni tua aggiunta sarà considerata allo stesso modo. Per questo motivo le persone possono usare porzioni dei tuoi esempi nei loro programmi, copie di questo documento possono essere distribuite all'infinito, ecc... Grazie.  <sect>Credits  Voglio qui ringraziare le persone che seguono, per il loro contributo alla stesura di questo testo. <itemize> <item>Bawer Dagdeviren, <tt><htmlurl url="mailto:chamele0n@geocities.com" name="chamele0n@geocities.com"></tt> per il tutorial sui menù. <item>Raph Levien, <tt><htmlurl url="mailto:raph@acm.org" name="raph@acm.org"></tt> per il "hello world" alla GTK, l'immpacchettamento del widget, e in generale per tutta la sua saggezza. Lui ha anche donato una casa per questo tutorial. <item>Peter Mattis, <tt><htmlurl url="mailto:petm@xcf.berkeley.edu" name="petm@xcf.berkeley.edu"></tt> Per il più semplice programma GTK e l'abilità di farlo. :) <item>Werner Koch <tt><htmlurl url="mailto:werner.koch@guug.de" name="werner.koch@guug.de"></tt> per la conversione da testo semplice a SGML e la gerarchia delle classi di widget. <item>Mark Crichton <tt><htmlurl url="mailto:crichton@expert.cc.purdue.edu" name="crichton@expert.cc.purdue.edu"></tt> per il codice della "MenuFactory" e per la parte sull'impacchettamento nelle tabelle del tutorial. <item>Owen Taylor <tt><htmlurl url="mailto:owt1@cornell.edu" name="mailto:owt1@cornell.edu"></tt> per la sezione del widget EventBox (e il patch alla distribuzione). Lui è anche responsabile per il codice e il tutorial delle selezioni, come per la sezione sulla scrittura di un proprio widget, e l'applicazione d'esempio. Grazie di tutto Owen. <item>Mark VanderBoom <tt><htmlurl url="mailto:mvboom42@calvin.edu" name="mailto:mailto:mvboom42@calvin.edu"></tt> per il suo meraviglioso lavoro sul Notebook, Progres Bar, Dialogs e File selection. Grazie molto Mark. Sei stato di grande aiuto. <item>Tim Janik <tt><htmlurl url="mailto:timj@psynet.net" name="mailto:timj@psynet.net"></tt> per il suo grande lavoro sul widget List. Grazie Tim :) <item> Michael K. Johnson <tt><htmlurl url="mailto:johnsonm@redhat.com" name="johnsonm@redhat.com"> </tt> per le informazioni e il codice dei menu a comparsa. </itemize> E a tutti voi che avete fatto commenti e avete aiutato a raffinare questo documento. Thanks.  <sect> Dichiarazione di Copyright e Licenza  A questa traduzione, Copyright (c) 1997-1998 di Michel Morelli, Daniele Canazza e Antonio Schifano, si applica la medesime licenza prevista dal lavoro originale di Ian Main e Tony Gale. Segue la traduzione di quelle disposizioni e la loro versione originale. In caso di discordanze fra traduzione e versione originale, fa fede quest'ultima. Il GTK Tutorial è Copyright (c) 1997 Ian Main. Copyright (c) 1998 Tony Gale. E' permesso fare e distribuire copie non modificate di questo manuale, sotto la condizione che la dichiarazione di copyright e queste disposizioni siano riportate su tutte le copie. E' permesso fare e distribuire copie di versioni modificate di questo documento, sotto le stesse condizioni previste per la copia non modificata, e che questa dichiarazione di copyright sia inclusa esattamente come nell'originale, e che l'intero lavoro risultante sia distribuito sotto i termini di una licenza identica a questa. E' permesso fare e distribuire copie di traduzioni di questo documento in altre lingue, sotto le stesse condizioni previste per le versioni modificate. Nel caso si intenda includere questo documento in un lavoro pubblicato, si prega di contattarne il curatore, che cercherà di mettere a disposizione le informazioni più aggiornate. Non c'è garanzia che questo documento sia rispondente ai propri propositi. Esso viene semplicemente fornito come una risorsa "free" (libera e gratuita). In quanto tale, gli autori e i curatori delle informazioni contenute in esso, non possono dare alcuna garanzia nemmeno sul fatto che tali informazioni siano accurate. --------------------- The GTK Tutorial is Copyright (C) 1997 Ian Main. Copyright (C) 1998 Tony Gale. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that this copyright notice is included exactly as in the original, and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this document into another language, under the above conditions for modified versions. If you are intending to incorporate this document into a published work, please contact the maintainer, and we will make an effort to ensure that you have the most up to date information available. There is no guarentee that this document lives up to its intended purpose. This is simply provided as a free resource. As such, the authors and maintainers of the information provided within can not make any guarentee that the information is even accurate. </article>