.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Gtk2::Helper 3pm"
.TH Gtk2::Helper 3pm "2019-09-16" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Gtk2::Helper \- Convenience functions for the Gtk2 module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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 )
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
This module collects Gtk2 helper functions, which should make
implementing some common tasks easier.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Gtk2::Helper\->add_watch ( ... )"
.IX Subsection "Gtk2::Helper->add_watch ( ... )"
.Vb 1
\&  $tag = Gtk2::Helper\->add_watch ( $fd, $cond, $callback, $data )
.Ve
.PP
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.
.ie n .IP "$fd" 4
.el .IP "\f(CW$fd\fR" 4
.IX Item "$fd"
Unix file descriptor to be watched. If you use the FileHandle
module you get this value from the FileHandle\->\fBfileno()\fR method.
.ie n .IP "$cond" 4
.el .IP "\f(CW$cond\fR" 4
.IX Item "$cond"
May be either 'in' or 'out', depending if you want to read from
the filehandle ('in') or write to it ('out').
.ie n .IP "$callback" 4
.el .IP "\f(CW$callback\fR" 4
.IX Item "$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.
.Sp
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 \fBsysread()\fR and
\&\fBsyswrite()\fR 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.
.Sp
The callback subroutine should return always true. Two signal
watchers are connected internally (the I/O watcher, and a \s-1HUP\s0
watcher, which is called on \fBeof()\fR 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.
.Sp
(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 \*(L"1;\*(R" at the end of your callback
solves this problem? ;)
.ie n .IP "$data" 4
.el .IP "\f(CW$data\fR" 4
.IX Item "$data"
This data is passed to the callback.
.ie n .IP "$tag" 4
.el .IP "\f(CW$tag\fR" 4
.IX Item "$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.
.PP
\&\fBExample:\fR
.PP
.Vb 4
\&  # open a pipe to a ls command
\&  use FileHandle;
\&  my $fh = FileHandle\->new;
\&  open ($fh, "ls \-l |") or die "can\*(Aqt fork";
\&
\&  # install a read watcher for this pipe
\&  my $tag;
\&  $tag = Gtk2::Helper\->add_watch ( $fh\->fileno, \*(Aqin\*(Aq, 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\*(Aqt remove watcher";
\&        close($fh);
\&        return 1;
\&      }
\&
\&      # do something with $buffer ...
\&      print $buffer;
\&
\&      # *always* return true
\&      return 1;
\&  }
.Ve
.SS "Gtk2::Helper\->remove_watch ( ... )"
.IX Subsection "Gtk2::Helper->remove_watch ( ... )"
.Vb 1
\&  $rc = Gtk2::Helper\->remove_watch ( $tag )
.Ve
.PP
This method removes a watcher, which was created using
Gtk2::Helper\->\fBadd_watch()\fR.
.ie n .IP "$tag" 4
.el .IP "\f(CW$tag\fR" 4
.IX Item "$tag"
This is the tag returned from Gtk2::Helper\->\fBadd_watch()\fR.
.ie n .IP "$rc" 4
.el .IP "\f(CW$rc\fR" 4
.IX Item "$rc"
The method returns true, if the watcher could be removed
successfully, and false if not.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBGtk2\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
Jörn Reder <joern \s-1AT\s0 zyn.de>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003 by Jörn Reder
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 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.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0
Library General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Library General Public
License along with this library; if not, write to the 
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 
Boston, \s-1MA\s0  02110\-1301  \s-1USA.\s0