Return to ch12e.t CVS log

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

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

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.