home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2004 July / APC0407D2.iso / workshop / apache / files / ActivePerl-5.6.1.638-MSWin32-x86.msi / _395b72282a41281b5017c92d656b044f < prev    next >
Encoding:
Text File  |  2004-04-13  |  4.9 KB  |  135 lines
  1. #  Copyright (c) 1990-1994 The Regents of the University of California.
  2. #  Copyright (c) 1994-1996 Sun Microsystems, Inc.
  3. #  See the file "license.terms" for information on usage and redistribution
  4. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  5. #
  6. #
  7.  
  8. =head1 NAME
  9.  
  10. Tk::after - Execute a command after a time delay
  11.  
  12. =for category  Binding Events and Callbacks
  13.  
  14. =head1 SYNOPSIS
  15.  
  16. S<  >I<$widget>-E<gt>B<after>(I<ms>)
  17.  
  18. S<  >I<$id> = I<$widget>-E<gt>B<after>(I<ms>?,I<callback>?)
  19.  
  20. S<  >I<$id> = I<$widget>-E<gt>B<repeat>(I<ms>?,I<callback>?)
  21.  
  22. S<  >I<$widget>-E<gt>B<afterCancel>(I<$id>)
  23.  
  24. S<  >I<$id> = I<$widget>-E<gt>B<afterIdle>(I<callback>)
  25.  
  26. S<  >I<$widget>-E<gt>B<afterInfo>?(I<$id>)?
  27.  
  28. =head1 DESCRIPTION
  29.  
  30. This method is used to delay execution of the program or to execute
  31. a callback in background sometime in the future.
  32.  
  33. In perl/Tk I<$widget>-E<gt>B<after> is implemented via the class C<Tk::After>,
  34. and callbacks are associated with I<$widget>, and are automatically cancelled
  35. when the widget is destroyed. An almost identical interface, but without
  36. automatic cancel, and without repeat is provided via Tk::after method.
  37.  
  38. The internal Tk::After class has the following synopsis:
  39.  
  40.   $id = Tk::After->new($widget,$time,'once',callback);
  41.   $id = Tk::After->new($widget,$time,'repeat',callback);
  42.   $id->cancel;
  43.  
  44. The B<after> method has several forms as follows:
  45.  
  46. =over 4
  47.  
  48. =item I<$widget>-E<gt>B<after>(I<ms>)
  49.  
  50. The value I<ms> must be an integer giving a time in milliseconds.
  51. The command sleeps for I<ms> milliseconds and then returns.
  52. While the command is sleeping the application does not respond to
  53. events.
  54.  
  55. =item I<$widget>-E<gt>B<after>(I<ms>,I<callback>)
  56.  
  57. In this form the command returns immediately, but it arranges
  58. for I<callback> be executed I<ms> milliseconds later as an
  59. event handler.
  60. The callback will be executed exactly once, at the given time.
  61. The command will be executed in context of I<$widget>.
  62. If an error occurs while executing the delayed command then the
  63. L<Tk::Error|Tk::Error> mechanism is used to report the error.
  64. The B<after> command returns an identifier (an object in the perl/Tk
  65. case) that can be used to cancel the delayed command using B<afterCancel>.
  66.  
  67. =item I<$widget>-E<gt>B<repeat>(I<ms>,I<callback>)
  68.  
  69. In this form the command returns immediately, but it arranges
  70. for I<callback> be executed I<ms> milliseconds later as an
  71. event handler. After I<callback> has executed it is re-scheduled,
  72. to be executed in a futher I<ms>, and so on until it is cancelled.
  73.  
  74. =item I<$widget>-E<gt>B<afterCancel>(I<$id>)
  75.  
  76. =item I<$id>-E<gt>cancel
  77.  
  78. Cancels the execution of a delayed command that
  79. was previously scheduled.
  80. I<$id> indicates which command should be canceled;  it must have
  81. been the return value from a previous B<after> command.
  82. If the command given by I<$id> has already been executed (and
  83. is not scheduled to be executed again) then B<afterCancel>
  84. has no effect.
  85.  
  86. =item I<$widget>-E<gt>B<afterCancel>(I<callback>)
  87.  
  88. I<This form is not robust in perl/Tk - its use is deprecated.>
  89. This command should also cancel the execution of a delayed command.
  90. The I<callback> argument is compared with pending callbacks,
  91. if a match is found, that callback is
  92. cancelled and will never be executed;  if no such callback is
  93. currently pending then the B<afterCancel> has no effect.
  94.  
  95. =item I<$widget>-E<gt>B<afterIdle>(I<callback>)
  96.  
  97. Arranges for I<callback> to be evaluated later as an idle callback.
  98. The script will be run exactly once, the next time the event
  99. loop is entered and there are no events to process.
  100. The command returns an identifier that can be used
  101. to cancel the delayed command using B<afterCancel>.
  102. If an error occurs while executing the script then the
  103. L<Tk::Error|Tk::Error> mechanism is used to report the error.
  104.  
  105. =item I<$widget>-E<gt>B<afterInfo>?(I<$id>)?
  106.  
  107. This command returns information about existing event handlers.  If no I<$id>
  108. argument is supplied, the command returns a list of the identifiers for all
  109. existing  event handlers created by the B<after> command for this MainWindow. If
  110. I<$id> is supplied, it specifies an existing handler; I<$id> must have been the
  111. return value from some previous call to B<after> and it must not have triggered
  112. yet or been cancelled. In this case the command returns a list with two elements.
  113. The first element of the list is the callback associated  with I<$id>, and the
  114. second element is either B<idle> or B<timer> to indicate what kind of event
  115. handler it is.
  116.  
  117. =back
  118.  
  119. The B<after>(I<ms>) and B<afterIdle> forms of the command
  120. assume that the application is event driven:  the delayed commands
  121. will not be executed unless the application enters the event loop.
  122. In applications that are not normally event-driven,
  123. the event loop can be entered with the B<vwait> and B<update> commands.
  124.  
  125. =head1 SEE ALSO
  126.  
  127. L<Tk::Error|Tk::Error>
  128. L<Tk::callbacks|Tk::callbacks>
  129.  
  130. =head1 KEYWORDS
  131.  
  132. cancel, delay, idle callback, sleep, time
  133.  
  134. =cut
  135.