![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch12e.t CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib|
Return to ch12e.t CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib |
1.1 root 1: .NH 2
2: When An Event?
3: .PP
4: The following discussion is meant to explain precisely when
5: events are generated and precisely what information is contained in
6: an event.
7: The structures below are all contained in \fI<X/Xlib.h>\fP;
8: the declarations below are for illustration only,
9: to explain the information in the structures.
10: .IN "File" "<X/Xlib.h>"
11: The \fIXlib.h\fP file is the final authority.
12: .PP
13: Events are often said to be generated on a window.
14: What this really means is that the window system
15: figures out which client to send the event to
16: by looking for the smallest enclosing window for which
17: a client program has selected input for that event type.
18: If no program has selected input for that event type somewhere
19: in the heirarchy, it will eventually be thrown away.
20: Some client programs need to override this behavior, and
21: may `grab' a button for some period of time under some circumstances.
22: .PP
23: .IN "Automatic Grabbing"
24: .IN "Grabbing" "Temporarily Button"
25: If both \fIButtonPressed\fP
26: and \fIButtonReleased\fP are selected by a client on a window,
27: then a \fIButtonPressed\fP event in that window will automatically `grab' the
28: mouse until all buttons are released.
29: .PP
30: If the mouse has been grabbed, either from a button press as above, or
31: .IN "XGrabMouse"
32: .IN "XGrabButton"
33: .IN "Grabbing" "Mouse"
34: .IN "Grabbing" "Button"
35: by a call to \fIXGrabMouse\fP or \fIXGrabButton\fP,
36: then \fIButtonPressed\fP, \fIButtonReleased\fP,
37: \fIMouseMoved\fP, \fIEnterWindow\fP,
38: and \fILeaveWindow\fP events will only go to windows
39: fo
40: .IN "XSelectInput"
41: which the grabbing client has called \fIXSelectInput\fP.
42: If the client
43: has not called \fIXSelectInput\fP on the window where the event would
44: normally be sent, then the window where the original \fIButtonPressed\fP
45: occurred will receive the event,
46: provided the event has been selected in that window
47: and the event is not \fIEnterWindow\fP or \fILeaveWindow\fP.
48: .PP
49: When an event is received,
50: programs first have to determine what kind of event was generated.
51: A generic event structure,
52: \fIXEvent\fP has been defined in the library which contains
53: information in common to all events.
54: A user will normally switch on the event type to handle different
55: events.
56: .nf
57: .DS
58: .TA .5i 2.5i
59: .ta .5i 2.5i
60: /* Definition of a generic event. It must be cast to a specific event
61: * type before one can read event-specific data */
62:
63: typedef struct _XEvent {
64: unsigned long type; /* of event (KeyPressed, ExposeWindow, etc.) */
65: Window window; /* which selected this event */
66: long pad_l1, pad_l2; /* event-specific data */
67: Window subwindow; /* child window (if any) event actually happened in */
68: long pad_l4; /* event-specific data */
69: } XEvent;
70: .DE
71: .fi
72: Only the type, window, and subwindow information is shared in common
73: among different event types.
74: .IN "Data Structures" "XEvent"
75: .PP
76: \fIKeyPressed\fP, \fIKeyReleased\fP, \fIButtonPressed\fP,
77: \fIButtonReleased\fP, \fIEnterWindow\fP,
78: \fILeaveWindow\fP, and \fIMouseMoved\fP events contain the same information
79: and have the following structure:
80: .nf
81: .DS
82: .TA .5i 2.5i
83: .ta .5i 2.5i
84: struct _XKeyOrButtonEvent {
85: unsigned long type; /* of event (KeyPressed, ButtonReleased, etc.) */
86: Window window; /* which selected this event */
87: unsigned short time; /* in 10 millisecond ticks */
88: short detail; /* event-dependent data (key state, etc.) */
89: short x; /* mouse x coordinate within event window */
90: short y; /* mouse y coordinate within event window */
91: Window subwindow; /* child window (if any) mouse was in */
92: Locator location; /* absolute coordinates of mouse */
93: };
94: .IN "Data Structures" "XKeyEvent"
95: .IN "Data Structures" "XKeyOrButtonEvent"
96: .IN "Data Structures" "XKeyPressedEvent"
97: .IN "Data Structures" "XKeyReleasedEvent"
98: .IN "Data Structures" "XButtonPressedEvent"
99: .IN "Data Structures" "XButtonReleasedEvent"
100: .IN "Data Structures" "XButtonButtonEvent"
101: typedef struct _XKeyOrButtonEvent XKeyEvent;
102: typedef struct _XKeyOrButtonEvent XKeyOrButtonEvent;
103: typedef struct _XKeyOrButtonEvent XKeyPressedEvent;
104: typedef struct _XKeyOrButtonEvent XKeyReleasedEvent;
105:
106: typedef struct _XKeyOrButtonEvent XButtonEvent;
107: typedef struct _XKeyOrButtonEvent XButtonPressedEvent;
108: typedef struct _XKeyOrButtonEvent XButtonReleasedEvent;
109: .DE
110: .DS
111: .TA .5i 2.5i
112: .ta .5i 2.5i
113: struct _XMouseOrCrossingEvent {
114: unsigned long type; /* EnterWindow, LeaveWindow, or MouseMoved */
115: Window window; /* which selected this event */
116: short pad_s2;
117: short detail; /* event-dependent data (key state, etc. ) */
118: short x; /* mouse x coordinate within event window */
119: short y; /* mouse y coordinate within event window */
120: Window subwindow; /* child window (if any) mouse was in */
121: Locator location; /* absolute coordinates of mouse */
122: };
123: .IN "Data Structures" "XMouseOrCrossingEvent"
124: .IN "Data Structures" "XEnterWindowEvent"
125: .IN "Data Structures" "XLeaveWindowEvent"
126: .IN "Data Structures" "XMouseMovedEvent"
127:
128: typedef struct _XMouseOrCrossingEvent XMouseOrCrossingEvent;
129: typedef struct _XMouseOrCrossingEvent XEnterWindowEvent;
130: typedef struct _XMouseOrCrossingEvent XLeaveWindowEvent;
131: typedef struct _XMouseOrCrossingEvent XMouseMovedEvent;
132: .fi
133: .DE
134: .PP
135: The coordinates of the mouse relative to the event window are reported, even
136: if the mouse is not in the window (because of mouse grabbing or keyboard
137: focusing).
138: If the mouse is also in a decendent of the event window, the sub window
139: is set to that decendent, otherwise the sub window is 0. The locator defines
140: the mouse coordinates in absolute terms, and can be used as an argument
141: .IN "XInterpretLocator"
142: to \fIXInterpretLocator\fP to interpret
143: the coordinates with respect to new window
144: configurations.
145: The representation of the Locator is <x,,y> in absolute screen
146: coordinates.
147: .PP
148: The time value is present only for \fIKeyPressed\fP, \fIKeyReleased\fP,
149: \fIButtonPressed\fP, and \fIButtonReleased\fP events.
150: Note that there are only 16 bits of time, which
151: wraps after approximately 11 minutes, so only time differences between
152: clustered events is interesting.
153: .PP
154: .IN "Event" "Detail"
155: For all events containing details,
156: the high bits of the detail encode the state of
157: various keys and buttons just before the event:
158: .IN "Key Mask"
159: .IN "Button Mask"
160: .KS
161: .TS
162: center;
163: lcl.
164: ControlMask 0x4000 Control key
165: MetaMask 0x2000 Meta (Symbol) key
166: ShiftMask 0x1000 Shift key
167: ShiftLockMask 0x0800 ShiftLock key
168: LeftMask 0x0400 Left button
169: MiddleMask 0x0200 Middle button
170: RightMask 0x0100 Right button
171: .TE
172: .KE
173: For \fIKeyPressed\fP and \fIKeyReleased\fP,
174: the low byte of the detail gives the keycode.
175: This is not an ASCII character.
176: .IN "File" "<X/Xkeyboard.h>"
177: .IN "Keyboard" "Classification"
178: .IN "Macros" "Keyboard"
179: There are useful macros defined in the file \fI<X/Xkeyboard.h>\fP
180: to classify keycodes.
181: The tests \fIIsShiftKey()\fP, \fIIsCursorKey()\fP, \fIIsKeypadKey()\fP,
182: \fIIsFunctionKey()\fP, \fIIsPFKey()\fP and \fIIsTypeWriterKey()\fP may be used
183: with a key code to classify the key as to grouping.
184: See the warning at the beginning of the section.
185: .IN "XLookupMapping"
186: Normally, however, a client will use the supplied \fIXLookupMapping\fP
187: subroutine to determine what string (if any) is associated with the key.
188: .LP
189: For \fIButtonPressed\fP and \fIButtonReleased\fP events
190: the low byte of the detail
191: is one of:
192: .IP
193: RightButton 0
194: .br
195: MiddleButton 1
196: .br
197: LeftButton 2
198: .LP
199: For \fIEnterWindow\fP and \fILeaveWindow\fP events,
200: the low byte of the detail is either zero
201: or one of:
202: .IP
203: IntoOrFromSubwindow 1
204: .br
205: VirtualCrossing 2
206: .LP
207: \fIEnterWindow\fP and \fILeaveWindow\fP events are generated as follows:
208: .nf
209: When the mouse moves from window A to window B, and B is an ancestor of A:
210: A will get a \fILeaveWindow\fP with detail 0
211: windows between A and B exclusive that have \fILeaveWindow\fP selected
212: will get a \fILeaveWindow\fP with detail 2
213: B will get an \fIEnterWindow\fP with detail 1
214:
215: When the mouse moves from window A to window B, and B is a descendant of A:
216: A will get a \fILeaveWindow\fP with detail 1
217: windows between A and B exclusive that have \fIEnterWindow\fP selected
218: will get an \fIEnterWindow\fP with detail 2
219: B will get an \fIEnterWindow\fP with detail 0
220:
221: When the mouse moves from window A to window B, with window C being their
222: least common ancestor:
223: A will get a \fILeaveWindow\fP with detail 0
224: windows between A and C exclusive that have \fILeaveWindow\fP selected
225: will get a \fILeaveWindow\fP with detail 2
226: windows between C and B exclusive that have \fIEnterWindow\fP selected
227: will get an \fIEnterWindow\fP with detail 2
228: B will get an \fIEnterWindow\fP with detail 0
229:
230: At the start of a mouse grab, either automatically from a button press,
231: or from an \fIXGrabMouse\fP or \fIXGrabButton\fP, with the mouse in window A:
232: A will get a \fILeaveWindow\fP with detail 0 if the grabbing client has
233: not issued an \fIXSelectInput\fP command on A.
234: ancestors of A (not including the root) will get a \fILeaveWindow\fP with
235: detail 2 if the grabbing client has not issued an \fIXSelectInput\fP
236: on the window and the window has \fILeaveWindow\fP selected.
237:
238: At the end of a mouse grab, with the mouse in window A:
239: ancestors of A (not including the root) will get an \fIEnterWindow\fP with
240: detail 2 if the grabbing client has not issued an \fIXSelectInput\fP
241: on the window and the window has \fIEnterWindow\fP selected.
242: A will get an \fIEnterWindow\fP with detail 0 if the grabbing client has
243: not issued an \fIXSelectInput\fP command on A.
244: .fi
245: .LP
246: Another way to look at this is:
247: .nf
248: a detail of 0 means that the mouse entered this window from, or left
249: this window towards, some place outside the window's hierarchy.
250: a detail of 1 means that the mouse entered this window from, or left
251: this window towards, one of its descendents.
252: a detail of 2 means that the mouse moved from a descendent of the
253: window to a place outside the window's hierarchy, or vice versa.
254: .fi
255: \fIEnterWindow\fP and \fILeaveWindow\fP events with detail 0 or 1 will propagate
256: to the smallest enclosing window that has actually selected the event.
257: .PP
258: There are a set of structure definitions
259: outlining the information and type of each event in \fI<X/Xlib.h>\fP.
260: Coordinates are relative to the inside of the window.
261: .PP
262: .IN "ExposeWindow Event"
263: .IN "ExposeRegion Event"
264: \fIExposeWindow\fP and \fIExposeRegion\fP
265: events are triggered as (parts of) windows become
266: exposed.
267: When an entire window becomes exposed (as when a window is mapped or
268: changes size), an \fIExposeWindow\fP event is sent.
269: The width and height of the
270: entire window is given, and the coordinates are (0, 0).
271: When only parts of a
272: window become exposed (as when an obscuring window is moved),
273: \fIExposeRegion\fP
274: events are sent describing each newly exposed area. However, if only
275: \fIExposeWindow\fP has been selected,
276: a single \fIExposeWindow\fP event will be sent instead.
277: .IN "XCopyArea"
278: .IN "XMoveArea"
279: If the region exposure is the result of an \fIXCopyArea\fP
280: or \fIXMoveArea\fP, then \fIExposeCopy\fP will
281: be set in the detail word.
282: If the exposure is actually that of a child of the
283: window selecting the event, the sub window is set to that child and the
284: coordinates are actually for the sub window, otherwise the sub window is 0.
285: For a given window exposure or \fIXCopyArea\fP
286: or \fIXMoveArea\fP,
287: all resulting \fIExposeRegion\fP events
288: will be sent contiguously, with no other events interspersed.
289: .PP
290: \fIXExposeCopyEvent\fP
291: are only sent to terminate a string of \fIExposeRegion\fP
292: events
293: that might be
294: .IN "XCopyArea"
295: .IN "XMoveArea"
296: generated by \fIXCopyArea\fP or \fIXMoveArea\fP commands.
297: Note that there is no information in the event as to what area was
298: exposed, as this is just an acknowledgement that all side effects have
299: been generated.
300: .PP
301: The structures for exposure events are given below:
302: .sp
303: .DS
304: .TA .5i 2.5i
305: .ta .5i 2.5i
306: struct _XExposeEvent {
307: unsigned long type; /* ExposeWindow or ExposeRegion */
308: Window window; /* that selected this event */
309: short pad_s2;
310: short detail; /* 0 or ExposeCopy */
311: short width; /* width of exposed area */
312: short height; /* height of exposed area */
313: Window subwindow; /* child window (if any) actually exposed */
314: short y; /* top of exposed area (0 for ExposeWindow) */
315: short x; /* left edge of exposed area (0 for ExposeWindow) */
316: };
317: .IN "Data Structures" "XExposeEvent"
318: .IN "Data Structures" "XExposeWindowEvent"
319: .IN "Data Structures" "XExposeCopyEvent"
320: typedef struct _XExposeEvent XExposeEvent;
321: typedef struct _XExposeEvent XExposeWindowEvent;
322: typedef struct _XExposeEvent XExposeRegionEvent;
323: .DE
324: .DS
325: .TA .5i 2.5i
326: .ta .5i 2.5i
327: typedef struct _XExposeCopyEvent {
328: unsigned long type; /* ExposeCopy */
329: Window window; /* that selected this event */
330: long pad_l1;
331: long pad_l2;
332: Window subwindow; /* child window (if any) actually exposed */
333: long pad_l4;
334: } XExposeCopyEvent;
335: .DE
336: .fi
337: .sp
338: .PP
339: .IN "XCopyArea"
340: If the XCopyArea was done in a child of the window selecting the event,
341: the subwindow is set to that child, otherwise the subwindow is 0.
342: .PP
343: The X server always clears to the
344: background color an exposed area before sending an exposure
345: event to the client.
346: Unfortunately, the client may have sent output to
347: a window between the time it is cleared and the time he reads the
348: exposure event off Xlib's queue. This can lead to difficulty in two
349: cases:
350: .LP
351: \(bu the exposure event was an \fIExposeWindow\fP with new window dimensions.
352: The client probably wants output to go to a different place after a size
353: change than before.
354: .LP
355: \(bu the client is using a display function which is not invertable; that
356: is, applying the function more than once does not have the same effect
357: as applying it just once.
358: .IN "Display Functions"
359: Seven of the 16 display functions are not
360: invertable: \fIGXandReverse\fP, \fIGXxor\fP, \fIGXnor\fP, \fIGXequiv\fP,
361: \fIGXinvert\fP, \fIGXorReverse\fP,
362: and \fIGXnand\fP.
363: The most obvious example of an invertable function is \fIGXinvert\fP,
364: which is a no-op if applied twice.
365: .PP
366: In both of these cases, the client should explicitly clear the exposed
367: area (i.e. paint it with the background) upon receipt of an exposure
368: event, BEFORE doing any repainting.
369: Failure to do so will cause ugly
370: glitches on the screen.
371: .PP
372: Unmap events have the following structure:
373: .DS
374: .TA .5i 2.5i
375: .ta .5i 2.5i
376: typedef struct _XUnmapEvent {
377: unsigned long type; /* UnmapWindow */
378: Window window; /* that selected this event */
379: long pad_l1;
380: long pad_l2;
381: Window subwindow; /* child window (if any) actually unmapped */
382: long pad_l4;
383: } XUnmapEvent;
384: .DE
385: .fi
386: .sp
387: .LP
388: These events will be sent to clients that ask to be informed when
389: they are unmapped from the screen.
390: For example, both the clock and the load monitor program
391: will stop updating themselves when turned into
392: an icon (i.e. their main window is unmapped by a window manager).
393: .PP
394: To allow certain styles of user interfaces to be built,
395: it is also possible to request to be informed if the
396: input focus is set or removed from a window.
397: The event has the following structure:
398: .IN "Data Structures" "XFocusChangeEvent"
399: .IN "Event Types" "FocusChange"
400: .IN "FocusChange Event"
401: .sp
402: .DS
403: .TA .5i 2.5i
404: .ta .5i 2.5i
405: typedef struct _XFocusChangeEvent {
406: unsigned long type; /* FocusChange */
407: Window window; /* that selected this event */
408: short pad_s2;
409: short detail; /* EnterWindow or LeaveWindow */
410: long pad_l2;
411: Window subwindow; /* child window (if any) of actual focus change*/
412: long pad_l4;
413: } XFocusChangeEvent;
414: .DE
415: .sp
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.