XFORMS (FORM LIBRARY)

Toolkit per la costruzione di interfacce grafiche (GUI) nel sistema 
X Window.

Principali vantaggi:
- Software di pubblico dominio, disponibile su diverse piattaforme
- Si basa su libreria Xlib
- Molte funzionalita'
- Semplice e intuitivo
- Comprende un Form Designer per la creazione interattiva di GUI

A differenza di altri toolkit (per es. Motif), nasconde completamente
X al programmatore: non e' necessario conoscere X per programmare in
XForms.

   +---------------+         +---------------+
   |Applicazione   |         |Applicazione   |
   +----------+--+-+         +---------------+
   |Motif     |  | |         |               |
   +----------+  | |         |XForms         |
   |Xt intrinsics| |         |               |
   +-------------+ |         +---------------+
   |Xlib           |         |Xlib           |
   +---------------+         +---------------+ 

Concetti base (Terminologia):

- Una form e' una finestra-contenitore in cui sono sistemati vari oggetti; 
  una form e' una finestra X situata a top-level, e gestita dal window
  manager

- Gli oggetti sono elementi di interfaccia contenuti in una form,
  attraverso i quali si svolge l'interazione tra utente e applicazione;
  es: bottoni, campi di inserimento, ecc.
  un oggetto e' una sotto-finestra X, avente un certo aspetto distintivo
  e certe capacita' di interazione (sensibile a certi eventi)

XForms non adopera il termine "widget".

OGGETTI

Oggetti statici (non hanno capacita' di interazione, servono solo per
visualizzare)

