tk busy hold window ?options?
tk busy configure window ?option value?...
tk busy forget window ?window ?...
tk busy current ?pattern?
tk busy status window
The tk busy command provides a simple means to block pointer events from Tk widgets, while overriding the widget's cursor with a configurable busy cursor. Note this command does not prevent keyboard events from being sent to the widgets made busy.
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. However, while the application is busy processing, you probably don't want 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 tk 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 descendants will ignore pointer 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 tk busy command can be used instead of Tk's grab command. Unlike grab which restricts all user interactions to one widget, with the tk 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 # . . . tk busy hold .top update
All the widgets within .top (including .top) are now busy. Using update insures that tk 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 and free any resources it allocated by the forget operation.
tk busy forget .top
The busy window has a configurable cursor. You can change the busy cursor using the configure operation.
tk busy configure .top -cursor "watch"
Destroying the widget will also clean up any resources allocated by the tk busy command.
The following operations are available for the tk busy command:
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
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.
tk 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''.
tk 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 a user clicking on it by the busy window. But if the widget already had focus, it still may receive keyboard events. The widget can also still receive focus through keyboard traversal. To prevent this, you must move focus to another window and make sure the focus can not go back to the widgets made busy (e.g. but restricting focus to a cancel button).
pack [frame .frame]
pack [text .frame.text]
tk busy hold .frame
pack [button .cancel -text "Cancel" -command exit]
focus .cancel
bind .cancel <Tab> {break}
bind .cancel <Shift-Tab> {break}
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. It also makes sure it's not possible to leave button .cancel using the keyboard.
Note that the tk busy command does not currently have any effect on OSX when Tk is built using Aqua support.