  GTK Tutorial
  Ian Main <imain@gtk.org>, Tony Gale <gale@gtk.org>
  May 24th, 1998  - Traduzione aggiornata al 27 Maggio 1998

  Tradotto da Michel Morelli, ziobudda@chiara.dei.unipd.it, Daniele
  Canazza, dcanazz@tin.it e Antonio Schifano, schifano@cli.di.unipi.it

  1.  Introduzione

  GTK (GIMP Toolkit) e stato orginariamente sviluppato come toolkit per
  il programma GIMP (General Image Manipulation Program). GTK e
  costruito sulla base del kit di disegno di GIMP, il GDK (GIMP Drawing
  Kit) il quale e costruito a sua volta attorno alle funzioni della
  Xlib. E' chiamato ``toolkit di GIMP'' perche era inizialmente scritto
  per sviluppare GIMP, ma ora viene utilizzato nello sviluppo di molti
  progetti software ``free''.  Gli autori sono

  o  Peter Mattis   petm@xcf.berkeley.edu

  o  Spencer Kimball spencer@xcf.berkeley.edu

  o  Josh MacDonald jmacd@xcf.berkeley.edu


  GTK e essenzialmente una API (application programmers interface)
  orientata agli oggetti.  Anche se scritto completamente in C, e
  implementato usando l'idea delle classi e delle funzioni di callback
  (puntatori a funzioni).


  C'e 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 portabilita 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 e 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 e 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'e 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.


  2.  Iniziamo

  La prima cosa da fare e 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 e il sito
  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 piu
  semplice programma possibile. Questo programma crea una finestra con
  dimensioni (in pixel) di 200x200 e l'unica possibilita di uscita e di
  ucciderlo usando la shell o il Window Manager.



       #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;
       }




  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:



       gtk_init (&argc, &argv);




  invoca la funzione gtk_init(gint *argc, gchar ***argv) che sara 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:

  o  --display

  o  --debug-level

  o  --no-xshm

  o  --sync

  o  --show-events

  o  --no-show-events

  Rimuove poi questi argomenti dalla lista degli argomenti passati,
  lasciando quelli non riconosciuti a disposizione della vostra
  applicazione che potra 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.



         window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
         gtk_widget_show (window);




  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 indichera. Invece di creare una
  finestra avente dimensioni 0x0, la dimensione di una finestra senza
  figli (altri widget, come i bottoni, etc) e predefinita a 200x200 cosi
  che si possa manipolarla.  La funzione gtk_widget_show()  fa si che
  GTK sappia che abbiamo finito di settare gli attributi di questo
  widget e che quindi quest'ultimo puo essere visualizzato.


  L'ultima linea ci fa entrare nel ciclo principale del GTK.



       gtk_main ();




  gtk_main() e un'altra chiamata che vedrete in tutte le applicazioni
  GTK.  Quando il controllo raggiunge questo punto, l'applicazione si
  mettera 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.


  2.1.  Hello World in GTK

  Ok, ora un programma con un widget (un bottone). E' il classico
  ``Hello World'' alla GTK.


















  /* 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 da 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 e NULL
       * ed e 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() e definita sopra. */
      gtk_signal_connect (GTK_OBJECT (button), "clicked",
                          GTK_SIGNAL_FUNC (hello), NULL);

      /* Questo fara si che la finestra venga distrutta dalla chiamata
       * gtk_widget_destroy(window) quando il bottone verra 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 e 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;
  }





  2.2.  Compilare hello World

  Per compilare si utilizza :




       gcc -Wall -g helloworld.c -o hello_world `gtk-config --cflags` \
           `gtk-config --libs`




  (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 gtk-config, che viene distribuito
  con gtk. Questo programma 'sa' che opzioni di compilatore sono
  necessarie per compilare i programmi che usano gtk.  gtk-config
  --cflags da come risultato una lista di directory in cui i file di
  include devono essere cercati, e 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:

  o  la libreria glib (-lglib), contiene varie funzioni, ma solo
     g_print() e usato in questo esempio. GTK si appoggia a questa
     libreria, quindi essa viene sempre, comunque, linkata. Vedi
     comunque la  sezione sulla ``glib'' per altri dettagli.

  o  La libreria GDK (-lgdk), la copertura della X11.

  o  La libreria GTK (-lgtk), la libreria dei widget, basata sulla GDK.

  o  La libreria Xlib(-lX11) la quale e usata dalla GDK.

  o  La libreria Xext(-lXext). Questa contiene il codice per le pixmap a
     memoria condivisa e altre estensioni di X.

  o  La libreria matematica (-lm). Questa e usata dalla GTK per vari
     scopi.


  2.3.  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  e un toolkit guidato dagli
  eventi, il che significa che se ne stara a dorimire in gtk_main finche
  non succede un evento ed il controllo viene passato alla funzione
  appropriata.


  Questo passaggio di controllo e basato sull'idea dei segnali.  Quando
  si ha un evento, come la pressione di un bottone del mouse, verra
  emesso il segnale appropriato, per esempio dal widget che e stato
  premuto.  Questo e il modo in cui GTK fa molto del suo utile lavoro.
  Per far si 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:



       gint gtk_signal_connect (GtkObject *object,
                                gchar *name,
                                GtkSignalFunc func,
                                gpointer func_data);




  in cui il primo argomento e il widget che emettera il segnale, il
  secondo e il nome del segnale che si vuole catturare, il terzo e la
  funzione che verra invocata quando il segnale sara catturato e il
  quarto e il dato che potra essere passato a questa funzione.

  La funzione specificata come terzo argomento e chiamata ``funzione di
  ritorno (callback)'', e dovrebbe essere della forma:



       void callback_func(GtkWidget *widget, gpointer callback_data);




  Dove il primo argomento sara 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 e:




  gint gtk_signal_connect_object (GtkObject *object,
                                  gchar  *name,
                                  GtkSignalFunc func,
                                  GtkObject *slot_object);




  gtk_signal_connect_object() e uguale a gtk_signal_connect() eccetto
  che la funzione di callback usa solo un argomento, un puntatore ad
  un'oggetto GTK.  Cosi quando si usa questa funzione per connettere i
  segnali, la callback dovrebbe essere della forma :



       void callback_func (GtkObject *object);




  dove object e 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 e
  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,
  cosi per queste si puo usare la funzione gtk_signal_connect_object(),
  mentre per le vostre funzioni potreste aver bisogno di passare dati
  supplementari alle funzioni di ritorno.


  2.4.  Attraverso Hello World passo per passo

  Ora che conosciamo la teoria che vi e dietro, iniziamo ad essere piu
  chiari camminando attraverso il programma di Hello World.

  Questa e la funzione di callback che sara invocata quando il bottone
  viene cliccato.  Noi, in questo esempio, ignoriamo sia il widget che i
  dati passati, ma non e difficile farci invece qualcosa. Il prossimo
  esempio usera l'argomento passato per dire quale bottone e stato
  premuto.



       void hello (GtkWidget *widget, gpointer data)
       {
           g_print ("Hello World\n");
       }





  Questa callback e 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 si che la GTK
  sappia cosa fare. Restituire TRUE significa che non vogliamo che il
  segnale ``destroy'' sia emesso, quindi far si che la nostra
  applicazione proceda normalmente.  Ritornare FALSE vuole dire far
  emettere il segnale ``destroy'' il quale chiamera la nostra funzione
  di callback che gestisce il segnale ``destroy''.



       gint delete_event(GtkWidget *widget, gpointer data)
       {
          g_print ("delete event occured\n");

          return (TRUE);
       }




  Questa e 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.



       void destroy (GtkWidget *widget, gpointer data)
       {
           gtk_main_quit ();
       }




  Ritengo che conosciate la funzione main()... si, come tutte le altre
  applicazioni anche le applicazioni GTK hanno questa funzione.



       int main (int argc, char *argv[])
       {




  Questa parte dichiara un puntatore ad una struttura di tipo GtkWidget.
  Queste sono usate piu sotto per creare una finestra ed un bottone.



           GtkWidget *window;
           GtkWidget *button;




  Qui vi e 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 cosi modificati argc e argv per far si
  che sembri che questi non siano mai esisiti e permettere alla vostra
  applicazione di analizzare gli argomenti rimasti.



           gtk_init (&argc, &argv);




  Crea una nuova finestra. Questo viene spiegato abbastanza
  approfonditamente piu avanti. Viene allocata la memoria per la
  struttura GtkWidget *window cosi 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).


           window = gtk_window_new (GTK_WINDOW_TOPLEVEL);




  Questo e 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 cosi, trattiamo entrambi i casi con una singola chiamata. Qui
  e giusto invocare la funzione destroy() definita sopra con NULL come
  argomento, la quale termina l'applicazione GTK per noi.  Questo ci
  permettera 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, cosi da rendere piu' leggibile il
  codice.



           gtk_signal_connect (GTK_OBJECT (window), "destroy",
                               GTK_SIGNAL_FUNC (destroy), NULL);




  La prossima funzione e usata per settare un attributo di un oggetto
  contenitore. Questo sistema la finestra cosi da avere un'area vuota
  all'interno della finestrra larga 10 pixel dove non potra andare
  nessun widget. Ci sono altre funzioni simili che vedremo nella sezione
  ``Settare gli attributi del Widget.''

  E ancora, GTK_CONTAINER e una macro per interpretare il casting di
  tipo.



           gtk_container_border_width (GTK_CONTAINER (window), 10);




  Questa chiamata crea un nuovo bottone. Alloca spazio in memoria per un
  nuovo GtkWidget, inizializzandolo e facendo si che il puntatore a
  bottone punti ad esso.  Quando sara visualizzato, avra etichetta
  ``Hello World''.



           button = gtk_button_new_with_label ("Hello World");




  Qui prendiamo il bottone e gli facciamo fare qualcosa di utile.  Gli
  colleghiamo un gestore di segnale  in modo che quando emettera il
  segnale ``clicked'', verra invocata la nostra funzione hello(). Il
  dato passato alla funzione e ignorato, cosicche alla funzione di
  callback hello() passiamo semplicemente NULL. Evidentemente il segnale
  ``clicked'' viene emesso quando premiamo il bottone con il mouse.



           gtk_signal_connect (GTK_OBJECT (button), "clicked",
                               GTK_SIGNAL_FUNC (hello), NULL);




  Usiamo questo bottone anche per uscire dal programma. Questo
  illustrera come il segnale ``destroy'' puo arrivare sia dal Window
  Manager che dal nostro programma. Quando il bottone viene cliccato
  come descritto sopra, chiamera la funzione di callback hello() e poi
  quest'ultima nell'ordine in cui sono definite. Si possono cioe 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().



           gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
                                      GTK_SIGNAL_FUNC (gtk_widget_destroy),
                                      GTK_OBJECT (window));




  Questa e una chiamata di ``impacchettamento'' che sara spiegata piu
  avanti. Ma e molto facile da capire. Semplicemente dice alla libreria
  GTK che il bottone e da mettere nella finestra dove sara visualizzato.



           gtk_container_add (GTK_CONTAINER (window), button);




  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 cosi che la finestra completa di tutti i suoi oggetti verra
  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 gia notato.


           gtk_widget_show (button);

           gtk_widget_show (window);




  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.


      gtk_main ();




  E il return finale. Il controllo ritorna qui dopo che viene invocata
  gtk_quit().



           return 0;




  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, dopoodiche viene invocato
  il successivo gestore di questo segnale.  Questo chiama la funziona
  gtk_widget_destroy(), passandole l'oggetto-finestra (window) come
  argomento, che distruggera la finestra. Questo fa si 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 e l'uso del window manager
  per uccidere la finestra. Questo causera' l'emissione del segnale
  ``delete_event'' che automaticamente chiamera il gestore del segnale
  ``delete_event''. Se qui noi restituiamo il valore TRUE, la finestra
  non verra toccata e tutto procedera come se nulla fosse successo. Dare
  invece il valore FALSE causera l'emissione da parte di GTK del segnale
  ``destroy'' il quale, a sua volta, invochera 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 e
  praticamente identica.


  3.  Proseguiamo



  3.1.  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 e ``gint32'' il quale sara 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 piu avanti e
  molto intuitivi. Sono definiti in glib/glib.h (il quale viene incluso
  da gtk.h).

  Noterete anche la possibilita di utilizzare un GtkWidget quando la
  funzione richiede un GtkObject. GTK e una libreria orienta agli
  oggetti ed un widget e un oggetto.




  3.2.  Altri Dettagli sui Segnali

  Diamo un'altra occhiata alla dichiarazione della funzione
  gtk_signal_connect.



       gint gtk_signal_connect (GtkObject *object, gchar *name,
                                GtkSignalFunc func, gpointer func_data);




  Notate il valore di ritorno definito come gint? Questo e un identifi-
  catore per la vostra funzione di callback. Come detto sopra, si pos-
  sono avere piu funzioni di ritorno per ogni segnale e per ogni ogetto
  a seconda delle necessita, ed ognuna sara eseguita in sequenza,
  nell'ordine in cui e stata collegata.

  Questo identificatore vi permette di rimuovere una funzione dalla
  lista delle funzioni di ritorno tramite la seguente chiamata



       void gtk_signal_disconnect (GtkObject *object,
                                   gint id);




  Cosi, passando il widget da cui si vuole rimuovere il gestore di seg-
  nale e l'identificativo restituito da una delle funzioni signal_con-
  nect, si puo rimuovere il gestore di segnale che si desidera dal wid-
  get.

  Un'altra funzione, usata per rimuovere tutti i segnali di un widget in
  una volta sola e:



       gtk_signal_handlers_destroy (GtkObject *object);




  Questa chiamata e abbastanza auto esplicativa. Semplicemente rimuove
  tutti i segnali collegati al widget che si passa alla funzione come
  argomento.


  3.3.  Miglioriamo Hello World

  Diamo un'occhiata ad una versione migliorata di Hello World con altri
  esempi sulle callback. Questo ci introdurra anche al nostro prossimo
  argomento, l'impacchettamento dei widget.











  /* 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 e descritta
         dettagliatamente nella sezione "packing". La scatola non e realmente
         visibile, e 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;
  }




  Compilate questo programma usando gli stessi argomenti di link del
  nostro primo esempio. Noterete che questa volta non c'e 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 e 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'e 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.


  4.  Come ``Impacchettare'' i Widget

  Nel momento in cui si crea un'applicazione, normalmente si avra la
  necessita di mettere piu di un unico bottone all'interno di una
  finestra. Il nostro primo esempio ``Hello World'' usava un solo
  oggetto, cosicche abbiamo potuto usare semplicemente una chiamata a
  gtk_container_add per impacchettare il widget nella finestra. Quando
  invece si vuole inserire piu 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''.

  4.1.  Teoria delle Scatole per Impacchettamento

  La maggior parte dell'impacchettamento viene effettuata creando delle
  scatole come nell'esempio piu sopra. Le scatole sono dei contenitori
  invisibili di widget che possiamo usare per imballarci i nostri
  oggetti e che esistono in due varieta: 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 puo 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() comincera 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
  puo 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 puo immaginare,
  questo metodo da una buona flessibilita nella creazione e nella
  disposizione dei propri widget.


  4.2.  Dettagli sulle Scatole

  A causa di questa flessibilita, le scatole per impacchettamento del
  GTK possono, di primo acchito, creare un po' di disorientamento. Sono
  infatti disponibili molte opzioni, e non e immediato il modo in cui si
  combinano l'una con l'altra.  Alla fine pero, 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 e una scorciatoia per la
  chiamata di impacchettamento di ognuno dei bottoni nella hbox. Ognuno
  dei bottoni viene impacchettato nella hbox nello stesso modo (cioe,
  con gli stessi argomenti per la funzione gtk_box_pack_start ()).

  Questa e la dichiarazione della funzione gtk_box_pack_start.



       void gtk_box_pack_start (GtkBox    *box,
                                GtkWidget *child,
                                gint       expand,
                                gint       fill,
                                gint       padding);




  Il primo argomento e la scatola nella quale si stanno inscatolando i
  widget, il secondo e il widget stesso. Gli oggetti per ora saranno
  bottoni, quindi quello che faremo sara impacchettare bottoni in sca-
  tole.

  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 puo 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 puo 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 e
  assegnato il valore TRUE.

  Quando si crea una nuova scatola, la funzione ha questo aspetto:



       GtkWidget * gtk_hbox_new (gint homogeneous,
                                 gint spacing);




  L'argomento homogeneous di gtk_hbox_new (la stesso per gtk_vbox_new)
  determina se ogni oggetto nella scatola deve avere la stessa
  dimensione (cioe la stessa ampiezza in una hbox o la stessa altezza in
  una vbox).  Se e settato, l'argomento expand delle routine
  gtk_box_pack e sempre attivato.

  Qual e la differenza fra la spaziatura (che e 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 e 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'.


  4.3.  Programma Dimostrativo di Impacchettamento


















  /* 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 e 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, cosicche 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
       * cio mandera alla finestra il segnale "destroy", che verra 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;
  }





  4.4.  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 e la funzione gtk_table_new:



       GtkWidget* gtk_table_new (gint rows,
                                 gint columns,
                                 gint homogeneous);




  Il primo argomento rappresenta il numero di righe da mettere nella
  tabella, mentre il secondo e 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 piu grande
  oggetto contenuto nella tabelle. Se e FALSE, la dimensione delle
  casellee decisa dal piu alto oggetto in una certa riga e dal piu largo
  oggetto in una stessa colonna.

  Le righe e le colonne sono disposte a partire da 0 fino a n, dove n e
  il numero che era stato specificato nella chiamata a gtk_table_new.
  Cosi, se specificate rows = 2 e columns = 2, lo schema avra questo
  aspetto:







   0          1          2
  0+----------+----------+
   |          |          |
  1+----------+----------+
   |          |          |
  2+----------+----------+




  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:



       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);





  In cui il primo argomento (``table'') e la tabella che avete creato e
  il secondo (``child'') e 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 piu 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 puo fare l'OR in modo di
  ottenere opzioni multiple.

  Le opzioni sono:

  o  GTK_FILL - Se la parte di tabella in cui si vuole inserire il
     widget e piu grande dell'oggetto, e se si specifica GTK_FILL,
     l'oggetto viene espanso fino ad occupare tutto lo spazio
     disponibile.

  o  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.

  o  GTK_EXPAND - Questo fa si che la tabella si espanda fino ad
     occupare tutto lo spazio che rimane nella finestra.


  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:



       void gtk_table_attach_defaults (GtkTable   *table,
                                       GtkWidget  *widget,
                                       gint        left_attach,
                                       gint        right_attach,
                                       gint        top_attach,
                                       gint        bottom_attach);




  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).



       void gtk_table_set_row_spacing (GtkTable      *table,
                                       gint           row,
                                       gint           spacing);




  e


       void       gtk_table_set_col_spacing  (GtkTable      *table,
                                              gint           column,
                                              gint           spacing);




  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 puo poi inserire una spaziatura identica fra tutte le righe e/o
  colonne usando:



       void gtk_table_set_row_spacings (GtkTable *table,
                                        gint      spacing);




  e




  void gtk_table_set_col_spacings (GtkTable  *table,
                                   gint       spacing);




  Notate che con queste chiamate,  all'ultima riga e all'ultima colonna
  non viene assegnata alcuna spaziatura.


  4.5.  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. Cio 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:











































  /* 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;
  }





  5.  Panoramica sui Widget

  La procedura generale di creazione di un widget in GTK prevede i
  seguenti passi:

  1. gtk_*_new - una delle varie funzioni che servono per greare un
     nuovo widget.  In questa sezione le vedremo tutte in dettaglio.

  2. Connettere tutti i segnali che si vogliono usare alle funzione
     gestione appfropriate.

  3. Assegnare gli attributi all'oggetto.

  4. Impacchettare l'oggetto in un contenitore usando la chiamate
     appropriata, per esempio gtk_container_add() o
     gtk_box_pack_start().

  5. Mostrare l'oggetto con gtk_widget_show().

  gtk_widget_show() fa si che GTK sappia che abbiamo terminato di
  assegnare gli attributi dell'oggetto grafico, e che e pronto per
  essere visualizzato.  Si puo anche usare la funzione gtk_widget_hide
  per farlo sparire di nuovo.  L'ordine in cui mostrate gli oggetti
  grafici non e importante, ma io suggerisco di mostrare per ultima la
  finestra, in modo che questa spunti fuori gia 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 e un
  oggetto grafico) non vengono infatti mostrati finche la finestra
  stessa non viene mostrata usando la funzione gtk_widget_show().


  5.1.  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 possibilita di effettuare il cast
  sull'elemento dato e lo effettuano realmente.  Alcune macro che avrete
  modo di incontrare sono:


  o  GTK_WIDGET(widget)

  o  GTK_OBJECT(object)

  o  GTK_SIGNAL_FUNC(function)

  o  GTK_CONTAINER(container)

  o  GTK_WINDOW(window)

  o  GTK_BOX(box)

  Tutte queste funzioni  sono usate per fare il cast di argomenti di
  funzione. Le vedrete negli esempi, e capirete se e il caso di usarle
  semplicemente guardando alle dichiarazioni delle funzioni.

  Come potrete vedere piu sotto nella gerarchia delle classi, tutti i
  GtkWidgets sono derivati dalla classe base GtkObject. Cio significa
  che potete usare un widget in ogni posto in cui una funzione richiede
  un oggetto - semplicemente usate la macro GTK_OBJECT().

  Per esempio:



       gtk_signal_connect(GTK_OBJECT(button), "clicked",
                          GTK_SIGNAL_FUNC(callback_function), callback_data);





  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 piu sotto, vedrete che molti oggetti grafici
  sono derivati dalla classe GtkContainer. Ognuna di queste classi puo
  essere usata, con la macro GTK_CONTAINER, come argomento per funzioni
  che richiedono un contenitore.

  Sfortunatamente, in questo tutorial non si parlera in modo estensivo
  di queste macro, ma raccomando di dare un'occhiata ai file header di
  GTK. Puo essere una cosa molto educativa. Infatti, non e difficile
  imparare come funziona un oggetto solo guardando le dichiarazioni
  delle funzioni.


  5.2.  Gerarchia degli Oggetti Grafici

  Ecco, per vostro riferimento, la gerarchia delle classi usata per
  implementare gli oggetti grafici.











    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





  5.3.  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 ``Il Widget EventBox''



       GtkAlignment
       GtkArrow
       GtkBin
       GtkBox
       GtkImage
       GtkItem
       GtkLabel
       GtkPixmap
       GtkScrolledWindow
       GtkSeparator
       GtkTable
       GtkAspectFrame
       GtkFrame
       GtkVBox
       GtkHBox
       GtkVSeparator
       GtkHSeparator




  Proseguiremo la nostra esplorazione di GTK esaminando uno alla volta
  tutti gli oggetti, creando qualche semplice funzione per mostrarli.
  Un'altra buona sorgente e il programma testgtk.c che viene fornito con
  GTK. Potete trovarlo in gtk/testgtk.c.


  6.  Il Widget Bottone (Button)

  6.1.  Bottoni Normali

  Ormai abbiamo visto tutto quello che c'e 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 e poi vostro compito
  impacchettare un'etichetta o una pixmap sul bottone creato.  Per fare
  cio, 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 se. Ho separato il codice usato
  per creare la scatola in modo che lo possiate usare nei vostri
  programmi.




























































  /* 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, e 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 e 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;
  }




  La funzione xpm_label_box puo essere usata per impacchettare delle xpm
  e delle etichette su qualsiasi oggetto che puo essere un contenitore.


  6.2.  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 giu.

  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:





  GtkWidget* gtk_toggle_button_new (void);

  GtkWidget* gtk_toggle_button_new_with_label (gchar *label);




  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 puo usare una macro come mostrato
  nell'esempio piu 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 e 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 avra un aspetto piu o meno cosi:



       void toggle_button_callback (GtkWidget *widget, gpointer   data)
        {
            if (GTK_TOGGLE_BUTTON (widget)->active)
            {
               /* Se il programma si e arrivato a questo punto, il bottone
                * a commutazione e premuto */

           } else {

               /* il bottone e sollevato */
            }
        }








       void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
                                         gint state);




  La chiamata qui sopra puo 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 puo specificare se il bottone deve essere sollevato
  (rilasciato) o abbassato (premuto). Il valore di difetto e sollevato,
  cioe 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''.



       void       gtk_toggle_button_toggled (GtkToggleButton *toggle_button);


  Questa funzione semplicemente commuta il bottone, ed emette il segnale
  ``toggled''.


  6.3.  Bottoni di Controllo (Check Buttons)

  I bottoni di controllo ereditano molte proprieta 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..



       GtkWidget* gtk_check_button_new (void);

       GtkWidget* gtk_check_button_new_with_label (gchar *label);




  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.


  6.4.  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 puo 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:



       GtkWidget* gtk_radio_button_new (GSList *group);

       GtkWidget* gtk_radio_button_new_with_label (GSList *group,
                                                   gchar *label);




  Avrete notato l'argomento in piu che c'e 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. Dopodiche potete creare
  un gruppo usando la funzione:



       GSList* gtk_radio_button_group (GtkRadioButton *radio_button);




  La cosa importante da ricordare e 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. Cio permette di creare una catena di
  bottoni. L'esempio piu sotto dovrebbe chiarire questo punto.

  E' poi una buona idea stabiire quale dev'essere il bottone premuto per
  difetto, usando:



       void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
                                         gint state);




  Questa funzione e descritta nella sezione sui bottoni a commutazione,
  e funziona nello stesso identico modo.


  Nel seguente esempio creiamo un gruppo di tre radio-bottoni.











































  /* 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);
  }




  La cosa puo essere accorciata un po' usando la seguente sintassi, che
  elimina la necessita di una variabile per contenere la lista di
  bottoni:



            button2 = gtk_radio_button_new_with_label(
                        gtk_radio_button_group (GTK_RADIO_BUTTON (button1)),
                        "button2");






  7.  Alcuni Widget

  7.1.  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 necessita di avere dei
  segnali o di fare delle operazioni di clipping, potete usare il widget
  EventBox.

  Per creare una nuova etichetta, si usa:



       GtkWidget* gtk_label_new (char *str);




  In cui l'unico argomento e la stringa che si vuole sia mostrata.

  Per cambiare il testo dell'etichetta dopo che e stata creata, si usa
  la funzione:



       void gtk_label_set (GtkLabel  *label,
                           char      *str);




  in cui il primo argomento e l'etichetta creata in precedenza (di cui
  si fa il cast usando la macro GTK_LABEL()), mentre il secondo e la
  nuova stringa.

  Nel caso, lo spazio necessario per la nuova stringa verra regolato
  automaticamente.

  Per ottenere la stringa corrente si usa:



       void gtk_label_get (GtkLabel  *label,
                           char     **str);




  in cui il primo argomento e l'etichetta che avete creato, e il secondo
  e il valore di ritorno per la stringa.


  7.2.  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 daro 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 e la
  seguente.  In una data funzione, e necessario chiamarla una sola
  volta: il GtkTooltip che viene restituito da questa funzione puo
  essere usato per creare suggerimenti multipli.



       GtkTooltips *gtk_tooltips_new (void);




  Una volta creato un nuovo suggerimento e il widget su cui lo volete
  usare, basta usare la seguente chiamata per fare l'assegnazione:



       void gtk_tooltips_set_tip (GtkTooltips *tooltips,
                                  GtkWidget   *widget,
                                  const gchar *tip_text,
                                  const gchar *tip_private);




  Il primo argomento e il suggerimento che era gia stato creato, che e
  seguito dal widget da cui volete che spunti il suggerimento e dal
  testo che volete venga mostrato. L'ultimo argomento puo essere posto a
  NULL.

  Ecco un piccolo esempio:










  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", NULL);




  Ci sono anche altre funzioni che si usano con i suggerimenti. Eccone
  una lista con una breve descrizione di quello che fanno.



       void gtk_tooltips_destroy    (GtkTooltips *tooltips);




  Distrugge un suggerimento esistente.



       void gtk_tooltips_enable     (GtkTooltips *tooltips);




  Abilita  un gruppo di suggerimenti disbilitato.



       void gtk_tooltips_disable    (GtkTooltips *tooltips);




  Disabilita un gruppo di suggerimenti abilitato.



       void gtk_tooltips_set_delay  (GtkTooltips *tooltips,
                                     gint         delay);




  Stabilisce quanti millisecondi si deve mantenere il puntatore sopra al
  widget prima che venga mostrato il suggerimento. Il valore di difetto
  e di 1000 millisecondi.



       void      gtk_tooltips_set_tips (GtkTooltips *tooltips,
                                        GtkWidget   *widget,
                                        gchar    *tips_text);




  Cambia il testo di un suggerimento gia esistente.



  void gtk_tooltips_set_colors (GtkTooltips *tooltips,
                                GdkColor    *background,
                                GdkColor    *foreground);




  Assegna i colori di primo piano e di sfondo dei suggerimenti. (Non ho
  idea di come si specifichino i colori).

  E questo e tutto riguardo alle funzioni relative ai suggerimenti. Piu
  di quanto avreste mai voluto sapere :)



  7.3.  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.



       GtkWidget *gtk_progress_bar_new (void);




  Ora che la barra di avanzamento e stata creata, possiamo usarla..



       void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage);




  Il primo argomento e la barra di avanzamento su cui volete lavorare, e
  il secondo e la quantita 'completato', cioe la quantita 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 ``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.
















  /* 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 e 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;
  }




  In questo programmino ci sono quattro aree che riguardano il modo di
  uso generale delle Barre di Avanzamento; le vediamo ora nell'ordine.



       pbar = gtk_progress_bar_new ();




  Questo codice crea una nuova barra ciamata pbar.



       ptimer = gtk_timeout_add (100, progress, pbar);




  Questo codice usa dei timeout per abilitare degli intervalli di tempo
  uguali.  Per usare le barre di avanzamento non e pero necessario
  servirsi di timeout.



       pvalue = GTK_PROGRESS_BAR (data)->percentage;




  Qui si assegna a pvalue il valore corrente della percentuale di
  avanzamento.




  gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);




  Infine, questo codice aggiorna la barra di avanzamento con il valore
  di pvalue.

  Questo e tutto quanto c'e da sapere sulle barre di avanzamento,
  divertitevi.


  7.4.  Dialoghi


  Il widget ``Dialogo'' e molto semplice: si tratta in realta di una
  finestra con alcuni elementi pre-impacchettati. La struttura di un
  dialogo e la seguente:



       struct GtkDialog
       {
             GtkWindow window;

             GtkWidget *vbox;
             GtkWidget *action_area;
       };




  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 puo essere utilizzato per messaggi per l'utente e altri
  scopi simili. E' un widget molto essenziale, che ha una sola funzione,
  e precisamente:



       GtkWidget* gtk_dialog_new (void);




  Per cui, per creare una nuova finestra di dialogo, uate:



       GtkWidget *window;
       window = gtk_dialog_new ();




  Questa funzione crea una finestra di dialogo, dopodiche sta a voi
  utilizzarla. Potete mettere un bottone nella action_area facendo
  qualcosa del tipo:






  button = ...
  gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button,
                      TRUE, TRUE, 0);
  gtk_widget_show (button);




  Potreste anche aggiungere, ad esempio, un'etichetta all'area della
  vbox, con qualcosa di questo genere:



       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);




  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.


  7.5.  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 e 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 puo 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.



       GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window,
                                               gchar     *data,
                                               gint      width,
                                               gint      height );




  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 e 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.







  GdkPixmap* gdk_pixmap_create_from_data( GdkWindow  *window,
                                          gchar      *data,
                                          gint        width,
                                          gint        height,
                                          gint        depth,
                                          GdkColor   *fg,
                                          GdkColor   *bg );




  Questa e usata per creare una pixmap con la profondita 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.



       GdkPixmap* gdk_pixmap_create_from_xpm( GdkWindow  *window,
                                              GdkBitmap **mask,
                                              GdkColor   *transparent_color,
                                              const gchar *filename );




  Il formato XPM e 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. Piu sotto mostreremo un esempio di uso di questa
  funzione.



       GdkPixmap* gdk_pixmap_create_from_xpm_d (GdkWindow  *window,
                                                GdkBitmap **mask,
                                                GdkColor   *transparent_color,
                                                gchar     **data);




  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 e

















  /* 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.    ",
  "   .........    ",
  "                ",
  "                "};






       void gdk_pixmap_destroy( GdkPixmap  *pixmap );




  Quando abbiamo finito di usare una pixmap e pensiamo di non doverla
  riutilizzare presto, e 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



       GtkWidget* gtk_pixmap_new( GdkPixmap  *pixmap,
                                  GdkBitmap  *mask );




  Le altre chiamate per i widget pixmap sono



       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);





  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'' e la
  pixmap che e stata creata usando il GDK.  Segue un esempio di uso di
  una pixmap in un bottone.





























































  /* 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 e 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;
  }





  Per caricare una pixmap da un file XPM chiamato icon0.xpm che si trova
  nella direttorio corrente, avremmo creato la pixmap in questo modo:



           /* 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 );





  Usare le Sagome

  Uno degli svantaggi di usare le pixmap e costituito dal fatto che
  l'oggetto mostrato e sempre rettangolare, a prescindere dall'immagine.
  Ci piacerebbe invece poter crare dei desktop e delle immagini con
  forme piu naturali. Per esempio, per l'interfaccia di un gioco,
  potremmo volere avere dei pulsanti circolari. Il modo per ottenere
  questo effetto e di usare delle finestre sagomate.

  Una finestra sagomata e semplicemente una pixmap in cui i pixel dello
  sfondo sono trasparenti. In questo modo, se l'immagine di sfondo e
  multicolore, possiamo evitare di sovrascriverla con un bordo
  rettangolare attorno all'icona. Il prossimo esempio mostra una
  carriola sul desktop.

















  /* 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 e 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;
  }




  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 si che l'applicazione
  termini.



       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 );





  7.6.  Righelli

  I widget righello vengono usati per indicare la posizione del
  pontatore del mouse in una certa finestra. Una finestra puo cioe 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



       GtkWidget *gtk_hruler_new(void);    /* horizontal ruler */
       GtkWidget *gtk_vruler_new(void);    /* vertical ruler   */




  Una volta che che si e creato il righello, si puo l'unita di misura.
  Le unita di misura possono essere GTK_PIXELS, GTK_INCHES oppure
  GTK_CENTIMETERS. Cio viene stabilito usando



       void gtk_ruler_set_metric( GtkRuler        *ruler,
                                  GtkMetricType   metric );




  La misura predefinita e  GTK_PIXELS.



       gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS );




  Altre caratteritiche importanti di un righello sono il modo in cui
  vengono segnate le tacche delle unita di misura e dove viene posto
  inizialmente l'indicatore di posizione. Questi vengono stabiliti
  usando



       void  gtk_ruler_set_range  (GtkRuler       *ruler,
                                   gfloat          lower,
                                   gfloat          upper,
                                   gfloat          position,
                                   gfloat          max_size);




  Gli argomenti lower e upper definiscono l'estensione del righello, e
  max_size rappresenta il numero massimo che verra mostrato.  Position
  definisce l posizione iniziale dell'indicatore del puntatore
  all'interno del righello.

  Quindi, un righello che puo stare su una finestra di 800 pixel sara:



       gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800);





  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:



       gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20);




  L'indicatore sul righello e 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:



       #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) );




  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.





























  /* 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;
  }





  7.7.  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, cosicchee rimuovendo il messaggio corrente fa
  si 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 e 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:


       GtkWidget* gtk_statusbar_new (void);




  Per richiedere un nuovo identificatore di contesto, si usa una
  chiamata alla seguente funzione con una breve descrizione testuale:


       guint gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
                                           const gchar  *context_description);




  Le seguenti sono tre funzioni che possono operare sulle barre di
  stato:


       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);





  La prima, gtk_statusbar_push, viene usata per aggiungere un nuovo
  messaggio alla barra di stato. Questa restituisce un identificatore di
  messaggio, che puo 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..






















































  /* 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;
  }





  7.8.  Inserimento di testo

  Questo widget permette diinserire e mostrare del testo in una casella
  contenente una sola linea. Il testo puo 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:


       GtkWidget* gtk_entry_new (void);

       GtkWidget* gtk_entry_new_with_max_length (guint16 max);




  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.


       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);




  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.


       void gtk_entry_set_position   (GtkEntry *entry,
                                      gint     position);




  Usando la seguente funzione, e possibile estrarre il contenuto di un
  widget di inserimento.  Cio puo essere utile nelle funzioni di ritorno
  come descritto piu sotto.



  gchar* gtk_entry_get_text (GtkEntry *entry);




  Se non si vuole che qualcuno possa cambiare il contenuto di una entry
  sovrascrivendola, ne possiamo cambiare lo stato di "editabilita"..


       void gtk_entry_set_editable (GtkEntry *entry,
                                    gboolean editable);




  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..


       void gtk_entry_set_visibility (GtkEntry *entry,
                                      gboolean visible);




  Si puo stabilire che una parte del testo  risulti selezionata usado la
  seguente funzione.  Si usera di solito questa possibilita dopo aver
  inserito nel widget un qualche valore predefinito, in modo che per
  l'utente sia semplice sostituirlo.



       void gtk_entry_select_region (GtkEntry *entry,
                                     gint     start,
                                     gint     end);




  Se vogliamo accorgerci del momento in cui l'utente ha inserito del
  testo, possiamo connettere il segnale activate o changed. activate
  viene reso attivo quando l'utente preme il tasto Enter mentre si trova
  nel widget. 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.  .













  /* 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);
  }





  7.9.  Selettori di Colore

  Il widget selettore di colore e 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 puo 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, e 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 e 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 e disponibile in due versioni, gtk_color_selection
  e gtk_color_selection_dialog:



       GtkWidget *gtk_color_selection_new(void);




  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.




       GtkWidget *gtk_color_selection_dialog_new(const gchar *title);


  Questo e il piu 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 (cioe
  (GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).



       void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel,
                                                  GtkUpdateType policy);




  Questa funzione stabilisce la politica di aggiornamento. Quella
  predefinita e 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 puo decidere
  di usare la politica GTK_UPDATE_DISCONTINOUS o GTK_UPDATE_DELAYED.



       void gtk_color_selection_set_opacity(GtkColorSelection *colorsel,
                                            gint use_opacity);




  Il widget di selezione di colore permette anche di variare l'opacita
  di un colore (conosciuta anche come canale alfa). Questa
  caratteristica e normalmente disabilitata. Chiamare la precedente
  funzione, con use_opacity uguale a TRUE abilita la manipolazione
  dell'opacita. Analogamente, mettendo use_opacity uguale a FALSE la
  disabilitera.



       void gtk_color_selection_set_color(GtkColorSelection *colorsel,
                                          gdouble *color);




  Si puo 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'opacita. La
  posizione 0 contiene la componente rossa, la 1 ' il verde, la 2 il blu
  e la 3 contiene l'opacita (se questa ' attivata, come si e detto per
  gtk_color_selection_set_opacity()). Tutti i valori sono compresi fra
  0.0 e 1.0.



       void gtk_color_selection_get_color(GtkColorSelection *colorsel,
                                          gdouble *color);




  Questa funzione viene usata per ottenere il colore corrente,
  tipicamente quando si e ricevuto il segnale "color_changed". Color e
  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 verra cambiato anche il
  colore dello sfondo.


























































  #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;
  }





  7.10.  Selezione di File (File Selections)

  Il widget Selezione di File e 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:



       GtkWidget* gtk_file_selection_new (gchar *title);




  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:



       void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);




  Per recuperare il testo che l'utente ha inserito o che ha selezionato
  con il mouse, si usa la funzione:



       gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);




  Ci sono anche dei puntatori ai widget che sono contenuti all'interno
  del widget di selezione file. Si tratta di:


  o  dir_list

  o  file_list

  o  selection_entry

  o  selection_text

  o  main_vbox

  o  ok_button

  o  cancel_button

  o  help_button

  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'e molto piu che la creazione di un
  widget di selezione file. In questo esempio, il bottone Help non fa
  nulla mentre e mostrato allo schermo, dal momento che non c'e alcun
  segnale collegato con esso.



       /* 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;
       }





  8.  Widget Contenitore



  8.1.  Il widget Blocco Note (Notebook)

  Il widget Blocco note e un insieme di pagine sovrapposte l'una con
  l'altra, ognuna contente cose diverse. Questo widget e diventato molto
  comune nella programmazione delle interfacce utente ed e 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 puo
  intuire, e usata per creare un nuovo Blocco Note.



       GtkWidget* gtk_notebook_new (void);




  Una volta che il notebook e 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.



       void gtk_notebook_set_tab_pos (GtkNotebook *notebook, GtkPositionType pos);




  GtkPositionType sara uno dei seguenti valori (molto autoesplicativi)

  o  GTK_POS_LEFT

  o  GTK_POS_RIGHT

  o  GTK_POS_TOP

  o  GTK_POS_BOTTOM

  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.



       void gtk_notebook_append_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);

       void gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);




  Queste funzioni aggiungono pagine al notebook inserendole
  rispettivamente alla fine (append) o all'inizio (prepend). *child e il
  widget che e 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 proprieta delle precedenti due, ma permette di specificare dove
  posizionare la pagina che si vuole inserire.



       void gtk_notebook_insert_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, gint position);




  I parametri sono gli stessi di _append_ e _prepend_ tranne che per il
  parametro in piu: ``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.



       void gtk_notebook_remove_page (GtkNotebook *notebook, gint page_num);




  Questa funzione prende il numero della pagina specificata dal campo
  page_num e rimuove la pagina corrispondente dal Blocco Note.

  Per trovare qual'e la pagina corrente nel notebook bisogna usare la
  funzione:



       gint gtk_notebook_current_page (GtkNotebook *notebook);




  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 puo
  operare. NB: quando un notebook e correntemente sull'ultima pagina e
  viene invocata la funzione gtk_notebook_next_page, il notebook
  ritornera automaticamente alla prima pagina. Logicamente succede anche
  il contrario quando invochi gtk_notebook_prev_page e ti trovi sulla
  prima pagina.



       void gtk_notebook_next_page (GtkNoteBook *notebook);
       void gtk_notebook_prev_page (GtkNoteBook *notebook);




  La prossima funzione stabilisce la pagina ``attiva''. Se si vuole che
  la pagina principale del notebook sia per esempio la 5 (ad esempio) si
  puo usare questa funzione.  Se non si usa questa funzione la pagina
  principale sara la 1.



       void gtk_notebook_set_page (GtkNotebook *notebook, gint page_num);





  Le prossime due funzioni aggiungono o rimuovono, rispettivamente, le
  intestazioni e i bordi delle pagine.



       void gtk_notebook_set_show_tabs (GtkNotebook *notebook, gint show_tabs);
       void gtk_notebook_set_show_border (GtkNotebook *notebook, gint show_border);




  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 e 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.













































  /* 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 sara la prima pagina che sara 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;
  }




  E speriamo che questo vi aiuti a creare i Blocco Note per le vostre
  applicazioni GTK!


  8.2.  Finestre Scorribili (Scrolled Windows)

  Le Finestre Scorribili sono usate per creare areee scorribili in una
  vera finestra.  Si puo 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 e usata per creare una nuova scrolled window.



       GtkWidget* gtk_scrolled_window_new (GtkAdjustment *hadjustment,
                                           GtkAdjustment *vadjustment);





  Il primo argomento e l'aggiustamento (di quanto scendere ogni volta)
  orizzontale e il secondo e quello verticale.  A questi si assegna
  quasi sempre il valore NULL.




       void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
                                            GtkPolicyType      hscrollbar_policy,
                            GtkPolicyType      vscrollbar_policy);




  Questa funzione stabilisce la politica da usare nella barra di
  scorrimento. Il primo argomento e la finestra scorribile interessata.
  Il secondo stabilisce la politica per la barra di scorrimento
  orizzontale e il terzo e quello per la politca verticale.

  La politica puo 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 verra
  sempre mostrata.











































  /* 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 sara
          inserita. Una finestra di dialogo e semplicemente come una
          finestra normale, ma ha anche un vbox e un separatore orizzontale
          gia 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 e 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 e creata con un vbox gia 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 si 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 avviera */
      gtk_widget_grab_default (button);
      gtk_widget_show (button);

      gtk_widget_show (window);

      gtk_main();

      return(0);
  }




  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.



  8.3.  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 puo

  trascinare per cambiare la proporzione fra le aree. La divisione puo

  essere sia di tipo orizzontale (HPaned) che verticale (VPaned).


  Per creare una finestra frazionata, si chiama una delle seguenti:



       GtkWidget* gtk_hpaned_new (void)
       GtkWidget* gtk_vpaned_new (void)





  Dopo aver creato il widget della finestra frazionata, si devono
  aggiungere dei


  widget figli alle due parti. Per farlo, si usano le funzioni:



       void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child)
       void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child)




  gtk_paned_add1() inserisce il widget figlo alla parte di sinistra o
  superiore

  della finestra. 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 e piuttosto banale. Un paio

  di punti da notare sono: Non si puo scrivere su un widget di testo
  prima

  che esso venga "realizato". Questa operazione puo essere fatta con una

  chiamata alla funzione 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 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.














  /* 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;
  }






  8.4.  Cornici ad aspetto fisso (Aspect Frames)

  Il widget aspect frame ' analogo al widget "cornice", tranne che per
  il

  fatto che e in grado di forzare le finestre figlie ad avere un certo
  aspetto,

  cioe un certo rapporto fra altezza e larghezza, aggiungendo se
  necessario

  dello spazio in piu. Cio puo 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:



       GtkWidget* gtk_aspect_frame_new  (const gchar *label,
                                               gfloat xalign,
                                               gfloat yalign,
                                               gfloat ratio,
                                               gint obey_child)




  xalign e yalign specificano l'allineamento come si fa con il widget di

  allineamento. Se obey_child e TRUE, le proporzioni di una finestra

  figlia saranno le stesse delle misure ideali richieste. In caso
  contrario, vengono

  stabilite da ratio.


  Per cambiare le opzioni di una finestra esistente, si puo usare: To
  change the options of an existing aspect frame, you can use:

       void gtk_aspect_frame_set (GtkAspectFrame *aspect_frame,
                                  gfloat xalign,
                                  gfloat yalign,
                                  gfloat ratio,
                                  gint obey_child)





  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.




       /* 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;
       }


  9.  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 e bianco. Dal
  momento che e direttamente derivato dal widget GtkContainer, puo
  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 potenzialita, si dovrebbe essere gia familiari
  con l'uso della GList e delle relative funzioni g_list_*().

  All'interno della definizione della struttura del widget GtkList c'e
  un campo che sara per noi di grande interesse, cioe:



       struct _GtkList
       {
         ...
         GList *selection;
         guint selection_mode;
         ...
       };




  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 e vuota. Quindi, per avere informazioni sulla
  selezione corrente, leggiamo il campo GTK_LIST()->selection, senza
  pero modificarlo dal momento che i campi interni debbono essere
  gestiti dalle funzioni gtk_list_*().

  Le modalita di selezione in una GtkList, e quindi il contenuto di
  GTK_LIST()->selection, sono determinate dal campo selection_mode:

  selection_mode puo assumere uno dei seguenti valori:

  o  GTK_SELECTION_SINGLE - La selezione puo essere o NULL oppure un
     puntatore GList* per un singolo elemento selezionato.

  o  GTK_SELECTION_BROWSE - La selezione e null se la lista non contiene
     alcun widget o se ha solo widget non sensibili, oppure puo
     contenere un puntatore a una struttura GList, e quindi esattamente
     un elemento di lista.

  o  GTK_SELECTION_MULTIPLE - La selezione e ``NULL'' se non e
     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 cosi via.

  o  GTK_SELECTION_EXTENDED - La selezione e sempre NULL.

  Il valore per difetto e  GTK_SELECTION_MULTIPLE.


  9.1.  Segnali



       void selection_changed (GtkList *LIST)


  Questo segnale verra invocato ogni volta che il campo di selezione di
  una GtkList e cambiato. Questo accade quando un figlio della GtkList
  viene selezionato o deselezionato.



       void select_child (GtkList *LIST, GtkWidget *CHILD)




  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 puo venir fatto scattare indirettamente
  in altre occasioni, in cui vengono aggiunti o rimossi dei figli dalla
  GtkList.



       void unselect_child (GtkList *LIST, GtkWidget *CHILD)




  Questo segnale viene invocato quando un figlio della GtkList sta per
  essere deselezionato. Cio accade principalmente in occasione di
  chiamate a gtk_list_unselect_item() e gtk_list_unselect_child(), di
  pressioni di bottoni, e a volte puo venir fatto scattare
  indirettamente in altre occasioni, in cui vengono aggiunti o rimossi
  dei figli dalla GtkList.


  9.2.  Funzioni



       guint gtk_list_get_type (void)




  Restituisce l'identificatore di tipo `GtkList'.



       GtkWidget* gtk_list_new (void)




  Crea un nuovo oggetto `GtkList'. Il nuovo widget viene restituito
  sotto forma di un puntoatore ad un oggetto `GtkWidgeti'. In caso di
  fallimento, viene ritornato NULL.



       void gtk_list_insert_items (GtkList *LIST, GList *ITEMS, gint POSITION)




  Inserisce degli elementi di lista nella LIST, a partire da POSITION.
  ITEMS ITEMS e 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.
       void gtk_list_append_items (GtkList *LIST, GList *ITEMS)




  Inserisce elementi di lista proprio come gtk_list_insert_items(), ma
  alla fine della LIST. I nodi GList di ITEMS vengono assunti dalla
  LIST.



       void gtk_list_prepend_items (GtkList *LIST, GList *ITEMS)




  Inserisce elementi di lista proprio come gtk_list_insert_items(), ma
  al principio della LIST. I nodi GList di ITEMS vengono assunti dalla
  LIST.



       void gtk_list_remove_items (GtkList *LIST, GList *ITEMS)




  Rimuove degli elementi di lista dalla LIST. ITEMS e una lista
  doppiamente collegata in cui ci si aspetta che i puntatori di ogni
  nodo puntino a un figlio diretto di LIST. E' poi responsabilita del
  chiamante di fare una chiamata a g_list_free(ITEMS). E' anche
  necessario che il chiamante distrugga lui stesso gli elementi della
  lista.



       void gtk_list_clear_items (GtkList *LIST, gint START, gint END)




  Rimuove e distrugge elementi di lista da LIST. Un widget ne e
  interessato se la sua posizione corrente all'interno di LIST e
  compreso fra START ed END.



       void gtk_list_select_item (GtkList *LIST, gint ITEM)




  Invoca il segnale select_child per un elemento di lista specificato
  dalla sua posizione corrente all'interno di LIST.



       void gtk_list_unselect_item (GtkList *LIST, gint ITEM)




  Invoca il segnale unselect_child per un elemento di lista specificato
  dalla sua posizione corrente all'interno di LIST.


       void gtk_list_select_child (GtkList *LIST, GtkWidget *CHILD)




  Invoca il segnale select_child per uno specifico CHILD.



       void gtk_list_unselect_child (GtkList *LIST, GtkWidget *CHILD)




  Invoca il segnale unselect_child per uno specifico CHILD.



       gint gtk_list_child_position (GtkList *LIST, GtkWidget *CHILD)




  Restituisce la posizione di CHILD all'interno di LIST. In caso di
  fallimento, viene restituito `-1'.



       void gtk_list_set_selection_mode (GtkList *LIST, GtkSelectionMode MODE)




  Assegna a LIST il modo di selezione MODE, che puo essere uno fra
  GTK_SELECTION_SINGLE, GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE o
  GTK_SELECTION_EXTENDED.



       GtkList* GTK_LIST (gpointer OBJ)




  Fa il cast di un generico puntatore a `GtkList*'. Per maggiori
  informazioni vedere Standard Macros::.



       GtkListClass* GTK_LIST_CLASS (gpointer CLASS)




  Fa il cast di un generico puntatore a `GtkListClass*'. Per maggiori
  informazioni vedere Standard Macros::.



       gint GTK_IS_LIST (gpointer OBJ)




  Determina se un generico puntatore si riferisce ad un oggetto
  `GtkList'.  Per maggiori informazioni vedere Standard Macros::.
  9.3.  Esempio

  Diamo di seguito un programma di esempio che stampera i campbiamenti
  della selezione di una GtkList, e vi lascia ``imprigionare'' gli
  elementi di una lista selezionandoli con il pulsante destro del mouse:





























































  /* 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 e 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");
  }





  9.4.  Il Widget Elemento di Lista (List Item)

  Il widget GtkListItem e 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 e bianco.

  Dal momento che questo widget deriva direttamente da GtkItem, puo
  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 puo 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 e obbligati a mettere una GtkLabel, si puo
  anche aggiungere una GtkVBox  una GtkArrow ecc. alla GtkListItem.



  9.5.  Segnali

  Un GtkListItem non crea alcun nuovo segnale di per se, ma eredita i
  segnali di GtkItem. Per ulteriori informazioni, vedere GtkItem::.


  9.6.  Funzioni




       guint gtk_list_item_get_type (void)



  Restituisce l'identificatore di tipo `GtkListItem'.



       GtkWidget* gtk_list_item_new (void)




  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'.



       GtkWidget* gtk_list_item_new_with_label (gchar *LABEL)




  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'.



       void gtk_list_item_select (GtkListItem *LIST_ITEM)




  Questa funzione e essenzialmente un wrapper per una chiamata a
  gtk_item_select (GTK_ITEM (list_item)) che emettera il segnale select.
  Vedere GtkItem:: per maggiori informazioni.



       void gtk_list_item_deselect (GtkListItem *LIST_ITEM)




  Questa funzione e essenzialmente un wrapper per una chiamata a
  gtk_item_deselect (GTK_ITEM (list_item)) che emettera il segnale
  deselect.  Vedere GtkItem:: per maggiori informazioni.



       GtkListItem* GTK_LIST_ITEM (gpointer OBJ)




  Effettua il cast di un puntatore generico a `GtkListItem*'. Vedere
  Standard Macros:: per maggiorni informazioni.



       GtkListItemClass* GTK_LIST_ITEM_CLASS (gpointer CLASS)




  Effettua il cast di un puntatore generico a `GtkListItemClass*'.
  Vedere Standard Macros:: per maggiorni informazioni.
       gint GTK_IS_LIST_ITEM (gpointer OBJ)




  Determina se un puntatore generico si riferisce ad un oggetto
  `GtkListItem'. Vedere Standard Macros:: per maggiorni informazioni.



  9.7.  Esempio

  Come esempio su questo argomento, si veda quello relativo alla
  GtkList, che riguarda anche l'uso del GtkListItem.


  10.  Il Widget Menu (Menu Widgets)

  Ci sono due modi per creare dei menu, quello facile e quello
  difficile.  Ognuno e piu adatto per certe circostanze, ma di solito si
  puo usare il modo semplice, cioe menu_factory (la ``fabbrica dei
  menu''). Il modo ``difficile'' e di crearsi tutti i menu usando
  direttamente le chiamate.  Quello semplice e di usare le chiamate di
  tipo gtk_menu_factory. Anche se e un modo molto piu semplice, ci sono
  svantaggi e vantaggi per ciascuno dei due approcci.

  La menu_factory e molto piu semplice da usare e per aggiungere dei
  nuovi menu, anche se scriversi un po' di funzioni per creare dei menu
  con il metodo manuale puo dare risultati molto migliori dal punto di
  vista dell'usabilita. Con la menufactory, non e possibile mettere
  immagini o caratteri '/' nei menu.


  10.1.  Creazione Manuale di Menu

  Seguendo la tradizionale arte dell'insegnamento, partiamo dal modo
  difficile. :)

  I widget che hanno a che fare con la creazione di una barra di menu e
  di sottomenu sono tre:

  o  un elemento di menu, che ' quello che l'utente poi selezionera, per
     esempio 'Salva'

  o  un menu, che fa la parte di contenitore per gli elementi di menu, e

  o  una barra dei menu, che e un contenitore per ciascuno dei menu


  La cosa viene un po' complicata dal fatto che i widget elemento di
  menu vngono usati per

  due scopi diversi. Essi sono sia i widget che vengono impacchettati
  nei menu, che

  quelli che vengono impacchettati nella barra dei menu che, quando
  selezonati, attivano i menu.

  Diamo un'occhiata alle funzioni usate per creare i menu e le barre di
  menu.  Con questa prima funzione si crea un nuova barra di menu:




       GtkWidget *gtk_menu_bar_new(void);

  Questa funzione crea una nuova barra di menu. 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.



       GtkWidget *gtk_menu_new();




  Questa funzione restituisce un puntatore ad un nuovo menu, non viene
  mai realmente mostrato (con gtk_widget_show), serve solo per contenere
  gli elementi del menu. Spero che il tutto risulti piu chiaro quando
  daremo un'occhiata all'esempio piu sotto.

  Le prossime due chiamate sono usate per creare degli elementi che poi
  vengono impacchettati nei menu e nelle barre dei menu..



       GtkWidget *gtk_menu_item_new();




  e



       GtkWidget *gtk_menu_item_new_with_label(const char *label);




  Queste chiamate sono usate per creare gli elementi di menu che devono
  poi essere mostrati.  Ricordate la differenza che esiste fra un
  ``menu'' come quelli creati con gtk_menu_new e un ``elemento di menu''
  (menu item) come quelli creati con la funzione gtk_menu_item_new.
  L'elemento di menu sara un bottone vero e proprio con una azione
  associata, mentre un menu e 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 menu con
  un'etichetta gia impacchettata,

  mentre l'altra crea un elemento di menu vuoto.


  Una volta che si ' creato un elemento di menu, e necessario piazzarlo
  su di un menu.

  Per fare cio si usa la funzione gtk_menu_append. Per determinare
  quando l'utente ha selezionato un elemento, abbiamo bisogno di
  connettere il segnale activate nel solito modo.

  Quindi, se volessimo creare un normale menu File, con le opzioni Open,
  Save e Quit, il codice avrebbe piu o meno il seguente aspetto:






  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 );






  A questo punto abbiamo il nostro menu Adesso abbiamo bisogno di creare
  una barra dei menu

  e un elemento di menu per File, a cui aggiungeremo il nostro menu. Il
  codice e questo:




       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);





  Ora dobbiamo associare il menu con file_item. Lo si puo fare con la
  funzione


       void gtk_menu_item_set_submenu( GtkMenuItem *menu_item, GtkWidget
       *submenu);



  Quindi, il nostro esempio continuerebbe con



  gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu);





  Cio che manca a questo punto e di collegare il menu alla barra, cosa
  che si puo ottenere tramite la funzione


       void gtk_menu_bar_append( GtkMenuBar *menu_bar, GtkWidget *menu_item);


  che nel nostro caso e:



       gtk_menu_bar_append( GTK_MENU_BAR(menu_bar), file_item );





  Se volessimo il menu giustificato a dstra, come sono spesso i menu di
  aiuto, potremm

  usare la seguente funzioe (di nuovo su file_item  in questo esempio)
  prima di fare il collegamento alla barra.




       void gtk_menu_item_right_justify (GtkMenuItem *menu_item);




  Ecco un riassunto dei passi necessari per creare una barra con i rela-
  tivi menu collegati:


  o  Create un nuovo menu con gtk_menu_new()

  o  Usate delle chiamate multiple a gtk_menu_item_new() per ognuno
     degli elementi che volete mettere nel vostro menu. Usate inoltre
     gtk_menu_item_append() per mettere ciascuno di questi nuovi
     elementi sul menu..

  o  Create un elemento di menu usando gtk_menu_item_new(). Questo
     rappresenta l'elemento di base

     delmenu, e il testo relativo sara il testo mostrato sulla barra dei
     menu stessa.

  o  Usate gtk_menu_item_set_submenu() per collegare i menu all'elemento
     base del menu (cioe quello creato al passaggio precedente).

  o  Create una nuova barra di menu usando gtk_menu_bar_new. Questo
     passo necessita di essere effettuato una sola volta quando si crea
     una serie di menu su una sola barra.

  o  Usate gtk_menu_bar_append per mettere il menu base sulla barra dei
     menu.

  Creare un menu a comparsa e piu o meno la stessa cosa. La differenza e
  che il il menu non viene attivato ``automaticamente'' da una barra,
  bensi per esempio con la chiamata espicita alla funzione
  gtk_menu_popup() da parte di un evento di pressione di un pulsante.
  Seguite questi passaggi:

  o  Create una funzione di gestione di un evento. Essa deve seguire il
     prototipo

       static gint handler(GtkWidget *widget, GdkEvent *event);


  e usare l'evento per scoprire dove il menu deve essere fatto compar-
  ire.

  o  Nel gestore di evento, se questo e la pressione di un bottone,
     trattate event come l'evento relativo ad un bottone (cosa che in
     effetti e) e usatelo come mostrato nel codice di esempio per
     passare informazioni a gtk_menu_popup().

  o  Collegate il gestore di evento a un widget con

       gtk_signal_connect_object(GTK_OBJECT(widget), "event", GTK_SIGNAL_FUNC
       (handler), GTK_OBJECT(menu));


  in cui widget e il widget a cui state effettuando il collegamento, e
  handler e la funzione di gestione, mentre menu e un menu creato con
  gtk_menu_new(). Quest'ultimo puo essere un menu che viene anche atti-
  vato da una barra di menu, come mostrato nel codice di esempio.



  10.2.  Esempio di Menu Manuale

  Per la teoria dovrebbe essere abbastanza. Diamo un'occhiata ad un
  esempio che ci aiuti a chiarire le cose.































  /* 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 menu, e ricordate: mai applicare
       * gtk_show_widget() al widget menu!!
       * Questo e il menu che contiene gli elementi, quello che
       * spunta quando si fa click sul "Menu 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 menu. 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
       * brevita. */

      for(i = 0; i < 3; i++)
          {
              /* Copia i nomi in buf. */
              sprintf(buf, "Test-undermenu - %d", i);

              /* Crea un nuovo elemento di menu con un nome... */
              menu_items = gtk_menu_item_new_with_label(buf);

              /* ...e aggiungilo al menu. */
              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 e il menu radice, e l'etichetta sara il nome del menu che
       * verra mostrato sulla barra dei menu. Non ci sara alcun gestore di
       * segnale collegato, dal momento che non fa altro che mostrare il resto
       * del menu quando viene premuto. */
      root_menu = gtk_menu_item_new_with_label("Root Menu");
      gtk_widget_show(root_menu);




      /* Ora specifichiamo che vogliamo che il menu che abbiamo appena creato
       * sia il menu radice *//
      gtk_menu_item_set_submenu(GTK_MENU_ITEM (root_menu), menu);

      /* Una vbox in cui mettere un menu ed un bottone: */
      vbox = gtk_vbox_new(FALSE, 0);
      gtk_container_add(GTK_CONTAINER(window), vbox);
      gtk_widget_show(vbox);

      /* Crea una barra dei menu per metterci i menu 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 menu */
      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 menu alla barra dei menu -- questo
       * e l'elemento di menu "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 gia
       * completa di tutti i suoi elementi. */
      gtk_widget_show(window);

      gtk_main ();

      return 0;
  }



  /* Risponde alla pressione di un bottone impostando un menu che
   * viene passato come widget.
   * Notate che l'argomento "widget" si riferisce al menu 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 menu */

  static void menuitem_response (gchar *string)
  {
      printf("%s\n", string);
  }




  Si puo anche fare in modo che un elemento di menu sia insensibile e,
  usando una tabella di acelleratori, collegare dei tasti a delle
  funzioni di menu.



  10.3.  Usare GtkMenuFactory

  Ora che vi abbiamo mostrato il modo difficile, ecco invece come si fa
  usando le chiamate di gtk_menu_factory.



  10.4.  Esempio di Menu Factory

  Ecco un esempio di utilizzo della ``Fabbrica'' di Menu di GTK (Menu
  Factory).  Questo e il primo file, menufactoy.h. Teniemo dei file
  menufactory.c e main.c separati a causa delle variabili globali usate
  nel file menufactory.c.




       /* 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__ */




  Ed ecco il file menufactory.c.













  /* 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 e la struttuta GtkMenuEntry, che viene usata per creare dei nuovi
   * menu. Il primo membro a la stringa di definizione del menu. Il secondo
   * e il tasto acceleratore predefinito, usato per accedere a questa funzione
   * con la tastiera. Il terzo e la funzione di ritorno che viene chiamata
   * quando si seleziona con la tastiera o il mouse questo elemento di menu.
   * 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 sensibilita a menu inesistente: %s", path);
  }




  Ed ecco mfmain.h



       /* 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__ */




  E mfmain.c






















  /* 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 e 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 li. Cosi le cose sono piu organizzate. */
  void file_quit_cmd_callback (GtkWidget *widget, gpointer data)
  {
      g_print ("%s\n", (char *) data);
      gtk_exit(0);
  }




  Ed infine un bel makefile per semplificare la compilazione.









  # 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 *~




  Per il momento, accontentatevi di questo esempio. Piu avanti
  aggiungeremo una spiegazione ed un bel po' di commenti.



  11.  Widget "Testo" (Text Widget)

  Il widget di testo permette di mostrare e modificare del testo
  disposto su piu 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 da la possibilita 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.


  11.1.  Creazione e configurazione di una casella di testo

  Esiste un'unica funzione per la creazione di un nuovo widget di testo:


       GtkWidget* gtk_text_new (GtkAdjustment *hadj,
                                GtkAdjustment *vadj);




  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, fa si che gtk_text_new li crei automaticamente.





  void gtk_text_set_adjustments (GtkText       *text,
                                 GtkAdjustment *hadj,
                                 GtkAdjustment *vadj);




  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 quantita e troppo grande per la finestra. Dobbiamo quindi crearle e
  aggiungerle alla finestra noi stessi.



         vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);
         gtk_box_pack_start(GTK_BOX(hbox), vscrollbar, FALSE, FALSE, 0);
         gtk_widget_show (vscrollbar);




  Il pezzetto di codice precedente crea una nuova barra di scorrimento
  verticale e la collega all'aggiustamento verticale del widget di
  testo, text, dopodiche 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 piu righe. Per
  passare dall'una all'altra di queste modalita, il widget di testo ci
  mette a disposizione la seguente funzione:



       void gtk_text_set_editable    (GtkText *text,
                                      gint    editable);




  L'argomento editable e un valore TRUE o FALSE che specifica se
  l'utente puo modificare o meno il contenuto del widgte. Quando il
  widget e modificabile, mostrera un cursore nel punto di inserimento
  corrente.

  Niente pero vi obbliga ad usare il widget di testo in questi due soli
  modi. Si puo passare dall'una all'altra delle due modalita in
  qualsiasi momento, e si puo inserire del testo in ogni momento.

  Il widget di testo e 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 e di andare a capo
  automaticamente al termine della linea. Questo puo essere cambiato con
  la seguente funzione:



       void gtk_text_set_word_wrap (GtkText *text,
                                    gint    word_wrap);




  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 word_wrap e un valore di tipo TRUE o FALSE.


  11.2.  Manipolazione del testo

  Il punto di inserimento corrente del widget puo essere stabilito
  usando


       void gtk_text_set_point (GtkText *text,
                                guint   index);




  in cui index e la posizione in cui mettere il punto di inserimento.

  La funzione per ottenere la posizione di inserimento corrente e
  analoga:


       guint gtk_text_get_point (GtkText *text);




  Una funzione che e utile in combinazione con le precedenti due e


       guint gtk_text_get_length (GtkText *text);




  la quale restituisce la lunghezza corrente del widget di testo. La
  lunghezza e definita come il numero di caratteri che si trovano nel
  blocco di testo della finestra, compresi i caratteri tipo CR, che mar-
  cano 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.



       void gtk_text_insert (GtkText    *text,
                             GdkFont    *font,
                             GdkColor   *fore,
                             GdkColor   *back,
                             const char *chars,
                             gint       length);




  Passare un valore di NULL come valore per il colore di primo piano
  (fore), di sfondo (back) o per il font, fara si che vengano usati i
  valori che sono specifici dello stile del widget. Usare un valore di
  -1 per il parametro lunghezza (length) avra come risultato
  l'inserzione dell'intera stringa di testo.

  Il widget di testo e uno dei pochi in GTK che vengono disegnati
  dinamicamente, fuori dalla funzione gtk_main. Cio significa che tutti
  i cambiamenti al suo contenuto avranno effetto immediato. Questo puo
  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 puo 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:



       void gtk_text_freeze (GtkText *text);
       void gtk_text_thaw   (GtkText *text);




  Il testo puo 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):



       gint gtk_text_backward_delete (GtkText *text,
                                      guint   nchars);
       gint gtk_text_forward_delete  (GtkText *text,
                                      guint   nchars);




  Quando si vuole recuperare il contenuto del widget di testo, e
  disponibile la macro GTK_TEXT_INDEX(t, index), che permette di
  ottenere il crattere alla posizione index all'interno del widget t.

  Per ecuperare un blocco di testo piu ampio, si usa la funzione:



       gchar *gtk_editable_get_chars (GtkEditable *editable,
                                      gint        start_pos,
                                      gint        end_pos);




  Questa e una funzione della classe madre del widget di testo. Un
  valore di -1 per 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 piu bisogno.


  11.3.  Keyboard Shortcuts

  Il widget di testo mette a disposizione un certo numero di scorciatoie
  da tastiera per le piu 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, causera lo spostamento parola per
  parola invece che carattere per carattere. Mantenere invece premuto il
  tasto Shift mentre si sposta il cursore, causera l'estensione della
  selezione.


  11.3.1.  Scorciatoie per il movimento


  o  Ctrl-A   Inizio della linea

  o  Ctrl-E Fine della linea

  o  Ctrl-N   Prossima linea

  o  Ctrl-P Linea precedente

  o  Ctrl-B   Indietro di un carattere

  o  Ctrl-F   Avanti di un carattere

  o  Alt-B    Indietro di una parola

  o  Alt-F  Avanti di una parola


  11.3.2.  Scorciatoie per la modifica


  o  Ctrl-H   Cancella il carattere precedente (Backspace)

  o  Ctrl-D   Cancella il carattere successivo (Delete)

  o  Ctrl-W Cancella la parola precedente

  o  Alt-D    Cancella la parola successiva

  o  Ctrl-K Cancella fino alla fine della linea

  o  Ctrl-U Cancella la linea


  11.3.3.  Scorciatoie per la selezione


  o  Ctrl-X   Taglia

  o  Ctrl-C   Copia

  o  Ctrl-V Incolla



  12.  Widget non documentati

  Per questi sarebbe utile il contributo degli autori! :) Prendete in
  considerazione la possibilita 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 e
  difficile dedurre il modo d'uso di un widget semplicemente guardando
  la dichiarazione di funzione associata ad esso. 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 possibilita di scrivere
  un tutorial su di esso, in modo che altri possano beneficiare del
  vostro lavoro.


  12.1.  Controlli di intervallo (Range Controls)

  12.2.  Anteprime

  Le anteprime servono a un certo numero di cose in GIMP/GTK. La piu
  importante e questa: a risoluzioni molto alte le immagini possono
  facilmente occupare diverse decine di megabyte di memoria; ogni
  operazione su immagini cosi grosse puo richiedere molto tempo. Se per
  la scelta di una data modifica vi occorrono 5-10 tentativi (cioe 10-20
  passi, poiche e necessario ripristinare l'originale se si e 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 e l'unico caso. Spesso e 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 e 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'e di piu. Con le anteprime e possibile scrivere plug-in per
  ottenere addirittura anteprime di anteprime (per esempio, la
  simulazione del pacchetto di filtri). Questi plug-in possono cosi
  fornire un certo numero di anticipazioni di quel che si otterrebbe
  applicando certe opzioni. Un simile approccio funziona come una
  tavolozza di anteprime, ed e molto efficace per piccoli cambiamenti!

  Non e finita. Per alcuni plug-in puo 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 piu semplice per fare questo e 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., poiche per
  queste cose GDK e molto piu 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 pero 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 e 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 cio che questo implica), con l'eccezione di avere una
  caratteristica in piu: e necessario che siano riempite con qualche
  tipo di immagine! Inizialmente parleremo solo dell'aspetto GTK delle
  anteprime e successivamente discuteremo di come riempirle.

  Semplicemente:



                                     /* 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);




  Come gia detto, le anteprime hanno un buon aspetto dentro le cornici,
  quindi:



       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;
       }




  Questa e una semplice anteprima. Questa funzione restituisce la
  cornice ``madre'', in modo che sia possibile metterla in qualche altro
  posto nella vostra interfaccia. Naturalmente e 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 cosi il controllo dopo.


  Un'avvertimento piu importante che potrebbe un giorno risparmiarvi
  tanto tempo perso: a volte e preferibile etichettare le anteprime; ad
  esempio, e 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 e piu ampia dell'anteprima (cosa che puo
  accadere per una varieta 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 piu
  perfettamente aderente all'anteprima. Questo stesso problema
  probabilmente puo verificarsi anche in altre situazioni.

  [Image]

  La soluzione e 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 e una delle varianti
  possibili, naturalmente; l'importante e che non ci sia GTK_FILL nella
  seconda gtk_table_attach):



       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);




  Ed ecco il risultato:

  [Image]

  Altri suggerimenti

  La maniera piu semplice per rendere cliccabile un'anteprima e 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 e 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]











  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" e 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? */
  }




  Coloro che non usano GIMP probabilmente hanno gia visto abbastanza per
  fare molte cose. Per gli utenti GIMP c'e ancora qualcosa da aggiun-
  gere.

  Anteprima dell'immagine

  Probabilmente e opportuno tenere pronta una versione ridotta
  dell'immagine, grande quanto basta per riempire l'anteprima. Questo
  puo essere fatto selezionando un pixel ogni n, dove n e 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 e
  riportata un'implementazione della riduzione dell'immagine (si tenga
  presente che ho preso solo lezioni basilari di C!).


  (ATTENZIONE: CODICE NON VERIFICATO!!!)








  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 e determinata da LongerSize, cioe la piu */
    /* 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'e 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         */
    /* diventera 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);
    }

    /* Cosi 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 piu lungo. L'idea e presa dal plug-in supernova. Ritengo   */
    /* che avrei potuto pensarci da solo, ma la verita 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;
  }





  La seguente e una funzione di anteprima che usa lo stesso tipo
  ReducedImage! Si noti che usa una finta trasparenza - se ne e presente
  una, tramite fake_transparency che e definita come segue:





  gint fake_transparency(gint i, gint j)
  {
    if ( ((i%20)- 10) * ((j%20)- 10)>0   )
      return 64;
    else
      return 196;
  }




  E adesso la funzione per l'anteprima:






















































  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    */
  /* e 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!





  12.3.  Curve



  13.  Il Widget EventBox


  Alcuni widget gtk non sono associati a finestre X, sicche
  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 piu da questi widget si puo 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. Cio e 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 puo 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 puo
  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:




  GtkWidget* gtk_event_box_new (void);





  All'EventBox si puo aggiungere un widget figlio:



       gtk_container_add (GTK_CONTAINER(event_box), widget);





  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.












































  /* 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;
  }





  14.  Selezionare gli Attributi dei Widget

  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).


       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);






  15.  Funzioni periodiche, di I/O e di attesa


  15.1.  Funzioni periodiche

  Probabilmente vi sarete chiesti come far fare qualcosa di utile a GTK
  durante la chiamata alla gtk_main(). Ci sono diverse possibilita.
  Usando le seguenti funzioni si possono creare funzioni che vengono
  chiamate periodicamente.



       gint gtk_timeout_add (guint32 interval,
                             GtkFunction function,
                             gpointer data);




  Il primo argomento e il numero di millisecondi tra le chiamate alla
  funzione. Il secondo e la funzione periodica, mentre il terzo
  rappresenta i dati che vengono passati alla funzione. Il valore
  restituito e un'etichetta che puo essere utilizzata per fermare la
  chiamata periodica, passandolo alla funzione:



       void gtk_timeout_remove (gint tag);




  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, cioe TRUE.

  La dichiarazione della funzione periodica dovrebbe essere come questa:



       gint timeout_callback (gpointer data);





  15.2.  Controllo dell'I/O

  Un'altra utile caratteristica di GTK e la possibilita di fargli
  controllare che siano verificate certe condizioni su un descrittore di
  file (come quelli restituiti da open(2) o socket(2)). Questo e utile
  in particolar modo per le applicazioni di rete. La funzione e la
  seguente:



       gint gdk_input_add (gint source,
                           GdkInputCondition condition,
                           GdkInputFunction  function,
                           gpointer data);




  Il primo argomento e il descrittore che si desidera venga controllato,
  mentre il secondo specifica quale condizione si vuole che GDK
  controlli.  Questa puo 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 e
  pronto per la scrittura.

  Come sicuramente avrete gia intuito, il terzo parametro e la funzione
  da chiamare quando la condizione specificata e soddisfatta, mentre il
  quarto rappresenta i dati da passare a questa funzione.

  Il valore di ritorno  e un etichetta che puo essere usata per fermare
  il controllo di GDK sul descrittore di file, usando la seguente
  funzione:



       void gdk_input_remove (gint tag);


  La funzione da richiamare va dichiarata cosi:



       void input_callback (gpointer data, gint source,
                            GdkInputCondition condition);






  15.3.  Funzioni di attesa (``Idle'')

  Cosa fare se si ha una funzione che si vuole venga chiamata quando non
  sta accadendo nient'altro?



       gint gtk_idle_add (GtkFunction function,
                          gpointer data);




  Questa fa si che GDK chiami la funzione specificata quando non c'e
  nessuna altra operazione in corso.



       void gtk_idle_remove (gint tag);




  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'opportunita;
  come negli altri casi, se essa restituisce FALSE non viene piu
  chiamata.


  16.  La gestione delle selezioni

  16.1.  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) puo essere proprietaria di una particolare selezione,
  sicche quando un'applicazione richiede una selezione il precedente
  proprietario deve comunicare all'utente che la selezione e stata
  ceduta. Altre applicazioni possono richiedere il contenuto di una
  selezione in diverse forme, chiamate obiettivi.  Ci puo essere un
  numero qualsiasi di selezioni, ma la maggior parte delle applicazioni
  X puo gestirne solo una, la selezione primaria.


  Nella maggior parte dei casi per una applicazione GTK non e necessario
  gestire esplicitamente le selezioni. I widget standard, come quello di
  Ingresso, hanno gia la capacita 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 capacita di fornire la selezione, o si vogliono
  recuperare degli obiettivi non supportati direttamente.


  Un concetto fondamentale necessario per comprendere la gestione delle
  selezioni e quello di atomo. Un atomo e un intero che identifica
  univocamente una stringa (su un certo display).  Certi atomi sono
  predefiniti dal server X, e in alcuni casi in gtk.h ci sono costanti
  corrispondenti a questi atomi. Per esempio, la costante
  GDK_PRIMARY_SELECTION corrisponde alla stringa ``PRIMARY''.  Negli
  altri casi bisogna usare le funzioni gdk_atom_intern() per ottenere
  l'atomo corrispondente ad una stringa, e gdk_atom_name() per ottenere
  il nome di un atomo. Sia le selezioni sia gli obiettivi sono
  identificati da atomi.

  16.2.  Recuperare le selezioni


  Il recupero di una selezione e  un processo asincrono. Per iniziare il
  processo, si chiama:


       gint gtk_selection_convert   (GtkWidget           *widget,
                                     GdkAtom              selection,
                                     GdkAtom              target,
                                     guint32              time)




  Questo converte la selezione nella forma specificata dall'obiettivo
  target. Se possibile, il campo 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 e stata
  attivata da un segnale di ``cliccato''), allora si puo usare la
  costante GDK_CURRENT_TIME.


  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 GtkSelectionData, che e definita nel modo seguente:


       struct _GtkSelectionData
       {
         GdkAtom selection;
         GdkAtom target;
         GdkAtom type;
         gint    format;
         guchar *data;
         gint    length;
       };




  selection e target sono i valori da voi specificati nella chiamata
  gtk_selection_convert(). type e un atomo che identifica il tipo di
  dati restituiti dal proprietario della selezione. Alcuni valori possi-
  bili sono ``STRING'', una stringa di caratteri latin-1, ``ATOM'', una
  serie di atomi, ``INTEGER'', un intero, ecc.  La maggior parte degli
  obiettivi puo restituire solo un tipo.  format ci da la lunghezza
  delle unita (per esempio caratteri) in bit. Di solito, quando si
  ricevono i dati non ci si cura di questo.  data e un puntatore ai dati
  restituiti, e length e la lunghezza dei dati restituiti, in byte. Se
  length e negativo allora si e verificato un errore e non e stato pos-
  sibile recuperare la selezione. Questo puo avvenire se nessuna appli-
  cazione era proprietaria della selezione, o se si e richiesto un obi-
  ettivo non supportato dall'applicazione. Viene garantito che il buffer
  sia un byte piu lungo di length; il byte in piu sara sempre zero, in
  modo che non sia necessario ricopiare le stringhe solo per farle ter-
  minare con zero.


  Nell'esempio che segue viene recuperato l'obiettivo speciale
  ``TARGETS'', che e una lista di tutti gli obiettivi in cui puo essere
  convertita la selezione.




















































  /* 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 puo 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;
  }





  16.3.  Fornire una selezione

  Fornire la selezione e un po' piu complicato. Bisogna registrare i
  gestori che verranno chiamati quando viene richiesta la propria
  selezione. Per ogni coppia selezione/obiettivo che si gestira occorre
  una chiamata a:



       void gtk_selection_add_handler (GtkWidget           *widget,
                                       GdkAtom              selection,
                                       GdkAtom              target,
                                       GtkSelectionFunction function,
                                       GtkRemoveFunction    remove_func,
                                       gpointer             data);




  widget, selection, e target identificano le richieste che questo
  gestore soddisfera.  remove_func, se non e NULL, verra chiamato quando
  il gestore di segnale viene rimosso.  Questo e utile, per esempio, per
  linguaggi interpretati ai quali serve di tener traccia di un conteggio
  di riferimento per data.


  La funzione di richiamo ha la forma:


       typedef void (*GtkSelectionFunction) (GtkWidget *widget,
                                             GtkSelectionData *selection_data,
                                             gpointer data);




  La GtkSelectionData e la stessa di prima, ma stavolta siamo
  responsabili di riempire i campi type, format, data, e length. (Il
  campo format qui e effettivamente importante - il server  X lo usa per
  capire se occorre che i byte dei dati vengano scambiati o no. Di
  solito sara 8 - cioe un carattere - o 32 - cioe un intero.) Questo
  viene fatto chiamando la funzione:



       void gtk_selection_data_set (GtkSelectionData *selection_data,
                                    GdkAtom           type,
                                    gint              format,
                                    guchar           *data,
                                    gint              length);




  Questa funzione si prende cura di fare propriamente una copia dei dati
  in modo che non ci si debba preoccupare di conservarli (e opportuno
  evitare di riempire a mano i campi della struttura GtkSelectionData).


  Quando richiesto dall'utente, richiederete la proprieta della
  selezione chiamando:



       gint gtk_selection_owner_set (GtkWidget           *widget,
                                     GdkAtom              selection,
                                     guint32              time);




  Se un'altra applicazione richiede la proprieta della selezione,
  riceverete un evento di azzeramento della selezione
  (``selection_clear_event'').

  Come esempio di fornitura della selezione, il programma seguente
  aggiunge la funzionalita 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) e l'obiettivo ``STRING''. Quando
  viene richiesto questo obiettivo, viene restituita una
  rappresentazione stringa del tempo.













  /* 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 e 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 verra 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;
  }





  17.  La 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 scendera nei dettagli.
  Questa vuole essere una lista di riferimento, in modo che si sappia
  cosa e possibile usare.


  17.1.  Definizioni

  Le definizioni per gli estremi di molti dei tipi standard sono:











  G_MINFLOAT
  G_MAXFLOAT
  G_MINDOUBLE
  G_MAXDOUBLE
  G_MINSHORT
  G_MAXSHORT
  G_MININT
  G_MAXINT
  G_MINLONG
  G_MAXLONG




  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
  portabilita! P.e., un puntatore su un Alpha e lungo 8 byte, ma 4 su un
  Intel.



       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





  17.2.  Liste a doppio collegamento

  le seguenti funzioni sono usate per creare, gestire e distruggere
  liste a doppio collegamento. Si assume che il lettore sappia gia cosa
  sono le liste collegate (linked list), poiche descriverle e fuori
  dagli scopi di questo documento. Naturalmente non e necessario
  conoscerle per l'uso generale di GTK, per quanto conoscerle sia
  comunque interessante.








  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);






  17.3.  Liste a collegamento singolo

  Molte delle funzioni per le liste a collegamento singolo sono
  identiche alle precedenti. Eccone una lista completa:

















  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);






  17.4.  Gestione della memoria



       gpointer g_malloc      (gulong    size);




  Questa e una sostituta di malloc(). Non occorre controllare il valore
  restituito, in quanto lo fa gia questa funzione.



       gpointer g_malloc0     (gulong    size);




  Come la precedente, ma la memoria viene azzerata prima di restituire
  un puntatore ad essa.


       gpointer g_realloc     (gpointer  mem,
                               gulong    size);




  Riloca ``size'' byte di memoria che inizia a ``mem''. Ovviamente, la
  memoria dovrebbe essere stata allocata precedentemente.



       void     g_free        (gpointer  mem);




  Libera la memoria. Facile!



       void     g_mem_profile (void);




  Emette un profilo della memoria usata, ma occorre ricompilare e
  reinstallare la libreria aggiungendo #define MEM_PROFILE all'inizio
  del file glib/gmem.c.



       void     g_mem_check   (gpointer  mem);




  Controlla che una locazione di memoria sia valida. Occorre ricompilare
  e reinstallare la libreria aggiungendo #define MEM_CHECK all'inizio
  del file gmem.c.


  17.5.  Timer

  Funzioni legate ai timer...



       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);







  17.6.  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.



       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,
                                    ...);






  17.7.  Funzioni d'utilita e di errore



       gchar* g_strdup    (const gchar *str);




  Funzione sostitutiva della strdup. Copia i contenuti originari delle
  stringhe in memoria appena allocata, restituendo un puntatore ad essa.



       gchar* g_strerror  (gint errnum);




  Si raccomanda di usare questa gunzione per tutti i messaggi di errore.
  E' molto piu graziosa, e piu portabile di perror() o di altre. L'out-
  put di solito ha la forma:
       nome programma:funzione fallita:file o altre descrizioni:strerror




  Di seguito un esempio di una chiamata di questo tipo usata nel nostro
  programma Hello World:



       g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));






       void g_error   (gchar *format, ...);




  Visualizza un messaggio di errore. Il formato e come quello di printf,
  ma prepone ``** ERROR **: '' al messaggio e termina il programma. Da
  usare solo per errori gravi.



       void g_warning (gchar *format, ...);




  Come la precedente, ma prepone ``** WARNING **: '' e non termina il
  programma.



       void g_message (gchar *format, ...);




  Visualizza ``message: '' e poi il messaggio.



       void g_print   (gchar *format, ...);




  Sostituta di printf().

  L'ultima funzione:



       gchar* g_strsignal (gint signum);




  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 piu o meno prese da glib.h. Se
  qualcuno volesse documentare qualche funzione, mandi una email
  all'autore!


  18.  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.


  18.1.  Funzioni per i file rc

  All'inizio della vostra applicazione dovrebbe esserci una chiamata a


       void gtk_rc_parse (char *filename);




  passando come parametro il nome del vostro file rc. Questo fara 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


       void gtk_widget_set_name (GtkWidget *widget,
                                 gchar *name);




  passando un widget appena creato come primo argomento, e il nome che
  gli si vuole dare come secondo. Questo consentira di cambiare gli
  attributi di questo widget per nome tramite il file rc.

  Effettuando una chiamata come questa:



       button = gtk_button_new_with_label ("Special Button");
       gtk_widget_set_name (button, "special button");




  allora a questo bottone viene dato il nome ``special button'' ed esso
  puo essere riferito per nome nel file rc come ``special
  button.GtkButton''. [<--- Verificatemi!]

  Il seguente esempio di file rc imposta le proprieta 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 e:



       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       gtk_widget_set_name (window, "main window");

  Lo stile viene definito nel file rc usando:



       widget "main window.*GtkButton*" style "main_button"




  che assegna a tutti i widget GtkButton nella finestra principale lo
  stile ``main_buttons'' secondo la definizione data nel file rc.

  Come si puo vedere, questo sistema e molto potente e flessibile. Usate
  la vostra immaginazione per trarre il massimo vantaggio da esso.


  18.2.  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.

  o  fg - Assegna il colore di primo piano di un widget.

  o  bg - Assegna il colore di sfondo di un widget.

  o  bg_pixmap - Inserisce nello sfondo di un widget una pixmap.

  o  font - Sceglie il font da usarsi con il dato widget.

  Inoltre ci sono diversi stati in cui puo trovarsi un widget, e si
  possono assegnare diversi colori, pixmap e font per ogni stato. Essi
  sono:

  o  NORMAL - Lo stato normale di un widget, quando il mouse non si
     trova su di esso, quando non e premuto, ecc.

  o  PRELIGHT (evidenziato)- Quando il mouse si trova sopra al widget
     verranno usati i colori assegnati per questo stato.

  o  ACTIVE (attivo) - Quando il widget e premuto o cliccato esso sara
     attivo, e verranno usati gli attributi assegnati da questa
     etichetta.

  o  INSENSITIVE (insensibile)- Quando un widget viene reso insensibile,
     e non puo essere attivato, prendera questi attributi.

  o  SELECTED (selezionato) - Quando un oggetto viene selezionato,
     prende questi attributi.

  Quando si usano le parole chiave ``fg'' e ``bg'' per assegnare i
  colori dei widget il formato e:


       fg[<STATE>] = { Rosso, Verde, Blu }




  Dove STATE e 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, sicche un ``1'' diretto non funziona, deve
  essere ``1.0''. Uno ``0'' diretto va invece bene, poiche poco importa
  se non viene riconosciuto: valori non riconosciuti vengono considerati
  0.

  bg_pixmap e molto simile al precedente, tranne per i colori che
  vengono sostituiti dal nome di un file.

  pixmap_path e una lista di percorsi separati da ``:''. In questi
  percorsi vengono cercate le pixmap specificate.

  La direttiva font e semplicemente:


       font = "<font name>"




  dove l'unica parte complicata e immaginare la stringa del font. Allo
  scopo puo servire usare xfontsel o una utilita 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 ``parent'' viene usata come un attributo, il
  widget ereditera 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.


       style "main_button" = "button"
       {
         font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
         bg[PRELIGHT] = { 0.75, 0, 0 }
       }




  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.


  18.3.  Esempio di file rc




  # 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 e 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 e premuto o cliccato esso sara attivo,
  # e verranno usati gli attributi assegnati da questa etichetta.
  #
  # INSENSITIVE (insensibile)- Quando un widget viene reso insensibile,
  # e non puo essere attivato, prendera questi attributi.
  #
  # SELECTED (selezionato) - Quando un oggetto viene selezionato, prende
  # questi attributi.
  #
  # Dati questi stati, e 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 e uno stile chiamato "button". Il nome non e 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 e applicabile e 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"





  19.  Scrivere un proprio Widget

  19.1.  Panoramica

  Anche se la distribuzione GTK contiene molto tipi di widget che
  possono coprire molte necessita basilari, puo essere necessario
  costruirsi un proprio widget. GTK usa molto l'ereditarieta tra i vari
  widget e, di solito, vi e un widget che si avvicina a quello che ti
  servirebbe, ed e 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 gia creato. Questo evitera un
  duplicazione di lavoro e fara si che i widget non-GTK puri siano
  minimi, cosi 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 cosi che le altre
  persone ne possano beneficiare. Il miglioro modo dove farlo e la  gtk-
  list.

  I sorgenti completi per i widget di esempio possono essere presi dallo
  stesso sito da cui avete scaricato questo tutorial, oppure da:

  http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial



  19.2.  L'anatomia di un widget

  Per creare un nuovo widget e importante aver capito come gli ogetti di
  GTK lavorano. Questa sezione e 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
  portabilita e la stabilita, 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) e 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'ereditarieta il primo campo della
  struttura di una classe deve essere una copia della struttura della
  classe genitore. La dichiarazione della struttura della classe
  GtkButton e:



       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);
       };





  Quando un bottone viene trattato come un contenitore (ad esempio
  quando viene ridimensionato) si puo fare il cast della struttura della
  sua classe con la GtkContainerClass, e usare i campi rilevanti per
  gestire i segnali.


  C'e 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:



       struct _GtkButton
       {
         GtkContainer container;

         GtkWidget *child;

         guint in_button : 1;
         guint button_down : 1;
       };





  Si noti che, similmente alla struttura della classe, il primo campo e
  la struttura dell'oggetto della classe madre, cosi che, se necessario,
  si puo fare il cast di questa struttura con quella dell'oggetto della
  classe madre.


  19.3.  Creare un Widget composto

  19.3.1.  Introduzione

  Un tipo di widget a cui potreste essere interessati e un widget che e
  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 e 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.


  19.3.2.  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 e la classe
  Dialog. Visto che i nostri bottoni sono inseriti in una tabella, e
  naturale pensare che la nostra classe madre possa essere la GtkTable.
  Sfortunatamente, cosi non e. La creazione di un widget e diviso tra 2
  funzioni : la funzione WIDGETNAME_new() che viene invocata
  dall'utente, e la funzione  WIDGETNAME_init() che ha il compito
  principale di inizializzare il widget che e indipendente dai valori
  passati alla funzione _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 comporra. A meno che non vogliamo duplicare molte delle
  fuinzionalita della 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.


  19.3.3.  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:



       #ifndef __TICTACTOE_H__
       #define __TICTACTOE_H__
       .
       .
       .
       #endif /* __TICTACTOE_H__ */




  E per far felici i programmi in C++ che includono il nostro file
  header, in:



       #ifdef __cplusplus
       extern "C" {
       #endif /* __cplusplus */
       .
       .
       .
       #ifdef __cplusplus
       }
       #endif /* __cplusplus */




  Insieme alle funzioni e alle strutture, dichiariamo tre macro standard
  nel nostro file header, TICTACTOE(obj), TICTACTOE_CLASS(klass), e
  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 e un widget Tictactoe.


  Qui vi e il file header completo:
















  /* 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__ */





  19.3.4.  La funzione _get_type()

  Continuiamo ora con l'implementazione del nostro widget. Una funzione
  basilare di ogni widget e la funzione 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.











  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;
  }





  La struttura GtkTypeInfo ha la seguente definizione:



       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;
       };





  I campi di questa struttura sono abbastanza auto-esplicativi.
  Ignoreremo, per ora, i campi  arg_set_func e 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.


  19.3.5.  La funzione _class_init()

  La funzione 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:





  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;
  }





  Il nostro  widget ha semplicemente il segnale ``tictactoe'' che e
  invocato quando una riga, colonna o diagonale e 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:


       gint   gtk_signal_new (const gchar         *name,
                              GtkSignalRunType    run_type,
                              GtkType             object_type,
                              gint                function_offset,
                              GtkSignalMarshaller marshaller,
                              GtkType             return_val,
                              guint               nparams,
                              ...);




  crea un nuovo segnale. I parametri sono:


  o  name: Il nome del segnale.

  o  run_type: Se il segstore predefinito viene eseguito prima o dopo di
     quello dell'utente. Di norma questo sara GTK_RUN_FIRST, o
     GTK_RUN_LAST, anche se ci sono altre possibilita.

  o  object_type: l'identificativo dell'oggetto a cui questo segnale si
     riferisce. Esso sara anche applicato agli oggetti discendenti.

  o  function_offset: L'offset nella struttura della classe di un
     puntatore al gestore predefinito.
  o  marshaller: una funzione che e 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 gtk_signal_default_marshaller

  o  return_val: Il tipo del valore di ritorno.

  o  nparams: Il numero di parametri del gestore di segnali (oltre ai
     due predefiniti menzionati sopra)

  o  ...: i tipi dei parametri

  Quando si specificano i tipi, si usa l'enumerazione GtkType:



       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;





  gtk_signal_new() restituisce un identificatore unico intero per il
  segnale, che memorizziamo nel vettore  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 TICTACTOE(), quindi
  l'abbiamo chiamato  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 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.




  19.3.6.  La funzione _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.




       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]);
             }
       }





  19.3.7.  E il resto...


  C'e 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 e
  convenzionalmente chiamata 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.


  tictactoe_clear() e una funzione pubblica che resetta tutti i bottoni,
  nel widget, allo stato iniziale (non premuto). Notate l'uso di
  gtk_signal_handler_block_by_data() per impedire che il nostro gestore
  dei segnali venga attivato quando non ce n'e bisogno.


  tictactoe_toggle() e il gestore del segnale che viene invocato quando
  l'utente preme il bottone. Esso guarda se vi e qualche combinazione
  vincente che coinvolge i bottoni premuti, e nel caso ci fosse, emette
  il segnale ``tictactoe''.





  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;
          }
      }
  }






  E finalmente un programma di esempio che usa il nostro widget
  Tictactoe:


       #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;
       }





  19.4.  Creare un widget a partire da zero

  19.4.1.  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 puo
  trascinare per assegnare il valore.


  19.4.2.  Mostrare un widget sullo schermo

  Ci sono alcuni passi che sono necessari nella visualizzazione sullo
  schermo. Dopo che il widget e stato creato con una chiamata a
  WIDGETNAME_new(), sono necessarie alcune altre funzioni:


  o  WIDGETNAME_realize() e responsabile della creazione di una finestra
     X per il widget se ne ha una.

  o  WIDGETNAME_map() e invocata dopo che l'utente ha chiamato
     gtk_widget_show(). E' responsabile di vedere se il widget e
     attualmente disegnato sullo schermo (mappato). Per una classe
     contenitore, essa deve anche creare chiamate alle funzioni  map()>
     per ogni widget figlio.

  o  WIDGETNAME_draw() e invocata quando gtk_widget_draw() viene
     chiamata per il widget o per uno dei suoi predecessori. Esso fa si
     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 gtk_widget_draw()
     di ogni suo widget figlio.

  o  WIDGETNAME_expose() e 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 e 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, sara X che generera i necessari
     eventi di expose).


  Potete notare che le ultime due funzioni sono molto simili, ognuna e
  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 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 puo ridisegnare solo la finestra interessata, cosa che non e
  possibile per chiamate a draw().


  I widget contenitori, anche se essi non farebbero differenze, non
  possono semplicemente usare la funzione draw() perche per i loro
  widget figli la differenza potrebbere essere importante. Comunque,
  sarebbe uno spreco duplicare il codice di disegno nelle due funzioni.
  La convenzione e che questi widget abbiano una funzione chiamata
  WIDGETNAME_paint() che disegna il widget, che e poi chiamata dalle
  funzioni draw() e 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 draw() e implementare solamente la funzione
  expose().


  19.4.3.  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. Cosi, anche se questa sezione e intitolata
  ``Creare un widget a partire da zero", il nostro widget inizia in
  realta con il codice sorgente del widget Range. Questo e stato preso
  come punto d'inizio perche' sarebbe carino se il nostro widget avesse
  la stessa interfaccia del widget Scale il quale e semplicemente una
  specializzazione del widget Range. Cosi, 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
  familiarita 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.


  19.4.4.  Le basi

  Una parte del nostro widget potrebbe essere simile al widget
  Tictactoe. In primo luogo, abbiamo il file header:



























































  /* 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 cosi 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__ */




  Essendoci piu cose da fare con questo widget, rispetto al precedente,
  abbiamo piu 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.
































  #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);
  }




  Notate che questa funzione init() fa meno rispetto all'analoga del
  widget Tictactoe, essendo questo un widget non composto, e la funzione
  new() fa di piu, 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 piu) cosi che GTK puo tener traccia di quando e
  possibile distruggerlo senza causare guai.


  Inoltre, ci sono alcune funzioni per manipolare le opzioni del widget:








  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);
  }





  19.4.5.  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 gdk_window_new() una maschera che specifica
  quali campi della struttura GdkWindowAttr non sono vuoti (ai rimanenti
  campi puo essere dato il valore predefinito). Anche il modo con cui la
  maschera degli eventi del widget  creata non e complicato. Chiameremo
  gtk_widget_get_events() per sapere la maschera degli eventi che
  l'utente ha specificato per questo widget (con
  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.



       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);
       }





  19.4.6.  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 e fatta dalla
  funzione  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.



       static void
       gtk_dial_size_request (GtkWidget      *widget,
                              GtkRequisition *requisition)
       {
         requisition->width = DIAL_DEFAULT_SIZE;
         requisition->height = DIAL_DEFAULT_SIZE;
       }

  Dopo che tutti i widget hanno restituito una dimensione ideale, viene
  calcolata la disposizione della finestra  e ad ogni widget figlio e
  notificata la propria dimensione attuale . Usualmente, questo sara
  almeno quanto richiesto, ma occasionalmente puo essere piu piccolo.
  La notifica della dimensione  viene fatta dalla funzione
  gtk_dial_size_allocate(). Notate che questa funzione e utilizzata
  anche quando la finestra X del widget e spostata o modificata come
  dimensione.



       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;
           }
       }



  .


  19.4.7.  gtk_dial_expose()

  Come menzionato sopra, tutto il lavoro di questo widget viene fatto
  nella gestione dell'evento ``expose''. Non c'e molto da notare su
  questo eccetto l'uso della funzione gtk_draw_polygon per disegnare il
  puntatore con un'ombreggiatura a tre dimensioni in accordo con il
  colore memorizzato nello stile del wiget.



















  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;
  }





  19.4.8.  Gestione degli eventi


  Il resto del codice del widget manipola vari tipi di eventi, e non e
  differente da quello che puo essere trovato in molte applicazione GTK.
  Due tipi di eventi possono verificarsi: l'utente puo clickare sul
  widget con il mouse e trascinare per muovere il puntatore, o il valore
  dell'oggetto Adjustmente puo 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 cosi, memorizziamo il bottone
  premuto dall'utente con il campo button della struttura del widget, e
  prendiamo tutti gli eventi del mouse con una chiamata alla funzione
  gtk_grab_add(). Successivi movimenti del mouse causano il ricalcolo
  dei valori di controllo (fatto dalla funzione gtk_dial_update_mouse).
  Dipendentemente dalla politica che abbiamo stabilito, gli eventi
  ``value_changed'' possono essere  generati istantaneamente
  (GTK_UPDATE_CONTINUOUS), dopo un certo tempo aggiunto con la funzione
  gtk_timeout_add() (GTK_UPDATE_DELAYED), o solamente quando il bottone
  del mouse e' rilasciato (GTK_UPDATE_DISCONTINUOUS).





































  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);
              }
          }
      }
  }





  Cambiamenti esterni all'Adjustment sono comunicati al nostro widget
  dai segnali ``changed'' e ``value_changed''. Il gestore per queste
  funzioni chiama  gtk_dial_update() per validare gli argomenti,
  calcolare il nuovo angolo del puntatore e ridisegnare il widget
  (chiamando gtk_widget_draw()).









  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;
      }
  }





  19.4.9.  Possibili Miglioramenti


  Il widget Dial, da come l'abbiamo costruito, e 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 e costituita da file header e
  commmenti. Comunque ci sono alcuni miglioramenti che potrebbero essere
  fatti a questo widget:


  o  Se tu provate questo widget, troverete che ci sono alcuni
     lampeggiamenti quando il puntatore viene trascinato in giro. Questo
     perche l'intero widget e cancellato ogni volta che il puntatore
     viene mosso, prima di essere ridisegnato. Spesso, il modo migliore
     per gestire questo tipo di problema e 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).

  o  L'utente potrebbe essere abilitato ad usare le frecce su e giu per
     incrementare e diminuire il valore.

  o  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 si 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 puo essere
     trovato nel widget GtkRange.

  o  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.


  19.5.  Impararne di piu


  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 e lo stesso codice sorgente GTK.
  Chiedete a voi stessi alcune cose su come deve essere il widget che
  volete scrivere: e un widget contenitore? dovra avere una propria
  finestra? e una modifica di un widget precedente? Trovate poi un
  widget simile e iniziate a fargli delle modifiche.  Buone Fortuna.


  20.  Scribble, Un semplice esempio di Programma di Disegno

  20.1.  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.


  20.2.  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 menu.
  Pero, a volte e utile sapere qualcosa su cose che si svolgono a
  livello piu 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 piu, che e 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 e fatta (in parte) cosi:



       struct _GdkEventMotion
       {
         GdkEventType type;
         GdkWindow *window;
         guint32 time;
         gdouble x;
         gdouble y;
         ...
         guint state;
         ...
       };




  type avra il valore del tipo di evento, in questo caso
  GDK_MOTION_NOTIFY, window rappresenta la finestra in cui l'evento si e
  verificato. x e y forniscono le coordinate dell'evento e state
  specifica lo stato dei modificatori nel momento in cui l'evento si e
  verificato (cioe, specifica quali tasti modificatori e tasti del mouse
  erano premuti in quel momento). E' un OR bit per bit dei seguenti
  valori:



       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





  Come succede per gli altri segnali, per determinare cosa deve accadere
  in corrispondenza di un evento, si chiama gtk_signal_connect(). Ma e
  anche necessario far si che GTK sappia di quali eventi vogliamo essere
  informati. A questo fine, chiamiamo la funzione:



       void  gtk_widget_set_events (GtkWidget *widget, gint events);




  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 e la seguente:



       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




  Per chiamare 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, cio
  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:



       GtkAlignment
       GtkArrow
       GtkBin
       GtkBox
       GtkImage
       GtkItem
       GtkLabel
       GtkPixmap
       GtkScrolledWindow
       GtkSeparator
       GtkTable
       GtkAspectFrame
       GtkFrame
       GtkVBox
       GtkHBox
       GtkVSeparator
       GtkHSeparator

  Per catturare degli eventi per questo tipo di widget, si deve fare uso
  del widget EventBox. Si veda a questo proposito la sezione su ``The
  EventBox Widget''.


  Per il nostro programma di disegno, vogliamo sapere quando il pulsante
  del mouse e premuto e quando viene mosso, quindi specificheremo
  GDK_POINTER_MOTION_MASK e GDK_BUTTON_PRESS_MASK. Vogliamo anche essere
  informati su quando e necessario ridisegnare la nostra finestra,
  quindi specifichiamo GDK_EXPOSURE_MASK. Anche se vogliamo essere
  avvertiti con un evento ``Configure'' se la dimensione della nostra
  finestra cambia, non e necessario specificare il flag
  GDK_STRUCTURE_MASK, dal momento che questo viene specificato
  automaticamente per tutte le finestre.


  Risulta, conunque, che specificando semplicemente
  GDK_POINTER_MOTION_MASK si crea un problema. Cio infatti fa si 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 e di specificare GDK_POINTER_MOTION_HINT_MASK.


  Quando specifichiamo 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 finche non richiediamo esplicitamente la posizione
  del puntatore con la funzione:



       GdkWindow*    gdk_window_get_pointer     (GdkWindow       *window,
                                                 gint            *x,
                                                 gint            *y,
                                                 GdkModifierType *mask);




  (c'e anche un'altra funzione, gtk_widget_get_pointer(), che ha
  un'interfaccia piu 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,
  avra l'aspetto:












    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);




  Teniamo per dopo i gestori di  ``expose_event'' e
  ``configure_event''. Quelli di ``motion_notify_event'' e
  ``button_press_event'' sono piuttosto semplici:



       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;
       }





  20.3.  Il widget Area di Disegno (DrawingArea) e il procedimento per
  Disegnare

  Vediamo ora il procedimento per disegnare sullo schermo. Il widget da
  usare e 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:
       GtkWidget* gtk_drawing_area_new        (void);




  Per specificare una dimensione predefinita, si puo fare:



       void       gtk_drawing_area_size       (GtkDrawingArea      *darea,
                                               gint                 width,
                                               gint                 height);




  Come e vero per tutti i widget, si puo modificare questa dimensione
  predefinita, tramite la chamata a gtk_widget_set_usize(), e questa a
  sua volta puo 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 cio che era stato precedente nascosto.


  Dover ricordare tutto quello che era disegnato sulla finestra in modo
  da poterlo ridisegnare successivamente, puo essere, come minimo,
  noioso.  In piu, puo 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 e 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:



       GdkPixmap* gdk_pixmap_new               (GdkWindow  *window,
                                                gint        width,
                                                gint        height,
                                                gint        depth);




  Il parametro windowspecifica una finestra GDK dalla quale questa
  pixmap prende alcune delle sue proprieta. width e height specificano
  le dimensioni della pixmap.  depth specifica la profondita di colore,
  cioe il numero di bit per ogni pixel, per la nuova pixmap. Se alla
  profondita e assegnato il valore -1, questa verra posta identica a
  quella di window.


  Creiamo la pixmap all'interno del gestore di ``configure_event''.
  Questo evento e generato ogni volta che la finestra cambia di
  dimensione, compreso il momento in cui viene creata per la prima
  volta.

       /* 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;
       }




  La chiamata a gdk_draw_rectangle() 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 e l'area da
  ridisegnare usando il campo event->area dell'evento di esposizione):



       /* 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;
       }




  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 e semplicemente qualcosa su cui si puo disegnare
  un'immagine.  Puo essere una finestra, una pixmap o una bitmap
  (un'immagine in bianco e nero). Abbiamo gia visto sopra due di
  chiamate, gdk_draw_rectangle() and gdk_draw_pixmap(). La lista
  completa e la seguente:


       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 ()




  Per ulteriori dettagli su queste funzioni, vedete la documentazione di
  riferimento nei file header <gdk/gdk.h>.  Tutte queste funzioni hanno
  i medesimi primi due argomenti. Il primo e la superficie disegnabili
  su cui disegnare, il secondo e 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 puo
  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:



       widget->style->white_gc
       widget->style->black_gc
       widget->style->fg_gc[GTK_STATE_NORMAL]
       widget->style->bg_gc[GTK_WIDGET_STATE(widget)]




  I campi fg_gc, bg_gc, dark_gc, e light_gc sono indicizzati tramite un
  parametri di tipo GtkStateType, che puo assumere i valori:



       GTK_STATE_NORMAL,
       GTK_STATE_ACTIVE,
       GTK_STATE_PRELIGHT,
       GTK_STATE_SELECTED,
       GTK_STATE_INSENSITIVE




  Per esempio, per  GTK_STATE_SELECTED il colore di sfondo predefinito e
  blu scuro e quello di primo piano bianco.


  La nostra funzione draw_brush(), che efettivamente disegna sullo
  schermo, diventa quindi:






  /* 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);
  }




  Dopo aver disegnato il rettangolo sulla pixmap, chiamiamo la funzione:



       void       gtk_widget_draw                (GtkWidget           *widget,
                                                  GdkRectangle        *area);




  che notifica a X che l'area data dal parametro area deve essere
  aggiornata. X poi generera un evento di esposizione (che puo essere
  combinato con le aree passate da diverse chiamate a gtk_widget_draw())
  che fara si 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 e reperibile dove avete
  ottenuto questo tutorial, oppure da:

  http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial


  20.4.  Aggiungere il supporto per XInput

  Al giorno d'oggi e possibile acquistare dei dispositivi abbastanza a
  buon mercato, come tavolette grafice, che permettono di disegnare con
  una espressivita artistica molto semplificata rispetto ad un mouse.
  Il modo piu semplice per usare questi dispositivi e di sostituirli
  semplicemente al mouse, ma in questo modo si perdono molti dei loro
  vantaggi, come:


  o  Sensibilita alla pressione

  o  Sensibilita all'inclinazione

  o  Posizionamento infra-pixel

  o  Ingressi multipli (per esempio, uno stilo che contiene sia una
     ``matita'' sia una ``gomma'')


  Per ulteriori informazioni sulle estensioni XInput, vedere l'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.



       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;
       };




  pressure fornisce la pressione sotto forma di un numero decimale
  compreso fra 0 e 1. xtilt e ytilt possono assumere valori compresi fra
  -1 e 1, corrispondenti al grado di inclinazione in ciascuna direzione.
  source e deviceid specificano il dispositivo per il quale si e
  verificato l'evento in due modi distinti. source  da alcune semplici
  informazioni sul tipo di dispositivo, e puo assumere i valori:



       GDK_SOURCE_MOUSE
       GDK_SOURCE_PEN
       GDK_SOURCE_ERASER
       GDK_SOURCE_CURSOR




  deviceid specifica invece un identificativo numerico univoco per il
  dispositivo. Questo puo essere a sua volta utilizzato per avere
  ulteriori informazioni sul dispositivo tramite la chiamata a
  gdk_input_list_devices() (vedi sotto). Il valore speciale
  GDK_CORE_POINTER viene usato per identificare il dispositivo di
  puntamento principale (di solito il mouse).


  20.4.1.  Abilitare le informazioni estese

  Per far si che GTK sappia che ci interessano le informazioni estese
  dai dispositivi, basta aggiungere un'unica linea al nostro programma:



       gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR);




  Dando il valore 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 piu sotto alla
  sezione ``Ulteriori Sofisticazioni'' per ulteriori informazioni sul
  modo si disegnare i cursori. Potremmo anche dare i valori
  GDK_EXTENSION_EVENTS_ALL se vogliamo disegnare il nostro cursore o
  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.



       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);
           }
       }




  (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.


  20.4.2.  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 e
  sempre sicuro, perche sono tutti posti per difetto a valori
  ragionevoli ancje quando la gestione degli eventi estesi non e
  abilitata.


  Un cambiamento che dobbiamo fare e di chiamare
  gdk_input_window_get_pointer() invece di gdk_window_get_pointer. Cio
  si rende necessario perche gdk_window_get_pointer non restituisce le
  informazioni esetese.



       void gdk_input_window_get_pointer     (GdkWindow       *window,
                                              guint32         deviceid,
                                              gdouble         *x,
                                              gdouble         *y,
                                              gdouble         *pressure,
                                              gdouble         *xtilt,
                                              gdouble         *ytilt,
                                              GdkModifierType *mask);




  Quando chiamiamo questa funzione, dobbiamo specificare
  l'identificativo del dispositivo e la finestra. Normalmente questo
  identificativo lo si ottiene dal campo deviceid della struttura
  dell'evento.  Questa funzione restituira valori ragionevoli nel caso
  che la gestione degli eventi estesi non sia attivata (in questo caso,
  event->deviceid avra il valore 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.





















  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;
  }




  Avremo anche bisogno di fare qualcosa con queste nuove informazioni.
  La nostra nuova funzione draw_brush disegna con un colore diverso per
  ogni event->source e cambia la dimensione della linea in funzione
  della pressione.
























  /* 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);
  }





  20.4.3.  Trovare ulteriori informazioni su di un dispositivo

  Come esempio del modo di trovare altre informazioni su di un
  dispositivo, il nostro programma stampera il nome di ogni dispositivo
  che genera un evento di pressione di un pulsante. Per avere il nome di
  un dispositivo, chiamiamo la funzione



       GList *gdk_input_list_devices               (void);




  che restituisce una GList (un tipo di lista collegata che si trova
  nella libreria glib) di strutture di tipo GdkDeviceInfo. La
  definizione di GdkDeviceInfo e la seguente:











  struct _GdkDeviceInfo
  {
    guint32 deviceid;
    gchar *name;
    GdkInputSource source;
    GdkInputMode mode;
    gint has_cursor;
    gint num_axes;
    GdkAxisUse *axes;
    gint num_keys;
    GdkDeviceKey *keys;
  };




  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 name, che e semplicemente il nome che X assegna al
  dispositivo, e has_cursor. Anche has_cursor non e informazione di
  configurazione, e indica, nel caso abbia valore ``falso'', che
  dobbiamo disegnare da soli il nostro cursore. Ma dal momento che
  abbiamo specificato GDK_EXTENSION_EVENTS_CURSOR, possiamo anche non
  preoccuparcene.



  La nostra funzione print_button_press() scorre semplicemente la lista
  che e stata restituita finche non trova il valore corretto, e poi
  stampa il nome del dispositivo.



       static void
       print_button_press (guint32 deviceid)
       {
         GList *tmp_list;

         /* gdk_input_list_devices restituisce una lista interna, cosi 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;
           }
       }




  Questo completa i cambiamenti necessari per usare gli XInput nel nos-
  tro programma. Come per la prima versione, i sorgenti completi sono
  prelevabili da dove avete prelevato questo tutorial, oppure da:

  http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial

  20.4.4.  Ulteriori sofisticazioni

  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 fara piacere dover configurare i propri dispositivi ogni volta che
  lanciano il programma, per cui dovremmo dare la possibilita di salvare
  la configurazione dei dispositivi.  Cio puo essere fatto scorrendo la
  lista restituita da 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:



       gdk_input_set_extension_events()
       gdk_input_set_source()
       gdk_input_set_mode()
       gdk_input_set_axes()
       gdk_input_set_key()




  (La lista restituita da gdk_input_list_devices() non dovrebbe essere
  modificata direttamente.) Un esempio di come fare puo essere trovato
  nel programma di disegno gsumi (disponibile da
  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' piu
  elevato ripetto a GTK, forse alla libreria GNOME.


  Un'altra notevole omissione a cui abbiamo accennato precedentemente e
  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  XInput-HOWTO
  <http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html> per
  ulteriori informazioni. Cio significa che le applicazioni che vogliono
  rivolgersi al pubblico piu ampio dovranno prevedere di disegnare esse
  stesse il proprio cursore.


  Un'applicazione che voglia disegnare il proprio cursore dovra fare due
  cose: determinare se il dispositivo corrente necessita che venga
  disegnato un cursore, e determinare se il dispositivo corrente e in
  prossimita. (Se il dispositivo e una tavoletta grafica, un tocco di
  finezza e fare sparire il puntatore quando lo stilo viene sollevato
  dalla tavoletta. Quando c'e contatto fra lo stilo e la tavoletta, si
  dice che il dispositivo e ``in prossimita".) 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.


  21.  Consigli per scrivere Applicazioni GTK


  Questa sezione e semplicemente una raccolta di saggezza, una guida di
  stile e un aiuto per creare buone applicazioni GTK. E' totalmente
  inutile per ora perche e solamente un appunto.
  Usa autoconf e automake! Sono tuoi amici :) Ho intenzione di fare una
  piccola introduzione su di loro qui.


  22.  Contributi

  Questo documento, come molti altri grandi software la fuori, e stato
  creato da volontari. Se sai tutto quello che c'e da sapere su GTK e
  non lo hai trovato qui allora considera la possibilita di contribuire
  a questo documento.


  Se decidi di contribuire, ti prego di trasmettere il tuo lavoro a Tony
  Gale, gale@gtk.org. Inoltre, ricorda  che l'intero documento e
  ``free'', e che ogni tua aggiunta sara 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.


  23.  Credits

  Voglio qui ringraziare le persone che seguono, per il loro contributo
  alla stesura di questo testo.


  o  Bawer Dagdeviren, chamele0n@geocities.com per il tutorial sui menu.

  o  Raph Levien, raph@acm.org 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.

  o  Peter Mattis, petm@xcf.berkeley.edu Per il piu semplice programma
     GTK e l'abilita di farlo. :)

  o  Werner Koch werner.koch@guug.de per la conversione da testo
     semplice a SGML e la gerarchia delle classi di widget.

  o  Mark Crichton crichton@expert.cc.purdue.edu per il codice della
     "MenuFactory" e per la parte sull'impacchettamento nelle tabelle
     del tutorial.

  o  Owen Taylor mailto:owt1@cornell.edu per la sezione del  widget
     EventBox (e il patch alla distribuzione). Lui e 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.

  o  Mark VanderBoom mailto:mailto:mvboom42@calvin.edu per il suo
     meraviglioso lavoro sul Notebook, Progres Bar, Dialogs e File
     selection. Grazie molto Mark. Sei stato di grande aiuto.

  o  Tim Janik mailto:timj@gtk.org per il suo grande lavoro sul widget
     List.  Grazie Tim :)

  o  Michael K. Johnson johnsonm@redhat.com  per le informazioni e il
     codice dei menu a comparsa.

  E a tutti voi che avete fatto commenti e avete aiutato a raffinare
  questo documento.



  Thanks.


  24.  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 e 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 cerchera di
  mettere a disposizione le informazioni piu aggiornate.

  Non c'e 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.






























































