diff options
Diffstat (limited to 'blt/html/busy.html')
| -rw-r--r-- | blt/html/busy.html | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/blt/html/busy.html b/blt/html/busy.html new file mode 100644 index 00000000000..c588faf252c --- /dev/null +++ b/blt/html/busy.html @@ -0,0 +1,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> |