/usr/share/doc/blt-dev/html/busy.html is in blt-dev 2.5.3+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>busy(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
busy - Make Tk widgets busy, temporarily blocking
user interactions.
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>busy hold <I>window</I></B> ?<I>option value</I>?... <P>
<B>busy release
<I>window</I></B> ?<I>window</I>?... <P>
<B>busy configure <I>window</I></B> ?<I>option value</I>?... <P>
<B>busy forget <I>window</I></B>
?<I>window</I>?... <P>
<B>busy isbusy </B>?<I>pattern</I>? <P>
<B>busy names </B>?<I>pattern</I>? <P>
<B>busy status <I>window</I></B>
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
<P>
The <B>busy</B> 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.
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
<P>
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. <P>
The <B>busy</B> 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. <P>
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. <P>
Often, the busy command
can be used instead of Tk's <B>grab</B> command. Unlike <B>grab</B> 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).
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
You can make several widgets busy by simply making its ancestor
widget busy using the <B>hold</B> operation. <BR>
<CODE>frame .top<BR>
button .top.button; canvas .top.canvas<BR>
pack .top.button .top.canvas<BR>
pack .top<BR>
. . .<BR>
busy hold .top<BR>
update<BR>
</CODE><P>All the widgets within <I>.top</I> (including <I>.top</I>) are now busy. Using <B>update</B>
insures that <B>busy</B> command will take effect before any other user events
can occur. <P>
When the application is no longer busy processing, you can allow
user interactions again by the <B>release</B> operation. <BR>
<PRE><I><tt> </tt> <tt> </tt> busy release .top </I>
</PRE>The busy window has a configurable cursor. You can change the busy cursor
using the <B>configure</B> operation. <BR>
<PRE><I><tt> </tt> <tt> </tt> busy configure .top -cursor "watch"</I>
</PRE>Finally, when you no longer need to the busy window, invoke the <B>forget</B>
operation to free any resources it allocated. <BR>
<PRE><I><tt> </tt> <tt> </tt> busy forget .top </I>
</PRE>Destroying the widget will also clean up any resources allocated by the
busy command. <P>
<H2><A NAME="sect5" HREF="#toc5">Operations</A></H2>
The following operations are available for the <B>busy</B>
command:
<DL>
<DT><B>busy hold <I>window</I></B> ?<I>option value</I>?... </DT>
<DD>Makes the widget <I>window</I> (and its
descendants in the Tk window hierarchy) busy. <I>Window</I> 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 <B>update</B> should be called immediately afterward to insure
that the <B>hold</B> operation is in effect <I>before</I> the application starts its
processing. The following configuration options are valid: <blockquote></DD>
<DT><B>-cursor <I>cursorName</I></B>
</DT>
<DD>Specifies the cursor to be displayed when the widget is made busy. <I>CursorName</I>
can be in any form accepted by <B>Tk_GetCursor</B>. The default cursor is <I>watch</I>.
</DD>
</DL>
</blockquote>
<DL>
<DT><B>busy configure <I>window</I></B> ?<I>option value</I>?... </DT>
<DD>Queries or modifies the <B>busy</B> command
configuration options for <I>window</I>. <I>Window</I> must be the path name of a widget
previously made busy by the <B>hold</B> operation. If no options are specified,
a list describing all of the available options for <I>window</I> (see <B>Tk_ConfigureInfo</B>
for information on the format of this list) is returned. If <I>option</I> is specified
with no <I>value</I>, 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 <I>option</I> is specified). If one or more <I>option-value</I> 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.
<I>Option</I> may have any of the values accepted by the <B>hold</B> operation. <P>
Please
note that the option database is referenced through <I>window</I>. For example,
if the widget <I>.frame</I> is to be made busy, the busy cursor can be specified
for it by either <B>option</B> command: <BR>
<PRE><tt> </tt> <tt> </tt> <I>option add *frame.busyCursor gumby</I>
<tt> </tt> <tt> </tt> <I>option add *Frame.BusyCursor gumby</I>
</PRE></DD>
<DT><B>busy forget <I>window</I></B> ?<I>window</I>?... </DT>
<DD>Releases resources allocated by the busy command
for <I>window</I>, including the busy window. User events will again be received
again by <I>window</I>. Resources are also released when <I>window</I> is destroyed.
<I>Window</I> must be the name of a widget specified in the <B>hold</B> operation, otherwise
an error is reported. </DD>
<DT><B>busy isbusy </B>?<I>pattern</I>? </DT>
<DD>Returns the pathnames of all
widgets that are currently busy. If a <I>pattern</I> is given, the path names of
busy widgets matching <I>pattern</I> are returned. </DD>
<DT><B>busy names </B>?<I>pattern</I>? </DT>
<DD>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 <I>pattern</I> is given, the path
names of busy widgets matching <I>pattern</I> are returned. </DD>
<DT><B>busy release <I>window</I></B>
?<I>window</I>?... </DT>
<DD>Restores user interactions to the widget <I>window</I> again. This differs
from the <B>forget</B> operation in that the busy window is not destroyed, but
simply unmapped. <I>Window</I> must be the name of a widget specified in a <B>hold</B>
operation, otherwise an error is reported. </DD>
<DT><B>busy status <I>window</I></B> </DT>
<DD>Returns the
status of a widget <I>window</I> previously made busy. An error is reported if
<I>window</I> was never made busy, or the <B>forget</B> operation was invoked (i.e. does
not currently have a busy window associated with it). If <I>window</I> is presently
can not receive user interactions, <I>1</I> is returned, otherwise <I>0</I>. <P>
</DD>
</DL>
<H2><A NAME="sect6" HREF="#toc6">Bindings</A></H2>
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 <B>bind</B> command, to handle
events in the busy window. <BR>
<CODE>busy hold .frame.canvas<BR>
bind .frame.canvas_Busy <Enter> { ... } <BR>
<P>
</CODE><P>Normally the busy window is a sibling of the widget. The name of the busy
window is "<I>widget<I>_Busy</I></I>" where <I>widget</I> is the name of the widget to be made
busy. In the previous example, the pathname of the busy window is "<I>.frame.canvas_Busy</I>"
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 "<I>widget<I>._Busy</I></I>" where <I>widget</I> is the name of the toplevel
widget. In the following example, the pathname of the busy window is "<I>._Busy</I>"
<BR>
<CODE>busy hold .<BR>
bind ._Busy <Enter> { ... } <BR>
<H2><A NAME="sect7" HREF="#toc7"></CODE><P>Enter/Leave Events</A></H2>
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.
<H2><A NAME="sect8" HREF="#toc8">Keyboard Events</A></H2>
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. <BR>
<CODE>busy hold .frame<BR>
label .dummy<BR>
focus .dummy<BR>
update<BR>
</CODE><P>The above example moves the focus from .frame immediately after invoking
the <B>hold</B> so that no keyboard events will be sent to <I>.frame</I> or any of its
descendants.
<H2><A NAME="sect9" HREF="#toc9">Keywords</A></H2>
busy, keyboard events, pointer events, window, cursor
<P>
<P>
<P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Operations</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Bindings</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Enter/Leave Events</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Keyboard Events</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Keywords</A></LI>
</UL>
</BODY></HTML>
|