1Gtk2::Helper(3)       User Contributed Perl Documentation      Gtk2::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
17       implementing some common tasks easier.
18

DESCRIPTION

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

SEE ALSO

117       perl(1), Gtk2(1)
118

AUTHOR

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.38.0                      2023-07-20                   Gtk2::Helper(3)
Impressum