SGI/util/SGI/man/mann/busy.n

   1 '\"
   2 '\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
   3 '\"
   4 '\" Permission to use, copy, modify, and distribute this software and its
   5 '\" documentation for any purpose and without fee is hereby granted, provided
   6 '\" that the above copyright notice appear in all copies and that both that the
   7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
   8 '\" and that the names of Lucent Technologies any of their entities not be used
   9 '\" in advertising or publicity pertaining to distribution of the software
  10 '\" without specific, written prior permission.
  11 '\"
  12 '\" Lucent Technologies disclaims all warranties with regard to this software,
  13 '\" including all implied warranties of merchantability and fitness.  In no event
  14 '\" shall Lucent Technologies be liable for any special, indirect or
  15 '\" consequential damages or any damages whatsoever resulting from loss of use,
  16 '\" data or profits, whether in an action of contract, negligence or other
  17 '\" tortuous action, arising out of or in connection with the use or performance
  18 '\" of this software.
  19 '\"
  20 '\" Busy command created by George Howlett.
  21 '\"
  22 '\" The definitions below are for supplemental macros used in Tcl/Tk
  23 '\" manual entries.
  24 '\"
  25 '\" .HS name section [date [version]]
  26 '\"     Replacement for .TH in other man pages.  See below for valid
  27 '\"     section names.
  28 '\"
  29 '\" .AP type name in/out [indent]
  30 '\"     Start paragraph describing an argument to a library procedure.
  31 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  32 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  33 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  34 '\"     needed;  use .AS below instead)
  35 '\"
  36 '\" .AS [type [name]]
  37 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  38 '\"     name are examples of largest possible arguments that will be passed
  39 '\"     to .AP later.  If args are omitted, default tab stops are used.
  40 '\"
  41 '\" .BS
  42 '\"     Start box enclosure.  From here until next .BE, everything will be
  43 '\"     enclosed in one large box.
  44 '\"
  45 '\" .BE
  46 '\"     End of box enclosure.
  47 '\"
  48 '\" .VS
  49 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  50 '\"     of man pages.
  51 '\"
  52 '\" .VE
  53 '\"     End of vertical sidebar.
  54 '\"
  55 '\" .DS
  56 '\"     Begin an indented unfilled display.
  57 '\"
  58 '\" .DE
  59 '\"     End of indented unfilled display.
  60 '\"
  61 '\"     # Heading for Tcl/Tk man pages
  62 .de HS
  63 .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  64 .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  65 .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  66 .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  67 .if '\\$2'BLT'        .TH \\$1 "BLT 2.4" \\$3 \\$4
  68 .if t .wh -1.3i ^B
  69 .nr ^l \\n(.l
  70 .ad b
  71 ..
  72 '\"     # Start an argument description
  73 .de AP
  74 .ie !"\\$4"" .TP \\$4
  75 .el \{\
  76 .   ie !"\\$2"" .TP \\n()Cu
  77 .   el          .TP 15
  78 .\}
  79 .ie !"\\$3"" \{\
  80 .ta \\n()Au \\n()Bu
  81 \&\\$1  \\fI\\$2\\fP    (\\$3)
  82 '\".b
  83 .\}
  84 .el \{\
  85 .br
  86 .ie !"\\$2"" \{\
  87 \&\\$1  \\fI\\$2\\fP
  88 .\}
  89 .el \{\
  90 \&\\fI\\$1\\fP
  91 .\}
  92 .\}
  93 ..
  94 '\"     # define tabbing values for .AP
  95 .de AS
  96 .nr )A 10n
  97 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  98 .nr )B \\n()Au+15n
  99 '\"
 100 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 101 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 102 ..
 103 '\"     # BS - start boxed text
 104 '\"     # ^y = starting y location
 105 '\"     # ^b = 1
 106 .de BS
 107 .br
 108 .mk ^y
 109 .nr ^b 1u
 110 .if n .nf
 111 .if n .ti 0
 112 .if n \l'\\n(.lu\(ul'
 113 .if n .fi
 114 ..
 115 '\"     # BE - end boxed text (draw box now)
 116 .de BE
 117 .nf
 118 .ti 0
 119 .mk ^t
 120 .ie n \l'\\n(^lu\(ul'
 121 .el \{\
 122 '\"     Draw four-sided box normally, but don't draw top of
 123 '\"     box if the box started on an earlier page.
 124 .ie !\\n(^b-1 \{\
 125 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 126 .\}
 127 .el \}\
 128 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 129 .\}
 130 .\}
 131 .fi
 132 .br
 133 .nr ^b 0
 134 ..
 135 '\"     # VS - start vertical sidebar
 136 '\"     # ^Y = starting y location
 137 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 138 .de VS
 139 .mk ^Y
 140 .ie n 'mc \s12\(br\s0
 141 .el .nr ^v 1u
 142 ..
 143 '\"     # VE - end of vertical sidebar
 144 .de VE
 145 .ie n 'mc
 146 .el \{\
 147 .ev 2
 148 .nf
 149 .ti 0
 150 .mk ^t
 151 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 152 .sp -1
 153 .fi
 154 .ev
 155 .\}
 156 .nr ^v 0
 157 ..
 158 '\"     # Special macro to handle page bottom:  finish off current
 159 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 160 '\"     # page bottom macro.
 161 .de ^B
 162 .ev 2
 163 'ti 0
 164 'nf
 165 .mk ^t
 166 .if \\n(^b \{\
 167 '\"     Draw three-sided box if this is the box's first page,
 168 '\"     draw two sides but no top otherwise.
 169 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 170 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 171 .\}
 172 .if \\n(^v \{\
 173 .nr ^x \\n(^tu+1v-\\n(^Yu
 174 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 175 .\}
 176 .bp
 177 'fi
 178 .ev
 179 .if \\n(^b \{\
 180 .mk ^y
 181 .nr ^b 2
 182 .\}
 183 .if \\n(^v \{\
 184 .mk ^Y
 185 .\}
 186 ..
 187 '\"     # DS - begin display
 188 .de DS
 189 .RS
 190 .ft CW
 191 .nf
 192 .sp
 193 ..
 194 '\"     # DE - end display
 195 .de DE
 196 .ft R
 197 .fi
 198 .sp
 199 .RE
 200 ..
 201 .HS busy BLT
 202 .BS
 203 '\" Note:  do not modify the .SH NAME line immediately below!
 204 .SH NAME
 205 busy \- Make Tk widgets busy, temporarily blocking user interactions.
 206 .SH SYNOPSIS
 207 \fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
 208 .sp
 209 \fBbusy release \fIwindow\fR ?\fIwindow\fR?...
 210 .sp
 211 \fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
 212 .sp
 213 \fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
 214 .sp
 215 \fBbusy isbusy \fR?\fIpattern\fR?
 216 .sp
 217 \fBbusy status \fIwindow\fR
 218 .sp
 219 \fBbusy windows \fR?\fIpattern\fR?
 220 .BE
 221 .SH DESCRIPTION
 222 .PP
 223 The \fBbusy\fR command provides a simple means to block
 224 keyboard, button, and pointer events from Tk widgets, while overriding
 225 the widget's cursor with a configurable busy cursor.
 226 .SH INTRODUCTION
 227 .PP
 228 There are many times in applications where you want to temporarily
 229 restrict what actions the user can take.  For example, an application
 230 could have a "run" button that when pressed causes some processing to
 231 occur.  But while the application is busy processing, you probably don't
 232 want the the user to be able to click the "run" button again.  You
 233 may also want restrict the user from other tasks such as clicking a
 234 "print" button.
 235 .PP
 236 The \fBbusy\fR command lets you make Tk widgets busy. This means
 237 that user interactions such as button clicks, moving the mouse, typing
 238 at the keyboard, etc. are ignored by the widget.  You can also set a
 239 special cursor (like a watch) which overrides the widget's normal
 240 cursor, providing feedback that the application (widget) is
 241 temporarily busy.
 242 .PP
 243 When a widget is made busy, all of the widgets in its window
 244 hierarchy also become busy.  It's easy then to make an entire panel of
 245 widgets busy by simply making the uppermost widget (such as ".") busy.
 246 This is far easier and much more efficient than recursively traversing
 247 the widget hierarchy, disabling each widget and re-configuring its
 248 cursor.
 249 .PP
 250 The busy command can also be used in many cases instead of Tk's \fBgrab\fR
 251 command.  Unlike \fBgrab\fR which directs all user interaction to one
 252 widget, the busy command allows more than one widget to be active (for
 253 example, a "cancel" dialog and a "help" button) while the other
 254 widgets are busy.
 255 .SH EXAMPLE
 256 You can make a set of widgets busy by simply making the uppermost widget
 257 in the hierarchy busy using the \fBhold\fR operation.
 258 .DS
 259 frame .top
 260 button .top.button; canvas .top.canvas
 261 pack .top.button .top.canvas
 262 pack .top
 263   . . .
 264 busy hold .top
 265 update
 266 .DE
 267 All the widgets within \f(CW.top\fR (including \f(CW.top\fR) are now busy.
 268 The \fBupdate\fR command insures that \fBbusy\fR command has a
 269 chance to effect.
 270 .PP
 271 When the application is no longer busy, you can allow user interaction again
 272 by the \fBrelease\fR operation.
 273 .nf
 274
 275 \f(CW   busy release .top \fR
 276
 277 .fi
 278 You can change the busy cursor using the \fBconfigure\fR operation.
 279 .nf
 280
 281 \f(CW   busy configure .top -cursor "watch"\fR
 282
 283 .fi
 284 Finally, when you no longer need to make the widget busy anymore,
 285 invoke the \fBforget\fR operation to free any resources allocated.
 286 .nf
 287
 288 \f(CW   busy forget .top \fR
 289
 290 .fi
 291 Destroying the widget also cleans up any resources allocated
 292 by the busy command.
 293 .PP
 294 .SH OPERATIONS
 295 The following operations are available for the \fBbusy\fR command:
 296 .TP
 297 \fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
 298 Makes the widget \fIwindow\fR (and its descendants in the Tk window
 299 hierarchy) busy.  \fIWindow\fR must be a valid path name of a Tk
 300 widget.  After idle tasks are processed, the widget will be blocked
 301 from user interactions. All device events in the widget window and its
 302 descendants will be ignored.  Typically \fBupdate\fR should be called
 303 immediately afterward to insure that the \fBhold\fR operation is in
 304 effect \fIbefore\fR the application starts its processing. The
 305 following configuration options are valid:
 306 .RS
 307 .TP
 308 \fB\-cursor \fIcursorName\fR
 309 Specifies the cursor to be displayed when the widget is made busy.
 310 \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR.
 311 The default cursor is \f(CWwatch\fR.
 312 .RE
 313 .TP
 314 \fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
 315 Queries or modifies the \fBbusy\fR command configuration options for
 316 \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously
 317 made busy by the \fBhold\fR operation.  If no options are
 318 specified, a list describing all of the available options for
 319 \fIwindow\fR (see \fBTk_ConfigureInfo\fR for information on the format
 320 of this list) is returned.  If \fIoption\fR is specified with no
 321 \fIvalue\fR, then the command returns a list describing the one named
 322 option (this list will be identical to the corresponding sublist of
 323 the value returned if no \fIoption\fR is specified).  If one or more
 324 \fIoption\-value\fR pairs are specified, then the command modifies the
 325 given widget option(s) to have the given value(s); in this case the
 326 command returns the empty string.  \fIOption\fR may have any of the
 327 values accepted by the \fBhold\fR operation.
 328 .sp
 329 Please note that the
 330 option database is referenced through \fIwindow\fR.  For example, if
 331 the widget \f(CW.frame\fR is to be made busy, the busy
 332 cursor can be specified for it by either \fBoption\fR command:
 333 .nf
 334
 335         \f(CWoption add *frame.busyCursor gumby\fR
 336         \f(CWoption add *Frame.BusyCursor gumby\fR
 337
 338 .fi
 339 .TP
 340 \fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
 341 Releases resources allocated by the busy command for \fIwindow\fR,
 342 including the InputOnly window.  User events will again be received again
 343 by \fIwindow\fR.  Busy resources are also released when \fIwindow\fR
 344 is destroyed. \fIWindow\fR must be the name of a widget specified
 345 in the \fBhold\fR operation, otherwise an error is reported.
 346 .TP
 347 \fBbusy isbusy \fR?\fIpattern\fR?
 348 Returns the pathnames of all widget windows which are currently busy.
 349 If a \fIpattern\fR is given, the path names of busy widgets
 350 matching \fIpattern\fR are returned.
 351 .TP
 352 \fBbusy release \fIwindow\fR ?\fIwindow\fR?...
 353 Restores user interactions to the widget \fIwindow\fR again.
 354 This differs from the \fBforget\fR operation in that the InputOnly window
 355 is not destroyed, but simply unmapped.
 356 \fIWindow\fR must be the name of a widget specified
 357 in a \fBhold\fR operation, otherwise an error is reported.
 358 .TP
 359 \fBbusy status \fIwindow\fR
 360 Returns the status of a widget \fIwindow\fR previously made busy.
 361 An error is reported if \fIwindow\fR was never made busy, or
 362 the \fBforget\fR operation was invoked (i.e. does not currently have a
 363 InputOnly window associated with it).  If \fIwindow\fR is presently can
 364 not receive user interaction, \f(CW1\fR is returned, otherwise \f(CW0\fR.
 365 .TP
 366 \fBbusy windows \fR?\fIpattern\fR?
 367 Returns the pathnames of all widget windows which have previously been
 368 made busy (i.e. an InputOnly is allocated and associated with the
 369 widget).  It makes no difference if the window is currently busy ot
 370 not.  If a \fIpattern\fR is given, the path names of busy widgets
 371 matching \fIpattern\fR are returned.
 372 .sp 1
 373 .SH BINDINGS
 374 The blocking feature is implemented by creating and mapping a
 375 transparent InputOnly class window which completely covers the
 376 widget.  When the InputOnly window is mapped, it intercepts all
 377 events which could be sent to the widget and its hierarchy.
 378 Like Tk widgets, the InputOnly windows have names in the
 379 Tk window hierarchy.  This means that you can use the \fBbind\fR
 380 command, to handle events in the InputOnly window.
 381 .DS
 382 busy hold .frame.canvas
 383 bind .frame.canvas_Busy <Enter> { ... }
 384 .DE
 385 .PP
 386 Typically, the InputOnly window is a sibling of the widget's window.
 387 The name of the InputOnly window will be "\fIwidget\f(CW_Busy\fR" where
 388 \fIwidget\fR is the name of the widget made busy.  In the above example,
 389 the pathname of the InputOnly window is "\f(CW.frame.canvas_Busy\fR"
 390 The exception is when the widget is a toplevel window (such as ".").
 391 Then the InputOnly window is a child of the widget's window and the name of
 392 the widget will be "\fIwidget\f(CW._Busy\fR" where \fIwidget\fR is the name
 393 of the widget made busy.  In the following example,
 394 the pathname of the InputOnly window is "\f(CW._Busy\fR"
 395 .DS
 396 busy hold .
 397 bind ._Busy <Enter> { ... }
 398 .DE
 399 .SH ENTER/LEAVE EVENTS
 400 Mapping and unmapping the InputOnly window generates Enter/Leave
 401 events for all widget (windows) that it covers.  Please note this when
 402 you are tracking Enter/Leave events in widgets.
 403 .SH KEYBOARD EVENTS
 404 When a widget is made busy, the widget is prevented from gaining the
 405 keyboard focus by the InputOnly window. But Tk widgets can still get
 406 keyboard events if the keyboard focus is already set. Care must be
 407 taken to move focus to another window.
 408 .DS
 409 busy hold .frame
 410 label .dummy
 411 focus .dummy
 412 update
 413 .DE
 414 The above example moves the focus from .frame immediately after
 415 invoking the \fBhold\fR so that no keyboard events will be relayed to
 416 windows under the hierarchy of \f(CW.frame\fR.
 417 .SH KEYWORDS
 418 busy, keyboard events, pointer events, window, cursor
 419
 420