`Gtk2-Perl` Study Guide: Gaining an understanding of `Gtk2-Perl`
Prev		Next

Chapter 3. Documentation

This chapter will teach you how to find your way around the POD (Plain Old Documentation). To find out more about POD and nice utilities available to you as programmer, Appendix B is your friend.

The POD is online here. You may also have it available on the machine where you installed Gtk2-Perl on. It will be in the form of man pages.

If you have the Konqueror browser on your machine, you can type "#Gtk2" in the Location and should get a list of available man pages to choose from.

3.1. Looking at a sample

In this sample we will look at Gtk2::Window.

Figure 3-1. Man page of Gtk2::Window

3.1.1. Hierarchy

One important category is "Hierarchy". It shows the inheritance that the Gtk2::Window class has. Knowing a widget's "Hierarchy" will ease working with it. If you require the widget to do something, and that something is not in the widget's own documentation, you are advised to check higher up in the hierarchy. Lets take the previous "Hello Gtk2-Perl" as a sample. We added an instance of the Gtk2::Button class to an instance of the Gtk2::Window class

($window->add ($button);)

The Gtk2::Window is a sub-class of the Gtk2::Container class. The add method belongs to the Gtk2::Container class.

3.1.2. Methods

The methods listed are also quick to understand. Lets take the Gtk2::Window as an example again.

The first method listed is the new method.

widget = Gtk2::Window->new ($type=GTK_WINDOW_TOPLEVEL) 
	* $type (Gtk2::WindowType)

Thus, to create an instance of the Gtk2::Window class, you also need to specify $type. $type must be of variable Gtk2::WindowType. This variable does not have its own man page. The bottom of the Gtk2::Window man page contains a section:

ENUMS AND FLAGS

This section contains more information on the Gtk2::WindowType variable:

enum Gtk2::WindowType 
	'toplevel' / 'GTK_WINDOW_TOPLEVEL'
	'popup' / 'GTK_WINDOW_POPUP'

$type can either be toplevel or popup. You can specify toplevel or GTK_WINDOW_TOPLEVEL.

Default values

You will notice that some methods specify a value in the parentheses. In the Gtk2::Window class, we see the following "($type=GTK_WINDOW_TOPLEVEL)". This will fall back to the listed value, if none is specified.

my $window = Gtk2::Window->new;

is the same as:

my $window = Gtk2::Window->new ('toplevel');

which is the same as:

my $window = Gtk2::Window->new ('GTK_WINDOW_TOPLEVEL');

As a final word on methods, you will find that there are some methods which barely gets used. The more you work with the toolkit, the more familiar you will get with the popular methods.

3.1.3. Properties

The properties of a class can not be directly manipulated. They are gathered and changed via class methods.

Let us refer to the Gtk2::Window class. The property that influences the position is the

'window-position' (Gtk2::WindowPosition : readable / writable) property.

You change (or set) it via the following method:

$window->set_position ($position)

$position (Gtk2::WindowPosition)

The Gtk2::WindowPosition variable is then specified at the bottom of the man page as:

	enum Gtk2::WindowPosition
		'none' / 'GTK_WIN_POS_NONE'
		'center' / 'GTK_WIN_POS_CENTER'
		'mouse' / 'GTK_WIN_POS_MOUSE'
		'center-always' / 'GTK_WIN_POS_CENTER_ALWAYS'
		'center-on-parent' / 'GTK_WIN_POS_CENTER_ON_PARENT'

The window is set to the center stage by the following line:

	$window->set_position('center');

You may find that the properties listed on a man page can not be changed or gathered using any available methods on the man page.

Because all Gtk2 objects stem from Glib::Object, you can use the $object->get_property (...) method to get, and the $object->set_property (key => $value, ...) method to set the property of a class.

3.1.4. Signals

Not all man pages has signals

The signals of a widget are those interesting happenings in a widget's life. It gets created, clicked upon, moved around on the screen, change value or size etc. Lets take the Gtk2::Button as an example this time. Under Signals in the man page, you can find the following:

clicked (Gtk2::Button)

This on its own is not of much use. You have to connect the signal to a sub procedure. The sub procedure will execute the necessary code the moment the signal is triggered. This makes your application more functional. IE To print a line each time the button gets clicked:

$button->signal_connect (clicked => sub { print("Hello Gtk2-Perl\n"); });

The above line connects the clicked signal to the sub that follows. This can be an anonymous sub or a reference to a sub created elsewhere:

$button->signal_connect (clicked => \&print_hello,$userdata);

On the Gtk2::Button man page you will notice that after the 'clicked' is a (Gtk2::Button). This is the first variable that gets passed to the sub procedure. In the button's case, it is a reference to the object instance on which the event occurred. $userdata allows you to pass an extra argument. This $userdata argument is implicitly appended to the signal's documented argument list.

It is important to remember that, just as in the case of the methods, the signals are also inherited from higher classes.

IE Gtk2::ToggleButton, is a sub-class of Gtk2::Button. This means that ALL Gtk2::Button's signals will also be available to Gtk2::ToggleButton, on top of it's own toggled ( Gtk2::ToggleButton) signal.

3.1.5. ENUMS AND FLAGS

Methods like widget = Gtk2::Window->new ($type=GTK_WINDOW_TOPLEVEL) requires values for $type where the value must be of type Gtk2::WindowType.

On the Gtk2::Window man page Gtk2::WindowType is specified:

	enum Gtk2::WindowType 
	* 'toplevel' / 'GTK_WINDOW_TOPLEVEL'
 	* 'popup' / 'GTK_WINDOW_POPUP'

Some of the entries here are also like the methods that hardly ever gets used.

To see all the available ENUMS AND FLAGS used in Gtk2-Perl, refer to Gtk2::enums

Prev	Home	Next
The trivial "Hello `Gtk2-Perl` "		The packing problem