=head1 NAME

Prima::Timer - programmable periodical events

=head1 SYNOPSIS

    my $timer = Prima::Timer-> create(
        timeout => 1000, # milliseconds
        onTick  => sub {
           print "tick!\n";
        },
    );

    $timer-> start;

=head1 DESCRIPTION

The Prima::Timer class arranges for the periodical notifications to be
delivered in certain time intervals.  The notifications are triggered by the
system and are seen as the C<Tick> events. There can be many active Timer
objects at one time, spawning events simultaneously.

=head1 USAGE

The Prima::Timer class is a descendant of the Prima::Component class.
Objects of the Prima::Timer class are created in the standard fashion:

  my $t = Prima::Timer-> create(
     timeout => 1000,
     onTick  => sub { print "tick\n"; },
  );
  $t-> start;

If no `owner` is given, $::application is assumed.

Timer objects are created in the inactive state; no events are spawned by
default. To start spawning events, the C<start()> method must be explicitly
called. The time interval value is assigned by calling the <::timeout>
property.

When the system generates a timer event, no callback is called immediately, -
an event is pushed into the internal event stack instead, to be delivered
during the next event loop.  Therefore it cannot be guaranteed that the onTick
noitifications will be called precisely after a timeout. A more accurate timing
scheme, as well as timing with a precision of less than a millisecond, is not
supported by the toolkit.

=head1 API

=head2 Properties

=over

=item timeout MILLISECONDS

Manages time intervals between the C<Tick> events.  In the set-mode call, if
the timer is in the active state already ( see C<get_active()>, the new timeout
value is applied immediately.

=back

=head2 Methods

=over

=item get_active

Returns the boolean flag that reflects whether the object is in the active state or
not. In the active state C<Tick> events are spawned after C<::timeout> time
intervals.

=item get_handle

Returns the system-dependent handle of the printer object

=item start

Sets the object in the active state. If succeeds or if the object is already in the
active state, returns 1. If the system is unable to create a system timer
instance, the value of 0 is returned.

=item stop

Sets object in the inactive state.

=item toggle

Toggles the timer state

=back

=head2 Events

=over

=item Tick

The system-generated event spawned every C<::timeout> milliseconds if the object is
in the active state.

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Object>
