Gtk2::Helper 1.122

Gtk2::Helper is a Perl module for convenience functions for the Gtk2 module.

SYNOPSIS

use Gtk2::Helper;

# Handle I/O watchers easily, like Gtk 1.x did
$tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
$rc = Gtk2::Helper->remove_watch ( $tag )

ABSTRACT

This module collects Gtk2 helper functions, which should make implementing some common tasks easier.

Gtk2::Helper->add_watch ( ... )

$tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )

This method is a wrapper for Glib::IO->add_watch. The callback is called every time when its safe to read from or write to the watched filehandle.

$fd

Unix file descriptor to be watched. If you use the FileHandle module you get this value from the FileHandle->fileno() method.

$cond

May be either in or out, depending if you want to read from the filehandle (in) or write to it (out).

$callback

A subroutine reference or closure, which is called, if you can safely operate on the filehandle, without the risk of blocking your application, because the filehandle is not ready for reading resp. writing.

But aware: you should not use Perls builtin read and write functions here because these operate always with buffered I/O. Use low level sysread() and syswrite() instead. Otherwise Perl may read more data into its internal buffer as your callback actually consumes. But Glib wont call the callback on data which is already in Perls buffer, only when events on the the underlying Unix file descriptor occur.

The callback subroutine should return always true. Two signal watchers are connected internally (the I/O watcher, and a HUP watcher, which is called on eof() or other exceptions). Returning false from a watcher callback, removes the correspondent watcher automatically. Because we have two watchers internally, only one of them is removed, but probably not both. So always return true and use Gtk2::Helper->remove_watch to disable a watcher, which was installed with Gtk2::Helper->add_watch.

(Gtk2::Helper could circumvent this by wrapping your callback with a closure returning always true. But why adding another level of indirection if writing a simple "1;" at the end of your callback solves this problem? ;)

$data

This data is passed to the callback.

$tag

The method returns a tag which represents the created watcher. Later you need to pass this tag to Gtk2::Helper->remove_watch to remove the watcher.