util/X86LINUX64/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 '\" .AP type name in/out ?indent?
  26 '\"     Start paragraph describing an argument to a library procedure.
  27 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  28 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  29 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  30 '\"     needed;  use .AS below instead)
  31 '\"
  32 '\" .AS ?type? ?name?
  33 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  34 '\"     name are examples of largest possible arguments that will be passed
  35 '\"     to .AP later.  If args are omitted, default tab stops are used.
  36 '\"
  37 '\" .BS
  38 '\"     Start box enclosure.  From here until next .BE, everything will be
  39 '\"     enclosed in one large box.
  40 '\"
  41 '\" .BE
  42 '\"     End of box enclosure.
  43 '\"
  44 '\" .CS
  45 '\"     Begin code excerpt.
  46 '\"
  47 '\" .CE
  48 '\"     End code excerpt.
  49 '\"
  50 '\" .VS ?version? ?br?
  51 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  52 '\"     of man pages.  The first argument is ignored and used for recording
  53 '\"     the version when the .VS was added, so that the sidebars can be
  54 '\"     found and removed when they reach a certain age.  If another argument
  55 '\"     is present, then a line break is forced before starting the sidebar.
  56 '\"
  57 '\" .VE
  58 '\"     End of vertical sidebar.
  59 '\"
  60 '\" .DS
  61 '\"     Begin an indented unfilled display.
  62 '\"
  63 '\" .DE
  64 '\"     End of indented unfilled display.
  65 '\"
  66 '\" .SO
  67 '\"     Start of list of standard options for a Tk widget.  The
  68 '\"     options follow on successive lines, in four columns separated
  69 '\"     by tabs.
  70 '\"
  71 '\" .SE
  72 '\"     End of list of standard options for a Tk widget.
  73 '\"
  74 '\" .OP cmdName dbName dbClass
  75 '\"     Start of description of a specific option.  cmdName gives the
  76 '\"     option's name as specified in the class command, dbName gives
  77 '\"     the option's name in the option database, and dbClass gives
  78 '\"     the option's class in the option database.
  79 '\"
  80 '\" .UL arg1 arg2
  81 '\"     Print arg1 underlined, then print arg2 normally.
  82 '\"
  83 '\" RCS: @(#) $Id: man.macros,v 1.1.1.1 2009/05/09 16:27:42 pcmacdon Exp $
  84 '\"
  85 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  86 .if t .wh -1.3i ^B
  87 .nr ^l \n(.l
  88 .ad b
  89 '\"     # Start an argument description
  90 .de AP
  91 .ie !"\\$4"" .TP \\$4
  92 .el \{\
  93 .   ie !"\\$2"" .TP \\n()Cu
  94 .   el          .TP 15
  95 .\}
  96 .ta \\n()Au \\n()Bu
  97 .ie !"\\$3"" \{\
  98 \&\\$1  \\fI\\$2\\fP    (\\$3)
  99 .\".b
 100 .\}
 101 .el \{\
 102 .br
 103 .ie !"\\$2"" \{\
 104 \&\\$1  \\fI\\$2\\fP
 105 .\}
 106 .el \{\
 107 \&\\fI\\$1\\fP
 108 .\}
 109 .\}
 110 ..
 111 '\"     # define tabbing values for .AP
 112 .de AS
 113 .nr )A 10n
 114 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 115 .nr )B \\n()Au+15n
 116 .\"
 117 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 118 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 119 ..
 120 .AS Tcl_Interp Tcl_CreateInterp in/out
 121 '\"     # BS - start boxed text
 122 '\"     # ^y = starting y location
 123 '\"     # ^b = 1
 124 .de BS
 125 .br
 126 .mk ^y
 127 .nr ^b 1u
 128 .if n .nf
 129 .if n .ti 0
 130 .if n \l'\\n(.lu\(ul'
 131 .if n .fi
 132 ..
 133 '\"     # BE - end boxed text (draw box now)
 134 .de BE
 135 .nf
 136 .ti 0
 137 .mk ^t
 138 .ie n \l'\\n(^lu\(ul'
 139 .el \{\
 140 .\"     Draw four-sided box normally, but don't draw top of
 141 .\"     box if the box started on an earlier page.
 142 .ie !\\n(^b-1 \{\
 143 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 144 .\}
 145 .el \}\
 146 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 147 .\}
 148 .\}
 149 .fi
 150 .br
 151 .nr ^b 0
 152 ..
 153 '\"     # VS - start vertical sidebar
 154 '\"     # ^Y = starting y location
 155 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 156 .de VS
 157 .if !"\\$2"" .br
 158 .mk ^Y
 159 .ie n 'mc \s12\(br\s0
 160 .el .nr ^v 1u
 161 ..
 162 '\"     # VE - end of vertical sidebar
 163 .de VE
 164 .ie n 'mc
 165 .el \{\
 166 .ev 2
 167 .nf
 168 .ti 0
 169 .mk ^t
 170 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 171 .sp -1
 172 .fi
 173 .ev
 174 .\}
 175 .nr ^v 0
 176 ..
 177 '\"     # Special macro to handle page bottom:  finish off current
 178 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 179 '\"     # page bottom macro.
 180 .de ^B
 181 .ev 2
 182 'ti 0
 183 'nf
 184 .mk ^t
 185 .if \\n(^b \{\
 186 .\"     Draw three-sided box if this is the box's first page,
 187 .\"     draw two sides but no top otherwise.
 188 .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
 189 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 190 .\}
 191 .if \\n(^v \{\
 192 .nr ^x \\n(^tu+1v-\\n(^Yu
 193 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 194 .\}
 195 .bp
 196 'fi
 197 .ev
 198 .if \\n(^b \{\
 199 .mk ^y
 200 .nr ^b 2
 201 .\}
 202 .if \\n(^v \{\
 203 .mk ^Y
 204 .\}
 205 ..
 206 '\"     # DS - begin display
 207 .de DS
 208 .RS
 209 .nf
 210 .sp
 211 ..
 212 '\"     # DE - end display
 213 .de DE
 214 .fi
 215 .RE
 216 .sp
 217 ..
 218 '\"     # SO - start of list of standard options
 219 .de SO
 220 .SH "STANDARD OPTIONS"
 221 .LP
 222 .nf
 223 .ta 4c 8c 12c
 224 .ft B
 225 ..
 226 '\"     # SE - end of list of standard options
 227 .de SE
 228 .fi
 229 .ft R
 230 .LP
 231 See the \\fBoptions\\fR manual entry for details on the standard options.
 232 ..
 233 '\"     # OP - start of full description for a single option
 234 .de OP
 235 .LP
 236 .nf
 237 .ta 4c
 238 Command-Line Name:      \\fB\\$1\\fR
 239 Database Name:  \\fB\\$2\\fR
 240 Database Class: \\fB\\$3\\fR
 241 .fi
 242 .IP
 243 ..
 244 '\"     # CS - begin code excerpt
 245 .de CS
 246 .RS
 247 .nf
 248 .ta .25i .5i .75i 1i
 249 .ft CW
 250 .sp
 251 ..
 252 '\"     # CE - end code excerpt
 253 .de CE
 254 .fi
 255 .RE
 256 .ft R
 257 .sp
 258 ..
 259 .de UL
 260 \\$1\l'|0\(ul'\\$2
 261 ..
 262 .TH busy n 2.5 BLT "BLT Built-In Commands"
 263 .BS
 264 '\" Note:  do not modify the .SH NAME line immediately below!
 265 .SH NAME
 266 busy \- Make Tk widgets busy, temporarily blocking user interactions.
 267 .SH SYNOPSIS
 268 \fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
 269 .sp
 270 \fBbusy release \fIwindow\fR ?\fIwindow\fR?...
 271 .sp
 272 \fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
 273 .sp
 274 \fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
 275 .sp
 276 \fBbusy isbusy \fR?\fIpattern\fR?
 277 .sp
 278 \fBbusy names \fR?\fIpattern\fR?
 279 .sp
 280 \fBbusy status \fIwindow\fR
 281 .BE
 282 .SH DESCRIPTION
 283 .PP
 284 The \fBbusy\fR command provides a simple means to block
 285 keyboard, button, and pointer events from Tk widgets, while overriding
 286 the widget's cursor with a configurable busy cursor.
 287 .SH INTRODUCTION
 288 .PP
 289 There are many times in applications where you want to temporarily
 290 restrict what actions the user can take.  For example, an application
 291 could have a "run" button that when pressed causes some processing to
 292 occur.  But while the application is busy processing, you probably don't
 293 want the the user to be able to click the "run" button again.  You
 294 may also want restrict the user from other tasks such as clicking a
 295 "print" button.
 296 .PP
 297 The \fBbusy\fR command lets you make Tk widgets busy. This means
 298 that user interactions such as button clicks, moving the mouse, typing
 299 at the keyboard, etc. are ignored by the widget.  You can set a
 300 special cursor (like a watch) that overrides the widget's normal
 301 cursor, providing feedback that the application (widget) is
 302 temporarily busy.
 303 .PP
 304 When a widget is made busy, the widget and all of its descendents will
 305 ignore events.  It's easy to make an entire panel of widgets busy. You
 306 can simply make the toplevel widget (such as ".") busy.  This is
 307 easier and far much more efficient than recursively traversing the
 308 widget hierarchy, disabling each widget and re-configuring its cursor.
 309 .PP
 310 Often, the busy command can be used instead of Tk's \fBgrab\fR
 311 command.  Unlike \fBgrab\fR which restricts all user interactions to
 312 one widget, with the busy command you can have more than one widget
 313 active (for example, a "cancel" dialog and a "help" button).
 314 .SH EXAMPLE
 315 You can make several widgets busy by simply making its ancestor widget
 316 busy using the \fBhold\fR operation.
 317 .CS
 318 frame .top
 319 button .top.button; canvas .top.canvas
 320 pack .top.button .top.canvas
 321 pack .top
 322   . . .
 323 busy hold .top
 324 update
 325 .CE
 326 All the widgets within \fB.top\fR (including \fB.top\fR) are now busy.
 327 Using \fBupdate\fR insures that \fBbusy\fR command will take effect before
 328 any other user events can occur.
 329 .PP
 330 When the application is no longer busy processing, you can allow user
 331 interactions again by the \fBrelease\fR operation.
 332 .nf
 333
 334 \fB     busy release .top \fR
 335
 336 .fi
 337 The busy window has a configurable cursor.  You can change the busy
 338 cursor using the \fBconfigure\fR operation.
 339 .nf
 340
 341 \fB     busy configure .top -cursor "watch"\fR
 342
 343 .fi
 344 Finally, when you no longer need to the busy window,
 345 invoke the \fBforget\fR operation to free any resources it allocated.
 346 .nf
 347
 348 \fB     busy forget .top \fR
 349
 350 .fi
 351 Destroying the widget will also clean up any resources allocated by
 352 the busy command.
 353 .PP
 354 .SH OPERATIONS
 355 The following operations are available for the \fBbusy\fR command:
 356 .TP
 357 \fBbusy hold \fIwindow\fR ?\fIoption value\fR?...
 358 Makes the widget \fIwindow\fR (and its descendants in the Tk window
 359 hierarchy) busy.  \fIWindow\fR must be a valid path name of a Tk
 360 widget.  The busy window is mapped the next time idle tasks are
 361 processed, and the widget and its descendants will be blocked from
 362 user interactions. All events in the widget window and its
 363 descendants are ignored.  Normally \fBupdate\fR should be called
 364 immediately afterward to insure that the \fBhold\fR operation is in
 365 effect \fIbefore\fR the application starts its processing. The
 366 following configuration options are valid:
 367 .RS
 368 .TP
 369 \fB\-cursor \fIcursorName\fR
 370 Specifies the cursor to be displayed when the widget is made busy.
 371 \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR.
 372 The default cursor is \fBwatch\fR.
 373 .RE
 374 .TP
 375 \fBbusy configure \fIwindow\fR ?\fIoption value\fR?...
 376 Queries or modifies the \fBbusy\fR command configuration options for
 377 \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously
 378 made busy by the \fBhold\fR operation.  If no options are
 379 specified, a list describing all of the available options for
 380 \fIwindow\fR (see \fBTk_ConfigureInfo\fR for information on the format
 381 of this list) is returned.  If \fIoption\fR is specified with no
 382 \fIvalue\fR, then the command returns a list describing the one named
 383 option (this list will be identical to the corresponding sublist of
 384 the value returned if no \fIoption\fR is specified).  If one or more
 385 \fIoption\-value\fR pairs are specified, then the command modifies the
 386 given widget option(s) to have the given value(s); in this case the
 387 command returns the empty string.  \fIOption\fR may have any of the
 388 values accepted by the \fBhold\fR operation.
 389 .sp
 390 Please note that the
 391 option database is referenced through \fIwindow\fR.  For example, if
 392 the widget \fB.frame\fR is to be made busy, the busy
 393 cursor can be specified for it by either \fBoption\fR command:
 394 .nf
 395
 396         \fBoption add *frame.busyCursor gumby\fR
 397         \fBoption add *Frame.BusyCursor gumby\fR
 398
 399 .fi
 400 .TP
 401 \fBbusy forget \fIwindow\fR ?\fIwindow\fR?...
 402 Releases resources allocated by the busy command for \fIwindow\fR,
 403 including the busy window.  User events will again be received again
 404 by \fIwindow\fR.  Resources are also released when \fIwindow\fR
 405 is destroyed. \fIWindow\fR must be the name of a widget specified
 406 in the \fBhold\fR operation, otherwise an error is reported.
 407 .TP
 408 \fBbusy isbusy \fR?\fIpattern\fR?
 409 Returns the pathnames of all widgets that are currently busy.
 410 If a \fIpattern\fR is given, the path names of busy widgets
 411 matching \fIpattern\fR are returned.
 412 .TP
 413 \fBbusy names \fR?\fIpattern\fR?
 414 Returns the pathnames of all widgets that have previously been
 415 made busy (i.e. a busy window is allocated and associated with the
 416 widget).  It makes no difference if the window is currently busy or
 417 not.  If a \fIpattern\fR is given, the path names of busy widgets
 418 matching \fIpattern\fR are returned.
 419 .TP
 420 \fBbusy release \fIwindow\fR ?\fIwindow\fR?...
 421 Restores user interactions to the widget \fIwindow\fR again.
 422 This differs from the \fBforget\fR operation in that the busy window
 423 is not destroyed, but simply unmapped.
 424 \fIWindow\fR must be the name of a widget specified
 425 in a \fBhold\fR operation, otherwise an error is reported.
 426 .TP
 427 \fBbusy status \fIwindow\fR
 428 Returns the status of a widget \fIwindow\fR previously made busy.
 429 An error is reported if \fIwindow\fR was never made busy, or
 430 the \fBforget\fR operation was invoked (i.e. does not currently have a
 431 busy window associated with it).  If \fIwindow\fR is presently can
 432 not receive user interactions, \fB1\fR is returned, otherwise \fB0\fR.
 433 .sp 1
 434 .SH BINDINGS
 435 The event blocking feature is implemented by creating and mapping a
 436 transparent window that completely covers the widget.  When the busy
 437 window is mapped, it invisibly shields the widget and its hierarchy
 438 from all events that may be sent.  Like Tk widgets, busy windows have
 439 widget names in the Tk window hierarchy.  This means that you can use
 440 the \fBbind\fR command, to handle events in the busy window.
 441 .CS
 442 busy hold .frame.canvas
 443 bind .frame.canvas_Busy <Enter> { ... }
 444 .CE
 445 .PP
 446 Normally the busy window is a sibling of the widget.  The
 447 name of the busy window is "\fIwidget\fB_Busy\fR" where \fIwidget\fR
 448 is the name of the widget to be made busy.  In the previous example, the
 449 pathname of the busy window is "\fB.frame.canvas_Busy\fR" The
 450 exception is when the widget is a toplevel widget (such as ".")  where
 451 the busy window can't be made a sibling.  The busy window is then a
 452 child of the widget named "\fIwidget\fB._Busy\fR" where \fIwidget\fR
 453 is the name of the toplevel widget.  In the following example, the
 454 pathname of the busy window is "\fB._Busy\fR"
 455 .CS
 456 busy hold .
 457 bind ._Busy <Enter> { ... }
 458 .CE
 459 .SH ENTER/LEAVE EVENTS
 460 Mapping and unmapping busy windows generates Enter/Leave events for
 461 all widgets they cover.  Please note this if you are tracking
 462 Enter/Leave events in widgets.
 463 .SH KEYBOARD EVENTS
 464 When a widget is made busy, the widget is prevented from gaining the
 465 keyboard focus by the busy window. But if the widget already had
 466 focus, it still may received keyboard events.  To prevent this, you
 467 must move focus to another window.
 468 .CS
 469 busy hold .frame
 470 label .dummy
 471 focus .dummy
 472 update
 473 .CE
 474 The above example moves the focus from .frame immediately after
 475 invoking the \fBhold\fR so that no keyboard events will be sent to
 476 \fB.frame\fR or any of its descendants.
 477 .SH KEYWORDS
 478 busy, keyboard events, pointer events, window, cursor
 479
 480