NAME

       Gtk2::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 ALSO

       perl(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.