In this tutorial we will work though the stages of installing PHP-GTK and creating a simple GUI application.
PHP has quickly evolved into one of the fastest growing web scripting languages on the Internet. Serving millions of web sites, PHP has proved itself as reliable, flexible and easy to learn. Many who have programmed with it would agree, that PHP is the ideal scripting language. On the PHP-GTK website, Andrei Zmievski, author of PHP-GTK, demonstrates how the ease and convenience of PHP can be taken to the next level, which is the creation of standalone, cross-platform GUI applications.
This following history of GTK was taken verbatim from the PHP-GTK website:
GTK+ was originally developed for GIMP, the GNU Image Manipulation Program. GTK+ stands for the GIMP Tool Kit. GTK+ has grown from these beginnings and is now used as a central part of GNOME, the GNU Projects desktop environment. GTK+ has also been ported to BeOS and Win32, making it the perfect choice to use as the basis for a PHP extension, keeping PHP as cross-platform as possible and allowing the creation of windowed applications in PHP for Linux, BeOS and Windows.
Learning Objectives
In this tutorial you will learn the following:
# What GTK+ is
# Basic Terms
# How to use the PHP-GTK extensions, including the following classes:
# GtkWindow()
# GtkFrame()
# GtkVBox
# GtkLabel()
# GtkHSeparator()
# GtkEntry()
# GtkHButtonBox
# GtkButton
Basic Terms
PHP-GTK is an extension that allows you to create GUI standalone, cross-platform applications. This extension is not used for the web in any way, but for client-side applications.
Widgets
Widgets are the basic forms and functions of a GUI application. Among the most frequently used widgets are: labels, buttons, windows, frames, and text boxes. All widgets are derived from an abstract base (parent) class, GtkWidget.
There are approximately five cycles in the life of a widget: creation (declaring and object), placement (adding it to a container), signal connection (the action it will perform), display (whether it is viewable or not), and destruction (closing of a program).
Containers
Containers are widgets that can contain another widget. Most widgets are containers. Some examples are: GtkWindow, GtkFrame, and GtkBox. Containers are used to create nice layout for the application. They give you control over where certain parts of the application are placed within the program window. All containers are derived from the base class, GtkContainer, which is derived from the GtkWidget class.
Signals
When a user performs a function on the application, a return process must be executed to respond to their actions. Signals allow the program to know that the user has performed an action and trigger the appropriate response.
For instance, the user clicks on a button that creates a new window. The program recognizes the request and then opens a new window. This is made possible by the use of signals. When the button is pushed it triggers the signal and the signal carries out the operation.
Not all widgets require a signal. Some widgets, such as the GtkHSeparator, which creates a horizontal bar, does not require an action when it is clicked.
Callbacks
When a signal is invoked, it normally sends the action to a function. The actual process of performing a function is called a Callback. Callbacks execute the function and return a value (most cases) or sometimes another operation to be performed. In order to create a callback you connect the function to the signal.
Installing PHP-GTK
Now that we have the basic vocabulary out of the way we can proceed to the installation of PHP-GTK. You can download PHP-GTK, by visiting their web site, PHP-GTK. Choose the appropriate link and begin downloading the file. I will be walking you through the installation of PHP-GTK on Windows (all versions).
Now that you have downloaded the file, unzip it. You will find one folder labeled "php4". Take this entire file and move it to your c:\ drive. (I have renamed the folder to "php" for easier reading and executing of programs (c:\php>).)
Inside this folder you should have about seven files, two of which are executable. There is also a folder called "samples". (I have moved all samples out of this file and have put them in the main folder where the .exe files are. This provides for an easier execution of your programs from the command line.)
Another folder is called "winnt". Inside it you will find two items, a .ini file and a folder. Copy the .ini file to the folder c:\winnt or, on later versions of windows (95/9
, to c:\windows.
Now open the "system32" folder. Inside this folder you will see eight .dll files. Copy these files to c:\winnt\system32 or, on windows 95/98, to c:\windows\system32. You are now set to run your programs.
Note: You will be running all programs from the command prompt. (Those who know how can make their computer recognize the .php extension and have it execute with a double click). Open up the command prompt and change directories to the ?php? folder by typing "cd php" (without the quotes). Once you have created all your programs and saved them into the main php folder, your command line will look like this: c:\php>php_win filename.php
Before we go onto creating the program, we need to make sure that our installation process is correct. Since you copied the "samples" contents into the php folder, you should have a file called ?gtk.php?. On the command line type: c:\php>php_win gtk.php and give the process a few seconds to execute. In the center of your screen you should see an application with a bunch of options and a scroll bar. If you do not see this, go back to the installation and make sure that you have completed all the steps.
GTK Classes
There are many GTK classes. Let?s take a look at the few that we will be using in this tutorial: GtkWindow(), GtkButton(), GtkButtonBox(), GtkEntry(), GtkLabel(), GtkVBox(), GtkHSeparator(), and GtkFrame(). Below are basic descriptions of each widget. For more information refer to the manual on the PHP-GTK site.
GtkWindow()
GtkWindow creates the new window. There are three different types of GtkWindow options. We will use the default, which is the TopLevel Window. There are many options you can use with the GtkWindow, such as: set_name, set_title, connect, and set_border_width.
GtkFrame()
GtkFrame simply gives the program have a nice border. You can set the label name, alignment, and shadow.
GtkVBox()
GtkVBox creates a vertical container in which other widgets will be stored.
GtkLabel()
GtkLabel creates a label that can be set either initially or by calling a function on it. If no value is set, an empty label is created.
GtkHSeparator()
GtkHSeparator creates simple horizontal line.
GtkEntry()
GtkEntry creates a textbox for user input.
GtkHButtonBox()
GtkHButtonBox is a container in which you can place a horizontal row of buttons.
GtkButton()
GtkButton is probably the most widely used widget in GUI applications. GtkButton creates a button for the user to click on. It has different options, which define how the button will behave when pressed, released, or clicked.
Creating Your First GUI Application
The best way to learn is by reading up on the subject and by working through examples.
As far as reading is concerned, the application that you just opened is a great resource. It covers most of the functions that GTK has to offer in a working environment. The PHP-GTK website is another great resource. There is a user forum where you can post questions (and if you are lucky you will even get answers). Now on to the examples!
The program that we will be creating will take a user input and display it as a label. In order to create this we must understand the layout of the widgets and what we want to accomplish with each area.
How it works
Example 1.1 ? Before you start your main code you have to enter an ?if? statement, something like this:
if (!class_exists('gtk')) {
if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN'){
dl('php_gtk.dll');
} else {
dl('php_gtk.so');
}
}
This statement determines if the PHP-GTK extension is available. If it isn?t, it loads the appropriate file. In the above example there are two possible files, depending on whethere the OS is Windows or Linux.
Example 1.2 ? The next feature that is a standard for any program is delete_event()
function delete_event()
{
return false;
}
This function is a registered handler returning false. This in turn, tells PHP-GTK to trigger the default signal handler. The default signal handler closes the current window. In this case it will close the program.
Example 1.3 ? destroy() function.
function destroy()
{
Gtk::main_quit();
}
This calls the static function to quit the program. This is a very important feature. If it is not included, your program will still close down, but it will not be shut down. This means that if you were to perform a ctrl+alt+delete and look at the task manager you would see that the php program was still running.
Example 1.4 ? Setting the Window.
/* Creates a new instance of the GtkWindow */
$window = &new GtkWindow();
/* Helps to differentiate between each of the windows */
$window->set_name('main window');
/* Sets the title of the window */
$window->set_title('Introduction to PHP-GTK');
/* Set the window size */
$window->set_usize(400, 300);
/* Calls the destroy function to end the program */
$window->connect('destroy', 'destroy');
/* Calls the delete_event function to close the window */
$window->connect('delete-event', 'delete_event');
/* Sets the windows border width */
$window->set_border_width(10);
/* Sets the window’s position */
$window->set_position(GTK_WIN_POS_CENTER);’
/* Shows the window */
$window->show_all();
There are many details involved in creating the main window of a program. First create a new instance of the GtkWindow ($window = &new GtkWindow()
.
The upper-left hand corner of the main window always displays the name of the program. To set the name of our program we will use the method set_title.
The other name to set is the set_name. This is most important when you start using signals to create pop-up windows; setting the name helps the user distinguish between windows.
We can set the size that the window will be when it first opens using the set_usize. When the program is actually running users will not be able to resize the window smaller than this minimum size (they will, however, be able to maximize it). There is a way to lock all resizing, but it will not be covered in this tutorial.
The connect method is a signal that connects the action of the user to the action of the program. In our program each of the connects deal with the closing of the program.
The delete_event closes the current window of the program.
The destroy closes the program down (see above functions for a more defined definition). The other settings for the window properties are pretty self-explanatory.
Now come two very important lines of code:
$window->show_all();
Gtk::main();
The first one tells the program that it needs to display the window. The second line of code acts like the cover. It wraps the entire program together into a nice bundle ready to be displayed. Without these two lines your program will not run.
Enter in all the code first, and run the program. Below you can see what the program should look like at this stage.
Example 1.5 ? Creating the Frame
/* Creates the frame with a label or title */
$frame = &new GtkFrame('A Simple Update Program');
/* Add the frame to the window */
$window->add($frame);
We are ready to add our first element to the window. Create a new instance of GtkFrame. Inside the parenthesis you can add a label to the frame, or you can leave it empty. In this case we have given our frame a label.
Now that we have created the frame we need to add it to the window. We do this using the add method and declaring what we want added.
$frame->show();
In order for the frame to appear we have to call the show method. No parameters are passed, it simply tells the program to show the item. All code put in the program must be before the $window->show_all(); and the Gtk::main(); , but after the $window information. This will guarantee that all the elements make it into the program.
Now execute the program. You should get a GUI that looks like this.
Example 1.6 ? Creating A Box
/* Create a new instance of a vertical box */
$box1 = &new GtkVBox();
/* Add the Vbox to the frame */
$frame->add($box1);
/* Set the Vbox to show */
$box1->show();
We will experiment with each element by creating an instance of each. In this case we are creating a vertical box that will reside inside of the frame. Note that since the vertical box will be inside of the frame, we add the box to the frame not to the window. A vertical box will allow us to add other widgets in a list format, one after the other.
Example 1.7 ? Creating a label
/* Create a label with an empty default value */
$label = &new GtkLabel(''
/* Pack it into the VBox */
$box1->pack_start($label);
/* Show the label, make is visible */
$label->show();
We have the basic layout of the program set up, now we need to add the main elements that will actually be the program.
The first widget that we will put in the vertical box is a GtkLabel label. A GtkLabel is different than the label in the frame, which acts like a title. This label allows you to change the text with a callback. After creating the Gtklabel we will add it to the vertical box by the pack_start function. This is different then the add we used for the GtkFrame and the GtkVBox. The previous two are containers. The GtkLabel is a widget. When adding the widget to the vertical box you essentially pack the widgets into the box starting at the top and working your way down.
Example 1.8 ? Horizontal Line
/* Creates a horizontal rule */
$separator = &new GtkHSeparator();
/* Pack it into the VBox */
$box1->pack_start($separator);
/* Show the widget */
$separator->show();
Creating the GtkHSeparator is just like creating a <hr> in HTML. It is used to separate different widgets. After creating it we pack it into the vertical box. Below is a view of the GtkHSeparator. You will notice (if you look carefully) that it is near the bottom of the GtkFrame?s border. Since there is no way to set the size of a label, it takes up the entire space of the vertical box and places the horizontal line at the bottom.
Example 1.9 ? Text Box
/* create the entry box (text box) */
$entry = &new GtkEntry();
/* Pack it into the vbox */
$box1->pack_start($entry);
/* Show the widget */
$entry->show();
We now have the display area and a nice separator for a visually appealing program, but we must add a place for the user to enter the information into the program. For this we use the GtkEntry, which is identical to the textbox in HTML (well, almost identical). We then add it to the vertical box. Below is an example of what the program should look like so far. The horizontal line is now much clearer.
Example 2.0 ? Horizontal Button Box
/* Create the horizontal button box */
$box2 = &new GtkHButtonBox();
/* Set the layout of the buttons */
$box2->set_layout(GTK_BUTTONBOX_SPREAD);
/* Add it to the VBox container */
$box1->add($box2);
/* Show the widget */
$box1->show();
Now we are going to add a horizontal box inside the vertical box. Think of nested tables. The GtkHButtonBox holds only buttons and because of this you must tell the program how you want those buttons spaced out. In the example I have them spread out evenly.
You can choose from the following options: GTK_BUTTONBOX_DEFAULT_STYLE, GTK_BUTTONBOX_SPREAD, GTK_BUTTONBOX_EDGE, GTK_BUTTONBOX_START, GTK_BUTTONBOX_END. Test each of these in your program to see what each does.
Example 2.1 ? Buttons
/* Create a new button with a name on it */
$button = &new GtkButton('Click to Update the Label');
/* Create a signal and callback */
$button->connect_object('clicked', 'set_name', $label, $entry);
/* Pack the element into the HButtonBox */
$box2->pack_start($button);
/* Show the widget */
$button->show();
We will be creating two buttons for our project. When you create the button you set the label you want to give it. In this case, I have put the label that describes the program.
Since this button will be running our program we need to create a signal for a callback. In this case we will use the connect_object. All connects require a minimum of two parameters. The first is the signal and the second is the function name you will be calling. You can choose between these different signals: pressed, clicked, released, enter, and leave. After these two elements we enter the parameters that we want to pass the function. In this case we want our button to update something, so we will pass it the two widgets that will be altered. We then add the button to the horizontal box. Below is a view of what the program should look like up until this point.
We will now create our second button.
/* Create the next button with the label */
$button = &new GtkButton('Close Window');
/* Create the signal and callback */
$button->connect_object('clicked', 'destroy');
/* Add it to the HButtonBox */
$box2->pack_start($button);
/* Show the widget */
$button->show();
This is the button that will close down the program. We use the signal to call the destroy function.
Below is a view of the finished program.
Now for the function that runs the entire program!
/* --- This takes the instance of entry class and grabs what has been entered into the textbox and saves it to $gettext.
--- The instance of the label class is then set with the text saved from the $entry class */
function set_name($label, $entry)
{
$gettext = $entry->get_text();
$label->set_text($gettext);
}
When the button is clicked to update the label, this is what is executed. Since we have passed this function the $label and $entry widgets, these are what we will be altering. The $entry widget calls the get_text() function. This grabs the information that the user has entered into the program. Then the $label widget calls the set_text function with the text we just receive from the entry box.
In order to make sure that our program works we will need to test it. Type in the box ?Hello World!? The following images show the program before and after the Update button is clicked.
After the button is clicked the following will be displayed in the Label.
You now have your first working GUI program built with PHP. The final script is below with limited comments.
The Script
<?php
/* This if statement determines where is finds the appropriate file to run
* the gtk program. It is for Windows and Linux (respectively) */
if (!class_exists('gtk'))
{
if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')
dl('php_gtk.dll');
else
dl('php_gtk.so');
}
/* This function closes the window it is defaulted to false */
function delete_event()
{
return false;
}
/* This is very important to actually destroying any instances
* of php running */
function destroy()
{
Gtk::main_quit();
}
/* This takes the instance of entry class and grabs what has been entered
* into the textbox and saves it to $gettext. The instance of the label
* class is then set with the text saved from the $entry class */
function set_name($label, $entry)
{
$gettext = $entry->get_text();
$label->set_text($gettext);
}
/* Creation of the window */
$window = &new GtkWindow();
$window->set_name('main window');
$window->set_title('Introduction to PHP-GTK');
$window->set_usize(400, 300);
$window->connect('destroy', 'destroy');
$window->connect('delete-event', 'delete_event');
$window->set_border_width(10);
$window->set_position(GTK_WIN_POS_CENTER);
/* Creates the frame */
$frame = &new GtkFrame('A Simple Update Program');
$window->add($frame);
/* Creates the Vertical box for putting things in. */
$box1 = &new GtkVBox();
$frame->add($box1);
$box1->show();
/* Creates the area where will be updating the information */
$label = &new GtkLabel('');
$box1->pack_start($label);
$label->show();
/* Creates a horizontal line */
$separator = &new GtkHSeparator();
$box1->pack_start($separator);
$separator->show();
/* Creates the textbox for the user to enter in the information */
$entry = &new GtkEntry();
$box1->pack_start($entry);
$entry->show();
/* Creates the horizontal box for across the bottom of the window */
$box2 = &new GtkHButtonBox();
$box2->set_layout(GTK_BUTTONBOX_SPREAD);
$box1->add($box2);
$box1->show();
/* Sets up one button that is in the button box */
$button = &new GtkButton('Click to Update the Label');
$button->connect_object('clicked', 'set_name', $label, $entry);
$box2->pack_start($button);
$button->show();
/* Sets up the other button in the button box */
$button = &new GtkButton('Close Window');
$button->connect_object('clicked', 'destroy');
$box2->pack_start($button);
$button->show();
/* Closes off the frame by showing it */
$frame->show();
/* Tells the window to show all elements */
$window->show_all();
/* Finishes off the entire program */
Gtk::main();
?>
http://www.zend.com/zend/tut/tutorial-silva.php
