=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

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

=head1 USAGE

Prima::Timer is a descendant of Prima::Component.
Objects of Prima::Timer class are created in 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 inactive state; no events
are spawned. To start spawning events, <start()> method
must be explicitly called. Time interval value is assigned
using the <::timeout> property in milliseconds.

When the system generates timer event, no callback
is called immediately, - an event is pushed into
stack instead, to be delivered during next event loop.
Therefore, timeout value is not held accurately, and events
may take longer time to pass. More accurate timing scheme,
as well as timing with precision less than a millisecond,
is not supported by the toolkit.

=head1 API

=head2 Properties

=over

=item timeout MILLISECONDS

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

=back

=head2 Methods

=over

=item get_active

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

=item get_handle

Returns a system-dependent handle of object

=item start

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

=item stop

Sets object in inactive state.

=item toggle

Toggles the timer state

=back

=head2 Events

=over

=item Tick

A system generated event, spawned every C<::timeout>
milliseconds if object is in active state.

=back

=head1 AUTHOR

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

=head1 SEE ALSO

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