Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Gtk2::Helper(3)	      User Contributed Perl Documentation      Gtk2::Helper(3)

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
       JA<paragraph>rn Reder <joern AT zyn.de>

COPYRIGHT AND LICENSE
       Copyright 2003 by JA<paragraph>rn 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., 51 Franklin Street, Fifth Floor, Boston, MA
       02110-1301  USA.

perl v5.32.1			  2017-05-21		       Gtk2::Helper(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Gtk2::Helper&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help