Una prima applicazione in PHP-GTK

La nostra prima applicazione

Dopo il Introduzione a PHP-GTK dedicato all’introduzione a PHP-GTK, è giunto il momento di capire come sia possibile creare delle applicazioni funzionanti. Come al solito, il primo programma sarà molto semplice, ma utile per introdurre aspetti fondamentali per la programmazione GTK. Il nostro obiettivo è quello di creare un’applicazione come la seguente:

(scusate la qualità pessima dell’immagine, comunque dovrebbe rendere l’idea)

Premendo sul pulsante ‘Saluta’ verrà visualizzato “Hello World” nella Label modificabile. Premendo su ‘Modifica’ potremo visualizzare una frase a notro piacimento, inserita all’interno dell’InputBox. Premendo ‘Chiudi’ chiuderemo il tutto.

Utilizzeremo la libreria che abbiamo creato nell’Introduzione a PHP-GTK e che abbiamo chiamato gtk_application.lib. Il nostro primo programma, introdurrà all’utilizzo dei seguenti widget:

• GtkWindow: un widget che fornisce una finestra nella quale contenere i componenti principali della nostra applicazione. Offre la possibilità di inserire un titolo, scegliere i bordi e scegliere la sua posizione sullo schermo. Ovviamente esistono altri metodi interessanti, che per ora non tratteremo.
• GtkButton: un widget di tipo container che emette un segnale quando vi si clicca sopra.
• GtkLabel: un widget che permette di visualizzare una piccola quantità di testo.
• GtkEntry: un widget che può contenere, in singola riga, del testo inserito dall’utente.
• GtkVSeparator, GtkHSeparator: widget che rappresentano una linea di separazione verticalo o orizzontale.
• GtkHBox, GtkVBox, GtkVButtonBox: container che servono per visualizzare correttamente il layout delle nostre applicazioni.

Creiamo un nuovo file, che chiameremo intro.php oppure intro.dgtk (in caso abbiate deciso di utilizzare gli installer), ed all’interno vi scriviamo quanto segue:

<?php
$myApp = require_once(‘gtk_application.lib’);
//classes def
//callbacks
//main init
//widget placement
//signals
//main-loop
?>

Come potete notare, non abbiamo fatto nulla di particolare, solamente incluso la libreria che abbiamo creato in precedenza ed assegnato l’istanza della classe GtkApplication (restituita dal nostro include) alla variabile $myApp.

Per comodità, ho deciso di scrivere due classi da sfruttare in questa applicazione. La prima è una semplice classe che ha la funzione di creare la finestra principale, la seocnda permette di gestire un’elenco di bottoni in modo relativamente semplice. Aggiungiamo il codice seguente sotto il commento “//classes def”:

class MainWindow extends GtkWindow{

function MainWindow($name, $title, $size, $border, $position){
$this->GtkWindow();
$this->set_name($name);
$this->set_title($title);
$this->set_usize($size[0], $size[1]);
$this->set_border_width($border);
$this->set_position($position);
}
}

class ButtonVList extends GtkVButtonBox{

function ButtonVList(){
$this->GtkVButtonBox();
$buttons = func_get_args();
foreach($buttons as $button){
$bt = &new GtkButton($button);
$this->pack_start($bt);
}
$this->show_all(); //mostro tutti i bottoni caricati
}

function connect_object_id($id){
$children = $this->children();
$bt = $children[$id];
if(!$bt)
return false;
$args = func_get_args();
call_user_method_array(‘connect_object’, $bt, array_slice($args, 1));
}
}

Qui le cose si fanno leggermete più complicate di prima. La prima classe è figlia della classe GtkWindow, che, come spiegato, serve a visualizzare una finestra che conterrà la nostra applicazione. GtkWindow ha vari metodi che servono per variare l’aspetto e lo stato della finestra stessa; solitamente vengono modificati il titolo attraverso il metodo GtkWindow::set_title, le dimensioni attraverso il metodo GtkWindow::set_usize ereditato dalla classe GtkWidget, la dimensione dei bordi attraverso GtkWindow::set_border_width ereditato dalla classe GtkContainer e la posizione della finestra al momento del suo primo caricamento attraverso GtkWindows:set_position . Tramite la classe MainWindow sarà quindi possibile creare una finestra settando direttamente le sue proprietà dal costruttore pincipale.

La seconda classe permette di gestire una lista verticale di bottoni. La classe eredita da GtkVButtonBox, che permette di visualizzare dei bottoni verticalmente e correttamente posizionati. Il costruttore accetta una quantità variabile di argomenti. Ognuno di questi rappresenta il titolo da associare ad un bottone. Per ogni argomento passato, difatti, viene generato un bottone che poi viene aggiunto al box. Queste due istruzioni, racchiudono 2 informazioni molto importanti: la prima è che ogni classe Gtk* DEVE essere istanziata per riferimento, anteponendo il simbolo & al costrutto “new”; la seconda è l’utilizzo dei Packer.

I packer sono un metodo tramite il quale le GUI gestiscono il posizionamento ordinato dei widget all’interno di un container. Nel nostro caso abbaimo usato GtkBox::pack_start che permette di posizionare il widget passato nella parte più alta o più a sinistra (in base al tipo di container, verticale o orizzontale) del container non ancora occupata. Utilizzando più volte pack_start in un container veticale, per esempio, incolonneremo i widget dall’alto verso il basso. Vengono mantenuti correttamente eventuali bordi per il container o spaziature standard da tenere tra i widget. Esiste un metodo simile, GtkBox::pack_end, che inserisce i widget partendo o dal basso o da destra. I packer, ovviamente, non si limitano a posizionare un widget, ma possono anche accettare parametri aggiuntivi per controllare lo status del widget in caso di ridimensionamento della finestra. Di questi tratteremo più avanti, ma potete controllare la documentazione ufficiale per saperne di più.

La seconda classe, per permetterci di gestire i segnali notificati da ogni bottone in modo corretto, dispone di un metodo, connect_object_id, che consente di connettere una callback ad un segnale per un solo bottone. Basta specificare come primo argomento l’indice del bottone all’interno della lista (basta seguire l’ordine di inserimento: il bottone corrispondente alla prima stringa sarà lo 0 e via dicendo … ) e come argomenti successivi quelli che avremmo passato normalmente al metodo connect_object.

Ora creiamo delle funzioni che sfrutteremo come callback da associare ai segnali notificati dai bottoni. La callback da associare al pulsante chiudi è già presente nella classe GtkApplication da noi sviluppata. Aggiungete sotto il commento ‘//callbacks’ le seguenti righe di codice:

function set_name($label, $entry){
$gettext = $entry->get_text();
$label->set_text($gettext);
}

function hello($label){
$label->set_text(‘Hello world’);
}

La prima funzione, set_name, visualizza nella label modificabile la frase da noi inserita nell box di input. Accetta 2 argomenti: il primo rappresenta la label da modificare, ed è un’istanza di GtkLabel, il secondo rappresenta il box contenente il testo ed è un’istanza di GtkEntry. La classe GtkLabel dispone di vari metodi per la gestione del testo presente al suo interno. In questo caso sfruttiamo GtkLabel::set_text, che ci permette di modificare il testo contenuto nella label. Della classe GtkEntry, invece, sfruttiamo il metodo GtkEntry::get_text per prelevare il testo contenuto nel box e salvarlo in una variabile. Essendo passati per riferimento, gli argomenti non saranno copiati ma faranno riferimento sempre ai widget generati dalla nostra applicazione all’inizio. In questo modo, tutte le modifiche a apportate agli argomenti, si riperquoteranno anche sui widget principali.

La seconda funzione, che accetta come solo argomento l’istanza di GtkLabel, sfrutta GtkLabel::set_text per modifcare il testo della label nell’ormai indispensabile, per le prime applicazioni, “Hello world”.

Terminata la preparazione, possiamo iniziare a creare i widget che comporranno la nostra applicazione. Per creare un widget, ci basterà solamente istaziare la classe che lo rappresenta. In questo modo il widget sarà creato, e pronto per essere posizionato sullo schermo. Aggiungete, sotto al commento ‘//main init’, il seguente codice:

