Return to ch12c.t CVS log

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

Annotation of 43BSDTahoe/new/X/doc/Xlib/ch12c.t, revision 1.1.1.1

1.1       root        1: .NH 2
                      2: Mouse, Button and Server Grabbing
                      3: .PP
                      4: Some programs need to  gain exclusive access to the mouse,
                      5: a single mouse button under some circumstances,
                      6: or the entire X server for the duration of some operation.
                      7: .FD
                      8: .IN "Definitions" "XGrabMouse"
                      9: .IN "XGrabMouse"
                     10: .IN "Mouse" "Grabbing"
                     11: Status XGrabMouse (w, cursor, mask)
                     12:        Window w;
                     13:        Cursor cursor;
                     14:        int mask;       /* event mask */
                     15: .FN
                     16: After \fIXGrabMouse\fP is called, all future mouse events will only go to
                     17: .IN "XSelectInput"
                     18: windows for which the client has previously called \fIXSelectInput\fP.  The
                     19: \fIButtonPressed\fP, \fIButtonReleased\fP, \fIEnterWindow\fP,
                     20: \fILeaveWindow\fP, \fIMouseMoved\fP,
                     21: \fILeftDownMotion\fP, \fIMiddleDownMotion\fP,
                     22: and \fIRightDownMotion\fP bits of the \fImask\fP
                     23: parameter temporarily override the corresponding bits in any mask
                     24: previously passed to \fIXSelectInput\fP; other bits in \fImask\fP are ignored.
                     25: .PP
                     26: .IN "XSelectInput"
                     27: If one of the above-mentioned events occurs, and the client has not
                     28: called \fIXSelectInput\fP on the window where the event would normally be
                     29: sent, then the event will be sent to the window \fIw\fP, provided that the
                     30: event is specified in 
                     31: \fImask\fP and is not \fIEnterWindow\fP or \fILeaveWindow\fP.
                     32: .PP
                     33: .IN "Grabbing Error"
                     34: An error will occur if a different client has already grabbed the mouse
                     35: and has not ungrabbed it.  It is not an error for the same client to
                     36: grab the mouse more than once without ungrabbing it in between.  A
                     37: mouse-grabbing client may want to do this in order to change the cursor
                     38: or event mask without ungrabbing the mouse.
                     39: .PP
                     40: Grabbing the mouse overrides any \fIXGrabButton\fP calls previously issued by
                     41: this or any other client, until the mouse is ungrabbed.
                     42: .PP
                     43: Note that this procedure returns a status and is therefore synchronous,
                     44: even though no other values are returned.
                     45: It returns 0 if the mouse could not be grabbed, non-zero if the
                     46: mouse was successfully grabbed.
                     47: .FD
                     48: .IN "Definitions" "XGrabMouse"
                     49: .IN "XGrabMouse"
                     50: XUngrabMouse ()
                     51: .FN
                     52: \fIXUngrabMouse\fP releases hold of the mouse if it was grabbed by 
                     53: \fIXGrabMouse\fP.
                     54: .FD
                     55: .IN "Definitions" "XGrabButton"
                     56: .IN "XGrabButton"
                     57: Status XGrabButton (w, cursor, buttonMask, eventMask)
                     58:        Window w;
                     59:        Cursor cursor;
                     60:        int buttonMask;
                     61:        int eventMask;
                     62: .FN
                     63: After \fIXGrabButton\fP has been called, the mouse will automatically be
                     64: grabbed whenever a particular mouse button is pressed while certain keys are
                     65: down.
                     66: .IN "Button Mask"
                     67: The combination is specified in \fIbuttonMask\fP;  this mask must
                     68: have exactly one of the \fILeftMask\fP, \fIMiddleMask\fP, and \fIRightMask\fP
                     69: bits set,
                     70: and may have some combination of the \fIControlMask\fP, \fIMetaMask\fP,
                     71: \fIShiftLockMask\fP and
                     72: \fIShiftMask\fP bits set as well.
                     73: .PP
                     74: If the specified button is pressed while exactly the specified keys are down,
                     75: this and all future mouse events are grabbed until all buttons are
                     76: .IN "XGrabMouse"
                     77: released, with events sent to windows as described under \fIXGrabMouse\fP
                     78: above.
                     79: .IN "Event Mask"
                     80: The \fIeventMask\fP determines what mouse events are reported while the
                     81: mouse is grabbed.
                     82: .PP
                     83: An error will occur if another client has already grabbed the same
                     84: button/key combination and has not ungrabbed it.
                     85: .PP
                     86: Note that this procedure returns a status and is therefore synchronous,
                     87: It returns 0 if the button could not be grabbed, non-zero if the
                     88: the button was grabbed successfully.
                     89: .FD
                     90: .IN "Definitions" "XUngrabButton"
                     91: .IN "XGrabButton"
                     92: XUngrabButton (mask)
                     93:        int mask;       /* button mask;  see XGrabButton */
                     94: .FN
                     95: \fIXUngrabButton\fP notifies the server that the client is no longer
                     96: interested in grabbing the mouse when the specified button/key
                     97: combination occurs.
                     98: See \fIXGrabButton\fP for the meaning of the button
                     99: mask bits.
                    100: This grab is overridden by a grab mouse request.
                    101: .FD
                    102: .IN "XGrabServer"
                    103: .IN "Definitions" "XGrabServer"
                    104: .IN "Grabbing" "Server"
                    105: XGrabServer()
                    106: 
                    107: XUngrabServer()
                    108: .FN
                    109: These requests can be used to control processing of output on other
                    110: connections by the window system server.
                    111: No processing of requests or close downs on all other connections
                    112: will occur while the server is grabbed.
                    113: .PP
                    114: .IN "Menus"
                    115: .IN "Window" "Managers"
                    116: This may be useful for menus or window manager programs who may want to
                    117: preserve bits on the screen while temporarily suspending processing
                    118: on other connections.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.