home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / busy.man < prev    next >
Encoding:
Text File  |  1995-07-01  |  7.4 KB  |  168 lines
  1. '\"
  2. '\" Copyright 1993-1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\" Busy command created by George Howlett.
  22. '\"
  23. .so man.macros
  24. .HS blt_busy cmds
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. blt_busy \- Block pointer and keyboard events from a window sub-tree
  29. .SH SYNOPSIS
  30. \fBblt_busy hold \fIwindow options\fR ?\fIwindow options \fR...?
  31. .sp
  32. \fBblt_busy release \fIwindow\fR ?\fIwindow ...\fR?
  33. .sp
  34. \fBblt_busy configure \fIwindow\fR ?\fIoptions...\fR?
  35. .sp
  36. \fBblt_busy forget \fIwindow\fR ?\fIwindow ...\fR?
  37. .sp
  38. \fBblt_busy hosts \fIpattern\fR
  39. .sp
  40. \fBblt_busy status \fIwindow\fR 
  41. .BE
  42. .SH DESCRIPTION
  43. .PP
  44. This command implements a mechanism to prevent keyboard, button, 
  45. and pointer events from reaching a window and its descendants.
  46. Events occurring in this window and its descendants in Tk's window 
  47. hierarchy  are effectively ignored.
  48. .PP
  49. This is particularly useful for temporarily deactivating an hierarchy 
  50. of widgets (e.g. buttons and entries) while other processing is occurring.
  51. .PP
  52. Once a window is made busy using the \fBblt_busy hold\fR command, the window and 
  53. its descendants are blocked from receiving events.  Please note that only the 
  54. descendants which exist at the time the \fBhold\fR command was invoked
  55. are affected.  If a new child window is created following the command, 
  56. its events are \fInot\fR blocked.  
  57. .PP
  58. The blocking feature is implemented by creating and mapping an 
  59. \f(CWInputOnly\fR class sub-window, obscuring some or all of the parent 
  60. window.  When the sub-window is mapped, it shields its parent and 
  61. sibling windows from events (it is always mapped to be the 
  62. uppermost sibling).  The size and position of the busy window are determined
  63. by a host window.  Typically the host and parent windows are the same.  
  64. But in cases where a window is not packed into its parent, the \fB-in\fR option
  65. may be used to specify a different parent.
  66. .PP
  67. The \fBblt_busy\fR command can take any of the following forms:
  68. .TP
  69. \fBblt_busy hold \fIwindow\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
  70. Creates and activates a busy window associated with \fIwindow\fR.
  71. \fIWindow\fR must be a valid path name of a Tk window.  It represents
  72. the host window which determines the position and size of the busy window.
  73. All device events for the host window and it descendants 
  74. will be effectively blocked.
  75. Typically \fBupdate\fR should be called immediately afterward to insure 
  76. that the busy cursor is updated \fIbefore\fR the application starts its work.
  77. This command returns the empty string.  The following configuration 
  78. options are valid:
  79. .RS
  80. .TP
  81. \fB\-cursor \fIcursorName\fR
  82. Specifies the cursor to be displayed when the busy window is activated.
  83. \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR.
  84. The default cursor is \fBwatch\fR.
  85. .TP
  86. \fB\-in \fIparent\fR
  87. Specifies the parent window of the busy window. This is needed when
  88. the parent and host windows are not the same.  \fIParent\fR 
  89. specifies the path name of a mutual ancestor of both the host window and 
  90. the window hierarchy. 
  91. .RE
  92. .TP
  93. \fBblt_busy configure \fIwindow\fR ?\fIoption\fR? ?\fIvalue option value
  94. ...\fR?  
  95. Queries or modifies the configuration options of the busy
  96. window.  \fIWindow\fR must be the path name of a host window 
  97. (associated by the \fBhold\fR command).  If no
  98. \fIoption\fR is specified, a list describing all of the available
  99. options for \fIwindow\fR (see \fBTk_ConfigureInfo\fR for information
  100. on the format of this list) is returned.  If \fIoption\fR is specified
  101. with no \fIvalue\fR, then the command returns a list describing the
  102. one named option (this list will be identical to the corresponding
  103. sublist of the value returned if no \fIoption\fR is specified).  If
  104. one or more \fIoption\-value\fR pairs are specified, then the command
  105. modifies the given widget option(s) to have the given value(s); in
  106. this case the command returns the empty string.  \fIOption\fR may have
  107. any of the values accepted by the \fBhold\fR command.
  108. Please note that the option database is referenced through \fIwindow\fR.
  109. For example, if a busy window exists for the window \f(CW.myframe\fR,
  110. the busy window cursor can be specified for it by either \fBoption\fR 
  111. command:
  112. .DS
  113.     \fBoption add \f(CW*myframe.busyCursor gumby\fR
  114.     \fBoption add \f(CW*Frame.BusyCursor gumby\fR
  115. .DE
  116. .TP
  117. \fBblt_busy release \fIwindow\fR ?\fIwindow ...\fR?
  118. Permits events to be received by \fIwindow\fR again. This differs from
  119. the \fBforget\fR command in that the busy window is retained, but is not 
  120. active.  An error is reported if \fIwindow\fR is not a host window. 
  121. This command returns the empty string.
  122. .TP
  123. \fBblt_busy forget \fIwindow\fR ?\fIwindow ...\fR?
  124. Permits events to be received again by \fIwindow\fR by destroying the
  125. busy window.  An error is reported \fIwindow\fR is not a host window.
  126. This command returns the empty string.
  127. .TP
  128. \fBblt_busy hosts \fI?pattern?\fR
  129. Returns the pathnames of all host windows which have a busy window 
  130. associated with them.  If a \fIpattern\fR argument is present, the
  131. pathnames of hosts matching \fIpattern\fR are returned.
  132. .TP
  133. \fBblt_busy status \fIwindow\fR
  134. Returns the status of the busy window associated with \fIwindow\fR.
  135. An error is reported if \fIwindow\fR is not a host window.  
  136. If \fIwindow\fR is currently prevented from receiving
  137. events, \fB1\fR is returned, otherwise \fB0\fR.
  138. .sp 1
  139. .SH KEYBOARD EVENTS
  140. Since Tk allows for keyboard events to be redirected through windows not 
  141. in the parent window's hierarchy, care must be taken to turn off
  142. focus while processing is occurring.
  143. .DS
  144.     \fBblt_busy hold \f(CW.frame\fR
  145.     \fBfocus none\fR
  146. .DE
  147. The above example clears the focus immediately after invoking the 
  148. \fBhold\fR command so that no keyboard events will be relayed to
  149. windows under the hierarchy of \f(CW.frame\fR.
  150. .SH BUGS
  151. .PP
  152. Creating a busy window will generate Enter/Leave events for 
  153. windows that it covers.  Please note this when tracking Enter/Leave
  154. events for windows.
  155. .PP
  156. There's no way to exempt particular windows in an hierarchy so that they
  157. may still receive events.  The busy window is always mapped above its 
  158. siblings. The work around is to create busy windows for
  159. each child in the hierarchy (except for the windows where events
  160. are desired) instead of the parent window.
  161. .PP
  162. When busy windows are created, they are automatically mapped; thus
  163. blocking events from the parent and its descendants.  There is no
  164. two-step process which allows one to create a busy window, and
  165. later when convenient, to activate it so that it blocks events.
  166. .SH KEYWORDS
  167. busy, keyboard events, pointer events, window, cursor
  168.