diff options
Diffstat (limited to 'libX11/specs/libX11/CH12')
| -rw-r--r-- | libX11/specs/libX11/CH12 | 2680 |
1 files changed, 2680 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH12 b/libX11/specs/libX11/CH12 new file mode 100644 index 000000000..08b9ba93a --- /dev/null +++ b/libX11/specs/libX11/CH12 @@ -0,0 +1,2680 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 12\fP\s-1 + +\s+1\fBInput Device Functions\fP\s-1 +.sp 2 +.nr H1 12 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 12: Input Device Functions +.XE +You can use the Xlib input device functions to: +.IP \(bu 5 +Grab the pointer and individual buttons on the pointer +.IP \(bu 5 +Grab the keyboard and individual keys on the keyboard +.IP \(bu 5 +Resume event processing +.IP \(bu 5 +Move the pointer +.IP \(bu 5 +Set the input focus +.IP \(bu 5 +Manipulate the keyboard and pointer settings +.IP \(bu 5 +Manipulate the keyboard encoding +.NH 2 +Pointer Grabbing +.XS +\*(SN Pointer Grabbing +.XE +.LP +Xlib provides functions that you can use to control input from the pointer, +which usually is a mouse. +Usually, as soon as keyboard and mouse events occur, +the X server delivers them to the appropriate client, +which is determined by the window and input focus. +The X server provides sufficient control over event delivery to +allow window managers to support mouse ahead and various other +styles of user interface. +Many of these user interfaces depend on synchronous delivery of events. +The delivery of pointer and keyboard events can be controlled +independently. +.LP +When mouse buttons or keyboard keys are grabbed, events +will be sent to the grabbing client rather than the normal +client who would have received the event. +If the keyboard or pointer is in asynchronous mode, +further mouse and keyboard events will continue to be processed. +If the keyboard or pointer is in synchronous mode, no +further events are processed until the grabbing client +allows them (see +.PN XAllowEvents ). +The keyboard or pointer is considered frozen during this +interval. +The event that triggered the grab can also be replayed. +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +.IN "Active grab" "" "@DEF@" +There are two kinds of grabs: +active and passive. +An active grab occurs when a single client grabs the keyboard and/or pointer +explicitly (see +.PN XGrabPointer +and +.PN XGrabKeyboard ). +.IN "Passive grab" +A passive grab occurs when clients grab a particular keyboard key +or pointer button in a window, +and the grab will activate when the key or button is actually pressed. +Passive grabs are convenient for implementing reliable pop-up menus. +For example, you can guarantee that the pop-up is mapped +before the up pointer button event occurs by +grabbing a button requesting synchronous behavior. +The down event will trigger the grab and freeze further +processing of pointer events until you have the chance to +map the pop-up window. +You can then allow further event processing. +The up event will then be correctly processed relative to the +pop-up window. +.LP +For many operations, +there are functions that take a time argument. +The X server includes a timestamp in various events. +One special time, called +.IN "CurrentTime" "" "@DEF@" +.IN "Time" "" "@DEF@" +.PN CurrentTime , +represents the current server time. +The X server maintains the time when the input focus was last changed, +when the keyboard was last grabbed, +when the pointer was last grabbed, +or when a selection was last changed. +Your +application may be slow reacting to an event. +You often need some way to specify that your +request should not occur if another application has in the meanwhile +taken control of the keyboard, pointer, or selection. +By providing the timestamp from the event in the request, +you can arrange that the operation not take effect +if someone else has performed an operation in the meanwhile. +.LP +A timestamp is a time value, expressed in milliseconds. +It typically is the time since the last server reset. +Timestamp values wrap around (after about 49.7 days). +The server, given its current time is represented by timestamp T, +always interprets timestamps from clients by treating half of the timestamp +space as being later in time than T. +One timestamp value, named +.PN CurrentTime , +is never generated by the server. +This value is reserved for use in requests to represent the current server time. +.LP +For many functions in this section, +you pass pointer event mask bits. +The valid pointer event mask bits are: +.PN ButtonPressMask , +.PN ButtonReleaseMask , +.PN EnterWindowMask , +.PN LeaveWindowMask , +.PN PointerMotionMask , +.PN PointerMotionHintMask , +.PN Button1MotionMask , +.PN Button2MotionMask , +.PN Button3MotionMask , +.PN Button4MotionMask , +.PN Button5MotionMask , +.PN ButtonMotionMask , +and +.PN KeyMapStateMask . +For other functions in this section, +you pass keymask bits. +The valid keymask bits are: +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +and +.PN Mod5Mask . +.LP +.sp +To grab the pointer, use +.PN XGrabPointer . +.IN "Grabbing" "pointer" +.IN "Pointer" "grabbing" +.IN "XGrabPointer" "" "@DEF@" +.sM +.FD 0 +int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^, + \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Window \fIconfine_to\fP\^; +.br + Cursor \fIcursor\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the pointer +events are to be reported as usual or reported with respect to the grab window +if selected by the event mask. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIconfine_to\fP 1i +Specifies the window to confine the pointer in or +.PN None . +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed during the grab or +.PN None . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XGrabPointer +function actively grabs control of the pointer and returns +.PN GrabSuccess +if the grab was successful. +Further pointer events are reported only to the grabbing client. +.PN XGrabPointer +overrides any active pointer grab by this client. +If owner_events is +.PN False , +all generated pointer events +are reported with respect to grab_window and are reported only if +selected by event_mask. +If owner_events is +.PN True +and if a generated +pointer event would normally be reported to this client, +it is reported as usual. +Otherwise, the event is reported with respect to the +grab_window and is reported only if selected by event_mask. +For either value of owner_events, unreported events are discarded. +.LP +If the pointer_mode is +.PN GrabModeAsync , +pointer event processing continues as usual. +If the pointer is currently frozen by this client, +the processing of events for the pointer is resumed. +If the pointer_mode is +.PN GrabModeSync , +the state of the pointer, as seen by +client applications, +appears to freeze, and the X server generates no further pointer events +until the grabbing client calls +.PN XAllowEvents +or until the pointer grab is released. +Actual pointer changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If the keyboard_mode is +.PN GrabModeAsync , +keyboard event processing is unaffected by activation of the grab. +If the keyboard_mode is +.PN GrabModeSync , +the state of the keyboard, as seen by +client applications, +appears to freeze, and the X server generates no further keyboard events +until the grabbing client calls +.PN XAllowEvents +or until the pointer grab is released. +Actual keyboard changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If a cursor is specified, it is displayed regardless of what +window the pointer is in. +If +.PN None +is specified, +the normal cursor for that window is displayed +when the pointer is in grab_window or one of its subwindows; +otherwise, the cursor for grab_window is displayed. +.LP +If a confine_to window is specified, +the pointer is restricted to stay contained in that window. +The confine_to window need have no relationship to the grab_window. +If the pointer is not initially in the confine_to window, +it is warped automatically to the closest edge +just before the grab activates and enter/leave events are generated as usual. +If the confine_to window is subsequently reconfigured, +the pointer is warped automatically, as necessary, +to keep it contained in the window. +.LP +The time argument allows you to avoid certain circumstances that come up +if applications take a long time to respond or if there are long network +delays. +Consider a situation where you have two applications, both +of which normally grab the pointer when clicked on. +If both applications specify the timestamp from the event, +the second application may wake up faster and successfully grab the pointer +before the first application. +The first application then will get an indication that the other application +grabbed the pointer before its request was processed. +.LP +.PN XGrabPointer +generates +.PN EnterNotify +and +.PN LeaveNotify +events. +.LP +Either if grab_window or confine_to window is not viewable +or if the confine_to window lies completely outside the boundaries of the root +window, +.PN XGrabPointer +fails and returns +.PN GrabNotViewable . +If the pointer is actively grabbed by some other client, +it fails and returns +.PN AlreadyGrabbed . +If the pointer is frozen by an active grab of another client, +it fails and returns +.PN GrabFrozen . +If the specified time is earlier than the last-pointer-grab time or later +than the current X server time, it fails and returns +.PN GrabInvalidTime . +Otherwise, the last-pointer-grab time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.LP +.PN XGrabPointer +can generate +.PN BadCursor , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab the pointer, use +.PN XUngrabPointer . +.IN "Ungrabbing" "pointer" +.IN "Pointer" "ungrabbing" +.IN "XUngrabPointer" "" "@DEF@" +.sM +.FD 0 +XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XUngrabPointer +function releases the pointer and any queued events +if this client has actively grabbed the pointer from +.PN XGrabPointer , +.PN XGrabButton , +or from a normal button press. +.PN XUngrabPointer +does not release the pointer if the specified +time is earlier than the last-pointer-grab time or is later than the +current X server time. +It also generates +.PN EnterNotify +and +.PN LeaveNotify +events. +The X server performs an +.PN UngrabPointer +request automatically if the event window or confine_to window +for an active pointer grab becomes not viewable +or if window reconfiguration causes the confine_to window to lie completely +outside the boundaries of the root window. +.LP +.sp +To change an active pointer grab, use +.PN XChangeActivePointerGrab . +.IN "Pointer" "grabbing" +.IN "Changing" "pointer grab" +.IN "XChangeActivePointerGrab" "" "@DEF@" +.sM +.FD 0 +XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + Cursor \fIcursor\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XChangeActivePointerGrab +function changes the specified dynamic parameters if the pointer is actively +grabbed by the client and if the specified time is no earlier than the +last-pointer-grab time and no later than the current X server time. +This function has no effect on the passive parameters of an +.PN XGrabButton . +The interpretation of event_mask and cursor is the same as described in +.PN XGrabPointer . +.LP +.PN XChangeActivePointerGrab +can generate +.PN BadCursor +and +.PN BadValue +errors. +.LP +.sp +To grab a pointer button, use +.PN XGrabButton . +.IN "Grabbing" "buttons" +.IN "Button" "grabbing" +.IN "XGrabButton" "" "@DEF@" +.sM +.FD 0 +XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, +.br + \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIbutton\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Window \fIconfine_to\fP\^; +.br + Cursor \fIcursor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Bu grabbed +.IP \fIbutton\fP 1i +Specifies the pointer button that is to be \*(Bu or +.PN AnyButton . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the pointer +events are to be reported as usual or reported with respect to the grab window +if selected by the event mask. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIconfine_to\fP 1i +Specifies the window to confine the pointer in or +.PN None . +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.LP +.eM +The +.PN XGrabButton +function establishes a passive grab. +In the future, +the pointer is actively grabbed (as for +.PN XGrabPointer ), +the last-pointer-grab time is set to the time at which the button was pressed +(as transmitted in the +.PN ButtonPress +event), and the +.PN ButtonPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The pointer is not grabbed, and the specified button is logically pressed +when the specified modifier keys are logically down, +and no other buttons or modifier keys are logically down. +.IP \(bu 5 +The grab_window contains the pointer. +.IP \(bu 5 +The confine_to window (if any) is viewable. +.IP \(bu 5 +A passive grab on the same button/key combination does not exist +on any ancestor of grab_window. +.LP +The interpretation of the remaining arguments is as for +.PN XGrabPointer . +The active grab is terminated automatically when the logical state of the +pointer has all buttons released +(independent of the state of the logical modifier keys). +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +This request overrides all previous grabs by the same client on the same +button/key combinations on the same window. +A modifiers of +.PN AnyModifier +is equivalent to issuing the grab request for all +possible modifier combinations (including the combination of no modifiers). +It is not required that all modifiers specified have currently assigned +KeyCodes. +A button of +.PN AnyButton +is equivalent to +issuing the request for all possible buttons. +Otherwise, it is not required that the specified button currently be assigned +to a physical button. +.LP +If some other client has already issued an +.PN XGrabButton +with the same button/key combination on the same window, a +.PN BadAccess +error results. +When using +.PN AnyModifier +or +.PN AnyButton , +the request fails completely, +and a +.PN BadAccess +error results (no grabs are +established) if there is a conflicting grab for any combination. +.PN XGrabButton +has no effect on an active grab. +.LP +.PN XGrabButton +can generate +.PN BadCursor , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab a pointer button, use +.PN XUngrabButton . +.IN "Ungrabbing" "buttons" +.IN "Button" "ungrabbing" +.IN "XUngrabButton" "" "@DEF@" +.sM +.FD 0 +XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIbutton\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Bu released +.IP \fIbutton\fP 1i +Specifies the pointer button that is to be \*(Bu or +.PN AnyButton . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.LP +.eM +The +.PN XUngrabButton +function releases the passive button/key combination on the specified window if +it was grabbed by this client. +A modifiers of +.PN AnyModifier +is +equivalent to issuing +the ungrab request for all possible modifier combinations, including +the combination of no modifiers. +A button of +.PN AnyButton +is equivalent to issuing the +request for all possible buttons. +.PN XUngrabButton +has no effect on an active grab. +.LP +.PN XUngrabButton +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 2 +Keyboard Grabbing +.XS +\*(SN Keyboard Grabbing +.XE +.LP +Xlib provides functions that you can use to grab or ungrab the keyboard +as well as allow events. +.LP +For many functions in this section, +you pass keymask bits. +The valid keymask bits are: +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +and +.PN Mod5Mask . +.LP +.sp +To grab the keyboard, use +.PN XGrabKeyboard . +.IN "Keyboard" "grabbing" +.IN "Grabbing" "keyboard" +.IN "XGrabKeyboard" "" "@DEF@" +.sM +.FD 0 +int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the keyboard events +are to be reported as usual. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XGrabKeyboard +function actively grabs control of the keyboard and generates +.PN FocusIn +and +.PN FocusOut +events. +Further key events are reported only to the +grabbing client. +.PN XGrabKeyboard +overrides any active keyboard grab by this client. +If owner_events is +.PN False , +all generated key events are reported with +respect to grab_window. +If owner_events is +.PN True +and if a generated +key event would normally be reported to this client, it is reported +normally; otherwise, the event is reported with respect to the +grab_window. +Both +.PN KeyPress +and +.PN KeyRelease +events are always reported, +independent of any event selection made by the client. +.LP +If the keyboard_mode argument is +.PN GrabModeAsync , +keyboard event processing continues +as usual. +If the keyboard is currently frozen by this client, +then processing of keyboard events is resumed. +If the keyboard_mode argument is +.PN GrabModeSync , +the state of the keyboard (as seen by client applications) appears to freeze, +and the X server generates no further keyboard events until the +grabbing client issues a releasing +.PN XAllowEvents +call or until the keyboard grab is released. +Actual keyboard changes are not lost while the keyboard is frozen; +they are simply queued in the server for later processing. +.LP +If pointer_mode is +.PN GrabModeAsync , +pointer event processing is unaffected +by activation of the grab. +If pointer_mode is +.PN GrabModeSync , +the state of the pointer (as seen by client applications) appears to freeze, +and the X server generates no further pointer events +until the grabbing client issues a releasing +.PN XAllowEvents +call or until the keyboard grab is released. +Actual pointer changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If the keyboard is actively grabbed by some other client, +.PN XGrabKeyboard +fails and returns +.PN AlreadyGrabbed . +If grab_window is not viewable, +it fails and returns +.PN GrabNotViewable . +If the keyboard is frozen by an active grab of another client, +it fails and returns +.PN GrabFrozen . +If the specified time is earlier than the last-keyboard-grab time +or later than the current X server time, +it fails and returns +.PN GrabInvalidTime . +Otherwise, the last-keyboard-grab time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.LP +.PN XGrabKeyboard +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To ungrab the keyboard, use +.PN XUngrabKeyboard . +.IN "Keyboard" "ungrabbing" +.IN "Ungrabbing" "keyboard" +.IN "XUngrabKeyboard" "" "@DEF@" +.sM +.FD 0 +XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XUngrabKeyboard +function +releases the keyboard and any queued events if this client has it actively grabbed from +either +.PN XGrabKeyboard +or +.PN XGrabKey . +.PN XUngrabKeyboard +does not release the keyboard and any queued events +if the specified time is earlier than +the last-keyboard-grab time or is later than the current X server time. +It also generates +.PN FocusIn +and +.PN FocusOut +events. +The X server automatically performs an +.PN UngrabKeyboard +request if the event window for an +active keyboard grab becomes not viewable. +.LP +.sp +To passively grab a single key of the keyboard, use +.PN XGrabKey . +.IN "Key" "grabbing" +.IN "Grabbing" "keys" +.IN "XGrabKey" "" "@DEF@" +.sM +.FD 0 +XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, +.br + \fIkeyboard_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIkeycode\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeycode\fP 1i +Specifies the KeyCode or +.PN AnyKey . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the keyboard events +are to be reported as usual. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.LP +.eM +The +.PN XGrabKey +function establishes a passive grab on the keyboard. +In the future, +the keyboard is actively grabbed (as for +.PN XGrabKeyboard ), +the last-keyboard-grab time is set to the time at which the key was pressed +(as transmitted in the +.PN KeyPress +event), and the +.PN KeyPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The keyboard is not grabbed and the specified key +(which can itself be a modifier key) is logically pressed +when the specified modifier keys are logically down, +and no other modifier keys are logically down. +.IP \(bu 5 +Either the grab_window is an ancestor of (or is) the focus window, +or the grab_window is a descendant of the focus window and contains the pointer. +.IP \(bu 5 +A passive grab on the same key combination does not exist +on any ancestor of grab_window. +.LP +The interpretation of the remaining arguments is as for +.PN XGrabKeyboard . +The active grab is terminated automatically when the logical state of the +keyboard has the specified key released +(independent of the logical state of the modifier keys). +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +A modifiers argument of +.PN AnyModifier +is equivalent to issuing the request for all +possible modifier combinations (including the combination of no +modifiers). +It is not required that all modifiers specified have +currently assigned KeyCodes. +A keycode argument of +.PN AnyKey +is equivalent to issuing +the request for all possible KeyCodes. +Otherwise, the specified keycode must be in +the range specified by min_keycode and max_keycode in the connection +setup, +or a +.PN BadValue +error results. +.LP +If some other client has issued a +.PN XGrabKey +with the same key combination on the same window, a +.PN BadAccess +error results. +When using +.PN AnyModifier +or +.PN AnyKey , +the request fails completely, +and a +.PN BadAccess +error results (no grabs are established) +if there is a conflicting grab for any combination. +.LP +.PN XGrabKey +can generate +.PN BadAccess , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab a key, use +.PN XUngrabKey . +.IN "Key" "ungrabbing" +.IN "Ungrabbing" "keys" +.IN "XUngrabKey" "" "@DEF@" +.sM +.FD 0 +XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIkeycode\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeycode\fP 1i +Specifies the KeyCode or +.PN AnyKey . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.LP +.eM +The +.PN XUngrabKey +function releases the key combination on the specified window if it was grabbed +by this client. +It has no effect on an active grab. +A modifiers of +.PN AnyModifier +is equivalent to issuing +the request for all possible modifier combinations +(including the combination of no modifiers). +A keycode argument of +.PN AnyKey +is equivalent to issuing the request for all possible key codes. +.LP +.PN XUngrabKey +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 2 +Resuming Event Processing +.XS +\*(SN Resuming Event Processing +.XE +.LP +The previous sections discussed grab mechanisms with which processing +of events by the server can be temporarily suspended. This section +describes the mechanism for resuming event processing. +.LP +.sp +To allow further events to be processed when the device has been frozen, use +.PN XAllowEvents . +.IN "XAllowEvents" "" "@DEF@" +.sM +.FD 0 +XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_mode\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mode\fP 1i +Specifies the event mode. +You can pass +.PN AsyncPointer , +.PN SyncPointer , +.PN AsyncKeyboard , +.PN SyncKeyboard , +.PN ReplayPointer , +.PN ReplayKeyboard , +.PN AsyncBoth , +or +.PN SyncBoth . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XAllowEvents +function releases some queued events if the client has caused a device +to freeze. +It has no effect if the specified time is earlier than the last-grab +time of the most recent active grab for the client or if the specified time +is later than the current X server time. +Depending on the event_mode argument, the following occurs: +.TS +lw(1.25i) lw(4.5i). +T{ +.PN AsyncPointer +T} T{ +If the pointer is frozen by the client, +pointer event processing continues as usual. +If the pointer is frozen twice by the client on behalf of two separate grabs, +.PN AsyncPointer +thaws for both. +.PN AsyncPointer +has no effect if the pointer is not frozen by the client, +but the pointer need not be grabbed by the client. +T} +.sp 6p +T{ +.PN SyncPointer +T} T{ +If the pointer is frozen and actively grabbed by the client, +pointer event processing continues as usual until the next +.PN ButtonPress +or +.PN ButtonRelease +event is reported to the client. +At this time, +the pointer again appears to freeze. +However, if the reported event causes the pointer grab to be released, +the pointer does not freeze. +.PN SyncPointer +has no effect if the pointer is not frozen by the client +or if the pointer is not grabbed by the client. +T} +.sp 6p +T{ +.PN ReplayPointer +T} T{ +If the pointer is actively grabbed by the client and is frozen as the result of +an event having been sent to the client (either from the activation of an +.PN XGrabButton +or from a previous +.PN XAllowEvents +with mode +.PN SyncPointer +but not from an +.PN XGrabPointer ), +the pointer grab is released and that event is completely reprocessed. +This time, however, the function ignores any passive grabs at or above +(toward the root of) the grab_window of the grab just released. +The request has no effect if the pointer is not grabbed by the client +or if the pointer is not frozen as the result of an event. +T} +.sp 6p +T{ +.PN AsyncKeyboard +T} T{ +If the keyboard is frozen by the client, +keyboard event processing continues as usual. +If the keyboard is frozen twice by the client on behalf of two separate grabs, +.PN AsyncKeyboard +thaws for both. +.PN AsyncKeyboard +has no effect if the keyboard is not frozen by the client, +but the keyboard need not be grabbed by the client. +T} +.sp 6p +T{ +.PN SyncKeyboard +T} T{ +If the keyboard is frozen and actively grabbed by the client, +keyboard event processing continues as usual until the next +.PN KeyPress +or +.PN KeyRelease +event is reported to the client. +At this time, +the keyboard again appears to freeze. +However, if the reported event causes the keyboard grab to be released, +the keyboard does not freeze. +.PN SyncKeyboard +has no effect if the keyboard is not frozen by the client +or if the keyboard is not grabbed by the client. +T} +.sp 6p +T{ +.PN ReplayKeyboard +T} T{ +If the keyboard is actively grabbed by the client and is frozen +as the result of an event having been sent to the client (either from the +activation of an +.PN XGrabKey +or from a previous +.PN XAllowEvents +with mode +.PN SyncKeyboard +but not from an +.PN XGrabKeyboard ), +the keyboard grab is released and that event is completely reprocessed. +This time, however, the function ignores any passive grabs at or above +(toward the root of) +the grab_window of the grab just released. +The request has no effect if the keyboard is not grabbed by the client +or if the keyboard is not frozen as the result of an event. +T} +.sp 6p +T{ +.PN SyncBoth +T} T{ +If both pointer and keyboard are frozen by the client, +event processing for both devices continues as usual until the next +.PN ButtonPress , +.PN ButtonRelease , +.PN KeyPress , +or +.PN KeyRelease +event is reported to the client for a grabbed device +(button event for the pointer, key event for the keyboard), +at which time the devices again appear to freeze. +However, if the reported event causes the grab to be released, +then the devices do not freeze (but if the other device is still +grabbed, then a subsequent event for it will still cause both devices +to freeze). +.PN SyncBoth +has no effect unless both pointer and keyboard +are frozen by the client. +If the pointer or keyboard is frozen twice +by the client on behalf of two separate grabs, +.PN SyncBoth +thaws for both (but a subsequent freeze for +.PN SyncBoth +will only freeze each device once). +T} +.sp 6p +T{ +.PN AsyncBoth +T} T{ +If the pointer and the keyboard are frozen by the +client, event processing for both devices continues as usual. +If a device is frozen twice by the client on behalf of two separate grabs, +.PN AsyncBoth +thaws for both. +.PN AsyncBoth +has no effect unless both +pointer and keyboard are frozen by the client. +T} +.TE +.LP +.PN AsyncPointer , +.PN SyncPointer , +and +.PN ReplayPointer +have no effect on the +processing of keyboard events. +.PN AsyncKeyboard , +.PN SyncKeyboard , +and +.PN ReplayKeyboard +have no effect on the +processing of pointer events. +It is possible for both a pointer grab and a keyboard grab (by the same +or different clients) to be active simultaneously. +If a device is frozen on behalf of either grab, +no event processing is performed for the device. +It is possible for a single device to be frozen because of both grabs. +In this case, +the freeze must be released on behalf of both grabs before events can +again be processed. +If a device is frozen twice by a single client, +then a single +.PN AllowEvents +releases both. +.LP +.PN XAllowEvents +can generate a +.PN BadValue +error. +.NH 2 +Moving the Pointer +.XS +\*(SN Moving the Pointer +.XE +.LP +Although movement of the pointer normally should be left to the +control of the end user, sometimes it is necessary to move the +pointer to a new position under program control. +.LP +.sp +To move the pointer to an arbitrary point in a window, use +.PN XWarpPointer . +.IN "XWarpPointer" "" "@DEF@" +.sM +.FD 0 +XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, +.br + \fIdest_y\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIsrc_w\fP\^, \fIdest_w\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc_w\fP 1i +Specifies the source window or +.PN None . +.IP \fIdest_w\fP 1i +Specifies the destination window or +.PN None . +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +.br +.ns +.IP \fIsrc_width\fP 1i +.br +.ns +.IP \fIsrc_height\fP 1i +Specify a rectangle in the source window. +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates within the destination window. +.LP +.eM +If dest_w is +.PN None , +.PN XWarpPointer +moves the pointer by the offsets (dest_x, dest_y) relative to the current +position of the pointer. +If dest_w is a window, +.PN XWarpPointer +moves the pointer to the offsets (dest_x, dest_y) relative to the origin of +dest_w. +However, if src_w is a window, +the move only takes place if the window src_w contains the pointer +and if the specified rectangle of src_w contains the pointer. +.LP +The src_x and src_y coordinates are relative to the origin of src_w. +If src_height is zero, +it is replaced with the current height of src_w minus src_y. +If src_width is zero, +it is replaced with the current width of src_w minus src_x. +.LP +There is seldom any reason for calling this function. +The pointer should normally be left to the user. +If you do use this function, however, it generates events just as if the user +had instantaneously moved the pointer from one position to another. +Note that you cannot use +.PN XWarpPointer +to move the pointer outside the confine_to window of an active pointer grab. +An attempt to do so will only move the pointer as far as the closest edge of the +confine_to window. +.LP +.PN XWarpPointer +can generate a +.PN BadWindow +error. +.NH 2 +Controlling Input Focus +.XS +\*(SN Controlling Input Focus +.XE +.LP +Xlib provides functions that you can use to set and get the input focus. +The input focus is a shared resource, and cooperation among clients is +required for correct interaction. See the +\fIInter-Client Communication Conventions Manual\fP +for input focus policy. +.LP +.sp +To set the input focus, use +.PN XSetInputFocus . +.IN "XSetInputFocus" "" "@DEF@" +.sM +.FD 0 +XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIfocus\fP\^; +.br + int \fIrevert_to\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfocus\fP 1i +Specifies the window, +.PN PointerRoot , +or +.PN None . +.IP \fIrevert_to\fP 1i +Specifies where the input focus reverts to if the window becomes not +viewable. +You can pass +.PN RevertToParent , +.PN RevertToPointerRoot , +or +.PN RevertToNone . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XSetInputFocus +function changes the input focus and the last-focus-change time. +It has no effect if the specified time is earlier than the current +last-focus-change time or is later than the current X server time. +Otherwise, the last-focus-change time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.PN XSetInputFocus +causes the X server to generate +.PN FocusIn +and +.PN FocusOut +events. +.LP +Depending on the focus argument, +the following occurs: +.IP \(bu 5 +If focus is +.PN None , +all keyboard events are discarded until a new focus window is set, +and the revert_to argument is ignored. +.IP \(bu 5 +If focus is a window, +it becomes the keyboard's focus window. +If a generated keyboard event would normally be reported to this window +or one of its inferiors, the event is reported as usual. +Otherwise, the event is reported relative to the focus window. +.IP \(bu 5 +If focus is +.PN PointerRoot , +the focus window is dynamically taken to be the root window of whatever screen +the pointer is on at each keyboard event. +In this case, the revert_to argument is ignored. +.LP +The specified focus window must be viewable at the time +.PN XSetInputFocus +is called, +or a +.PN BadMatch +error results. +If the focus window later becomes not viewable, +the X server +evaluates the revert_to argument to determine the new focus window as follows: +.IP \(bu 5 +If revert_to is +.PN RevertToParent , +the focus reverts to the parent (or the closest viewable ancestor), +and the new revert_to value is taken to be +.PN RevertToNone . +.IP \(bu 5 +If revert_to is +.PN RevertToPointerRoot +or +.PN RevertToNone , +the focus reverts to +.PN PointerRoot +or +.PN None , +respectively. +When the focus reverts, +the X server generates +.PN FocusIn +and +.PN FocusOut +events, but the last-focus-change time is not affected. +.LP +.PN XSetInputFocus +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To obtain the current input focus, use +.PN XGetInputFocus . +.IN "XGetInputFocus" "" "@DEF@" +.sM +.FD 0 +XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window *\fIfocus_return\fP\^; +.br + int *\fIrevert_to_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfocus_return\fP 1i +Returns the focus window, +.PN PointerRoot , +or +.PN None . +.IP \fIrevert_to_return\fP 1i +Returns the current focus state +.Pn ( RevertToParent , +.PN RevertToPointerRoot , +or +.PN RevertToNone ). +.LP +.eM +The +.PN XGetInputFocus +function returns the focus window and the current focus state. +.NH 2 +Manipulating the Keyboard and Pointer Settings +.XS +\*(SN Manipulating the Keyboard and Pointer Settings +.XE +.LP +Xlib provides functions that you can use to +change the keyboard control, obtain a list of the auto-repeat keys, +turn keyboard auto-repeat on or off, ring the bell, +set or obtain the pointer button or keyboard mapping, +and obtain a bit vector for the keyboard. +.LP +.IN "Keyboard" "bell volume" +.IN "Keyboard" "keyclick volume" +.IN "Keyboard" "bit vector" +.IN "Mouse" "programming" +This section discusses +the user-preference options of bell, key click, +pointer behavior, and so on. +The default values for many of these options are server dependent. +Not all implementations will actually be able to control all of these +parameters. +.LP +The +.PN XChangeKeyboardControl +function changes control of a keyboard and operates on a +.PN XKeyboardControl +structure: +.sM +.LP +/* Mask bits for ChangeKeyboardControl */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN KBKeyClickPercent +T} T{ +(1L<<0) +T} +T{ +#define +T} T{ +.PN KBBellPercent +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN KBBellPitch +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN KBBellDuration +T} T{ +(1L<<3) +T} +T{ +#define +T} T{ +.PN KBLed +T} T{ +(1L<<4) +T} +T{ +#define +T} T{ +.PN KBLedMode +T} T{ +(1L<<5) +T} +T{ +#define +T} T{ +.PN KBKey +T} T{ +(1L<<6) +T} +T{ +#define +T} T{ +.PN KBAutoRepeatMode +T} T{ +(1L<<7) +T} +.TE +.IN "XKeyboardControl" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +/* Values */ + +typedef struct { + int key_click_percent; + int bell_percent; + int bell_pitch; + int bell_duration; + int led; + int led_mode; /* LedModeOn, LedModeOff */ + int key; + int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, + AutoRepeatModeDefault */ +} XKeyboardControl; +.De +.LP +.eM +The key_click_percent member sets the volume for key clicks between 0 (off) +and 100 (loud) inclusive, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +.LP +The bell_percent sets the base volume for the bell between 0 (off) and 100 +(loud) inclusive, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +The bell_duration member sets the duration of the +bell specified in milliseconds, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +.LP +If both the led_mode and led members are specified, +the state of that LED is changed, if possible. +The led_mode member can be set to +.PN LedModeOn +or +.PN LedModeOff . +If only led_mode is specified, the state of +all LEDs are changed, if possible. +At most 32 LEDs numbered from one are supported. +No standard interpretation of LEDs is defined. +If led is specified without led_mode, a +.PN BadMatch +error results. +.LP +If both the auto_repeat_mode and key members are specified, +the auto_repeat_mode of that key is changed (according to +.PN AutoRepeatModeOn , +.PN AutoRepeatModeOff , +or +.PN AutoRepeatModeDefault ), +if possible. +If only auto_repeat_mode is +specified, the global auto_repeat_mode for the entire keyboard is +changed, if possible, and does not affect the per-key settings. +If a key is specified without an auto_repeat_mode, a +.PN BadMatch +error results. +Each key has an individual mode of whether or not it should auto-repeat +and a default setting for the mode. +In addition, +there is a global mode of whether auto-repeat should be enabled or not +and a default setting for that mode. +When global mode is +.PN AutoRepeatModeOn , +keys should obey their individual auto-repeat modes. +When global mode is +.PN AutoRepeatModeOff , +no keys should auto-repeat. +An auto-repeating key generates alternating +.PN KeyPress +and +.PN KeyRelease +events. +When a key is used as a modifier, +it is desirable for the key not to auto-repeat, +regardless of its auto-repeat setting. +.LP +A bell generator connected with the console but not directly on a +keyboard is treated as if it were part of the keyboard. +The order in which controls are verified and altered is server-dependent. +If an error is generated, a subset of the controls may have been altered. +.LP +.sp +.IN "XChangeKeyboardControl" "" "@DEF@" +.sM +.FD 0 +XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fIvalue_mask\fP\^; +.br + XKeyboardControl *\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvalue_mask\fP 1i +Specifies which controls to change. +This mask is the bitwise inclusive OR of the valid control mask bits. +.IP \fIvalues\fP 1i +Specifies one value for each bit set to 1 in the mask. +.LP +.eM +The +.PN XChangeKeyboardControl +function controls the keyboard characteristics defined by the +.PN XKeyboardControl +structure. +The value_mask argument specifies which values are to be changed. +.LP +.PN XChangeKeyboardControl +can generate +.PN BadMatch +and +.PN BadValue +errors. +.LP +.sp +To obtain the current control values for the keyboard, use +.PN XGetKeyboardControl . +.IN "XGetKeyboardControl" "" "@DEF@" +.sM +.FD 0 +XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XKeyboardState *\fIvalues_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvalues_return\fP 1i +Returns the current keyboard controls in the specified +.PN XKeyboardState +structure. +.LP +.eM +The +.PN XGetKeyboardControl +function returns the current control values for the keyboard to the +.PN XKeyboardState +structure. +.LP +.IN "XGetKeyboardControl" +.IN "XKeyboardState" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + int key_click_percent; + int bell_percent; + unsigned int bell_pitch, bell_duration; + unsigned long led_mask; + int global_auto_repeat; + char auto_repeats[32]; +} XKeyboardState; +.De +.LP +.eM +For the LEDs, +the least significant bit of led_mask corresponds to LED one, +and each bit set to 1 in led_mask indicates an LED that is lit. +The global_auto_repeat member can be set to +.PN AutoRepeatModeOn +or +.PN AutoRepeatModeOff . +The auto_repeats member is a bit vector. +Each bit set to 1 indicates that auto-repeat is enabled +for the corresponding key. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +.LP +.sp +To turn on keyboard auto-repeat, use +.PN XAutoRepeatOn . +.IN "XAutoRepeatOn" "" "@DEF@" +.sM +.FD 0 +XAutoRepeatOn\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XAutoRepeatOn +function turns on auto-repeat for the keyboard on the specified display. +.LP +.sp +To turn off keyboard auto-repeat, use +.PN XAutoRepeatOff . +.IN "XAutoRepeatOff" "" "@DEF@" +.sM +.FD 0 +XAutoRepeatOff\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XAutoRepeatOff +function turns off auto-repeat for the keyboard on the specified display. +.LP +.sp +To ring the bell, use +.PN XBell . +.IN "XBell" "" "@DEF@" +.sM +.FD 0 +XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIpercent\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIpercent\fP 1i +Specifies the volume for the bell, +which can range from \-100 to 100 inclusive. +.LP +.eM +The +.PN XBell +function rings the bell on the keyboard on the specified display, if possible. +The specified volume is relative to the base volume for the keyboard. +If the value for the percent argument is not in the range \-100 to 100 +inclusive, a +.PN BadValue +error results. +The volume at which the bell rings +when the percent argument is nonnegative is: +.IP +base \- [(base * percent) / 100] + percent +.LP +The volume at which the bell rings +when the percent argument is negative is: +.IP +base + [(base * percent) / 100] +.LP +To change the base volume of the bell, use +.PN XChangeKeyboardControl . +.LP +.PN XBell +can generate a +.PN BadValue +error. +.LP +.sp +To obtain a bit vector that describes the state of the keyboard, use +.PN XQueryKeymap . +.IN "XQueryKeymap" "" "@DEF@" +.sM +.FD 0 +XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char \fIkeys_return\fP[32]\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeys_return\fP 1i +Returns an array of bytes that identifies which keys are pressed down. +Each bit represents one key of the keyboard. +.LP +.eM +The +.PN XQueryKeymap +function returns a bit vector for the logical state of the keyboard, +where each bit set to 1 indicates that the corresponding key is currently +pressed down. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +.sp +To set the mapping of the pointer buttons, use +.PN XSetPointerMapping . +.IN "XSetPointerMapping" "" "@DEF@" +.sM +.FD 0 +int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned char \fImap\fP\^[]\^; +.br + int \fInmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImap\fP 1i +Specifies the mapping list. +.IP \fInmap\fP 1i +Specifies the number of items in the mapping list. +.LP +.eM +The +.PN XSetPointerMapping +function sets the mapping of the pointer. +If it succeeds, the X server generates a +.PN MappingNotify +event, and +.PN XSetPointerMapping +returns +.PN MappingSuccess . +Element map[i] defines the logical button number for the physical button +i+1. +The length of the list must be the same as +.PN XGetPointerMapping +would return, +or a +.PN BadValue +error results. +A zero element disables a button, and elements are not restricted in +value by the number of physical buttons. +However, no two elements can have the same nonzero value, +or a +.PN BadValue +error results. +If any of the buttons to be altered are logically in the down state, +.PN XSetPointerMapping +returns +.PN MappingBusy , +and the mapping is not changed. +.LP +.PN XSetPointerMapping +can generate a +.PN BadValue +error. +.LP +.sp +To get the pointer mapping, use +.PN XGetPointerMapping . +.IN "XGetPointerMapping" "" "@DEF@" +.sM +.FD 0 +int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned char \fImap_return\fP\^[]\^; +.br + int \fInmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImap_return\fP 1i +Returns the mapping list. +.IP \fInmap\fP 1i +Specifies the number of items in the mapping list. +.LP +.eM +The +.PN XGetPointerMapping +function returns the current mapping of the pointer. +Pointer buttons are numbered starting from one. +.PN XGetPointerMapping +returns the number of physical buttons actually on the pointer. +The nominal mapping for a pointer is map[i]=i+1. +The nmap argument specifies the length of the array where the pointer +mapping is returned, and only the first nmap elements are returned +in map_return. +.LP +.sp +To control the pointer's interactive feel, use +.PN XChangePointerControl . +.IN "XChangePointerControl" "" "@DEF@" +.sM +.FD 0 +XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, +.br + \fIaccel_denominator\fP\^, \fIthreshold\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^; +.br + int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^; +.br + int \fIthreshold\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdo_accel\fP 1i +Specifies a Boolean value that controls whether the values for +the accel_numerator or accel_denominator are used. +.IP \fIdo_threshold\fP 1i +Specifies a Boolean value that controls whether the value for the +threshold is used. +.IP \fIaccel_numerator\fP 1i +Specifies the numerator for the acceleration multiplier. +.IP \fIaccel_denominator\fP 1i +Specifies the denominator for the acceleration multiplier. +.IP \fIthreshold\fP 1i +Specifies the acceleration threshold. +.LP +.eM +The +.PN XChangePointerControl +function defines how the pointing device moves. +The acceleration, expressed as a fraction, is a +multiplier for movement. +For example, +specifying 3/1 means the pointer moves three times as fast as normal. +The fraction may be rounded arbitrarily by the X server. +Acceleration +only takes effect if the pointer moves more than threshold pixels at +once and only applies to the amount beyond the value in the threshold argument. +Setting a value to \-1 restores the default. +The values of the do_accel and do_threshold arguments must be +.PN True +for the pointer values to be set, +or the parameters are unchanged. +Negative values (other than \-1) generate a +.PN BadValue +error, as does a zero value +for the accel_denominator argument. +.LP +.PN XChangePointerControl +can generate a +.PN BadValue +error. +.LP +.sp +To get the current pointer parameters, use +.PN XGetPointerControl . +.IN "XGetPointerControl" "" "@DEF@" +.sM +.FD 0 +XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, +.br + \fIthreshold_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^; +.br + int *\fIthreshold_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIaccel_numerator_return\fP 1i +Returns the numerator for the acceleration multiplier. +.IP \fIaccel_denominator_return\fP 1i +Returns the denominator for the acceleration multiplier. +.IP \fIthreshold_return\fP 1i +Returns the acceleration threshold. +.LP +.eM +The +.PN XGetPointerControl +function returns the pointer's current acceleration multiplier +and acceleration threshold. +.NH 2 +Manipulating the Keyboard Encoding +.XS +\*(SN Manipulating the Keyboard Encoding +.XE +.LP +A KeyCode represents a physical (or logical) key. +KeyCodes lie in the inclusive range [8,255]. +A KeyCode value carries no intrinsic information, +although server implementors may attempt to encode geometry +(for example, matrix) information in some fashion so that it can +be interpreted in a server-dependent fashion. +The mapping between keys and KeyCodes cannot be changed. +.LP +A KeySym is an encoding of a symbol on the cap of a key. +The set of defined KeySyms includes the ISO Latin character sets (1\-4), +Katakana, Arabic, Cyrillic, Greek, Technical, +Special, Publishing, APL, Hebrew, Thai, Korean +and a miscellany of keys found +on keyboards (Return, Help, Tab, and so on). +To the extent possible, these sets are derived from international +standards. +In areas where no standards exist, +some of these sets are derived from Digital Equipment Corporation standards. +The list of defined symbols can be found in +.hN X11/keysymdef.h . +Unfortunately, some C preprocessors have +limits on the number of defined symbols. +If you must use KeySyms not +in the Latin 1\-4, Greek, and miscellaneous classes, +you may have to define a symbol for those sets. +Most applications usually only include +.hN X11/keysym.h , +which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous. +.LP +A list of KeySyms is associated with each KeyCode. +The list is intended to convey the set of symbols on the corresponding key. +If the list (ignoring trailing +.PN NoSymbol +entries) is +a single KeySym ``\fIK\fP'', +then the list is treated as if it were the list +``\fIK\fP NoSymbol \fIK\fP NoSymbol''. +If the list (ignoring trailing +.PN NoSymbol +entries) is a pair of KeySyms ``\fIK1 K2\fP'', +then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP''. +If the list (ignoring trailing +.PN NoSymbol +entries) is a triple of KeySyms ``\fIK1 K2 K3\fP'', +then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''. +When an explicit ``void'' element is desired in the list, +the value +.PN VoidSymbol +can be used. +.LP +The first four elements of the list are split into two groups of KeySyms. +Group 1 contains the first and second KeySyms; +Group 2 contains the third and fourth KeySyms. +Within each group, +if the second element of the group is +.PN NoSymbol , +then the group should be treated as if the second element were +the same as the first element, +except when the first element is an alphabetic KeySym ``\fIK\fP'' +for which both lowercase and uppercase forms are defined. +In that case, +the group should be treated as if the first element were +the lowercase form of ``\fIK\fP'' and the second element were +the uppercase form of ``\fIK\fP''. +.LP +The standard rules for obtaining a KeySym from a +.PN KeyPress +event make use of only the Group 1 and Group 2 KeySyms; +no interpretation of other KeySyms in the list is given. +Which group to use is determined by the modifier state. +Switching between groups is controlled by the KeySym named MODE SWITCH, +by attaching that KeySym to some KeyCode and attaching +that KeyCode to any one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is called the \fIgroup modifier\fP\^. +For any KeyCode, +Group 1 is used when the group modifier is off, +and Group 2 is used when the group modifier is on. +.LP +The +.PN Lock +modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock +is attached to some KeyCode and that KeyCode is attached to the +.PN Lock +modifier. The +.PN Lock +modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock +is attached to some KeyCode and that KeyCode is attached to the +.PN Lock +modifier. If the +.PN Lock +modifier could be interpreted as both +CapsLock and ShiftLock, the CapsLock interpretation is used. +.LP +The operation of keypad keys is controlled by the KeySym named XK_Num_Lock, +by attaching that KeySym to some KeyCode and attaching that KeyCode to any +one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is called the +\fInumlock modifier\fP\^. The standard KeySyms with the prefix ``XK_KP_'' +in their +name are called keypad KeySyms; these are KeySyms with numeric value in +the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, +vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF +are also keypad KeySyms. +.LP +Within a group, the choice of KeySym is determined by applying the first +rule that is satisfied from the following list: +.IP \(bu 5 +The numlock modifier is on and the second KeySym is a keypad KeySym. In +this case, if the +.PN Shift +modifier is on, or if the +.PN Lock +modifier is on and +is interpreted as ShiftLock, then the first KeySym is used, otherwise the +second KeySym is used. +.IP \(bu 5 +The +.PN Shift +and +.PN Lock +modifiers are both off. In this case, the first +KeySym is used. +.IP \(bu 5 +The +.PN Shift +modifier is off, and the +.PN Lock +modifier is on and is +interpreted as CapsLock. In this case, the first KeySym is used, but if +that KeySym is lowercase alphabetic, then the corresponding uppercase +KeySym is used instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, and the +.PN Lock +modifier is on and is interpreted +as CapsLock. In this case, the second KeySym is used, but if that KeySym +is lowercase alphabetic, then the corresponding uppercase KeySym is used +instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, or the +.PN Lock +modifier is on and is interpreted +as ShiftLock, or both. In this case, the second KeySym is used. +.LP +No spatial geometry of the symbols on the key is defined by +their order in the KeySym list, +although a geometry might be defined on a +server-specific basis. +The X server does not use the mapping between KeyCodes and KeySyms. +Rather, it merely stores it for reading and writing by clients. +.sp +.LP +To obtain the legal KeyCodes for a display, use +.PN XDisplayKeycodes . +.IN "XDisplayKeycodes" "" "@DEF@" +.sM +.FD 0 +XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \ +\fImax_keycodes_return\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImin_keycodes_return\fP 1i +Returns the minimum number of KeyCodes. +.IP \fImax_keycodes_return\fP 1i +Returns the maximum number of KeyCodes. +.LP +.eM +The +.PN XDisplayKeycodes +function returns the min-keycodes and max-keycodes supported by the +specified display. +The minimum number of KeyCodes returned is never less than 8, +and the maximum number of KeyCodes returned is never greater than 255. +Not all KeyCodes in this range are required to have corresponding keys. +.sp +.LP +To obtain the symbols for the specified KeyCodes, use +.PN XGetKeyboardMapping . +.IN "XGetKeyboardMapping" "" "@DEF@" +.sM +.FD 0 +KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, +.br + \fIkeysyms_per_keycode_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + KeyCode \fIfirst_keycode\fP\^; +.br + int \fIkeycode_count\fP\^; +.br + int *\fIkeysyms_per_keycode_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Kc returned +.IP \fIfirst_keycode\fP 1i +Specifies the first KeyCode that is to be \*(Kc. +.IP \fIkeycode_count\fP 1i +Specifies the number of KeyCodes that are to be returned. +.IP \fIkeysyms_per_keycode_return\fP 1i +Returns the number of KeySyms per KeyCode. +.LP +.eM +The +.PN XGetKeyboardMapping +function returns the symbols for the specified number of KeyCodes +starting with first_keycode. +The value specified in first_keycode must be greater than +or equal to min_keycode as returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results. +In addition, the following expression must be less than or equal +to max_keycode as returned by +.PN XDisplayKeycodes : +.LP +.Ds +first_keycode + keycode_count \- 1 +.De +.LP +If this is not the case, a +.PN BadValue +error results. +The number of elements in the KeySyms list is: +.LP +.Ds +keycode_count * keysyms_per_keycode_return +.De +.LP +KeySym number N, counting from zero, for KeyCode K has the following index +in the list, counting from zero: +.Ds +(K \- first_code) * keysyms_per_code_return + N +.De +.LP +The X server arbitrarily chooses the keysyms_per_keycode_return value +to be large enough to report all requested symbols. +A special KeySym value of +.PN NoSymbol +is used to fill in unused elements for +individual KeyCodes. +To free the storage returned by +.PN XGetKeyboardMapping , +use +.PN XFree . +.LP +.PN XGetKeyboardMapping +can generate a +.PN BadValue +error. +.LP +.sp +To change the keyboard mapping, use +.PN XChangeKeyboardMapping . +.IN "XChangeKeyboardMapping" "" "@DEF@" +.sM +.FD 0 +XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIfirst_keycode\fP\^; +.br + int \fIkeysyms_per_keycode\fP\^; +.br + KeySym *\fIkeysyms\fP\^; +.br + int \fInum_codes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Kc changed +.IP \fIfirst_keycode\fP 1i +Specifies the first KeyCode that is to be \*(Kc. +.IP \fIkeysyms_per_keycode\fP 1i +Specifies the number of KeySyms per KeyCode. +.IP \fIkeysyms\fP 1i +Specifies an array of KeySyms. +.IP \fInum_codes\fP 1i +Specifies the number of KeyCodes that are to be changed. +.LP +.eM +The +.PN XChangeKeyboardMapping +function defines the symbols for the specified number of KeyCodes +starting with first_keycode. +The symbols for KeyCodes outside this range remain unchanged. +The number of elements in keysyms must be: +.LP +.Ds +num_codes * keysyms_per_keycode +.De +.LP +The specified first_keycode must be greater than or equal to min_keycode +returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results. +In addition, the following expression must be less than or equal to +max_keycode as returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results: +.LP +.Ds +first_keycode + num_codes \- 1 +.De +.LP +KeySym number N, counting from zero, for KeyCode K has the following index +in keysyms, counting from zero: +.LP +.Ds +(K \- first_keycode) * keysyms_per_keycode + N +.De +.LP +The specified keysyms_per_keycode can be chosen arbitrarily by the client +to be large enough to hold all desired symbols. +A special KeySym value of +.PN NoSymbol +should be used to fill in unused elements +for individual KeyCodes. +It is legal for +.PN NoSymbol +to appear in nontrailing positions +of the effective list for a KeyCode. +.PN XChangeKeyboardMapping +generates a +.PN MappingNotify +event. +.LP +There is no requirement that the X server interpret this mapping. +It is merely stored for reading and writing by clients. +.LP +.PN XChangeKeyboardMapping +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +The next six functions make use of the +.PN XModifierKeymap +data structure, which contains: +.LP +.IN "XModifierKeymap" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int max_keypermod; /* This server's max number of keys per modifier */ + KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */ +} XModifierKeymap; +.De +.LP +.eM +To create an +.PN XModifierKeymap +structure, use +.PN XNewModifiermap . +.IN "XNewModifiermap" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^) +.br + int \fImax_keys_per_mod\fP\^; +.FN +.IP \fImax_keys_per_mod\fP 1i +Specifies the number of KeyCode entries preallocated to the modifiers +in the map. +.LP +.eM +The +.PN XNewModifiermap +function returns a pointer to +.PN XModifierKeymap +structure for later use. +.LP +.sp +To add a new entry to an +.PN XModifierKeymap +structure, use +.PN XInsertModifiermapEntry . +.IN "XInsertModifiermapEntry" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \ +\fIkeycode_entry\fP, \fImodifier\fP\^) +.br + XModifierKeymap *\fImodmap\fP\^; +.br + KeyCode \fIkeycode_entry\fP\^; +.br + int \fImodifier\fP\^; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.IP \fIkeycode_entry\fP 1i +Specifies the KeyCode. +.IP \fImodifier\fP 1i +Specifies the modifier. +.LP +.eM +The +.PN XInsertModifiermapEntry +function adds the specified KeyCode to the set that controls the specified +modifier and returns the resulting +.PN XModifierKeymap +structure (expanded as needed). +.LP +.sp +To delete an entry from an +.PN XModifierKeymap +structure, use +.PN XDeleteModifiermapEntry . +.IN "XDeleteModifiermapEntry" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \ +\fIkeycode_entry\fP, \fImodifier\fP\^) +.br + XModifierKeymap *\fImodmap\fP\^; +.br + KeyCode \fIkeycode_entry\fP\^; +.br + int \fImodifier\fP\^; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.IP \fIkeycode_entry\fP 1i +Specifies the KeyCode. +.IP \fImodifier\fP 1i +Specifies the modifier. +.LP +.eM +The +.PN XDeleteModifiermapEntry +function deletes the specified KeyCode from the set that controls the +specified modifier and returns a pointer to the resulting +.PN XModifierKeymap +structure. +.LP +.sp +To destroy an +.PN XModifierKeymap +structure, use +.PN XFreeModifiermap . +.IN "XFreeModifiermap" "" "@DEF@" +.sM +.FD 0 +XFreeModifiermap(\^\fImodmap\fP\^) +.br + XModifierKeymap *\fImodmap\fP; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.LP +.eM +The +.PN XFreeModifiermap +function frees the specified +.PN XModifierKeymap +structure. +.LP +.sp +To set the KeyCodes to be used as modifiers, use +.PN XSetModifierMapping . +.IN "XSetModifierMapping" "" "@DEF@" +.sM +.FD 0 +int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XModifierKeymap *\fImodmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.LP +.eM +The +.PN XSetModifierMapping +function specifies the KeyCodes of the keys (if any) that are to be used +as modifiers. +If it succeeds, +the X server generates a +.PN MappingNotify +event, and +.PN XSetModifierMapping +returns +.PN MappingSuccess . +X permits at most 8 modifier keys. +If more than 8 are specified in the +.PN XModifierKeymap +structure, a +.PN BadLength +error results. +.LP +The modifiermap member of the +.PN XModifierKeymap +structure contains 8 sets of max_keypermod KeyCodes, +one for each modifier in the order +.PN Shift , +.PN Lock , +.PN Control , +.PN Mod1 , +.PN Mod2 , +.PN Mod3 , +.PN Mod4 , +and +.PN Mod5 . +Only nonzero KeyCodes have meaning in each set, +and zero KeyCodes are ignored. +In addition, all of the nonzero KeyCodes must be in the range specified by +min_keycode and max_keycode in the +.PN Display +structure, +or a +.PN BadValue +error results. +.LP +An X server can impose restrictions on how modifiers can be changed, +for example, +if certain keys do not generate up transitions in hardware, +if auto-repeat cannot be disabled on certain keys, +or if multiple modifier keys are not supported. +If some such restriction is violated, +the status reply is +.PN MappingFailed , +and none of the modifiers are changed. +If the new KeyCodes specified for a modifier differ from those +currently defined and any (current or new) keys for that modifier are +in the logically down state, +.PN XSetModifierMapping +returns +.PN MappingBusy , +and none of the modifiers is changed. +.LP +.PN XSetModifierMapping +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +.sp +To obtain the KeyCodes used as modifiers, use +.PN XGetModifierMapping . +.IN "XGetModifierMapping" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; + +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XGetModifierMapping +function returns a pointer to a newly created +.PN XModifierKeymap +structure that contains the keys being used as modifiers. +The structure should be freed after use by calling +.PN XFreeModifiermap . +If only zero values appear in the set for any modifier, +that modifier is disabled. +.bp |