pm::Helper(3) User Contributed Perl Documentation pm::Helper(3)NAMEGtk2::Helper - 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.
DESCRIPTION
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 it's 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 Perl's 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 won't call the callback on data which is already
in Perl's 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.
Example:
# open a pipe to a ls command
use FileHandle;
my $fh = FileHandle->new;
open ($fh, "ls -l |") or die "can't fork";
# install a read watcher for this pipe
my $tag;
$tag = Gtk2::Helper->add_watch ( $fh->fileno, 'in', sub {
watcher_callback( $fh, $tag );
});
sub watcher_callback {
my ($fh, $tag) = @_;
# we safely can read a chunk into $buffer
my $buffer;
if ( not sysread($fh, $buffer, 4096) ) {
# obviously the connected pipe was closed
Gtk2::Helper->remove_watch ($tag)
or die "couldn't remove watcher";
close($fh);
return 1;
}
# do something with $buffer ...
print $buffer;
# *always* return true
return 1;
}
Gtk2::Helper->remove_watch ( ... )
$rc = Gtk2::Helper->remove_watch ( $tag )
This method removes a watcher, which was created using
Gtk2::Helper->add_watch().
$tag
This is the tag returned from Gtk2::Helper->add_watch().
$rc The method returns true, if the watcher could be removed
successfully, and false if not.
SEE ALSOperl(1), Gtk2(1)AUTHOR
Joern Reder <joern AT zyn.de>
COPYRIGHT AND LICENSE
Copyright 2003 by Joern Reder
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
USA.
perl v5.10.0 2005-03-22 pm::Helper(3)
