_________________________________________________________________
NAME
blt_busy - Block pointer and keyboard events from a window
sub-tree
SYNOPSIS
blt_busy hold window options ?window options ...?
blt_busy release window ?window ...?
blt_busy configure window ?options...?
blt_busy forget window ?window ...?
blt_busy hosts pattern
blt_busy status window
_________________________________________________________________
DESCRIPTION
This command implements a mechanism to prevent keyboard,
button, and pointer events from reaching a window and its
descendants. Events occurring in this window and its
descendants in Tk's window hierarchy are effectively
ignored.
This is particularly useful for temporarily deactivating an
hierarchy of widgets (e.g. buttons and entries) while other
processing is occurring.
Once a window is made busy using the blt_busy hold command,
the window and its descendants are blocked from receiving
events. Please note that only the descendants which exist
at the time the hold command was invoked are affected. If a
new child window is created following the command, its
events are not blocked.
The blocking feature is implemented by creating and mapping
an InputOnly class sub-window, obscuring some or all of the
parent window. When the sub-window is mapped, it shields
its parent and sibling windows from events (it is always
mapped to be the uppermost sibling). The size and position
of the busy window are determined by a host window.
Typically the host and parent windows are the same. But in
cases where a window is not packed into its parent, the -in
option may be used to specify a different parent.
The blt_busy command can take any of the following forms:
blt_busy hold window ?option? ?value option value ...?
Creates and activates a busy window associated with
window. Window must be a valid path name of a Tk
window. It represents the host window which determines
the position and size of the busy window. All device
events for the host window and it descendants will be
effectively blocked. Typically update should be called
immediately afterward to insure that the busy cursor is
updated before the application starts its work. This
command returns the empty string. The following
configuration options are valid:
-cursor cursorName
Specifies the cursor to be displayed when the busy
window is activated. CursorName can be in any
form accepted by Tk_GetCursor. The default cursor
is watch.
-in parent
Specifies the parent window of the busy window.
This is needed when the parent and host windows
are not the same. Parent specifies the path name
of a mutual ancestor of both the host window and
the window hierarchy.
blt_busy configure window ?option? ?value option value
Queries or modifies the configuration options of the
busy window. Window must be the path name of a host
window (associated by the hold command). If no option
is 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 command. Please note that the
option database is referenced through window. For
example, if a busy window exists for the window
.myframe, the busy window cursor can be specified for
it by either option command:
option add *myframe.busyCursor gumby
option add *Frame.BusyCursor gumby
9
blt_busy release window ?window ...?
Permits events to be received by window again. This
differs from the forget command in that the busy window
is retained, but is not active. An error is reported
if window is not a host window. This command returns
blt_busy forget window ?window ...?
Permits events to be received again by window by
destroying the busy window. An error is reported
window is not a host window. This command returns the
empty string.
blt_busy hosts ?pattern?
Returns the pathnames of all host windows which have a
busy window associated with them. If a pattern
argument is present, the pathnames of hosts matching
pattern are returned.
blt_busy status window
Returns the status of the busy window associated with
window. An error is reported if window is not a host
window. If window is currently prevented from receiving
events, 1 is returned, otherwise 0.
KEYBOARD EVENTS
Since Tk allows for keyboard events to be redirected through
windows not in the parent window's hierarchy, care must be
taken to turn off focus while processing is occurring.
blt_busy hold .frame
focus none
9 The above example clears the focus immediately after
invoking the hold command so that no keyboard events will be
relayed to windows under the hierarchy of .frame.
BUGS
Creating a busy window will generate Enter/Leave events for
windows that it covers. Please note this when tracking
Enter/Leave events for windows.
There's no way to exempt particular windows in an hierarchy
so that they may still receive events. The busy window is
always mapped above its siblings. The work around is to
create busy windows for each child in the hierarchy (except
for the windows where events are desired) instead of the
parent window.
When busy windows are created, they are automatically
mapped; thus blocking events from the parent and its
descendants. There is no two-step process which allows one
to create a busy window, and later when convenient, to
activate it so that it blocks events.
KEYWORDS
busy, keyboard events, pointer events, window, cursor