Table of Contents
busy - Make Tk widgets busy, temporarily blocking
user interactions.
busy hold window ?option value ?...
busy release
window ?window ?...
busy configure window ?option value ?...
busy forget
window ?window ?...
busy isbusy ?pattern ?
busy names ?pattern ?
busy
status window
The busy command provides a simple means
to block keyboard, button, and pointer events from Tk widgets, while overriding
the widget's cursor with a configurable busy cursor.
There
are many times in applications where you want to temporarily restrict
what actions the user can take. For example, an application could have
a "run" button that when pressed causes some processing to occur. But
while the application is busy processing, you probably don't want the the
user to be able to click the "run" button again. You may also want restrict
the user from other tasks such as clicking a "print" button.
The busy
command lets you make Tk widgets busy. This means that user interactions
such as button clicks, moving the mouse, typing at the keyboard, etc. are
ignored by the widget. You can set a special cursor (like a watch) that
overrides the widget's normal cursor, providing feedback that the application
(widget) is temporarily busy.
When a widget is made busy, the widget and
all of its descendents will ignore events. It's easy to make an entire
panel of widgets busy. You can simply make the toplevel widget (such as
".") busy. This is easier and far much more efficient than recursively
traversing the widget hierarchy, disabling each widget and re-configuring
its cursor.
Often, the busy command can be used instead of Tk's grab command.
Unlike grab which restricts all user interactions to one widget, with
the busy command you can have more than one widget active (for example,
a "cancel" dialog and a "help" button).
You can make several widgets
busy by simply making its ancestor widget busy using the hold operation.
frame .top
button .top.button; canvas .top.canvas
pack .top.button .top.canvas
pack .top
. . .
busy hold .top
update
All the widgets within .top (including
.top ) are now busy. Using update insures that busy command will take
effect before any other user events can occur.
When the application is
no longer busy processing, you can allow user interactions again by the
release operation.
busy release .top
The busy window has a configurable
cursor. You can change the busy cursor using the configure operation.
busy configure .top -cursor "watch"
Finally, when you no longer
need to the busy window, invoke the forget operation to free any resources
it allocated.
busy forget .top
Destroying the widget will also
clean up any resources allocated by the busy command.
The following
operations are available for the busy command:
- busy hold window ?option
value ?...
- Makes the widget window (and its descendants in the Tk window
hierarchy) busy. Window must be a valid path name of a Tk widget. The
busy window is mapped the next time idle tasks are processed, and the
widget and its descendants will be blocked from user interactions. All
events in the widget window and its descendants are ignored. Normally
update should be called immediately afterward to insure that the hold
operation is in effect before the application starts its processing.
The following configuration options are valid:
- -cursor cursorName
- Specifies
the cursor to be displayed when the widget is made busy. CursorName can
be in any form accepted by Tk_GetCursor . The default cursor is watch .
- busy configure window ?option value ?...
- Queries or modifies the busy
command configuration options for window . Window must be the path name
of a widget previously made busy by the hold operation. If no options
are specified, a list describing all of the available options for window
(see Tk_ConfigureInfo for information on the format of this list) is
returned. If option is specified with no value , then the command returns
a list describing the one named option (this list will be identical to
the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies
the given widget option(s) to have the given value(s); in this case the
command returns the empty string. Option may have any of the values accepted
by the hold operation.
Please note that the option database is referenced
through window . For example, if the widget .frame is to be made busy,
the busy cursor can be specified for it by either option command:
option add *frame.busyCursor gumby
option add *Frame.BusyCursor gumby
- busy forget window ?window ?...
- Releases resources allocated by the
busy command for window , including the busy window. User events will
again be received again by window . Resources are also released when
window is destroyed. Window must be the name of a widget specified in
the hold operation, otherwise an error is reported.
- busy isbusy ?pattern
?
- Returns the pathnames of all widgets that are currently busy. If a pattern
is given, the path names of busy widgets matching pattern are returned.
- busy names ?pattern ?
- Returns the pathnames of all widgets that have
previously been made busy (i.e. a busy window is allocated and associated
with the widget). It makes no difference if the window is currently busy
or not. If a pattern is given, the path names of busy widgets matching
pattern are returned.
- busy release window ?window ?...
- Restores user interactions
to the widget window again. This differs from the forget operation in
that the busy window is not destroyed, but simply unmapped. Window
must be the name of a widget specified in a hold operation, otherwise
an error is reported.
- busy status window
- Returns the status of a widget
window previously made busy. An error is reported if window was never
made busy, or the forget operation was invoked (i.e. does not currently
have a busy window associated with it). If window is presently can not
receive user interactions, 1 is returned, otherwise 0 .
The
event blocking feature is implemented by creating and mapping a transparent
window that completely covers the widget. When the busy window is mapped,
it invisibly shields the widget and its hierarchy from all events that
may be sent. Like Tk widgets, busy windows have widget names in the Tk
window hierarchy. This means that you can use the bind command, to handle
events in the busy window.
busy hold .frame.canvas
bind .frame.canvas_Busy
<Enter> { ... }
Normally the busy window is a sibling of the widget. The
name of the busy window is "widget_Busy " where widget is the name of
the widget to be made busy. In the previous example, the pathname of the
busy window is ".frame.canvas_Busy " The exception is when the widget is
a toplevel widget (such as ".") where the busy window can't be made a sibling.
The busy window is then a child of the widget named "widget._Busy " where
widget is the name of the toplevel widget. In the following example,
the pathname of the busy window is "._Busy "
busy hold .
bind ._Busy <Enter>
{ ... }
Mapping and unmapping busy windows generates
Enter/Leave events for all widgets they cover. Please note this if you
are tracking Enter/Leave events in widgets.
When a widget
is made busy, the widget is prevented from gaining the keyboard focus
by the busy window. But if the widget already had focus, it still may received
keyboard events. To prevent this, you must move focus to another window.
busy hold .frame
label .dummy
focus .dummy
update
The above example
moves the focus from .frame immediately after invoking the hold so that
no keyboard events will be sent to .frame or any of its descendants.
busy, keyboard events, pointer events, window, cursor