Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |