Beginning PHP-GTK: Creating a Simple Interface [Tutorial]

[Baljeet]

• Part 1 - Beginning PHP-GTK: Creating a Simple Interface
• You must be registered for see links
• Part 3 - Coming soon

This tutorial will guide you through creating a simple PHP-GTK Graphical User Interface (GUI). The tutorial assumes that you already know PHP5 and will not cover beginning PHP or programming development. This tutorial is basic but assumes you already know basic PHP-GTK development.

You should have PHP-GTK installed and able to use it. I suggest using

You must be registered for see links

. Gnope provides an easy method to install PHP-GTK on Windows, Linux and Mac. Gnope is also a method to distribute PHP applications that you complete.

At the end of this tutorial we will have created an interface that uses tables (GtkTable), Labels (GtkLabel), allows user input (GtkEntry), and two buttons (GtkButton). These widgets will not be connected to any events in this part of the tutorial.

This tutorial is part of a series. At the end of the tutorial you will have created a very simplistic Keep Alive script. In time, the Keep Alive script will also be a community project and given away for free.

Getting Started
Lets begin extending the GtkWindow class and creating a basic GUI to work with:

<?php

class CodeCallGtk extends GtkWindow {
    
    /**
     * FirstGTK constructor. Actually creates the
     * window
     *
     * @return FirstGtk
     */
    public function __construct() {
    	/*
    	 * Call the parent constructor
    	 */
        parent::__construct();
        
        /*
         * Set the size of the new GTK Window
         * Set the Title
         * Connect the destroy/exit event to a function
         */
        $this->set_default_size(400,100);
        $this->set_title('CodeCall.net PHP-GTK GUI Tutorial');
        $this->connect_simple('destroy', array('gtk', 'main_quit'));

         /*
         * This will realize and show
         * all windows from child to parent.
         */
        $this->show_all();
    }
}
    
new CodeCallGtk();
Gtk::main();

Which will result in a window that looks like this:

Which is empty. The only thing that can be done is minimize, maximize and exit. We need to add contents.

GtkTable
All widgets (objects such as buttons, lists, views, etc) must be in a container. There are numerous containers. Three popular containers are

You must be registered for see links

es,

You must be registered for see links

and

You must be registered for see links

.

All windows must have at least one container. A container allows widgets to be attached which are then realized (or shown) in the Window. They can be realized individually or by calling the parent show_all() function (done in the constructor above) which will also realize all child objects.

GtkTable is a widget that consists of columns and rows. It is the same concept as a table in HTML or a table in a database. The PHP Manual explains it as this:



Constructor:

GtkTable ([int n_rows = 1 [, int n_columns = 1 [, bool homogeneous = false]]]);

rows : The number of rows the new table should have.
columns : The number of columns the new table should have.
homogeneous : If set to TRUE, all table cells are resized to the size of the cell containing the largest widget.
Returns : A pointer to the the newly created table widget.

We want our program to look like this:

So we will need 2 rows and 4 columns. This will be how we construct the table:

$table = new GtkTable(4,2);

I realize that the image looks like there is only 3 columns and 2 rows but if you setup your table as such, your buttons will be irregular. You could use a button container but that is beyond the scope of this tutorial. For now, just use 4.

Add this code before the show_all() function is executed:

/*
 * Create a virticle and horizontal box
 * container to hold our widgets
 */
$table = new GtkTable(4,2);

/*
 * Add the table to the GTK Window
 */
$this->add($table);

We've created the table and added it to the Window. The table automatically takes up all space available. If you execute the program at this point you will not see any difference. The table is invisible. We still need to attach widgets to the table, but first we need to create those widgets.

We will come back to the table...

GtkLabel
A label is a widget that displays text. They are commonly used to identify objects or provide text updates. We will use a label to identify a user entry, GtkEntry, which accepts a host name.

Constructor:

GtkLabel ([string string = null [, boolean parse_mnemonic = false]]);

It takes two arguments. The first is the text you would like to display. The second is a boolean value to tell the label to parse mnemonics. A mnemonic is an underlined key in a label, used for keyboard navigation. Both arguments can be null. Creating a label is simple:

$lblHost1   = new GtkLabel(); // Null
$lblHost2   = new GtkLabel("Host:"); // Text only
$lblHost3   = new GtkLabel("_Host:", true);

Here is an example label with a mnemonic:

Since we won't be using a mnemonic (yet), we simply need to past text to the Label:

/*
 * Create Label
 */
$lblHost   = new GtkLabel("Host:");

Add this code before you add the table to the window ($this->add($table)). The placement isn't particularly important, so you could add this after - anywhere before the show_all() function is executed.

Note: GtkLabel has many methods not covered here.

You must be registered for see links

to see a listing of methods.


GtkEntry
GtkEntry is a single line text entry widget, similar to a single line textbox. This widget allows your application to accept user input.

Constructor:

GtkEntry ([ string text [, int max ]]);

text: Default text to be shown
max: Maximum input length

Create a new instance of GtkEntry for our program:

/*
 * Create an entry for entering 
 * host to access
 */
$txtEntry = new GtkEntry();

Add this below your GtkLabel() creation.

Note: There are several methods and none are discuss here. You can learn about them

You must be registered for see links

as well as some of them in part 2 of this tutorial.

