1busy(n) Tk Built-In Commands busy(n)
2______________________________________________________________________________
6
8 busy - confine pointer events to a window sub-tree
9
11 tk busy window ?options?
12 tk busy hold window ?options?
14 tk busy configure window ?option value?...
16 tk busy forget window ?window ?...
18 tk busy current ?pattern?
20 tk busy status window
22______________________________________________________________________________
23
25 The tk busy command provides a simple means to block pointer events
26 from Tk widgets, while overriding the widget's cursor with a config‐
27 urable busy cursor. Note this command does not prevent keyboard events
28 from being sent to the widgets made busy.
29
31 There are many times in applications where you want to temporarily
32 restrict what actions the user can take. For example, an application
33 could have a “Run” button that when pressed causes some processing to
34 occur. However, while the application is busy processing, you probably
35 don't want the user to be able to click the “Run” button again. You may
36 also want restrict the user from other tasks such as clicking a “Print”
37 button.
38 The tk busy command lets you make Tk widgets busy. This means that user
40 interactions such as button clicks, moving the mouse, typing at the
41 keyboard, etc. are ignored by the widget. You can set a special cursor
42 (like a watch) that overrides the widget's normal cursor, providing
43 feedback that the application (widget) is temporarily busy.
44 When a widget is made busy, the widget and all of its descendants will
46 ignore pointer events. It's easy to make an entire panel of widgets
47 busy. You can simply make the toplevel widget (such as “.”) busy. This
48 is easier and far much more efficient than recursively traversing the
49 widget hierarchy, disabling each widget and re-configuring its cursor.
50 Often, the tk busy command can be used instead of Tk's grab command.
52 Unlike grab which restricts all user interactions to one widget, with
53 the tk busy command you can have more than one widget active (for exam‐
54 ple, a “Cancel” dialog and a “Help” button).
55 EXAMPLE
57 You can make several widgets busy by simply making its ancestor widget
58 busy using the hold operation.
59 frame .top
61 button .top.button; canvas .top.canvas
62 pack .top.button .top.canvas
63 pack .top
64 # . . .
65 tk busy hold .top
66 update
67 All the widgets within .top (including .top) are now busy. Using update
69 insures that tk busy command will take effect before any other user
70 events can occur.
71 When the application is no longer busy processing, you can allow user
73 interactions again and free any resources it allocated by the forget
74 operation.
75 tk busy forget .top
77 The busy window has a configurable cursor. You can change the busy cur‐
79 sor using the configure operation.
80 tk busy configure .top -cursor "watch"
82 Destroying the widget will also clean up any resources allocated by the
84 tk busy command.
85
87 The following operations are available for the tk busy command:
88 tk busy window ?option value?...
90 Shortcut for tk busy hold command.
91 tk busy hold window ?option value?...
93 Makes the specified window (and its descendants in the Tk window
94 hierarchy) appear busy. Window must be a valid path name of a Tk
95 widget. A transparent window is put in front of the specified
96 window. This transparent window is mapped the next time idle
97 tasks are processed, and the specified window and its descen‐
98 dants will be blocked from user interactions. Normally update
99 should be called immediately afterward to insure that the hold
100 operation is in effect before the application starts its pro‐
101 cessing. The following configuration options are valid:
102 -cursor cursorName
104 Specifies the cursor to be displayed when the widget is
105 made busy. CursorName can be in any form accepted by
106 Tk_GetCursor. The default cursor is wait on Windows and
107 watch on other platforms.
108 tk busy cget window option
110 Queries the tk busy command configuration options for window.
111 Window must be the path name of a widget previously made busy by
112 the hold operation. The command returns the present value of the
113 specified option. Option may have any of the values accepted by
114 the hold operation.
115 tk busy configure window ?option value?...
117 Queries or modifies the tk busy command configuration options
118 for window. Window must be the path name of a widget previously
119 made busy by the hold operation. If no options are specified, a
120 list describing all of the available options for window (see
121 Tk_ConfigureInfo for information on the format of this list) is
122 returned. If option is specified with no value, then the command
123 returns a list describing the one named option (this list will
124 be identical to the corresponding sublist of the value returned
125 if no option is specified). If one or more option-value pairs
126 are specified, then the command modifies the given widget
127 option(s) to have the given value(s); in this case the command
128 returns the empty string. Option may have any of the values
129 accepted by the hold operation.
130 Please note that the option database is referenced through win‐
132 dow. For example, if the widget .frame is to be made busy, the
133 busy cursor can be specified for it by either option command:
134 option add *frame.busyCursor gumby
136 option add *Frame.BusyCursor gumby
137 tk busy forget window ?window?...
139 Releases resources allocated by the tk busy command for window,
140 including the transparent window. User events will again be
141 received by window. Resources are also released when window is
142 destroyed. Window must be the name of a widget specified in the
143 hold operation, otherwise an error is reported.
144 tk busy current ?pattern?
146 Returns the pathnames of all widgets that are currently busy. If
147 a pattern is given, only the path names of busy widgets matching
148 pattern are returned.
149 tk busy status window
151 Returns the status of a widget window. If window presently can
152 not receive user interactions, 1 is returned, otherwise 0.
153
155 BINDINGS
156 The event blocking feature is implemented by creating and mapping a
157 transparent window that completely covers the widget. When the busy
158 window is mapped, it invisibly shields the widget and its hierarchy
159 from all events that may be sent. Like Tk widgets, busy windows have
160 widget names in the Tk window hierarchy. This means that you can use
161 the bind command, to handle events in the busy window.
162 tk busy hold .frame.canvas
164 bind .frame.canvas_Busy <Enter> { ... }
165 Normally the busy window is a sibling of the widget. The name of the
167 busy window is “widget_Busy” where widget is the name of the widget to
168 be made busy. In the previous example, the pathname of the busy window
169 is “.frame.canvas_Busy”. The exception is when the widget is a
170 toplevel widget (such as “.”) where the busy window can't be made a
171 sibling. The busy window is then a child of the widget named “wid‐
172 get._Busy” where widget is the name of the toplevel widget. In the fol‐
173 lowing example, the pathname of the busy window is “._Busy”.
174 tk busy hold .
176 bind ._Busy <Enter> { ... }
177 ENTER/LEAVE EVENTS
179 Mapping and unmapping busy windows generates Enter/Leave events for all
180 widgets they cover. Please note this if you are tracking Enter/Leave
181 events in widgets.
182 KEYBOARD EVENTS
184 When a widget is made busy, the widget is prevented from gaining the
185 keyboard focus by a user clicking on it by the busy window. But if the
186 widget already had focus, it still may receive keyboard events. The
187 widget can also still receive focus through keyboard traversal. To pre‐
188 vent this, you must move focus to another window and make sure the
189 focus can not go back to the widgets made busy (e.g. but restricting
190 focus to a cancel button).
191 pack [frame .frame]
193 pack [text .frame.text]
194 tk busy hold .frame
195 pack [button .cancel -text "Cancel" -command exit]
196 focus .cancel
197 bind .cancel <Tab> {break}
198 bind .cancel <Shift-Tab> {break}
199 update
200 The above example moves the focus from .frame immediately after invok‐
202 ing the hold so that no keyboard events will be sent to .frame or any
203 of its descendants. It also makes sure it's not possible to leave but‐
204 ton .cancel using the keyboard.
205
207 Note that the tk busy command does not currently have any effect on OSX
208 when Tk is built using Aqua support.
209
211 grab(n)
212
214 busy, keyboard events, pointer events, window
215Tk busy(n)