Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | focus - Manage the input focus | |
11 | ||
12 | =for category User Interaction | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | S< >I<$widget>-E<gt>B<focus> | |
17 | ||
18 | S< >I<$widget>-E<gt>B<focus>I<Option> | |
19 | ||
20 | S< >I<$widget>-E<gt>B<focusNext> | |
21 | ||
22 | S< >I<$widget>-E<gt>B<focusPrev> | |
23 | ||
24 | S< >I<$widget>-E<gt>B<focusFollowsMouse> | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | The B<focus> methods are used to manage the Tk input focus. | |
29 | At any given time, one window on each display is designated as | |
30 | the I<focus window>; any key press or key release events for the | |
31 | display are sent to that window. | |
32 | It is normally up to the window manager to redirect the focus among the | |
33 | top-level windows of a display. For example, some window managers | |
34 | automatically set the input focus to a top-level window whenever | |
35 | the mouse enters it; others redirect the input focus only when | |
36 | the user clicks on a window. | |
37 | Usually the window manager will set the focus | |
38 | only to top-level windows, leaving it up to the application to | |
39 | redirect the focus among the children of the top-level. | |
40 | ||
41 | Tk remembers one focus window for each top-level (the most recent | |
42 | descendant of that top-level to receive the focus); when the window | |
43 | manager gives the focus | |
44 | to a top-level, Tk automatically redirects it to the remembered | |
45 | window. Within a top-level Tk uses an I<explicit> focus model | |
46 | by default. Moving the mouse within a top-level does not normally | |
47 | change the focus; the focus changes only when a widget | |
48 | decides explicitly to claim the focus (e.g., because of a button | |
49 | click), or when the user types a key such as Tab that moves the | |
50 | focus. | |
51 | ||
52 | The method B<focusFollowsMouse> may be invoked to | |
53 | create an I<implicit> focus model: it reconfigures Tk so that | |
54 | the focus is set to a window whenever the mouse enters it. | |
55 | The methods B<focusNext> and B<focusPrev> | |
56 | implement a focus order among the windows of a top-level; they | |
57 | are used in the default bindings for Tab and Shift-Tab, among other | |
58 | things. | |
59 | ||
60 | The B<focus> methods can take any of the following forms: | |
61 | ||
62 | =over 4 | |
63 | ||
64 | =item I<$widget>-E<gt>B<focusCurrent> | |
65 | ||
66 | Returns the focus window on the display containing | |
67 | the I<$widget>, or an empty string if no window in | |
68 | this application has the focus on that display. | |
69 | ||
70 | =item I<$widget>-E<gt>B<focus> | |
71 | ||
72 | If the application currently has the input focus on I<$widget>'s | |
73 | display, this command resets the input focus for I<$widget>'s display | |
74 | to I<$widget> and returns an empty string. | |
75 | If the application doesn't currently have the input focus on | |
76 | I<$widget>'s display, I<$widget> will be remembered as the focus | |
77 | for its top-level; the next time the focus arrives at the top-level, | |
78 | Tk will redirect it to I<$widget>. | |
79 | ||
80 | =item I<$widget>-E<gt>B<focusForce> | |
81 | ||
82 | Sets the focus of I<$widget>'s display to I<$widget>, even if | |
83 | the application doesn't currently have the input focus for the display. | |
84 | This command should be used sparingly, if at all. | |
85 | In normal usage, an application should not claim the focus for | |
86 | itself; instead, it should wait for the window manager to give it | |
87 | the focus. | |
88 | ||
89 | =item I<$widget>-E<gt>B<focusLast> | |
90 | ||
91 | Returns the name of the most recent window to have the input focus | |
92 | among all the windows in the same top-level as I<$widget>. | |
93 | If no window in that top-level has ever had the input focus, or | |
94 | if the most recent focus window has been deleted, then | |
95 | the top-level is returned. The return value is the window that | |
96 | will receive the input focus the next time the window manager gives | |
97 | the focus to the top-level. | |
98 | ||
99 | =item I<$widget>-E<gt>B<focusNext> | |
100 | ||
101 | =item I<$widget>-E<gt>B<focusPrev> | |
102 | ||
103 | B<focusNext> is a utility method used for keyboard traversal, but can be | |
104 | useful in other contexts. | |
105 | It sets the focus to the ``next'' window after I<$widget> in focus order. | |
106 | The focus order is determined by | |
107 | the stacking order of windows and the structure of the window hierarchy. | |
108 | Among siblings, the focus order is the same as the stacking order, with the | |
109 | lowest window being first. | |
110 | If a window has children, the window is visited first, followed by | |
111 | its children (recursively), followed by its next sibling. | |
112 | Top-level windows other than I<$widget> are skipped, so that | |
113 | B<focusNext> never returns a window in a different top-level | |
114 | from I<$widget>. | |
115 | ||
116 | After computing the next window, B<focusNext> examines the | |
117 | window's B<-takefocus> option to see whether it should be skipped. | |
118 | If so, B<focusNext> continues on to the next window in the focus | |
119 | order, until it eventually finds a window that will accept the focus | |
120 | or returns back to I<$widget>. | |
121 | ||
122 | B<focusPrev> is similar to B<focusNext> except that it | |
123 | sets the focus to the window just before I<$widget> in the focus order. | |
124 | ||
125 | =item I<$widget>-E<gt>B<focusFollowsMouse> | |
126 | ||
127 | B<focusFollowsMouse> changes the focus model for the application | |
128 | to an implicit one where the window under the mouse gets the focus. | |
129 | After this procedure is called, whenever the mouse enters a window | |
130 | Tk will automatically give it the input focus. | |
131 | The B<focus> command may be used to move the focus to a window | |
132 | other than the one under the mouse, but as soon as the mouse moves | |
133 | into a new window the focus will jump to that window. | |
134 | Note: at present there is no built-in support for returning the | |
135 | application to an explicit focus model; to do this you'll have | |
136 | to write a script that deletes the bindings created by | |
137 | B<focusFollowsMouse>. | |
138 | ||
139 | =back | |
140 | ||
141 | =head1 QUIRKS | |
142 | ||
143 | When an internal window receives the input focus, Tk doesn't actually | |
144 | set the X focus to that window; as far as X is concerned, the focus | |
145 | will stay on the top-level window containing the window with the focus. | |
146 | However, Tk generates FocusIn and FocusOut events just as if the X | |
147 | focus were on the internal window. This approach gets around a | |
148 | number of problems that would occur if the X focus were actually moved; | |
149 | the fact that the X focus is on the top-level is invisible unless | |
150 | you use C code to query the X server directly. | |
151 | ||
152 | =head1 CAVEATS | |
153 | ||
154 | Note that for the B<Canvas> widget, the call to B<focus> has to be | |
155 | fully qualified. This is because there is already a focus method for | |
156 | the B<Canvas> widget, which sets the focus on individual canvas tags. | |
157 | ||
158 | S< >I<$canvas>-E<gt>B<Tk::focus> | |
159 | ||
160 | ||
161 | =head1 KEYWORDS | |
162 | ||
163 | events, focus, keyboard, top-level, window manager | |
164 | ||
165 | =cut | |
166 |