- Box: area rettangolare contenente testo
- Frame: cornice racchiudente area rettangolare (puo' racchiudere altri
  oggetti
- Text: testo alfanumerico
- Bitmap: immagine raster B/N (matrice di bit)
- Pixmap: immagine raster a colori o a livelli di grigio
- Clock: orologio analogico o digitale
- Chart: area rettangolare destinata a contenere grafici a linea, a barre,
  a torta, ecc.

Bottoni (interazione col mouse tramite click)

- Button: varie classi e tipi di bottoni (ved. piu' avanti)

Quantificatori (interazione col mouse mediante click o trascinamento,
permettono di introdurre un valore numerico)

- Slider: vari tipi di potenziometri lineari
- Dial: vari tipi di potenziometri rotanti
- Counter: potenziometro digitale
- Positioner: fornisce non un singolo valore, ma una coppia di coordinate
  (x,y) in un'area rettangolare indicata

Campi di input (attivazione col mouse, input da tastiera)

- Input: campo di una o piu' linee contenente un cursore

Selezionatori (interazione col mouse tramite click, permettono di immettere
una scelta tra un insieme predefinito)

- Menu: diversi tipi di menu' (push, pulldown, touch)
- Choice: stessa funzione dei menu', ma ha un unico bottone che mostra
  in ogni momento la scelta corrente, la scelta corrente puo' essere 
  cambiata ciclando sull'insieme delle scelte possibili
- Browser: si una per lunghe liste di scelte, permette di muoversi
  attraverso la lista e selezionare elementi attraverso un cursore
  (scrollbar)

Inoltre:

- Timer: contatore alla rovescia
- XYPlot: consente di disegnare e modificare agevolmente funzioni
- Canvas: sottofinestra utilizzabile per output grafico; in un canvas
  posso utilizzare X direttamente, scavalcando XForms; in particolare,
  posso usare altri pacchetti grafici operanti sotto X.
  Noi useremo un canvas per fare grafica in OpenGL.

STRUTTURA DI UN PROGRAMMA IN XFORMS

Un programma applicativo che utilizza XForms deve contenere le seguenti
parti:

-A- Inizializzazione: stabilisce connessione tra programma e X-server,
  e inizializza strutture interne di XForms
-B- Definizione delle (una o piu') form necessarie al programma,
    con tutti i loro oggetti
-C- Visualizzazione delle form per rendere visibile la GUI
-D- Interazione (main loop): gestione dell'interazione con l'utente
  e delle operazioni che il programma deve compiere di conseguenza

INTERAZIONE CON L'UTENTE: PRINCIPIO DI FUNZIONAMENTO (ci torneremo)

- utente interagisce con gli oggetti generando evevnti
- XForms pesca gli eventi dalla coda di X e li associa agli oggetti
- a questo punto deve essere chiamato il codice applicativo che
  gestisce l'evento; vi sono due vie possibili:
  1) il programmatore definisce (nella fase -B-) callback associate a ogni 
  oggetto, e demanda a XForms il compito di chiamare la callback opportuna
  in risposta all'evento
  2) in assenza di callback, XForms passa il controllo al programma,
  che dovra' guardare di che evento ed oggetto si tratta, e agire di
  conseguenza
- il controllo passa quindi alle procedure applicative (siano esse callback
  o no) per il tempo necessario a compiere tali operazioni
- quindi XForms riprende il controllo per gestire gli eventi successivi

Nota: XForms si pone sempre come "cuscinetto" tra applicazione e Xlib,
Xlib rimane trasparente al programmatore.

Vediamo le funzioni di XForms relative alle 4 fasi.

INIZIALIZZAZIONE

fl_initialize ( &argc, argv, <titolo>, 0, 0);

argc, argv = argomenti passati al main da command line
<titolo> = titolo dell'applicazione (char *)

DEFINIZIONE DELLE FORMS

FL_FORM * fl_bgn_form(<tipo>, w, h);

<tipo> = tipo di form (costante simbolica)
w, h = larghezza e altezza (in pixel)

FL_OBJECT * fl_add_XXXX(....);

XXXX = tipo di oggetto che aggiungo alla form
.... = parametri per definire l'oggetto

void fl_end_form();

Tra fl_bgn_form e fl_end_form trovano posto le definizioni di tutti
gli oggetti contenuti nella form (mediante fl_add_XXXX).

VISUALIZZAZIONE DELLE FORM

fl_show_form(<form>, <place>, <border>, <titolo>);

<form> = la form da visualizzare (FL_FORM * ritornato da fl_bgn_form
         quando ho definito la form)
<place> = indica come deve essere posizionata di preferenza la form 
         (costante simbolica)
<border> = indica che tipo di bordo deve essere aggiunto di preferenza
         alla form (costante simbolica)

fl_hide_form(<form>);

MAIN LOOP

FL_OBJECT * fl_do_forms();

Attende che un evento accada in qualche oggetto.
In assenza di callback, non appena accade un evento esce e ritorna
l'oggetto in cui l'evento e' accaduto. Il programma poi agira' di
conseguenza.
Se invece ho definito una callback per l'oggetto in cui l'evento si
e' verificato, la callback e' eseguita automaticamente, senza che
si esca dal ciclo.

ESEMPIO DI PROGRAMMA SENZA CALLBACK (ved. file yesno.c)

Crea una form con un titolo testuale "Do you want to quit?" e due 
bottoni "Yes" e "No".
Visualizza la form, poi chiama fl_do_forms(). Quando uno dei due
bottoni viene premuto, fl_do_forms() esce e lo ritorna. Se il
bottone premuto e' "Yes", il programma esce, altrimenti chiama
nuovamente fl_do_forms(), e cosi' via.

#include "forms.h"

FL_FORM *form;
FL_OBJECT *yes, *no, *but;

main (int argc, char *argv[])
{
  /*** Inizializzazione ***/
  fl_initialize ( &argc, argv, "FormDemo", 0, 0);
  /*** Definizione forms ***/
  form = fl_bgn_form(FL_UP_BOX, 320, 120);
  /* crea form con aspetto di box tridimensionale sporgente da schermo,
     larga 320 pixel e alta 120 */
  fl_add_box(FL_NO_BOX, 160, 40, 0, 0, "Do you want to quit?");
  /* aggiunge alla form che sto definendo un box contenente la
     scritta "Do you want to quit?" */
  yes = fl_add_button(FL_NORMAL_BUTTON, 40, 70, 80, 30, "Yes");
  /* aggiunge alla form un bottone di etichetta "Yes", posizionato con 
     l'angolo in alto a sinistra nel punto 40,70 della form, largo 80 
     pixel e alto 30 */
  no = fl_add_button(FL_NORMAL_BUTTON, 200, 70, 80, 30, "No");
  /* analogo per bottone "No" */
  fl_end_form();
  /*** Visualizzazione forms ***/
  fl_show_form(form, FL_PLACE_MOUSE,FL_TRANSIENT,"Question");
  /* FL_TRANSIENT causa un tipo di bordo adatto a finestre che
     devono stare visualizzate per poco tempo */
  /*** Main loop ***/
  while ( (but = fl_do_forms()) != yes ) ;
  /* fintanto che il bottone cliccato non e' yes, continua a ciclare */
  /*** Terminazione ***/
  fl_hide_form(form);
  return 0;
}

INTERAZIONE

La procedura   FL_OBJECT * fl_do_forms()
gestisce l'interazione con l'utente nel seguente modo:

-1- tiene il controllo da quando viene invocata a quando si verifica un evento
  proveniente da un oggetto usato nel programma

-2a- a tale oggetto il programmatore potrebbe aver associato una callback,
  nel qual caso fl_do_forms() chiama automaticamente la callback, e 
  al termine della callback riprende il controllo
  
-2b- se l'oggetto in cui si e' verificato l'evento non ha una callback
  associata, allora fl_do_forms() esce, restituendo l'oggetto, e il
  controllo passa al programma

Una callback e' una procedura del programma applicativo che viene
associata a un oggetto in fase di definizione e che viene eseguita ogni
volta che tale oggetto genera un evento.

Una procedura di callback accetta due parametri (che vengono passati
automaticamente da XForms):
- un oggetto (tipo FL_OBJECT *) ---> quello che ha generato l'evento
- un intero (tipo long) ---> deciso dal programmatore quando ha associato
  la callback all'oggetto, e' usato come switch per poter adoperare la
  stessa callback per diversi eventi

La procedura callback (nel caso -2a-) o il programma (nel caso -2b-) deve
interpretare l'evento che si e' verificato interrogando l'oggetto che lo
ha prodotto con apposite procedure, in modo da poter decidere che cosa
fare.

Nota: un oggetto ha una sola callback per tutti gli eventi a cui e'
sensibile, il tipo di evento lo devo determinare io interrogando l'oggetto.

STESSO ESEMPIO DI PRIMA RISCRITTO USANDO CALLBACK (ved. file yncallbk.c)

#include "forms.h"

FL_FORM *form;

void yes_callback(FL_OBJECT *ob, long user_data)
{
  printf("Yes is pushed\n");
  fl_finish();
  exit(0);
}

void no_callback(FL_OBJECT *ob, long user_data)
{
  printf("No is pushed\n");
}

main (int argc, char *argv[])
{
  FL_OBJECT *obj;
  /*** Inizializzazione ***/
  fl_initialize ( &argc, argv, "FormDemo", 0, 0);
  /*** Definizione forms ***/
  form = fl_bgn_form(FL_UP_BOX, 320, 120);
  /* crea form con aspetto di box tridimensionale sporgente da schermo,
     larga 320 pixel e alta 120 */
  fl_add_box(FL_NO_BOX, 160, 40, 0, 0, "Do you want to quit?");
  /* aggiunge alla form che sto definendo un box contenente la
     scritta "Do you want to quit?" */
  obj = fl_add_button(FL_NORMAL_BUTTON, 40, 70, 80, 30, "Yes");
  /* aggiunge alla form un bottone di etichetta "Yes", posizionato con 
     l'angolo in alto a sinistra nel punto 40,70 della form, largo 80 
     pixel e alto 30 */
  fl_set_object_callback(obj, yes_callback, 0);
  /* assegna al bottone "Yes" la callback */
  obj = fl_add_button(FL_NORMAL_BUTTON, 200, 70, 80, 30, "No");
  fl_set_object_callback(obj, no_callback, 0);
  /* analogo per bottone "No" */
  fl_end_form();
  /*** Visualizzazione forms ***/
  fl_show_form(form, FL_PLACE_MOUSE,FL_TRANSIENT,"Question");
  /* FL_TRANSIENT causa un tipo di bordo adatto a finestre che
     devono stare visualizzate per poco tempo */
  /*** Main loop ***/
  fl_do_forms();
  /* poiche' ogni oggetto capace di catturare eventi ha una callback,
     fl_do_forms() non esce mai, la terminazione del programma avviene
     dentro la callback di "Yes" */
}

SCHEMI DI PROGRAMMA NELLE DUE MODALITA' DI GESTIONE DELL'INTERAZIONE

Interazione semplice:

<inizializzazione>
<definizione forms>
<visualizzazione forms>
while (!ready)
{
  obj = fl_do_forms();
  <gestione evento generato da obj>
}

Interazione con callback:

<inizializzazione>
<definizione forms e associazione callback ai loro oggetti>
<visualizzazione forms>
fl_do_forms();

ESEMPIO DI INTERAZIONE SEMPLICE (ved. file demo05.c)

Visualizza una form contenente uno slider, un box la cui etichetta mostra 
il valore corrente dello slider (aggiornato da programma ogni volta che
l'utente interagisce con lo slider), e un bottone "Exit".

#include <stdio.h>
#include "forms.h"

int
main(int argc, char *argv[])
{
  FL_FORM *form;
  FL_OBJECT *retobj, *slider, *button, *value;
  char str[30];

  fl_initialize(&argc, argv, "FormDemo", 0, 0);
  form = fl_bgn_form(FL_UP_BOX,240,400);
  /* aggiunge slider alla form corrente */
     slider = fl_add_slider(FL_VERT_SLIDER,40,40,60,320,"");
  /* assegna valori limite dello slider */
     fl_set_slider_bounds(slider,-1,1);
  /* assegna valore iniziale dello slider */
     fl_set_slider_value(slider,0);
  /* assegna attributo colore del cursore */
     fl_set_object_color(slider,FL_SLIDER_COL1,FL_GREEN);
  /* aggiunge box, per ora con etichetta nulla */
     value = fl_add_box(FL_DOWN_BOX,120,180,100,30,"");
  /* assegna attributo allineamento della label del box */
     fl_set_object_lalign(value,FL_ALIGN_CENTER);
  /* aggiunge bottone "Exit" */
     button = fl_add_button(FL_RETURN_BUTTON,120,290,100,30,"Exit");
  fl_end_form();

  fl_show_form(form,FL_PLACE_CENTER,FL_NOBORDER,"Slider");
  do
  {
    sprintf(str,"%f",fl_get_slider_value(slider));
    fl_set_object_label(value,str);
    retobj = fl_do_forms();
  } while (retobj != button);
  fl_hide_form(form);
  return 0;
}

TIPI DI FORMS (per fl_bgn_form)

FL_UP_BOX
FL_DOWN_BOX
FL_BORDER_BOX
FL_FLAT_BOX ...

POSIZIONI DI UNA FORM (per fl_show_form)

FL_PLACE_FREE
FL_PLACE_MOUSE
FL_PLACE_FULLSCREEEN
FL_PLACE_ICONIC ...

AGGIUNGERE OGGETTI DENTRO UNA FORM

Box

FL_OBJECT * fl_add_box(<tipo>, x,y, w,h, <label>);

<tipo> = tipo di box (FL_UP_BOX, FL_DOWN_BOX, FL_FLAT_BOX, FL_SHADOW_BOX,
         e altri ...)
x,y = posizione all'interno della form in cui lo sto aggiungento 
      dell'angolo in alto a sinistra del box
w,h = larghezza e altezza
<label> = etichetta da mostrare al centro del box (char *)

Frame ("cornice", come box ma vuoto)

FL_OBJECT * fl_add_frame(<tipo>, x,y, w,h, <label>);

<tipo> = tipo di frame (FL_NO_FRAME, FL_UP_FRAME, FL_DOWN_FRAME, 
         FL_BORDER_FRAME, FL_ENGRAVED_FRAME, ed altri ...)
altri paramatri come sopra

Text

FL_OBJECT * fl_add_text(<tipo>, x,y, w,h, <label>);

<tipo> = sempre FL_NORMAL_TEXT
x,y,w,h = specificano un bounding box all'interno del quale la stringa
          viene posizionata allineata a sinistra
<label> = stringa da visualizzare

BOTTONI

Si differenziano per forma e comportamento.
forma ----> classe di bottone, ogni classe ha una diversa funzione
            fl_add_XXXXbutton, dove XXXX e' il nome della classe
tipo -----> argomento passato a fl_add_XXXXbutton

FL_OBJECT * fl_add_XXXXbutton(<tipo>, x,y, w,h, <label>);

parametri col solito significato

Classi di bottoni:

button
roundbutton
checkbutton
lightbutton
...

Tipi di bottoni (alcuni):

FL_NORMAL_BUTTON
FL_PUSH_BUTTON -- resta schiacciato finche' non clicco di nuovo
FL_RETURN_BUTTON -- mostra freccetta accanto all'etichetta
FL_INOUT_BUTTON -- ritorna valore sia quando premuto che quando rilasciato
...

FUNZIONI PER CONTROLLO DEI BOTTONI

int fl_get_button(FL_OBJECT *); ritorna se bottone e' premuto o no

int fl_get_button_numb(FL_OBJECT *); ritorna il tasto del mouse
    con cui ho premuto il bottone (1,2, o 3)

int fl_set_button(FL_OBJECT *, int); cambia lo stato di un bottone,
    argomento = 1 (premuto) o = 0 (rilasciato)

void fl_set_button_shortcut(FL_OBJECT *, char *, int);
    Assegna un insieme di tasti della tastiera come "scorciatoia" per
    attivare il bottone in alternativa ad usare il mouse
    char * --> stringa contenente i tasti scorciatoia (es. "qQ" per tasto
               quit, posso usare "^q" per control+q e "#q" per alt+q
    int --> flag se vogli che i caratteri scorciatioia appaiano 
            sottolineati nell'etichetta del bottone

CONTROLLO INTERAZIONE CON L'UTENTE 

Per le forms

fl_show_form(FL_FORM *, ...);  fl_hide_form(FL_FORM *);
  mostra / nasconde una form

fl_activate_form(FL_FORM *);  fl_deactivate_form(FL_FORM *);  
  attiva/disattiva la capacita' di interagire con l'utente
  (catturare eventi) di una form

Per gli oggetti

fl_show_object(FL_OBJECT *);  fl_hide_object(FL_OBJECT *);
fl_activate_object(FL_OBJECT *);  fl_deactivate_object(FL_OBJECT *); 
  analogo

Disattivare un oggetto e' utile per esempio per bottoni corrispondenti 
ad opzioni non valide (non selezionabili) nello stato attuale.

GRUPPI DI OGGETTI

FL_OBJECT * fl_bgn_group(FL_OBJECT *);
FL_OBJECT * fl_end_group(FL_OBJECT *);

Delimitano la definizione di oggetti che sono visti come un unico 
oggetto. Per esempio, posso assegnare attributi, attivare/disattivare, 
nascondere/mostrare tutto il gruppo in una istruzione sola.

E' vietato annidare le definizioni di gruppi.

Esiste un tipo di bottone, FL_RADIO_BUTTON, dove la pressione di un
bottone del gruppo provoca automaticamente il rilascio di tutti gli
altri bottoni del gruppo. Gruppi di bottoni FL_RADIO_BUTTON servono a
implementare scelte mutuamente esclusive.

AGGIUNGERE UN OGGETTO A UNA FORM O A UN GRUPPO GIA' DEFINITI

fl_addto_form(FL_FORM *);
fl_addto_group(FL_OBJECT *); l'argomento e' il gruppo a cui voglio
                             aggiungere l'oggetto

CANCELLARE UN OGGETTO

fl_delete_object(FL_OBJECT *); lo cancella dalla form che lo contiene
fl_free_object(FL_OBJECT *); ne libera la memoria

Vanno chiamate in questa sequenza.

AGGIUNGERE CALLBACK

Ogni oggetto e' sensibile a certi eventi predefiniti, dipendenti dal
tipo di oggetto. 
Se esiste una callback associata a un oggetto, essa viene 
automaticamente chiamata, all'interno di fl_do_forms, ogni volta che
l'evento prestabilito accade nell'oggetto.
Altrimenti, quando l'evento accade, fl_do_forms esce e ritorna 
l'oggetto: stara' al programma decidere che cosa fare.

fl_set_object_callback(FL_OBJECT *, <funzione>, <argomento>);

<funzione> e' del tipo f(FL_OBJECT *, long);
<argomento> e' un long

Quando la callback e' chiamata, le vengono passati in argomento
l'oggetto dove l'evento e' accaduto e il valore dell'<argomento>
che ho specificato al momento di associare la callback all'oggetto.

La callback di un oggetto puo' essere cambiata in qualsiasi momento.

fl_call_object_callback(FL_OBJECT *);
  mi permette di invocare "artificialmente" la callback di un oggetto
  da programma, senza che nessun evento accada.

ATTRIBUTI DEGLI OGGETTI (NE VEDIAMO ALCUNI)

fl_set_object_color(FL_OBJECT *, int, int);

i due argomenti interi sono due colori (indici in una color map)
che controllano i colori dell'oggetto, in un modo che dipende dal tipo
di oggetto. Es, per un bottone sono il colore del bottone quando 
e' premuto e quando e' rilasciato.

Per i colori esistono simboli predefiniti: FL_BLACK, FL_RED, ....

fl_set_object_geometry(FL_OBJECT *, x,y, w,h)

x,y,w,h = coordinate in pixel dell'angolo in alto a sinistra, 
          larghezza e altezza del box.
Posso anche cambiare solo la posizione o solo le dimensioni con
fl_set_object_position e fl_set_object_size

fl_set_object_lcol   ---> cambia colore dell'etichetta
fl_set_object_label  ---> cambia l'etichetta
fl_set_object_lsize  ---> cambia la dimensione del carattere
fl_set_object_lstyle ---> cambia lo stile (bold,italic,...)
fl_set_object_lalign ---> cambia l'allineamento

ESEMPIO DI INTERAZIONE CON CALLBACK (ved. file demo09.c)

Visualizza una form con un bottone in alto, etichettato "The Color Map",
e 64 bottoni ognuno di un colore diverso.
Cliccare uno dei 64 bottoni provoca il cambiamento di colore del bottone
in alto, che diventa uguale a quello del colore selezionato.
Cliccare il bottone in alto provoca l'uscita dal programma.

I 64 bottoni condividono la stessa callback, ma con un diverso valore
come secondo argomento (quelle di tipo "long") che e' uguale al colore
del bottone, e che viene usato all'interno della callback per cambiare 
il colore del bottone in alto.

Il bottone in alto non ha callback, cosi' che cliccare su di esso provoca
l'uscita da fl_do_forms().

#include <stdio.h>
#include "forms.h"

FL_FORM *form;
FL_OBJECT *topbox;

void change_color(FL_OBJECT *ob, long col)
{  fl_set_object_color(topbox, col, col);  }

void makeform(void)
{
  FL_OBJECT *obj;
  int i,j;
  char str[100];
  form = fl_bgn_form(FL_UP_BOX,400,400);
    for (i=0; i<8; i++) for (j=0; j<8; j++)
    {
      sprintf(str,"%d",8*j+i);
      obj = fl_add_button(FL_RADIO_BUTTON,44+40*i,70+40*j,32,24,str);
      fl_set_object_color(obj,8*j+i,8*j+i);
      fl_set_object_lalign(obj,FL_ALIGN_BOTTOM);
      fl_set_object_callback(obj,change_color, (long)(8*j+i));
    }
    topbox = fl_add_button(FL_NORMAL_BUTTON,120,30,160,32,"The Color Map");
    fl_set_object_lsize(topbox,FL_LARGE_SIZE);
    fl_set_object_lstyle(topbox,FL_BOLD_STYLE);
  fl_end_form();
}

int
main(int argc, char *argv[])
{
  fl_initialize(&argc, argv, "FormDemo", 0, 0);
  makeform();
  fl_show_form(form,FL_PLACE_FREE,FL_NOBORDER,NULL);
  fl_do_forms();
  fl_hide_form(form);
  return 0;
}