home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / TimerHndlr.3 < prev    next >
Encoding:
Text File  |  1993-04-01  |  3.4 KB  |  90 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/TimerHndlr.3,v 1.6 93/04/01 09:41:59 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_CreateTimerHandler tkc
  25. .BS
  26. .SH NAME
  27. Tk_CreateTimerHandler, Tk_DeleteTimerHandler \- call a procedure at a
  28. given time
  29. .SH SYNOPSIS
  30. .nf
  31. \fB#include <tk.h>\fR
  32. .sp
  33. Tk_TimerToken
  34. \fBTk_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
  35. .sp
  36. \fBTk_DeleteTimerHandler\fR(\fItoken\fR)
  37. .SH ARGUMENTS
  38. .AS Tk_TimerToken milliseconds
  39. .AP int milliseconds  in
  40. How many milliseconds to wait before invoking \fIproc\fR.
  41. .AP Tk_TimerProc *proc in
  42. Procedure to invoke after \fImilliseconds\fR have elapsed.
  43. .AP ClientData clientData in
  44. Arbitrary one-word value to pass to \fIproc\fR.
  45. .AP Tk_TimerToken token in
  46. Token for previously-created timer handler (the return value
  47. from some previous call to \fBTk_CreateTimerHandler).
  48. .BE
  49.  
  50. .SH DESCRIPTION
  51. .PP
  52. \fBTk_CreateTimerHandler\fR arranges for \fIproc\fR to be
  53. invoked at a time \fImilliseconds\fR milliseconds in the
  54. future.
  55. The callback to \fIproc\fR will be made by \fBTk_DoOneEvent\fR,
  56. so \fBTk_CreateTimerHandler\fR is only useful in
  57. programs that dispatch events
  58. through \fBTk_DoOneEvent\fR or through other Tk procedures that
  59. call \fBTk_DoOneEvent\fR, such as \fBTk_MainLoop\fR.  The call
  60. to \fIproc\fR may not be made at the exact time given by
  61. \fImilliseconds\fR:  it will be made at the next opportunity
  62. after that time.  For example, if \fBTk_DoOneEvent\fR isn't
  63. called until long after the time has elapsed, or if there
  64. are other pending events to process before the call to
  65. \fIproc\fR, then the call to \fIproc\fR will be delayed.
  66. .PP
  67. \fIProc\fP should have arguments and return value that match
  68. the type \fBTk_TimerProc\fR:
  69. .nf
  70. .RS
  71. typedef void Tk_TimerProc(ClientData \fIclientData\fR);
  72. .RE
  73. .fi
  74. The \fIclientData\fP parameter to \fIproc\fR is a
  75. copy of the \fIclientData\fP argument given to
  76. \fBTcl_CreateTimerHandler\fR when the callback
  77. was created.  Typically, \fIclientData\fR points to a data
  78. structure containing application-specific information about
  79. what to do in \fIproc\fR.
  80. .PP
  81. \fBTk_DeleteTimerHandler\fR may be called to delete a
  82. previously-created timer handler.  It deletes the handler
  83. indicated by \fItoken\fR so that no call to \fIproc\fR
  84. will be made;  if that handler no longer exists
  85. (e.g. because the time period has already elapsed and \fIproc\fR
  86. has been invoked) then \fBTk_DeleteTimerHandler\fR does nothing.
  87.  
  88. .SH KEYWORDS
  89. callback, clock, handler, timer
  90.