Gtk2::Helper(3)

💖 Gtk2::Helper 💖

okay bestie, gather round, because we're talking about Gtk2::Helper — the little User Contributed Perl Documentation gem that's literally just a bag of convenience functions for the Gtk2 module. it's giving helpful. it's giving "i gotchu." 🫶

---

✨ NAME ✨

Gtk2::Helper — Convenience functions for the Gtk2 module. that's it. that's the whole name. short, sweet, iconic. 👑

---

🌸 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 )

see that comment? "like Gtk 1.x did" — the nostalgia is real, the convenience is realer. 💅

---

🦋 ABSTRACT 🦋

This module collects Gtk2 helper functions, which should make implementing some common tasks easier. that's the whole vibe: it's a lil collection box of helpers so you don't have to do everything the hard way. no cap. ✨

---

🎀 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. like, it taps you on the shoulder only when the filehandle is actually ready — no awkward blocking, no standing around at a party nobody's at. 🎉

• $fd — Unix file descriptor to be watched. If you use the FileHandle module you get this value from the FileHandle->fileno() method. that's the plug. 🔌
• $cond — May be either 'in' or 'out', depending if you want to read from the filehandle ('in') or write to it ('out'). in = reading era, out = writing era. simple as that. 🌈
• $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. 💀 yeah this is the part where buffering betrays you. use the low-level ones, bestie, i'm begging.

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? ;)

😭 so real. just return 1;. it costs you nothing and it saves you everything. return true or perish (metaphorically). 🫶

• $data — This data is passed to the callback. lil gift, lil payload, lil carry-on. 🎁
• $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. hold onto this tag like it's your iced coffee order — you'll need it later. 🧊

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;
}

see the sysread? see the return 1? we love a callback that respects the rules. ate and left no crumbs. 🔥

---

🧚 Gtk2::Helper->remove_watch ( ... )

$rc = Gtk2::Helper->remove_watch ( $tag )

This method removes a watcher, which was created using Gtk2::Helper->add_watch(). it's the breakup function. clean, respectful, no lingering watchers. 💔➡️✨

• $tag — This is the tag returned from Gtk2::Helper->add_watch(). yeah, the one i told you to hold onto. told you. 💅
• $rc — The method returns true, if the watcher could be removed successfully, and false if not. true = slay, false = it did not slay, check your tag bestie. 🎀

---

⭐ SEE ALSO ⭐

perl(1), Gtk2(1)

---

👑 AUTHOR 👑

Jörn Reder <joern AT zyn.de>

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright 2003 by Jö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.

🚨 bestie read the caps: WITHOUT ANY WARRANTY. fr fr. the law has spoken. 💀

---

aaaand that's the whole page, no notes. this was documented by the fine folks behind perl v5.42.0, dated 2025-07-25, and it lives in the Gtk2::Helper(3) section of your friendly neighborhood manual. go forth and watch your filehandles responsibly. mwah. 💖🦋✨