NAME

Gtk2::Ex::TimerObject -- oop Glib timer

SYNOPSIS

 use Gtk2::Ex::TimerObject;
 my $timer = Gtk2::Ex::TimerObject->new
     (period   => 1000,    # milliseconds
      callback => \&my_func,
      userdata => 'some value');

 # or weak reference to a widget
 my $timer = Gtk2::Ex::TimerObject->new
     (period        => 500,
      run           => 0,    # start off stopped too
      callback      => \&my_update_func,
      userdata      => $widget,
      weak_userdata => 1);

 $timer->set_period (100);
 $timer->start;
 $timer->stop;

DESCRIPTION

Gtk2::Ex::TimerObject is an object-oriented wrapper around the Glib::Timeout->add timer mechanism. A timer object can be stopped and later restarted, and is automatically stopped if the object is destroyed (when all references to it are dropped).

The "weak" option allows only a weak reference to be kept to the userdata passed to the callback function. If the userdata object or widget is destroyed then the timer stops. This is good if the timer is part of a widget implementation (the weakening avoid a circular reference).

FUNCTIONS

Gtk2::Ex::TimerObject->new (key=>value, ...)

Create and return a new timer object. Parameters are taken as key/value pairs. The following keys are supported

    period       time in milliseconds, or undef
    callback     function to call
    userdata     parameter to each callback call
    weak         if true then weaken userdata (default false)
    priority     Glib main loop level (default G_PRIORITY_DEFAULT)

When the timer is running the given callback function is called every period milliseconds,

    $callback->($timerobj, $userdata);

Any return value from it is ignored, but it can change the period or stop the timer within that callback, if desired.

If period is undef it means the timer should not run, and no calls to the callback function are made. This can be good for an initialization function where a timer should be created, but it shouldn't run until some later setups.

If the weak option is true then the userdata value is kept only as a weak reference (if it is in fact a reference). If that value is garbage collected (because nothing else is using it) then the timer stops.

The priority parameter controls the priority of the timer within the Glib main loop. The default is Glib::G_PRIORITY_DEFAULT, which is 0. Positive values are lower priority, negative values higher.

$timer->set_period ($milliseconds)

Set the period of $timer to $milliseconds, or stop it if $milliseconds is undef.

In the current implementation, if the timer is running and the period is changed then it starts counting down again from a whole new $milliseconds period. Perhaps in the future it'll be possible to take into account how long since the last firing, to keep it running smoothly if merely making small adjustments to the period, but current Glib (version 2.14) doesn't allow that (not with the basic Glib::Timeout->add).

$timer->stop

Stop $timer, so no further calls to its $callback are made. This is the same as a $timer->set_period(undef). The timer can be restarted later by a new set_period, if desired.

OTHER NOTES

TimerObject is currently implemented as a Perl object holding a timer ID from Glib::Timeout->add. If GSource was available at the Perl level in the future then perhaps TimerObject could become a subclass of that.

SEE ALSO

Glib::MainLoop, Gtk2::Ex::IdleObject, Glib::Ex::SignalObject