GtkButton
Finally, we arrive at the button. The GtkButton widget displays a clickable pushbutton to the user in your container on your window. Upon click, an event is fired.

Constructors:

GtkButton (string label, boolean use_underline);

GtkButton::new_from_stock (string stock_id);

use_underline is the same as mnemonics above. A boolean value passed that identifies letters with underline values. Why it has a different name? I don't know.

A stock button is a button that has an image and mnemonic. It is a prefabricated button. You can find a list of stock_ids

You must be registered for see links

.

Example Stock Button:

$btnStop  = GtkButton::new_from_stock(Gtk::STOCK_STOP);

Our program will not use mnemonics or stock buttons (yet). We will need two buttons, a start and stop:

/*
 * Create two buttons, one for starting
 * and another for stopping
 */
$btnStart = new GtkButton('Start');
$btnStop  = new GtkButton('Stop');

Add this code after creating the GtkEntry() object.

Note: Again, there are many methods not covered here. You can find a listing

You must be registered for see links

.

Table Attaching and Display
At this point you've created several objects but the window doesn't show anything if you execute the code. This is because you have to attach the widgets to the table, which is attached to the window. Because they are not attached to any container, the objects are never realized (nor can be).

Using the table

You must be registered for see links

method, we will not add our widgets.

Constructor:

void attach(GtkWidget child, int left_attach, int right_attach, int top_attach, int bottom_attach [, GtkAttachOptions xoptions = Gtk::EXPAND|Gtk::FILL [, GtkAttachOptions yoptions = Gtk::EXPAND|Gtk::FILL [, int xpadding = Gtk::EXPAND|Gtk::FILL [, int ypadding = Gtk::EXPAND|Gtk::FILL]]]]);

The attach method takes up to 9 arguments of which only 5 are required. We will only be using the 5 required for this tutorial. You can read more about the other options

You must be registered for see links

.

child: The widget to add.
left_attach: the column number to attach the left side of a child widget to.
right_attach: the column number to attach the right side of a child widget to.
top_attach: the row number to attach the top of a child widget to.
bottom_attach: the row number to attach the bottom of a child widget to.
xoptions: Used to specify the properties of the child widget when the table is resized.
yoptions: The same as xoptions, except this field determines behaviour of vertical resizing.
xpadding: An integer value specifying the padding on the left and right of the widget being added to the table.
ypadding: The amount of padding above and below the child widget.

When attaching a widget, the left_attach and right_attach are the columns while the top_attach and bottom_attach are the rows. Starting with 0, 0-1 is column1/row1, 1-2 is column2/row2, 2-3 is column3/row3, etc.

To attach a widget to column 2, row 1 you would use this combination

1, 2, 0, 1

Let's attach our Widgets

/*
 * Attach widgets to the table
 */
$table->attach($lblHost, 0, 1, 0, 1); // Column 1, Row 1
$table->attach($txtEntry, 1, 4, 0, 1); // Comumn 2-4, Row 1
$table->attach($btnStop, 2, 3, 1, 2); // Column 3, Row 2
$table->attach($btnStart, 3, 4, 1, 2); // Column 4, Row 2

Since we only use the default options for arguments 6-9, widgets are set to automatically expand/fill the entire space given by the table.

Add the code above after the button creation and before the $this->add($table);.

Your code should look like this:

<?php

class CodeCallGtk extends GtkWindow {
    
    /**
     * FirstGTK constructor. Actually creates the
     * window
     *
     * @return FirstGtk
     */
    public function __construct() {
    	/*
    	 * Call the parent constructor
    	 */
        parent::__construct();
        
        /*
         * Set the size of the new GTK Window
         * Set the Title
         * Connect the destroy/exit event to a function
         */
        $this->set_default_size(400,100);
        $this->set_title('CodeCall.net PHP-GTK GUI Tutorial');
        $this->connect_simple('destroy', array('gtk', 'main_quit'));
        
        /*
         * Create a virticle and horizontal box
         * container to hold our widgets
         */
		$table = new GtkTable(4,2);
		
		/*
		 * Create Label
		 */
		$lblHost   = new GtkLabel("Host:");
		
		/*
         * Create an entry for entering 
         * host to access
         */
		$txtEntry = new GtkEntry(); 
		
		/*
		 * Create two buttons, one for starting
		 * and another for stopping
		 */
		$btnStart = new GtkButton('Start');
		$btnStop  = new GtkButton('Stop');
		
		/*
		 * Attach widgets to the table
		 */
		$table->attach($lblHost, 0, 1, 0, 1); // Column 1, Row 1
		$table->attach($txtEntry, 1, 4, 0, 1); // Comumn 2-4, Row 1
		$table->attach($btnStop, 2, 3, 1, 2); // Column 3, Row 2
		$table->attach($btnStart, 3, 4, 1, 2); // Column 4, Row 2
		
		/*
 		 * Add the table to the GTK Window
 		 */
		$this->add($table);


         /*
         * This will realize and show
         * all windows from child to parent.
         */
        $this->show_all();
    }
}
    
    new CodeCallGtk();
    Gtk::main();

Execute the code and you should see this window:

Part 1 Conclusion
We've created a very basic GUI. It currently does nothing. The next part of this series we will connect the button click events to functions.

You must be registered for see links

------

All Credits goes to one who really made this...