view release on metacpan or  search on metacpan

Gtk/cookbook.pod  view on Meta::CPAN

A good introduction to object oriented programming in Perl is available in
the perltoot manpage.

One fundamental concept in Gtk programming is I<signals>: objects
emit a signal whenever something interesting happens to them, for
example when a button is clicked or when a window is closed, or when
an item in a list is selected and so on (note that these signals have nothing
to do with POSIX signals). Every kind of widgets has a set of
signals and you can connect to a signal emission to run your code or
even to stop the signal. In the same way methods are inherited by derived
classes, signals may be defined in a base class and they are available to
derived classes, too.

=head2 Event-driven programming concepts in Gtk

To take advantage of the Gtk module you also need to understand event-driven programming:
this means that you tell the toolkit to wake your program up whenever
something interesting happens and then let it wait for the events to happen
in the so-called main loop (with a call to C<Gtk-E<gt>main()>).

When you tell the library you are interested in an event, you hand it a
subroutine to be called whenever that event happens. The subroutine
(often called handler) will receive as arguments the data specific to
the event (if any) and any additional data you passed in when installing the
handler. See below for specific examples.

Note that you can use as handler a subroutine name, an anonymous
subroutine or a subroutine reference.

There are several events that you may be interested in:

=over 4

=item * Timeout events 

To execute code after a certain amount of time.

	sub handler {
		my ($data) = @_;
		# do something here ...
		# return 1 if you want the handler to be called again later
		# return 0 to stop the handler from being called again
		return 0;
	}
	my $data = "yadda";
	# execute handler after 1000 milliseconds
	my $id = Gtk->timeout_add(1000, \&handler, $data);

You may remove the timeout handler by returning a FALSE value from it or
at any time by calling 

	Gtk->timeout_remove($id);

where C<$id> is the value returned by the C<Gtk-E<gt>timeout_add()> call.

Note that the first value to the C<Gtk-E<gt>timeout_add()> call is the timeout in
milliseconds.

=item * Idle events 

To execute code whenever the toolkit is not busy handling other events.

	sub handler {
		my ($data) = @_;
		# do something here ...
		# return 1 if you want the handler to be called again
		# return 0 to stop the handler from being called again
		return 0;
	}
	my $data = "yadda";
	# execute handler when there aren't other events to service
	my $id = Gtk->idle_add(\&handler, $data);

You may remove the idle handler by returning a FALSE value from it or
at any time by calling 

	Gtk->idle_remove($id);

where C<$id> is the value returned by the C<Gtk-E<gt>idle_add()> call.

=item * I/O events

To execute code when a pipe or socket is ready to be read or written to.

	sub io_handler {
		my ($socket, $fd, $flags) = @_;
		# check here $flags to see if the events we are
		# actually interested in happened.
		# You probably also need a state machine (represented
		# here with the $need_read and $need_write scalars).
		if ($flags->{'read'} && $need_read) {
			$socket->sysread($buffer, 1024);
		} elsif ($flags->{'write'} && $need_write) {
			$socket->syswrite($buffer, length($buffer));
		}
	}
	my $socket = new IO::Socket::INET(PeerAddr => 'www.gtk.org:80');
	my $id = Gtk::Gdk->input_add($socket->fileno, ['read', 'write'], 
		\&io_handler, $socket);

You may remove an I/O handler at any time by calling

	Gtk::Gdk->input_remove($id);

where C<$id> is the value returned by the C<Gtk::Gdk-E<gt>input_add()> call.

Note that the I/O handler subroutine gets the additional data as first arguments
and then the handler-specific data, unlike the other more common signal handlers
the get the signal-specific data first.

The first argument to input_add() is an integer file descriptor (see the fileno()
function description in the perlfunc manpage). The second argument is an
array reference that may contain the 'read', 'write' and/or 'exception' strings
if you want your handler to be called when you can read or write or when you get
an exception on the file descriptor, respectively.

=item * Perl scalar changes

To execute code whenever the value of a Perl scalar is changed.

=item * Gtk signals