1pm::Helper(3)         User Contributed Perl Documentation        pm::Helper(3)
2
3
4

NAME

6       Gtk2::Helper - Convenience functions for the Gtk2 module
7

SYNOPSIS

9         use Gtk2::Helper;
10
11         # Handle I/O watchers easily, like Gtk 1.x did
12         $tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
13         $rc  = Gtk2::Helper->remove_watch ( $tag )
14

ABSTRACT

16       This module collects Gtk2 helper functions, which should make imple‐
17       menting some common tasks easier.
18

DESCRIPTION

20       Gtk2::Helper->add_watch ( ... )
21
22         $tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
23
24       This method is a wrapper for Glib::IO->add_watch. The callback is
25       called every time when it's safe to read from or write to the watched
26       filehandle.
27
28       $fd Unix file descriptor to be watched. If you use the FileHandle mod‐
29           ule you get this value from the FileHandle->fileno() method.
30
31       $cond
32           May be either 'in' or 'out', depending if you want to read from the
33           filehandle ('in') or write to it ('out').
34
35       $callback
36           A subroutine reference or closure, which is called, if you can
37           safely operate on the filehandle, without the risk of blocking your
38           application, because the filehandle is not ready for reading resp.
39           writing.
40
41           But aware: you should not use Perl's builtin read and write func‐
42           tions here because these operate always with buffered I/O. Use low
43           level sysread() and syswrite() instead. Otherwise Perl may read
44           more data into its internal buffer as your callback actually con‐
45           sumes. But Glib won't call the callback on data which is already in
46           Perl's buffer, only when events on the the underlying Unix file
47           descriptor occur.
48
49           The callback subroutine should return always true. Two signal
50           watchers are connected internally (the I/O watcher, and a HUP
51           watcher, which is called on eof() or other exceptions). Returning
52           false from a watcher callback, removes the correspondent watcher
53           automatically. Because we have two watchers internally, only one of
54           them is removed, but probably not both. So always return true and
55           use Gtk2::Helper->remove_watch to disable a watcher, which was
56           installed with Gtk2::Helper->add_watch.
57
58           (Gtk2::Helper could circumvent this by wrapping your callback with
59           a closure returning always true. But why adding another level of
60           indirection if writing a simple "1;" at the end of your callback
61           solves this problem? ;)
62
63       $data
64           This data is passed to the callback.
65
66       $tag
67           The method returns a tag which represents the created watcher.
68           Later you need to pass this tag to Gtk2::Helper->remove_watch to
69           remove the watcher.
70
71       Example:
72
73         # open a pipe to a ls command
74         use FileHandle;
75         my $fh = FileHandle->new;
76         open ($fh, "ls -l ⎪") or die "can't fork";
77
78         # install a read watcher for this pipe
79         my $tag;
80         $tag = Gtk2::Helper->add_watch ( $fh->fileno, 'in', sub {
81           watcher_callback( $fh, $tag );
82         });
83
84         sub watcher_callback {
85             my ($fh, $tag) = @_;
86
87             # we safely can read a chunk into $buffer
88             my $buffer;
89
90             if ( not sysread($fh, $buffer, 4096) ) {
91               # obviously the connected pipe was closed
92               Gtk2::Helper->remove_watch ($tag)
93                   or die "couldn't remove watcher";
94               close($fh);
95               return 1;
96             }
97
98             # do something with $buffer ...
99             print $buffer;
100
101             # *always* return true
102             return 1;
103         }
104
105       Gtk2::Helper->remove_watch ( ... )
106
107         $rc = Gtk2::Helper->remove_watch ( $tag )
108
109       This method removes a watcher, which was created using
110       Gtk2::Helper->add_watch().
111
112       $tag
113           This is the tag returned from Gtk2::Helper->add_watch().
114
115       $rc The method returns true, if the watcher could be removed success‐
116           fully, and false if not.
117

SEE ALSO

119       perl(1), Gtk2(1)
120

AUTHOR

122       Jörn Reder <joern AT zyn.de>
123

125       Copyright 2003 by Jörn Reder
126
127       This library is free software; you can redistribute it and/or modify it
128       under the terms of the GNU Library General Public License as published
129       by the Free Software Foundation; either version 2.1 of the License, or
130       (at your option) any later version.
131
132       This library is distributed in the hope that it will be useful, but
133       WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
134       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
135       General Public License for more details.
136
137       You should have received a copy of the GNU Library General Public
138       License along with this library; if not, write to the Free Software
139       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
140       USA.
141
142
143
144perl v5.8.8                       2007-03-18                     pm::Helper(3)
Impressum