home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / focus.n < prev    next >
Encoding:
Text File  |  1993-04-01  |  6.0 KB  |  139 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/focus.n,v 1.9 93/04/01 09:52:39 ouster Exp $ SPRITE (Berkeley)
  22. '/" 
  23. .so man.macros
  24. .HS focus tk
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. focus \- Direct keyboard events to a particular window
  29. .SH SYNOPSIS
  30. \fBfocus\fR
  31. .br
  32. \fBfocus \fIwindow\fR
  33. .br
  34. \fBfocus \fIoption\fR ?\fIarg arg ...\fR?
  35. .BE
  36.  
  37. .SH DESCRIPTION
  38. .PP
  39. .VS
  40. The \fBfocus\fR command is used to manage the Tk input focus.
  41. At any given time, one window in an application is designated as
  42. the focus window for that application;  any key press or key release
  43. events directed to any window in the application will be redirected
  44. instead to the focus window.  If there is no focus window for an
  45. application then keyboard events are discarded.
  46. Typically, windows that are prepared to deal with the focus
  47. (e.g. entries and other widgets that display editable text) will
  48. claim the focus when mouse button 1 is pressed in them.
  49. When an application is created its main window is initially given
  50. the focus.
  51. .PP
  52. The \fBfocus\fR command can take any of the following forms:
  53. .TP
  54. \fBfocus\fR
  55. If invoked with no arguments, \fBfocus\fR returns the path name of
  56. the current focus window, or \fBnone\fR if there is no focus window.
  57. .TP
  58. \fBfocus \fIwindow\fR
  59. If invoked with a single argument consisting of a window's path
  60. name, \fBfocus\fR sets the input focus to that window.
  61. The return value is an empty string.
  62. .TP
  63. \fBfocus default \fR?\fIwindow\fR?
  64. If \fIwindow\fR is specified, it becomes the default focus window
  65. (the window that receives the focus whenever the focus window is
  66. deleted) and the command returns an empty string.
  67. If \fIwindow\fR isn't specified, the command returns the path name
  68. of the current default focus window, or \fBnone\fR if there is no
  69. default.
  70. \fIWindow\fR may be specified as \fBnone\fR to clear its existing
  71. value.
  72. The default window is initially \fBnone\fR.
  73. .TP
  74. \fBfocus none\fR
  75. Clears the focus window, so that keyboard input to this application
  76. will be discarded.
  77.  
  78. .SH "FOCUS EVENTS"
  79. .PP
  80. Tk's model of the input focus is different than X's model, and the
  81. focus window set with the \fBfocus\fR command is not usually the
  82. same as the X focus window.
  83. Tk never explicitly changes the official X focus window.
  84. It waits for the window manager to direct the X input focus to
  85. and from the application's top-level windows, and it intercepts
  86. \fBFocusIn\fR and \fBFocusOut\fR events coming from the X
  87. server to detect these changes.
  88. All of the focus events received from X are discarded by Tk;  they
  89. never reach the application.
  90. Instead, Tk generates a different stream of \fBFocusIn\fR and
  91. \fBFocusOut\fR for the application.
  92. This means that \fBFocusIn\fR and
  93. and \fBFocusOut\fR events seen by the application will not obey the
  94. conventions described in the documentation for Xlib.
  95. .PP
  96. Tk applications receive two kinds of \fBFocusIn\fR and \fBFocusOut\fR
  97. events, which can be distinguished by their \fIdetail\fR fields.
  98. Events with a \fIdetail\fR of \fBNotifyAncestor\fR are directed
  99. to the current focus window when it becomes active or inactive.
  100. A window is the active focus whenever two conditions are
  101. simultaneously true: (a) the window is the focus window for its
  102. application, and (b) some top-level window in the application has
  103. received the X focus.
  104. When this happens Tk generates a \fBFocusIn\fR event for the focus
  105. window with detail \fBNotifyAncestor\fR.
  106. When a window loses the active focus (either because the window manager
  107. removed the focus from the application or because the focus window changed
  108. within the application) then it receives a \fBFocusOut\fR event
  109. with detail \fBNotifyAncestor\fR.
  110. .PP
  111. The events described above are directed to the application's focus
  112. window regardless of which top-level window within the application
  113. has received the focus.
  114. The second kind of focus event is provided for applications that
  115. need to know which particular top-level window has the X focus.
  116. Tk generates \fBFocusIn\fR and \fBFocusOut\fR events with detail
  117. \fBNotifyVirtual\fR for top-level windows whenever they receive or
  118. lose the X focus.
  119. These events are generated regardless of which window in the
  120. application has the Tk input focus.
  121. They do not imply that keystrokes will be directed to the window
  122. that receives the event;  they simply indicate which top-level
  123. window is active as far as the window manager is concerned.
  124. If a top-level window is also the application's focus window,
  125. then it will receive both \fBNotifyVirtual\fR and \fBNotifyAncestor\fR
  126. events when it receives or loses the X focus.
  127. .PP
  128. Tk does not generate the hierarchical chains of \fBFocusIn\fR and
  129. \fBFocusOut\fR events described in the Xlib documentation (e.g.
  130. a window can get a \fBFocusIn\fR or \fBFocusOut\fR event without
  131. all of its ancestors getting events too).
  132. Furthermore, the \fImode\fR field in focus events is always
  133. \fBNotifyNormal\fR and the only values ever present in the
  134. \fIdetail\fR field are \fBNotifyAncestor\fR and \fBNotifyVirtual\fR.
  135. .VE
  136.  
  137. .SH KEYWORDS
  138. events, focus, keyboard, top-level, window manager
  139.