Implementation of the [tk busy] command on non-OSX.

Adapted from [Patch 1997907]

3 files changed, 281 insertions, 4 deletions

diff --git a/doc/busy.n b/doc/busy.n
new file mode 100644
index 0000000..b355a29
--- /dev/null
+++ b/doc/busy.n
@@ -0,0 +1,268 @@
+'\"
+'\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
+'\" Copyright (c) 2008, Jos Decoster
+'\"
+'\" 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.
+'\"
+'\" BLT::busy command created by George Howlett.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: busy.n,v 1.1 2008/10/18 14:22:21 dkf Exp $
+'\"
+.so man.macros
+.TH busy n "" Tk "Tk Built-In Commands"
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+busy \- confine pointer and keyboard events to a window sub-tree
+.SH SYNOPSIS
+\fBtk busy\fR \fIwindow \fR?\fIoptions\fR?
+.sp
+\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR?
+.sp
+\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?...
+.sp
+\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?...
+.sp
+\fBtk busy current\fR ?\fIpattern\fR?
+.sp
+\fBtk busy status \fIwindow\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBtk busy\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
+.QW 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
+.QW Run
+button again. You may also want restrict the user from other tasks such as
+clicking a
+.QW Print
+button.
+.PP
+The \fBtk busy\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.\0are 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
+.QW . )
+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 \fBtk busy\fR command can be used instead of Tk's \fBgrab\fR
+command. Unlike \fBgrab\fR which restricts all user interactions to one
+widget, with the \fBtk busy\fR command you can have more than one widget
+active (for example, a
+.QW Cancel
+dialog and a
+.QW Help
+button).
+.SS EXAMPLE
+.PP
+You can make several widgets busy by simply making its ancestor widget busy
+using the \fBhold\fR operation.
+.PP
+.CS
+frame .top
+button .top.button; canvas .top.canvas
+pack .top.button .top.canvas
+pack .top
+# . . .
+\fBtk busy\fR hold .top
+update
+.CE
+.PP
+All the widgets within \fB.top\fR (including \fB.top\fR) are now busy. Using
+\fBupdate\fR insures that \fBtk busy\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 and free any resources it allocated by the \fBforget\fR
+operation.
+.PP
+.CS
+\fBtk busy\fR forget .top
+.CE
+.PP
+The busy window has a configurable cursor. You can change the busy cursor
+using the \fBconfigure\fR operation.
+.PP
+.CS
+\fBtk busy\fR configure .top \-cursor "watch"
+.CE
+.PP
+Destroying the widget will also clean up any resources allocated by the \fBtk
+busy\fR command.
+.PP
+.SH OPERATIONS
+.PP
+The following operations are available for the \fBtk busy\fR command:
+.TP
+\fBtk busy \fIwindow\fR ?\fIoption value\fR?...
+.
+Shortcut for \fBtk busy hold\fR command.
+.TP
+\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?...
+.
+Makes the specified \fIwindow\fR (and its descendants in the Tk window
+hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget.
+A transparent window is put in front of the specified window. This transparent
+window is mapped the next time idle tasks are processed, and the specified
+window and its descendants will be blocked from user interactions. Normally
+\fBupdate\fR 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:
+.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 \fBwait\fR on Windows and \fBwatch\fR on other platforms.
+.RE
+.TP
+\fBtk busy cget \fIwindow\fR \fIoption\fR
+.
+Queries the \fBtk busy\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. The command returns the present value of the specified
+\fIoption\fR. \fIOption\fR may have any of the values accepted by the
+\fBhold\fR operation.
+.TP
+\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?...
+.
+Queries or modifies the \fBtk busy\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.
+.RS
+.PP
+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:
+.PP
+.CS
+option add *frame.busyCursor gumby
+option add *Frame.BusyCursor gumby
+.CE
+.RE
+.TP
+\fBtk busy forget \fIwindow\fR ?\fIwindow\fR?...
+.
+Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR,
+including the transparent window. User events will again be received 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
+\fBtk busy current \fR?\fIpattern\fR?
+.
+Returns the pathnames of all widgets that are currently busy. If a
+\fIpattern\fR is given, only the path names of busy widgets matching
+\fIpattern\fR are returned.
+.TP
+\fBtk busy status \fIwindow\fR
+.
+Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not
+receive user interactions, \fB1\fR is returned, otherwise \fB0\fR.
+.SH "EVENT HANDLING"
+.SS BINDINGS
+.PP
+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.
+.PP
+.CS
+\fBtk busy\fR 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
+.QW \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
+.QW \fB.frame.canvas_Busy\fR .
+The exception is when the widget is a toplevel widget (such as
+.QW . )
+where the busy window can't be made a sibling. The busy window is then a child
+of the widget named
+.QW \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
+.QW \fB._Busy\fR .
+.PP
+.CS
+\fBtk busy\fR hold .
+bind ._Busy <Enter> { ... }
+.CE
+.SS "ENTER/LEAVE EVENTS"
+.PP
+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.
+.SS "KEYBOARD EVENTS"
+.PP
+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.
+.PP
+.CS
+\fBtk busy\fR hold .frame
+label .dummy
+focus .dummy
+update
+.CE
+.PP
+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 PORTABILITY
+.PP
+Note that the \fBtk busy\fR command does not currently have any effect on OSX
+when Tk is built using Aqua support.
+.SH "SEE ALSO"
+grab(n)
+.SH KEYWORDS
+busy, keyboard events, pointer events, window
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/grab.n b/doc/grab.n
index 1d87086..670dc9d 100644
--- a/doc/grab.n
+++ b/doc/grab.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: grab.n,v 1.10 2008/09/23 13:36:40 dkf Exp $
+'\" RCS: @(#) $Id: grab.n,v 1.11 2008/10/18 14:22:21 dkf Exp $
 '\" 
 .so man.macros
 .TH grab n "" Tk "Tk Built-In Commands"
@@ -133,6 +133,8 @@ pack [button .b2 \-text "Click me! #2" \-command {destroy .b2}]
 pack [button .b3 \-text "Click me! #3" \-command {destroy .b3}]
 \fBgrab\fR .b2
 .CE
+.SH "SEE ALSO"
+busy(n)
 .SH KEYWORDS
 grab, keyboard events, pointer events, window
 '\" Local Variables:
diff --git a/doc/tk.n b/doc/tk.n
index e36106f..ece777e 100644
--- a/doc/tk.n
+++ b/doc/tk.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tk.n,v 1.19 2008/09/23 13:36:55 dkf Exp $
+'\" RCS: @(#) $Id: tk.n,v 1.20 2008/10/18 14:22:21 dkf Exp $
 '\" 
 .so man.macros
 .TH tk n 8.4 Tk "Tk Built-In Commands"
@@ -47,6 +47,13 @@ If sends have been disabled by deleting the \fBsend\fR command,
 this command will reenable them and recreate the \fBsend\fR
 command.
 .TP
+\fBtk busy \fIsubcommand\fR ...
+.
+This command controls the marking of window hierarchies as
+.QW busy ,
+rendering them non-interactive while some other operation is proceeding. For
+more details see the \fBbusy\fR manual page.
+.TP
 \fBtk caret window \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR?
 .
 Sets and queries the caret location for the display of the specified
@@ -65,7 +72,7 @@ Sets and queries the current scaling factor used by Tk to convert between
 physical units (for example, points, inches, or millimeters) and pixels.  The
 \fInumber\fR argument is a floating point number that specifies the number of
 pixels per point on \fIwindow\fR's display.  If the \fIwindow\fR argument is
-omitted, it defaults to the main window.  If the \fInumber\fR argument is 
+omitted, it defaults to the main window.  If the \fInumber\fR argument is
 omitted, the current value of the scaling factor is returned.
 .RS
 .PP
@@ -118,7 +125,7 @@ Returns the current Tk windowing system, one of
 \fBx11\fR (X11-based), \fBwin32\fR (MS Windows),
 or \fBaqua\fR (Mac OS X Aqua).
 .SH "SEE ALSO"
-send(n), winfo(n)
+busy(n), send(n), winfo(n)
 .SH KEYWORDS
 application name, send
 '\" Local Variables: