diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/busy.n | 268 | ||||
| -rw-r--r-- | doc/grab.n | 4 | ||||
| -rw-r--r-- | doc/tk.n | 13 |
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: @@ -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: @@ -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: |