Creating Basic GTK Objects

   

---

The GTK+ extension is an object oriented programming (OOP) extension to PHP. You need to use OOP syntax and structures to use the GTK+ library. If you haven't already done so, you may want to go all the way back to Chapter 1 and review the material about OOP in PHP.

Creating Your First PHPGTK Window

Before you can create any PHPGTK applications, you must tell PHP which GTK library you want to use. Since GTK runs on Windows and many flavors of UNIX, that leaves us with two types of libraries. Windows uses dynamic link libraries, also called DLLs. Most *nix based operating systems use .so libraries. Since you want your application to be able to be used on both types of operating systems without modification, you must provide a dynamic method of loading the libraries. The standard method of doing this is:

 if (!class_exists('gtk')) {  if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')       dl('php_gtk.dll'); else       dl('php_gtk.so'); } 

Side Note

If you intend for your script to run on platforms other than Linux or Windows (if support for these other platforms is added in later versions of PHPGTK), then you must ensure that the proper PHPGTK library is loaded using the same manner as above.

The core part of any PHPGTK application is the main window. Each application you create should have a main window that acts as a container into which you place your other widgets.

The basic window class in PHPGTK is GtkWindow(). You create a new window object like this:

 $window = &new GtkWindow();  

Now that you have a window, you must provide for a way to destroy that window. In most operating systems, a user can destroy a window by clicking the "X" in the upper right corner of the window (some Linux desktops provide a different control).

When you click the "X" in a PHPGTK application, two signals are sent to the application. These signals are delete_event and destroy. For now we'll just concentrate on the destroy signal.

Signals are generally user input, and callbacks are functions that you create to do something in response to the user input. However, you need to connect the signal to the callback. To do this, you use the connect() method. To connect the destroy signal to our destroy callback:

 $window->connect('destroy','destroy');  

The first argument is the name of the signal that is sent by PHPGTK. The second argument is the name of the function (callback) that you want to call in response to the signal. To keep things simple, we'll name the function (callback) 'destroy'.

 function destroy() {  Gtk::main_quit(); } 

The Gtk::main_quit(); is the PHPGTK function that kills the application.

Now we have created a window and provided a means for the user to get rid of the window. But we still can't run the application. PHPGTK requires two more things to be done. First, we need to show the window. You show a window by calling the show_all() method:

 $window->show_all();  

Finally, you need to start the event sequence (polling events?) by calling the special PHPGTK function main():

 Gtk::main();  

Side Note

You must begin your scripts with the full "<?php" tag when using PHPGTK. Using the shorthand "<?" may cause PHPGTK to just echo the entire script to the screen instead of creating a GTK window.

When we put it all together, you get Script 12-1, basic_window.php.

Script 12-1 basic_window.php

  1.  <?php  2.    if (!class_exists('gtk')) {  3.    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')  4.      dl('php_gtk.dll');  5.    else  6.      dl('php_gtk.so');  7.  }  8.  function destroy(){  9.    Gtk::main_quit(); 10.  } 11.  $window = &new GtkWindow(); 12.  $window->connect('destroy', 'destroy'); 13.  $window->show_all(); 14.  Gtk::main(); 15.  ?> 

Run the script from the command line (remember, you need to add the full path to the PHP executable if it is not in the current directory):

 php -q basic_window.php  

The result should look similar to Figure 12-2. You can close the window by clicking the "X" in the upper right corner.

Figure 12-2. basic_window.php

Script 12-1. basic_window.php Line-by-Line Explanation

LINE	DESCRIPTION
2	If the GTK class has not been defined, then execute lines 3 7. If the GTK class has been defined, then the script needs to do nothing.
3	Check the first three characters of the PHP_OS environment variable.
4	If it is WIN, then the system is running Windows. Load the PHPGTK library for Windows.
5 7	If the PHP_OS environment variable is not WIN, then assume that PHP is running on a Linux system and load the Linux PHPGTK library.
8 10	Define a function, destroy(), that stops the script when called.
9	Execute the Gtk::main_quit() method to stop the script and close the GTK window.
10	End the function declaration.
11	Create a new window object called $window.
12	Connect the destroy method of the window to the destroy() function that you defined earlier. The destroy method is called when the user clicks the "X" on the top right of the window.
13	Issue the show_all() function call to the $window object so that everything within the object is displayed.
14	Call the Gtk::main() method to run the script.

Adding a GTK Button

The simplest and most basic example in all of programming is the Hello World example. The goal of the example, if you didn't know, is to get the program to print out the words "Hello, World!" We are going to enhance our Hello World program slightly. Instead of merely printing out "Hello World," let's add that text to a button. When the button is clicked, we'll close our application. Try out this example, then look at the brief line-by-line explanation for details. Figure 12-3 shows the output of the script in Linux and in Windows.

Script 12-2 hello.php

  1.  <?php  2.  if (!class_exists('gtk')) {  3.    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')  4.      dl('php_gtk.dll');  5.    else  6.      dl('php_gtk.so');  7.  }  8.  function destroy() {  9.    Gtk::main_quit(); 10.  } 11.  function hello(){ 12.    global $window; 13.    print "Hello World!\n"; 14.    $window->destroy(); 15.  } 16.  $window = &new GtkWindow(); 17.  $window->connect('destroy', 'destroy'); 18.  $button = &new GtkButton('Hello World!'); 19.  $button->connect('clicked', 'hello'); 20.  $window->add($button); 21.  $window->show_all(); 22.  Gtk::main(); 23. ? > 

Figure 12-3. hello.php in Linux (Gnome) and Windows

Script 12-2. hello.php Line-by-Line Explanation

LINE	DESCRIPTION
2	If the GTK class has not been defined, then execute lines 3 7. If the GTK class has been defined, then the script needs to do nothing.
3	Check the first three characters of the PHP_OS environment variable.
4	If it is WIN, then the system is running Windows. Load the PHPGTK library for Windows.
5 7	If the PHP_OS environment variable is not WIN, then assume that PHP is running on a Linux system and load the Linux PHPGTK library.
8 10	Define a function, destroy(), that stops the script when called.
9	Execute the Gtk::main_quit() method to stop the script and close the GTK window.
10	End the function declaration.
11 14	Define a function, hello(), that prints the text "Hello World!"
12	Allow the $window object to be accessed by this function.
13	Print the text "Hello World!" to STDOUT (the same command line from which you executed the script).
14	Use the destroy() method on the $window object to close the window.
15	End the function declaration.
16	Create a new window object called $window.
17	Connect the 'destroy' method of the window to the destroy() function that you defined earlier. The 'destroy' method is called when the user clicks the "X" on the top right of the window.
18	Create a new button object called $button.
19	Connect the 'clicked' method of the button to the hello() function.
20	Add the button to the window using the add() method.
21	Issue the show_all() function call to the $window object so that everything within the object is displayed.
22	Call the Gtk::main() method to run the script.

Modifying Basic Widget Appearance

The syntax for creating buttons and windows looks very similar. That is because they are both classes of a GTK widget. Each object (buttons, windows, etc.) has certain methods available to them for example, the connect() method.

If you run the hello.php script, you will notice that the window size is pretty small in fact, it is only as big as the button inside it. That's because PHP shrinks the window to the smallest size possible when creating it. We can modify the default appearance of the GtkWindow widget by using some methods. For example, if you wanted to set a default size for the window, you could use the set_default_size($width, $height)method:

 $window->set_default_size(200,200);  

This would create a window that is 200 pixels by 200 pixels. You can also set a window title:

 $window->set_title("My PHPGTK APP");  

Figure 12-4 shows a window modified by the set_default _size() and set_title() methods.

Figure 12-4. Window modified with property methods (Linux and Windows)

There are many methods available that can affect the appearance and behavior of GTK widgets. See the documentation on http://gtk.php.net for details on these methods.

Text Entry

A desktop application wouldn't be too useful if you couldn't insert data into it. GTK provides a text entry widget that allows you to input a line of text to your application. To create a text entry field:

 $text1 = &new GtkEntry();  

A text entry field isn't really useful unless you have some way to label it. That's where the GtkLabel comes in handy:

 $label1 = &new GtkLabel("A Text Entry Field:");  

Now that we have our new text entry field and a label, we need to put it into our window. There's a slight problem, though. You just can't add() multiple widgets into the top-level window. Instead, you place a box into the window, and add your subobjects into that box.

hbox and vbox

There are two types of boxes that you can use to hold your widgets in place within the main window. They are the hbox (horizontal) and the vbox (vertical). As their names imply, the hbox allows you to place objects into it so that the objects are aligned horizontally, and the vbox allows you to place objects into it so that the objects are aligned vertically. Since we want to align our text entry field and label horizontally (like normal applications do), we'll create an hbox and add it to our window, then pack the label and text entry field into the box:

 $box = &new GtkHBox();  $window->add($box); 

The hbox and vbox widgets are special containers into which you can add multiple widgets. To add them, you need to pack the widgets into the box:

 $box->pack_start($label1, false, false, 0);  $box->pack_start($text1, false, false, 0); 

pack_start

The pack_start method allows you to add the widgets into the box. If you are packing widgets into vbox, then pack_start adds the widgets from the top of the box. Each time you pack another widget into the box, the preceding widget is moved down and the newly added widget is at the top of the vbox. If you are packing widgets into an hbox, then pack_start adds the widgets into the box from the left. Each time you pack a new widget into the box, it is placed to the right of the preceding widget.

The pack_start() method takes four arguments:

• The object you are packing.

• Whether or not to expand the object if the box is resized (true or false).

• Whether or not the object should fill the space which is available to it (true or false).

• The amount of padding to use around the object (an integer).

The default arguments used, if none are specified, are true, true, 0. These mean to expand and fill and use no padding.

Let's look at a script the uses the label and text entry field. See Script 12-3, text_entry.php, below. See Figure 12-5 for the example output.

Script 12-3 text_entry.php

  1.  <?php  2.    if (!class_exists('gtk')) {  3.    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')  4.      dl('php_gtk.dll');  5.    else  6.      dl('php_gtk.so');  7.  }  8.  function destroy(){  9.    Gtk::main_quit(); 10.  } 11.  $window = &new GtkWindow(); 12.  $window->connect('destroy', 'destroy'); 13.  $text1 = &new GtkEntry(); 14.  $label1 = &new GtkLabel("A Text Entry Field"); 15.  $box = &new GtkHBox(); 16.  $window->add($box); 17.  $box->pack_start($label1, false, false, 0); 18.  $box->pack_start($text1, false, false, 0); 19.  $window->show_all(); 20.  Gtk::main(); 21.  ?> 

Figure 12-5. text_entry.php

Script 12-3. text_entry.php Line-by-Line Explanation

LINE	DESCRIPTION
2	If the GTK class has not been defined, then execute lines 3 7. If the GTK class has been defined, then the script needs to do nothing.
3	Check the first three characters of the PHP_OS environment variable.
4	If it is WIN, then the system is running Windows. Load the PHPGTK library for Windows.
5 7	If the PHP_OS environment variable is not WIN, then assume that PHP is running on a Linux system and load the Linux PHPGTK library.
8 10	Define a function, destroy(), that stops the script when called.
9	Execute the Gtk::main_quit() method to stop the script and close the GTK window.
10	End the function declaration.
11	Create a new window object called $window.
12	Connect the 'destroy' method of the window to the destroy() function that you defined earlier. The 'destroy' method is called when the user clicks the "X" on the top right of the window.
13	Create a new text-entry object called $text1.
14	Create a new label object called $label1 containing the text "A Text Entry Field".
15	Create a new horizontal box object called $box.
16	Add the box to the window using the add() method.
17	Pack the label object into the box.
18	Pack the text-entry object into the box.
19	Issue the show_all() function call to the $window object so that everything within the object is displayed.
20	Call the Gtk::main() method to run the script.

---

   

Top