NAME
busy - Make Tk widgets busy, temporarily blocking user interactions.

SYNOPSIS
busy hold window ?option value?...

busy release window ?window?...

busy configure window ?option value?...

busy forget window ?window?...

busy isbusy ?pattern?

busy status window

busy windows ?pattern?

DESCRIPTION

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.

INTRODUCTION

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 also set a special cursor (like a watch) which overrides the widget's normal cursor, providing feedback that the application (widget) is temporarily busy.

When a widget is made busy, all of the widgets in its window hierarchy also become busy. It's easy then to make an entire panel of widgets busy by simply making the uppermost widget (such as ".") busy. This is far easier and much more efficient than recursively traversing the widget hierarchy, disabling each widget and re-configuring its cursor.

The busy command can also be used in many cases instead of Tk's grab command. Unlike grab which directs all user interaction to one widget, the busy command allows more than one widget to be active (for example, a "cancel" dialog and a "help" button) while the other widgets are busy.

EXAMPLE
You can make a set of widgets busy by simply making the uppermost widget in the hierarchy 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. The update command insures that busy command has a chance to effect.

When the application is no longer busy, you can allow user interaction again by the release operation.
	busy release .top
You can change the busy cursor using the configure operation.
	busy configure .top -cursor "watch"
Finally, when you no longer need to make the widget busy anymore, invoke the forget operation to free any resources allocated.
	busy forget .top
Destroying the widget also cleans up any resources allocated by the busy command.

OPERATIONS
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. After idle tasks are processed, the widget will be blocked from user interactions. All device events in the widget window and its descendants will be ignored. Typically 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 InputOnly window. User events will again be received again by window. Busy 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 widget windows which are currently busy. 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 InputOnly 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 InputOnly window associated with it). If window is presently can not receive user interaction, 1 is returned, otherwise 0.

busy windows ?pattern?
    Returns the pathnames of all widget windows which have previously been made busy (i.e. an InputOnly is allocated and associated with the widget). It makes no difference if the window is currently busy ot not. If a pattern is given, the path names of busy widgets matching pattern are returned.

BINDINGS
The blocking feature is implemented by creating and mapping a transparent InputOnly class window which completely covers the widget. When the InputOnly window is mapped, it intercepts all events which could be sent to the widget and its hierarchy. Like Tk widgets, the InputOnly windows have names in the Tk window hierarchy. This means that you can use the bind command, to handle events in the InputOnly window. busy hold .frame.canvas bind .frame.canvas_Busy <Enter> { ... }

Typically, the InputOnly window is a sibling of the widget's window. The name of the InputOnly window will be "widget_Busy" where widget is the name of the widget made busy. In the above example, the pathname of the InputOnly window is ".frame.canvas_Busy" The exception is when the widget is a toplevel window (such as "."). Then the InputOnly window is a child of the widget's window and the name of the widget will be "widget._Busy" where widget is the name of the widget made busy. In the following example, the pathname of the InputOnly window is "._Busy" busy hold . bind ._Busy <Enter> { ... }

ENTER/LEAVE EVENTS
Mapping and unmapping the InputOnly window generates Enter/Leave events for all widget (windows) that it covers. Please note this when you are tracking Enter/Leave events in widgets.

KEYBOARD EVENTS
When a widget is made busy, the widget is prevented from gaining the keyboard focus by the InputOnly window. But Tk widgets can still get keyboard events if the keyboard focus is already set. Care must be taken to 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 relayed to windows under the hierarchy of .frame.

KEYWORDS
busy, keyboard events, pointer events, window, cursor