$window = &new MainWindow(‘main_win’, ‘Introduzione a PHP-GTK. by HTML.it’, array(400, 250), 5, GTK_WIN_POS_CENTER);
$box1 = &new GtkHBox();
$bbox = &new ButtonVList(‘Saluta’, ‘Modifica’, ‘Chiudi’);
$separator1 = &new GtkvSeparator();
$box2 = &new GtkVBox();
$labelx = &new GtkLabel(‘Qui sotto c’è un’etichetta che verrà modificata:’);
$separator2 = &new GtkhSeparator();
$entry = &new GtkEntry();
$label = &new GtkLabel(”);

Abbiamo creato, in successione:

• La finestra principale tramite la classe da noi creata, passandole come argomento il nome della finestra, il titolo, le dimensioni iniziali, la dimensione dei bordi e la posizione (sfruttando una costante built-in che specifica che la posizione della finestra dovrà essere centrale rispetto allo schermo);
• Un box orizzontale necessario per contenere i tre widget principali che comporranno la nostra applicazione: il box che conterrà i bottoni, un separatore verticale, ed un box che conterrà le label e la entry;
• La lista di bottoni;
• Un box verticale;
• Una label statica che non verrà modificata dal programma, a cui viene passata come argomento la stringa da visualizzare;
• Un separatore orizzontale
• Una entry dove inserire il testo a visualizzare;
• La label, inizialmente vuota, che visualizzerà il testo da noi inserito.

L’operazione è stata abbastanza semplice, come avete potuto vedere. Ora non ci resta che posizionare correttamente questi widget, associargli eventuali callback e inizializzare il tutto. Andando per ordine, aggiungete il seguente codice dopo il commento ‘//widget placement’:

$window->add($box1);
$box1->show();

$bbox->set_layout(GTK_BUTTONBOX_SPREAD);
$box1->add($bbox);
$box1->show();

$box1->pack_start($separator1);
$separator1->show();

$box1->add($box2);
$box2->show();

$box2->pack_start($labelx);
$labelx->show();

$box2->pack_start($label);
$label->show();

$box2->pack_start($separator2);
$separator2->show();

$box2->pack_start($entry);
$entry->show();

$window->show_all();

Sfruttando i packer, posizioniamo i widget all’interno dei rispettivi container; il metodo GtkContainer::add ci permette di aggiungere un widget ad un container, posizionandolo in modo simile a quanto avviene per pack_start. Se un widget non viene aggiunto o posizionato, e non viene riciamato il metodo show, questi non viene visualizzato. Il metodo GtkWidget::show permette di visualizare il widget dal quale viene richiamato, mentre il metodo GtkWidget::show_all permette di visualizzare il widget dal quale è chiamato e tutti i suoi widget figli. È buona norma, chiamare sempre il metodo show per ogni widget non container, altrimenti show_all.

Una piccola precisazione va fatta per la funzione set_layout; questa funzione, appartenete alla classe da noi creata ButtonVList, è ereditata da GtkVButtonBox, e permette di scegliere il layout di visualizzazione dei bottoni scegliendo una delle seguenti costanti come argomento:

• GTK_BUTTONBOX_DEFAULT_STYLE: lo stile di default, solitamente GTK_BUTTONBOX_EDGE;
• GTK_BUTTONBOX_SPREAD: specifica che i bottoni devono essere visualizzati all’interno del box con spazi regolari ai bordi e tra uno e l’altro;
• GTK_BUTTONBOX_EDGE: come sopra, ma senza spazi dal bordo superiore ed inferiore;
• GTK_BUTTONBOX_START: i bottoni verranno inseriti partendo all’alto o da sinistra, visualizzati in base alla loro spaziatura interna e alla dimensione dei bordi;
• GTK_BUTTONBOX_END: come sopra, ma partendo dal basso o da destra.

In PHP-GTK troviamo molte costanti predefinite di indubbio utilizzo. Una lista completa può essere tovata nella documentazione ufficiale.

Ora, per completare il tuto aggiungiamo dopo il commento ‘//signals’ questo codice:

$bbox->connect_object_id(0,’clicked’, ‘hello’, $label);
$bbox->connect_object_id(1,’clicked’, ‘set_name’, $label, $entry);
$bbox->connect_object_id(2,’clicked’, $myApp->destroy());

e dopo il commento ‘//main-loop’ quest’altro:

$myApp->set_main($window);
$myApp->main_loop();

