![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch12a.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 ch12a.t CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib |
1.1 root 1: .NH
2: Input Event Handling
3: .XS
4: Input Event Handling
5: .XE
6: .PP
7: .IN "Input Control"
8: .IN "Output" "Control"
9: Input from the window system is asynchronous, but the window
10: system never gives you information you did not ask for.
11: .IN "Definitions" "Event"
12: This input comes in the form of `events'.
13: There are keyboard, mouse button, window crossing, mouse motion,
14: exposure, unmap and focus change events.
15: .IN "File" "<X/Xlib.h>"
16: There are structures defined for these events in \fI<X/Xlib.h>\fP.
17: These may arrive at any time in the input stream even between the
18: time you send a command and get a reply.
19: Accordingly, the library queues any events received while waiting for
20: a reply for later use.
21: .PP
22: Only the type and window fields are defined for all types of events.
23: .IN "Definitions" "XEvent"
24: There is a generic structure declared called \fIXEvent\fP defined in
25: .IN "File" "<X/Xlib.h>"
26: \fI<X/Xlib.h>\fP.
27: Once the type has been determined, future references to the event structure
28: should be made using the structures declared in the library.
29: .FD
30: .IN "Definitions" "XCompressEvents"
31: .IN "XCompressEvents"
32: .IN "Definitions" "XExpandEvents"
33: .IN "XExpandEvents"
34: XCompressEvents()
35: .sp
36: XExpandEvents()
37: .FN
38: .PP
39: .IN "Event Compression"
40: If the X server sends multiple \fIMouseMoved\fP events without any other
41: intervening events or replies, the X library by default suppresses all but
42: the last such event.
43: .PP
44: If you want to see all events, you can call \fIXExpandEvents\fP
45: and the library
46: will supply all events without compression.
47: .NH 2
48: Event Handling
49: .PP
50: Before the window system will send an event, you must
51: request it.
52: You can request events in particular circumstances,
53: for example,
54: mouse motion when a mouse button is held down.
55: In this example,
56: mouse motion events are generated;
57: X does not distinguish between different types of mouse events,
58: even though you can request them under different circumstances.
59: .IN "Event" "Types"
60: .FD
61: .IN "Definitions" "XSelectInput"
62: .IN "XSelectInput"
63: XSelectInput (w, mask)
64: Window w;
65: int mask; /* event mask */
66: .FN
67: \fIXSelectInput\fP defines which input events the window is interested in. If
68: a window is not interested in an event, it usually will propagate up to
69: the closest ancestor that is interested.
70: .IN "Event" "Propagation"
71: The bits of the mask are
72: .IN "File" "<X/X.h>"
73: defined in \fI<X/X.h>\fP:
74: .IN "Event Types" "EnterWindow"
75: .IN "Event Types" "LeaveWindow"
76: .IN "Event Types" "MouseMoved"
77: .IN "Event Types" "ExposeWindow"
78: .IN "Event Types" "ExposeRegion"
79: .IN "Event Types" "ExposeCopy"
80: .IN "Event Types" "ExposeRegion"
81: .IN "Event Types" "MouseMoved"
82: .IN "Event Types" "FocusChange"
83: .IN "Event Types" "UnmapWindow"
84: .IN "Event Types" "Keyboard"
85: .IN "Event Types" "Button"
86: .IN "Key Event"
87: .IN "Button Event"
88: .IN "EnterWindow Event"
89: .IN "LeaveWindow Event"
90: .IN "MouseMoved Event"
91: .IN "ExposeWindow Event"
92: .IN "ExposeRegion Event"
93: .IN "ExposeCopy Event"
94: .IN "MouseMoved Event"
95: .IN "Mouse" "Event"
96: .IN "FocusChange Event"
97: .in "UnmapWindow Event"
98: .LP
99: .TS
100: center,box;
101: c c c
102: ___
103: l c l.
104: Request Hex Code Circumstances
105: KeyPressed 0x0001 keyboard key pressed
106: KeyReleased 0x0002 keyboard key released
107: ButtonPressed 0x0004 mouse button pressed
108: ButtonReleased 0x0008 mouse button released
109: EnterWindow 0x0010 mouse entering window
110: LeaveWindow 0x0020 mouse leaving window
111: MouseMoved 0x0040 mouse moves within window
112: ExposeWindow 0x0080 full window changed and/or exposed
113: ExposeRegion 0x0100 region of window exposed
114: ExposeCopy 0x0200 region exposed by XCopyArea
115: RightDownMotion 0x0400 mouse moves with right button down
116: MiddleDownMotion 0x0800 mouse moves with middle button down
117: LeftDownMotion 0x1000 mouse moves with left button down
118: UnmapWindow 0x2000 window is unmapped
119: FocusChange 0x4000 keyboard focus changed
120: .TE
121: Selecting \fIExposeRegion\fP also selects \fIExposeWindow\fP.
122: .PP
123: .IN "XSelectInput"
124: A call on \fIXSelectInput\fP overrides any previous call on \fIXSelectInput\fP
125: for the
126: same window, whether from the same client or a different one.
127: It is not
128: possible for two clients to each select events simultaneously
129: from the same window.
130: Initially,
131: no events will be generated on a window.
132: .PP
133: If a window has both \fIButtonPressed\fP and \fIButtonReleased\fP selected,
134: then
135: a \fIButtonPressed\fP event in that window will automatically `grab' the
136: mouse until all buttons are released, with events sent to windows as
137: .IN "XGrabMouse"
138: described for \fIXGrabMouse\fP.
139: This ensures that a window will see the release event
140: corresponding to the pressed event,
141: even though the mouse may have exited the window in the meantime.
142: .PP
143: If \fIMouseMoved\fP is selected, events will be sent independent of the state
144: of the mouse buttons. If instead, one or more of \fIRightDownMotion\fP,
145: \fIMiddleDownMotion\fP, \fILeftDownMotion\fP is selected,
146: \fIMouseMoved\fP events will be
147: generated only when one or more of the specified buttons is depressed.
148: (There are NO events of type \fIRightDownMotion\fP, \fIMiddleDownMotion\fP, or
149: \fILeftDownMotion\fP;
150: these are ways to request \fIMouseMoved\fP events only when particular buttons
151: are held down).
152: .FD
153: .IN "Definitions" "XFlush"
154: .IN "XFlush"
155: XFlush ()
156: .FN
157: \fIXFlush\fP sends (`flushes') all output requests that have been buffered but
158: not yet sent.
159: Flushing is done automatically the next time input is
160: .IN "XPending"
161: .IN "XNextEvent"
162: .IN "XWindowEvent"
163: read (with \fIXPending\fP, \fIXNextEvent\fP, or \fIXWindowEvent\fP),
164: so most clients
165: should not need to use this subroutine.
166: .FD
167: .IN "Definitions" "XSync"
168: .IN "XSync"
169: XSync (discard)
170: int discard; /* 0 or 1 */
171: .FN
172: \fIXSync\fP flushes the output buffer, then waits until all events and errors
173: resulting from previous calls have been received and processed by
174: the X server.
175: Events are placed on
176: the input queue.
177: .IN "XError"
178: The client's \fIXError\fP subroutine is called once for EACH
179: error received.
180: .IN "XFlush"
181: Even fewer clients need to use this subroutine than \fIXFlush\fP.
182: .PP
183: If discard is true, \fIXSync\fP then discards all events on the input queue
184: (including those events that were on the queue before \fIXSync\fP was called).
185: .FD
186: .IN "Definitions" "XPending"
187: .IN "XPending"
188: int XPending ()
189: .FN
190: \fIXPending\fP flushes the output buffer, then returns the number of input
191: events that have been received from the server, but not yet removed from
192: .IN "XNextEvent"
193: .IN "XWindowEvent"
194: the queue. (Events are removed from the queue by calling \fIXNextEvent\fP or
195: \fIXWindowEvent\fP, described below.)
196: .PP
197: .IN "XPending"
198: .IN "Unix System Call" "select"
199: You should always call \fIXPending\fP before doing a select(2) on the
200: file descriptor contained in the display structure.
201: The input you are trying to wait for may have already arrived and be
202: sitting in Xlib's queue.
203: .IN "XFlush"
204: Another strategy might be to call \fIXFlush\fP after
205: finding out if there are any unprocessed events on the queue by
206: .IN "Macro" "QLength"
207: using the \fIQLength()\fP macro before calling \fIselect(2)\fP.
208: .FD
209: .IN "Definitions" "XNextEvent"
210: XNextEvent (rep)
211: XEvent *rep; /* RETURN */
212: .FN
213: \fIXNextEvent\fP flushes the output buffer, then removes an input event from
214: .IN "XEvent"
215: the head of the queue and copies it into an \fIXEvent\fP
216: supplied by the caller.
217: If the queue is empty, \fIXNextEvent\fP blocks until an event is received.
218: .FD
219: .IN "Definitions" "XPutBackEvent"
220: .IN "XPutBackEvent"
221: XPutBackEvent(event)
222: XEvent *event;
223: .FN
224: \fIXPutBackEvent\fP pushes an event back onto the head of the current
225: display's input queue.
226: This can be useful if you have read an event and then decide that you'd
227: rather deal with it later.
228: .FD
229: .IN "Definitions" "XPeekEvent"
230: .IN "XPeekEvent"
231: XPeekEvent (rep)
232: XEvent *rep; /* RETURN */
233: .FN
234: \fIXPeekEvent\fP flushes the output buffer, then peeks at an input event from
235: the head of the queue and copies it into an
236: \fIXEvent\fP supplied by the caller,
237: without removing it from the input queue.
238: If the queue is empty, \fIXPeekEvent\fP blocks until an event is received.
239: .IN "Macro" "QLength()"
240: You can use the \fIQLength()\fP macro to determine if there are any
241: events to peek at.
242: .PP
243: Note: We may add more specialized peek functions later as the need arises.
244: .FD
245: .IN "Definitions" "XWindowEvent"
246: .IN "XWindowEvent"
247: XWindowEvent (w, mask, rep)
248: Window w;
249: int mask; /* event mask */
250: XEvent *rep; /* RETURN */
251: .FN
252: This subroutine is used to look for specific events from specific windows.
253: \fIXWindowEvent\fP flushes the output buffer, then removes the next event in
254: the queue which matches both the passed window and the passed \fImask\fP.
255: The
256: .IN "XEvent"
257: event is copied into an \fIXEvent\fP supplied by the caller.
258: Events earlier in
259: the queue are not discarded. If no such event has been queued,
260: \fIXWindowEvent\fP blocks until one is received.
261: .FD
262: .IN "Definitions" "XMaskEvent"
263: .IN "XMaskEvent"
264: XMaskEvent (mask, rep)
265: int mask; /* event mask */
266: XEvent *rep; /* RETURN */
267: .FN
268: This subroutine is used to look for specific events.
269: \fIXMaskEvent\fP flushes the output buffer, then removes the next event in
270: the queue which matches the passed mask. The
271: event is copied into an \fIXEvent\fP supplied by the caller. Events earlier in
272: the queue are not discarded. If no such event has been queued,
273: \fIXMaskEvent\fP blocks until one is received.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.