Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1992 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 | grab - Confine pointer and keyboard events to a window sub-tree | |
11 | ||
12 | =for category User Interaction | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$widget>-E<gt>B<grab> | |
17 | ||
18 | I<$widget>-E<gt>B<grab>I<Option> | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | This set of methods implement simple pointer and keyboard grabs for Tk. | |
23 | Tk's grabs are different than the grabs | |
24 | described in the Xlib documentation. | |
25 | When a grab is set for a particular window, Tk restricts all pointer | |
26 | events to the grab window and its descendants in Tk's window hierarchy. | |
27 | Whenever the pointer is within the grab window's subtree, the pointer | |
28 | will behave exactly the same as if there had been no grab at all | |
29 | and all events will be reported in the normal fashion. | |
30 | When the pointer is outside I<$widget>'s tree, button presses and | |
31 | releases and | |
32 | mouse motion events are reported to I<$widget>, and window entry | |
33 | and window exit events are ignored. | |
34 | The grab subtree ``owns'' the pointer: | |
35 | windows outside the grab subtree will be visible on the screen | |
36 | but they will be insensitive until the grab is released. | |
37 | The tree of windows underneath the grab window can include top-level | |
38 | windows, in which case all of those top-level windows | |
39 | and their descendants will continue to receive mouse events | |
40 | during the grab. | |
41 | ||
42 | Two forms of grabs are possible: local and global. | |
43 | A local grab affects only the grabbing application: events will | |
44 | be reported to other applications as if the grab had never occurred. | |
45 | Grabs are local by default. | |
46 | A global grab locks out all applications on the screen, | |
47 | so that only the given subtree of the grabbing application will be | |
48 | sensitive to pointer events (mouse button presses, mouse button releases, | |
49 | pointer motions, window entries, and window exits). | |
50 | During global grabs the window manager will not receive pointer | |
51 | events either. | |
52 | ||
53 | During local grabs, keyboard events (key presses and key releases) | |
54 | are delivered as usual: the window | |
55 | manager controls which application receives keyboard events, and | |
56 | if they are sent to any window in the grabbing application then they are | |
57 | redirected to the focus window. | |
58 | During a global grab Tk grabs the keyboard so that all keyboard events | |
59 | are always sent to the grabbing application. | |
60 | The B<focus> method is still used to determine which window in the | |
61 | application receives the keyboard events. | |
62 | The keyboard grab is released when the grab is released. | |
63 | ||
64 | Grabs apply to particular displays. If an application has windows | |
65 | on multiple displays then it can establish a separate grab on each | |
66 | display. | |
67 | The grab on a particular display affects only the windows on | |
68 | that display. | |
69 | It is possible for different applications on a single display to have | |
70 | simultaneous local grabs, but only one application can have a global | |
71 | grab on a given display at once. | |
72 | ||
73 | The B<grab> methods take any of the following forms: | |
74 | ||
75 | =over 4 | |
76 | ||
77 | =item I<$widget>-E<gt>B<grabCurrent> | |
78 | ||
79 | Returns the current grab | |
80 | window in this application for I<$widget>'s display, or an empty | |
81 | string if there is no such window. | |
82 | ||
83 | =item I<$widget>-E<gt>B<grabs> | |
84 | ||
85 | Returns a list whose elements | |
86 | are all of the windows grabbed by this application for all displays, | |
87 | or an empty string if the application has no grabs. | |
88 | ||
89 | I<Not implemented yet!> | |
90 | ||
91 | =item I<$widget>-E<gt>B<grabRelease> | |
92 | ||
93 | Releases the grab on I<$widget> if there is one, otherwise does | |
94 | nothing. Returns an empty string. | |
95 | ||
96 | =item I<$widget>-E<gt>B<grab> | |
97 | ||
98 | Sets a local grab on I<$widget>. | |
99 | If a grab was already in effect for this application on | |
100 | I<$widget>'s display then it is automatically released. | |
101 | If there is already a local grab on I<$widget>, then the command | |
102 | does nothing. Returns an empty string. | |
103 | ||
104 | =item I<$widget>-E<gt>B<grabGlobal> | |
105 | ||
106 | Sets a global grab on I<$widget>. | |
107 | If a grab was already in effect for this application on | |
108 | I<$widget>'s display then it is automatically released. | |
109 | If there is already a global grab on I<$widget>, | |
110 | then the command does nothing. Returns an empty string. | |
111 | ||
112 | =item I<$widget>-E<gt>B<grabStatus> | |
113 | ||
114 | Returns B<none> if no grab is currently set on I<$widget>, | |
115 | B<local> if a local grab is set on I<$widget>, and | |
116 | B<global> if a global grab is set. | |
117 | ||
118 | =back | |
119 | ||
120 | =head1 BUGS | |
121 | ||
122 | It took an incredibly complex and gross implementation to produce | |
123 | the simple grab effect described above. | |
124 | Given the current implementation, it isn't safe for applications | |
125 | to use the Xlib grab facilities at all except through the Tk grab | |
126 | procedures. | |
127 | If applications try to manipulate X's grab mechanisms directly, | |
128 | things will probably break. | |
129 | ||
130 | If a single process is managing several different Tk applications, | |
131 | only one of those applications can have a local grab for a given | |
132 | display at any given time. If the applications are in different | |
133 | processes, this restriction doesn't exist. | |
134 | ||
135 | =head1 KEYWORDS | |
136 | ||
137 | grab, keyboard events, pointer events, window | |
138 | ||
139 | =cut | |
140 |