Il primo spezzone di codice è quello fondamentale per il funzionamento della nostra applicazione; senza di quello vedremmo il layout correttamente, ma l’applicazione non funzionerebbe. Sfruttando il metodo connect_object_id, associamo ai vari pulsanti presenti nella ButtonVList delle callback, da richiamare in caso il pulsante sia cliccato: al pulsante ‘Saluta’ associamo la funzione hello, al pulsante ‘Modifica’ la funzione set_name ed infine, al pulsante ‘Chiudi’ la funzione, presa dalla classe GtkApplication, che permette di terminare la nostra applicazione GTK.

Il secondo spezzone di codice serve per settare la finestra principale, alla quale la funzione set_main si preoccuperà di associare una callback per chiudere GTK in caso la finestra venga chiusa, e per avviare il tutto.

Per facilitarvi nel testing dell’applicaizone, includo il codice sorgente per intero:

<?php
$myApp = require_once(‘gtk_application.lib’);

class MainWindow extends GtkWindow{

function MainWindow($name, $title, $size, $border, $position){
$this->GtkWindow();
$this->set_name($name);
$this->set_title($title);
$this->set_usize($size[0], $size[1]);
$this->set_border_width($border);
$this->set_position($position);
}
}

class ButtonVList extends GtkVButtonBox{

function ButtonVList(){
$this->GtkVButtonBox();
$buttons = func_get_args();
foreach($buttons as $button){
$bt = &new GtkButton($button);
$this->pack_start($bt);
}
$this->show_all();
}

function connect_object_id($id){
$children = $this->children();
$bt = $children[$id];
if(!$bt)
return false;
$args = func_get_args();
call_user_method_array(‘connect_object’, $bt, array_slice($args, 1));
}

function &get_button($id){
return $this->buttons[$id];
}
}

function set_name($label, $entry){
$gettext = $entry->get_text();
$label->set_text($gettext);
}

function hello($label){
$label->set_text(‘Hello world’);
}

$window = &new MainWindow(‘main_win’, ‘Introduzione a PHP-GTK. by HTML.it’, array(400, 250), 5, GTK_WIN_POS_CENTER);
$box1 = &new GtkHBox();
$bbox = &new ButtonVList(‘Saluta’, ‘Modifica’, ‘Chiudi’);
$separator1 = &new GtkvSeparator();
$box2 = &new GtkVBox();
$labelx = &new GtkLabel(‘Qui sotto c’è un’etichetta che verrà modificata:’);
$separator2 = &new GtkhSeparator();
$entry = &new GtkEntry();
$label = &new GtkLabel(”);

$window->add($box1);
$box1->show();

$bbox->set_layout(GTK_BUTTONBOX_SPREAD);
$box1->add($bbox);
$box1->show();

$box1->pack_start($separator1);
$separator1->show();

$box1->add($box2);
$box2->show();

$box2->pack_start($labelx);
$labelx->show();

$box2->pack_start($label);
$label->show();

$box2->pack_start($separator2);
$separator2->show();

$box2->pack_start($entry);
$entry->show();

$window->show_all();

$bbox->connect_object_id(0,’clicked’, ‘hello’, $label);
$bbox->connect_object_id(1,’clicked’, ‘set_name’, $label, $entry);
$bbox->connect_object_id(2,’clicked’, $myApp->destroy());

$myApp->set_main($window);
$myApp->main_loop();
?>

Conclusioni

Il nostro tour introduttivo è terminato. Nei prossimi articoli tenteremo di approfondire l’argomento PHP-GTK, imparando a sfruttare i widget più complessi per creare applicazioni professionali e portabili. Le potenzialità di GTK sono comunque talmente tante che l’unico modo per imparare ad utilizzare la libreria al meglio è quello di sperimentare il più possibile. Potrete ottenere aiuti sul forum di html.it, oppure iscrivervi alla mailing list ufficiale.

Al prossimo articolo, in cui:

• Aplieremo la nostra libreria, aggiungendoclassi per la gestione dei menu;
• Impareremo a gestire le toolbar;
• Impareremo a gestire le finestre figlie;
• Impareremo a gestire le tabelle;
• Creeremo un’applicazion per decomprimere file compressi con PHP-GTK.