#  Copyright (c) 1990 The Regents of the University of California.
#  Copyright (c) 1994 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#  @(#) TimerHndlr.3 1.9 95/05/28 13:52:12
#

=head1 NAME

Tk_CreateTimerHandler, Tk_DeleteTimerHandler - call a procedure at a
given time

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

Tk_TimerToken
B<Tk_CreateTimerHandler>(I<milliseconds, proc, clientData>)

B<Tk_DeleteTimerHandler>(I<token>)

=head1 ARGUMENTS

=over 4

=item int milliseconds (in)

How many milliseconds to wait before invoking I<proc>.

=item Tk_TimerProc *proc (in)

Procedure to invoke after I<milliseconds> have elapsed.

=item ClientData clientData (in)

Arbitrary one-word value to pass to I<proc>.

=item Tk_TimerToken token (in)

Token for previously-created timer handler (the return value
from some previous call to B<Tk_CreateTimerHandler>).

=back

=head1 DESCRIPTION

B<Tk_CreateTimerHandler> arranges for I<proc> to be
invoked at a time I<milliseconds> milliseconds in the
future.
The callback to I<proc> will be made by B<Tk_DoOneEvent>,
so B<Tk_CreateTimerHandler> is only useful in
programs that dispatch events
through B<Tk_DoOneEvent> or through other Tk procedures that
call B<Tk_DoOneEvent>, such as B<Tk_MainLoop>.  The call
to I<proc> may not be made at the exact time given by
I<milliseconds>:  it will be made at the next opportunity
after that time.  For example, if B<Tk_DoOneEvent> isn't
called until long after the time has elapsed, or if there
are other pending events to process before the call to
I<proc>, then the call to I<proc> will be delayed.

I<Proc> should have arguments and return value that match
the type B<Tk_TimerProc>:

=over 4

typedef void Tk_TimerProc(ClientData I<clientData>);

=back

The I<clientData> parameter to I<proc> is a
copy of the I<clientData> argument given to
B<Tcl_CreateTimerHandler> when the callback
was created.  Typically, I<clientData> points to a data
structure containing application-specific information about
what to do in I<proc>.

B<Tk_DeleteTimerHandler> may be called to delete a
previously-created timer handler.  It deletes the handler
indicated by I<token> so that no call to I<proc>
will be made;  if that handler no longer exists
(e.g. because the time period has already elapsed and I<proc>
has been invoked) then B<Tk_DeleteTimerHandler> does nothing.

=head1 KEYWORDS

callback, clock, handler, timer