NAME

Gtk2::Ex::IdleObject -- oop Glib idle calls

SYNOPSIS

 use Gtk2::Ex::IdleObject;

 # idle as a perl object
 $idle = Gtk2::Ex::IdleObject->new (callback => \&my_callback);

 # idle on a widget, firing for as long as the widget lives
 $idle = Gtk2::Ex::IdleObject->new (callback => \&my_callback,
                                    userdata => $my_widget,
                                    weak     => 1);

 $idle->stop;    # explicit stop
 $idle = undef;  # or just drop it

DESCRIPTION

Gtk2::Ex::IdleObject is an object-oriented wrapper around the Glib::Idle->add mechanism. It automatically removes the idle from the main loop just by forgetting the object, and an idle object can be associated with a widget to have it stop if/when that widget is destroyed.

Automatic removal saves you fiddling about with Glib::Source->remove in a cleanup, and the widget version uses weak references so the widget doesn't stay alive forever just because it's in an idle handler.

FUNCTIONS

Gtk2::Ex::IdleObject->new ($callback, [$userdata, [$priority]])

Create and return a new idle object. The parameters are the same as for Glib::Idle->add, but the return is an object instead of an ID number.

Gtk2::Ex::IdleObject->new_weak ($callback, [$userdata, [$priority]])

Create and return a new idle object which keeps only a weak reference to its $userdata, if $userdata is a reference.

If the $userdata object is being used nowhere other than the idle then it's garbage collected and the idle makes no further $callback calls. This is an easy way to ensure the mere fact an idle is operating on a Perl object won't keep it alive when nothing else is interested in it.

If $userdata is not a reference then new_weak is the same as plain new above.

Gtk2::Ex::IdleObject->new_for_widget ($callback, $widget, [$priority])

Create and return a new idle object with a Gtk2::Widget as the $userdata. The idle keeps only a weak reference to the widget, so that if/when it's no longer used anywhere else then the widget is destroyed and the idle stops.

This is the same as new_weak above, except that it can use the widget destroy signal to immediately remove the idle from the Glib main loop, whereas the new_weak only notices the object gone at the next idle call. In practice this makes very little difference, but it gets defunct idles out of the main loop sooner.

The idle object can be stored in the instance data of the widget without creating a circular reference. In fact that's the recommended place to keep it since then the idle is garbage collected at the same time as the widget.

    $widget->{'my_idle'} = Gtk2::Ex::IdleObject->new
                                (\&my_idle_callback, $widget);

$idle->stop

Stop $idle, so no further calls to its $callback will be made. stop can be called either inside or outside the $callback function, though of course from inside the callback it also suffices to return 0 to have the idle stop, in the usual way.

OTHER NOTES

The idle object is currently implemented as a Perl object holding the idle ID from Glib::Idle->add. If GSource was available at the Perl level in the future then perhaps Gtk2::Ex::IdleObject could use that.

SEE ALSO

Glib::MainLoop