=for comment based on iup-3.5

=head1 NAME

IUP::Timer - [special] periodicaly invokes a callback when the time is up

=head1 DESCRIPTION

Creates a timer which periodicaly invokes a callback when the time is up.
Each timer should be destroyed using L<Destroy|IUP::Manual::02_Elements/"Destroy()"> (or simply by C<undef $timer>).

=head1 USAGE

=head2 CREATION - new() method

 $timer = IUP::Timer->new();

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.)
see L<IUP::Manual::03_Attributes|IUP::Manual::03_Attributes>. Attributes specific to this element:

=over

=item * B<TIME>

The time interval in milliseconds. In Windows the minimum
value is 10ms.

=item * B<RUN>

Starts and stops the timer. Possible values: "YES" or "NO".
Returns the current timer state. If you have multiple threads start the
timer in the main thread.

=item * B<WID> (read-only)

Returns the native serial number of the timer.
Returns -1 if not running. A timer is mapped only when it is running.

=back

=head2 CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.)
see L<IUP::Manual::04_Callbacks|IUP::Manual::04_Callbacks>. Callbacks specific to this element:

=over

=item * B<ACTION_CB>

Called when the time is up.

B<Callback handler prototype:>

 sub action_cb_handler {
   my ($self) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::Timer) that activated the event

B<Returns:> IUP_CLOSE will be processed.

=back

=back

=head1 EXAMPLES


The element B<IUP::Timer> is used in the following sample scripts:

=over

=item * L<0-basic/glcanvas2.pl|http://cpansearch.perl.org/src/KMX/IUP-0.004/examples/0-basic/glcanvas2.pl> - IUP::CanvasGL example

=item * L<0-basic/progressbar2.pl|http://cpansearch.perl.org/src/KMX/IUP-0.004/examples/0-basic/progressbar2.pl> - IUP::ProgressBar example

=item * L<0-basic/timer.pl|http://cpansearch.perl.org/src/KMX/IUP-0.004/examples/0-basic/timer.pl> - IUP::Timer example

=back 



=head1 SEE ALSO

The original doc: L<iuptimer.html|http://www.tecgraf.puc-rio.br/iup/en/elem/iuptimer.html>
 

=cut