--- /dev/null
+'\"
+'\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
+'\"
+'\" Permission to use, copy, modify, and distribute this software and its
+'\" documentation for any purpose and without fee is hereby granted, provided
+'\" that the above copyright notice appear in all copies and that both that the
+'\" copyright notice and warranty disclaimer appear in supporting documentation,
+'\" and that the names of Lucent Technologies any of their entities not be used
+'\" in advertising or publicity pertaining to distribution of the software
+'\" without specific, written prior permission.
+'\"
+'\" Lucent Technologies disclaims all warranties with regard to this software,
+'\" including all implied warranties of merchantability and fitness. In no event
+'\" shall Lucent Technologies be liable for any special, indirect or
+'\" consequential damages or any damages whatsoever resulting from loss of use,
+'\" data or profits, whether in an action of contract, negligence or other
+'\" tortuous action, arising out of or in connection with the use or performance
+'\" of this software.
+'\"
+'\" Busy command created by George Howlett.
+'\"
+.so man.macros
+.TH busy n BLT_VERSION BLT "BLT Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+busy \- Make Tk widgets busy, temporarily blocking user interactions.
+.SH SYNOPSIS
+\fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
+.sp
+\fBbusy release \fIwindow\fR ?\fIwindow\fR?...
+.sp
+\fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
+.sp
+\fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
+.sp
+\fBbusy isbusy \fR?\fIpattern\fR?
+.sp
+\fBbusy names \fR?\fIpattern\fR?
+.sp
+\fBbusy status \fIwindow\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBbusy\fR 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.
+.SH INTRODUCTION
+.PP
+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.
+.PP
+The \fBbusy\fR 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.
+.PP
+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.
+.PP
+Often, the busy command can be used instead of Tk's \fBgrab\fR
+command. Unlike \fBgrab\fR 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).
+.SH EXAMPLE
+You can make several widgets busy by simply making its ancestor widget
+busy using the \fBhold\fR operation.
+.CS
+frame .top
+button .top.button; canvas .top.canvas
+pack .top.button .top.canvas
+pack .top
+ . . .
+busy hold .top
+update
+.CE
+All the widgets within \fB.top\fR (including \fB.top\fR) are now busy.
+Using \fBupdate\fR insures that \fBbusy\fR command will take effect before
+any other user events can occur.
+.PP
+When the application is no longer busy processing, you can allow user
+interactions again by the \fBrelease\fR operation.
+.nf
+
+\fB busy release .top \fR
+
+.fi
+The busy window has a configurable cursor. You can change the busy
+cursor using the \fBconfigure\fR operation.
+.nf
+
+\fB busy configure .top -cursor "watch"\fR
+
+.fi
+Finally, when you no longer need to the busy window,
+invoke the \fBforget\fR operation to free any resources it allocated.
+.nf
+
+\fB busy forget .top \fR
+
+.fi
+Destroying the widget will also clean up any resources allocated by
+the busy command.
+.PP
+.SH OPERATIONS
+The following operations are available for the \fBbusy\fR command:
+.TP
+\fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
+Makes the widget \fIwindow\fR (and its descendants in the Tk window
+hierarchy) busy. \fIWindow\fR 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 \fBupdate\fR should be called
+immediately afterward to insure that the \fBhold\fR operation is in
+effect \fIbefore\fR the application starts its processing. The
+following configuration options are valid:
+.RS
+.TP
+\fB\-cursor \fIcursorName\fR
+Specifies the cursor to be displayed when the widget is made busy.
+\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR.
+The default cursor is \fBwatch\fR.
+.RE
+.TP
+\fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
+Queries or modifies the \fBbusy\fR command configuration options for
+\fIwindow\fR. \fIWindow\fR must be the path name of a widget previously
+made busy by the \fBhold\fR operation. If no options are
+specified, a list describing all of the available options for
+\fIwindow\fR (see \fBTk_ConfigureInfo\fR for information on the format
+of this list) is returned. If \fIoption\fR is specified with no
+\fIvalue\fR, 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 \fIoption\fR is specified). If one or more
+\fIoption\-value\fR 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. \fIOption\fR may have any of the
+values accepted by the \fBhold\fR operation.
+.sp
+Please note that the
+option database is referenced through \fIwindow\fR. For example, if
+the widget \fB.frame\fR is to be made busy, the busy
+cursor can be specified for it by either \fBoption\fR command:
+.nf
+
+ \fBoption add *frame.busyCursor gumby\fR
+ \fBoption add *Frame.BusyCursor gumby\fR
+
+.fi
+.TP
+\fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
+Releases resources allocated by the busy command for \fIwindow\fR,
+including the busy window. User events will again be received again
+by \fIwindow\fR. Resources are also released when \fIwindow\fR
+is destroyed. \fIWindow\fR must be the name of a widget specified
+in the \fBhold\fR operation, otherwise an error is reported.
+.TP
+\fBbusy isbusy \fR?\fIpattern\fR?
+Returns the pathnames of all widgets that are currently busy.
+If a \fIpattern\fR is given, the path names of busy widgets
+matching \fIpattern\fR are returned.
+.TP
+\fBbusy names \fR?\fIpattern\fR?
+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 \fIpattern\fR is given, the path names of busy widgets
+matching \fIpattern\fR are returned.
+.TP
+\fBbusy release \fIwindow\fR ?\fIwindow\fR?...
+Restores user interactions to the widget \fIwindow\fR again.
+This differs from the \fBforget\fR operation in that the busy window
+is not destroyed, but simply unmapped.
+\fIWindow\fR must be the name of a widget specified
+in a \fBhold\fR operation, otherwise an error is reported.
+.TP
+\fBbusy status \fIwindow\fR
+Returns the status of a widget \fIwindow\fR previously made busy.
+An error is reported if \fIwindow\fR was never made busy, or
+the \fBforget\fR operation was invoked (i.e. does not currently have a
+busy window associated with it). If \fIwindow\fR is presently can
+not receive user interactions, \fB1\fR is returned, otherwise \fB0\fR.
+.sp 1
+.SH BINDINGS
+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 \fBbind\fR command, to handle events in the busy window.
+.CS
+busy hold .frame.canvas
+bind .frame.canvas_Busy <Enter> { ... }
+.CE
+.PP
+Normally the busy window is a sibling of the widget. The
+name of the busy window is "\fIwidget\fB_Busy\fR" where \fIwidget\fR
+is the name of the widget to be made busy. In the previous example, the
+pathname of the busy window is "\fB.frame.canvas_Busy\fR" 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 "\fIwidget\fB._Busy\fR" where \fIwidget\fR
+is the name of the toplevel widget. In the following example, the
+pathname of the busy window is "\fB._Busy\fR"
+.CS
+busy hold .
+bind ._Busy <Enter> { ... }
+.CE
+.SH ENTER/LEAVE EVENTS
+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.
+.SH KEYBOARD EVENTS
+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.
+.CS
+busy hold .frame
+label .dummy
+focus .dummy
+update
+.CE
+The above example moves the focus from .frame immediately after
+invoking the \fBhold\fR so that no keyboard events will be sent to
+\fB.frame\fR or any of its descendants.
+.SH KEYWORDS
+busy, keyboard events, pointer events, window, cursor
+
+
OSDN Git Service
