Return to ch12a.t CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib

Annotation of 43BSD/contrib/X/doc/Xlib/ch12a.t, revision 1.1

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.