1Gtk2::Helper(3) User Contributed Perl Documentation Gtk2::Helper(3)
2
3
4
6 Gtk2::Helper - Convenience functions for the Gtk2 module
7
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
16 This module collects Gtk2 helper functions, which should make
17 implementing some common tasks easier.
18
20 Gtk2::Helper->add_watch ( ... )
21 $tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
22
23 This method is a wrapper for Glib::IO->add_watch. The callback is
24 called every time when it's safe to read from or write to the watched
25 filehandle.
26
27 $fd Unix file descriptor to be watched. If you use the FileHandle
28 module you get this value from the FileHandle->fileno() method.
29
30 $cond
31 May be either 'in' or 'out', depending if you want to read from the
32 filehandle ('in') or write to it ('out').
33
34 $callback
35 A subroutine reference or closure, which is called, if you can
36 safely operate on the filehandle, without the risk of blocking your
37 application, because the filehandle is not ready for reading resp.
38 writing.
39
40 But aware: you should not use Perl's builtin read and write
41 functions here because these operate always with buffered I/O. Use
42 low level sysread() and syswrite() instead. Otherwise Perl may read
43 more data into its internal buffer as your callback actually
44 consumes. But Glib won't call the callback on data which is already
45 in Perl's buffer, only when events on the the underlying Unix file
46 descriptor occur.
47
48 The callback subroutine should return always true. Two signal
49 watchers are connected internally (the I/O watcher, and a HUP
50 watcher, which is called on eof() or other exceptions). Returning
51 false from a watcher callback, removes the correspondent watcher
52 automatically. Because we have two watchers internally, only one of
53 them is removed, but probably not both. So always return true and
54 use Gtk2::Helper->remove_watch to disable a watcher, which was
55 installed with Gtk2::Helper->add_watch.
56
57 (Gtk2::Helper could circumvent this by wrapping your callback with
58 a closure returning always true. But why adding another level of
59 indirection if writing a simple "1;" at the end of your callback
60 solves this problem? ;)
61
62 $data
63 This data is passed to the callback.
64
65 $tag
66 The method returns a tag which represents the created watcher.
67 Later you need to pass this tag to Gtk2::Helper->remove_watch to
68 remove the watcher.
69
70 Example:
71
72 # open a pipe to a ls command
73 use FileHandle;
74 my $fh = FileHandle->new;
75 open ($fh, "ls -l |") or die "can't fork";
76
77 # install a read watcher for this pipe
78 my $tag;
79 $tag = Gtk2::Helper->add_watch ( $fh->fileno, 'in', sub {
80 watcher_callback( $fh, $tag );
81 });
82
83 sub watcher_callback {
84 my ($fh, $tag) = @_;
85
86 # we safely can read a chunk into $buffer
87 my $buffer;
88
89 if ( not sysread($fh, $buffer, 4096) ) {
90 # obviously the connected pipe was closed
91 Gtk2::Helper->remove_watch ($tag)
92 or die "couldn't remove watcher";
93 close($fh);
94 return 1;
95 }
96
97 # do something with $buffer ...
98 print $buffer;
99
100 # *always* return true
101 return 1;
102 }
103
104 Gtk2::Helper->remove_watch ( ... )
105 $rc = Gtk2::Helper->remove_watch ( $tag )
106
107 This method removes a watcher, which was created using
108 Gtk2::Helper->add_watch().
109
110 $tag
111 This is the tag returned from Gtk2::Helper->add_watch().
112
113 $rc The method returns true, if the watcher could be removed
114 successfully, and false if not.
115
117 perl(1), Gtk2(1)
118
120 Jörn Reder <joern AT zyn.de>
121
123 Copyright 2003 by Jörn Reder
124
125 This library is free software; you can redistribute it and/or modify it
126 under the terms of the GNU Library General Public License as published
127 by the Free Software Foundation; either version 2.1 of the License, or
128 (at your option) any later version.
129
130 This library is distributed in the hope that it will be useful, but
131 WITHOUT ANY WARRANTY; without even the implied warranty of
132 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
133 Library General Public License for more details.
134
135 You should have received a copy of the GNU Library General Public
136 License along with this library; if not, write to the Free Software
137 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
138 02110-1301 USA.
139
140
141
142perl v5.34.0 2022-01-21 Gtk2::Helper(3)