diff options
Diffstat (limited to 'libX11/specs/libX11/CH12.xml')
| -rw-r--r-- | libX11/specs/libX11/CH12.xml | 3928 |
1 files changed, 3928 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH12.xml b/libX11/specs/libX11/CH12.xml new file mode 100644 index 000000000..210a2be9f --- /dev/null +++ b/libX11/specs/libX11/CH12.xml @@ -0,0 +1,3928 @@ +<chapter id="input_device_functions">
+<title>Input Device Functions</title>
+
+<para>
+You can use the Xlib input device functions to:
+</para>
+
+<itemizedlist>
+ <listitem><para>Grab the pointer and individual buttons on the pointer</para></listitem>
+ <listitem><para>Grab the keyboard and individual keys on the keyboard</para></listitem>
+ <listitem><para>Resume event processing</para></listitem>
+ <listitem><para>Move the pointer</para></listitem>
+ <listitem><para>Set the input focus</para></listitem>
+ <listitem><para>Manipulate the keyboard and pointer settings</para></listitem>
+ <listitem><para>Manipulate the keyboard encoding</para></listitem>
+</itemizedlist>
+
+<sect1 id="Pointer_Grabbing_">
+<title>Pointer Grabbing </title>
+<!-- .XS -->
+<!-- (SN Pointer Grabbing -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .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
+<function>XAllowEvents</function>).
+The keyboard or pointer is considered frozen during this
+interval.
+The event that triggered the grab can also be replayed.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>
+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
+<function>XGrabPointer</function>
+and
+<function>XGrabKeyboard</function>).
+<indexterm><primary>Passive grab</primary></indexterm>
+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.
+</para>
+<para>
+<!-- .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
+<indexterm significance="preferred"><primary>CurrentTime</primary></indexterm>
+<indexterm significance="preferred"><primary>Time</primary></indexterm>
+<function>CurrentTime</function>,
+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.
+</para>
+<para>
+<!-- .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
+<function>CurrentTime</function>,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass pointer event mask bits.
+The valid pointer event mask bits are:
+<function>ButtonPressMask</function>,
+<function>ButtonReleaseMask</function>,
+<function>EnterWindowMask</function>,
+<function>LeaveWindowMask</function>,
+<function>PointerMotionMask</function>,
+<function>PointerMotionHintMask</function>,
+<function>Button1MotionMask</function>,
+<function>Button2MotionMask</function>,
+<function>Button3MotionMask</function>,
+<function>Button4MotionMask</function>,
+<function>Button5MotionMask</function>,
+<function>ButtonMotionMask</function>,
+and
+<function>KeyMapStateMask</function>.
+For other functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+and
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the pointer, use
+<function>XGrabPointer</function>.
+<indexterm><primary>Grabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGrabPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Window<parameter> confine_to</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window to confine the pointer in or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed during the grab or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabPointer</function>
+function actively grabs control of the pointer and returns
+<function>GrabSuccess</function>
+if the grab was successful.
+Further pointer events are reported only to the grabbing client.
+<function>XGrabPointer</function>
+overrides any active pointer grab by this client.
+If owner_events is
+<function>False</function>,
+all generated pointer events
+are reported with respect to grab_window and are reported only if
+selected by event_mask.
+If owner_events is
+<function>True</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If the pointer_mode is
+<function>GrabModeAsync</function>,
+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
+<function>GrabModeSync</function>,
+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
+<function>XAllowEvents</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode is
+<function>GrabModeAsync</function>,
+keyboard event processing is unaffected by activation of the grab.
+If the keyboard_mode is
+<function>GrabModeSync</function>,
+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
+<function>XAllowEvents</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If a cursor is specified, it is displayed regardless of what
+window the pointer is in.
+If
+<function>None</function>
+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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer </function>
+generates
+<function>EnterNotify </function>
+and
+<function>LeaveNotify </function>
+events.
+</para>
+<para>
+<!-- .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,
+<function>XGrabPointer</function>
+fails and returns
+<function>GrabNotViewable</function>.
+If the pointer is actively grabbed by some other client,
+it fails and returns
+<function>AlreadyGrabbed</function>.
+If the pointer is frozen by an active grab of another client,
+it fails and returns
+<function>GrabFrozen</function>.
+If the specified time is earlier than the last-pointer-grab time or later
+than the current X server time, it fails and returns
+<function>GrabInvalidTime</function>.
+Otherwise, the last-pointer-grab time is set to the specified time
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer</function>
+can generate
+<function>BadCursor</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the pointer, use
+<function>XUngrabPointer</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabPointer</function>
+function releases the pointer and any queued events
+if this client has actively grabbed the pointer from
+<function>XGrabPointer</function>,
+<function>XGrabButton</function>,
+or from a normal button press.
+<function>XUngrabPointer</function>
+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
+<function>EnterNotify </function>
+and
+<function>LeaveNotify </function>
+events.
+The X server performs an
+<function>UngrabPointer </function>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change an active pointer grab, use
+<function>XChangeActivePointerGrab</function>.
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm ><primary>Changing</primary><secondary>pointer grab</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeActivePointerGrab</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeActivePointerGrab</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeActivePointerGrab</function>
+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
+<function>XGrabButton</function>.
+The interpretation of event_mask and cursor is the same as described in
+<function>XGrabPointer</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeActivePointerGrab</function>
+can generate
+<function>BadCursor </function>
+and
+<function>BadValue</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab a pointer button, use
+<function>XGrabButton</function>.
+<indexterm><primary>Grabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGrabButton</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> button</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Window<parameter> confine_to</parameter></paramdef>
+ <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Bu grabbed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be (Bu or
+<function>AnyButton</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window to confine the pointer in or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the cursor that is to be displayed or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabButton</function>
+function establishes a passive grab.
+In the future,
+the pointer is actively grabbed (as for
+<function>XGrabPointer</function>),
+the last-pointer-grab time is set to the time at which the button was pressed
+(as transmitted in the
+<function>ButtonPress</function>
+event), and the
+<function>ButtonPress</function>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The grab_window contains the pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The confine_to window (if any) is viewable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A passive grab on the same button/key combination does not exist
+on any ancestor of grab_window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for
+<function>XGrabPointer</function>.
+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).
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+This request overrides all previous grabs by the same client on the same
+button/key combinations on the same window.
+A modifiers of
+<function>AnyModifier </function>
+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
+<function>AnyButton </function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If some other client has already issued an
+<function>XGrabButton</function>
+with the same button/key combination on the same window, a
+<function>BadAccess </function>
+error results.
+When using
+<function>AnyModifier </function>
+or
+<function>AnyButton</function>,
+the request fails completely,
+and a
+<function>BadAccess</function>
+error results (no grabs are
+established) if there is a conflicting grab for any combination.
+<function>XGrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabButton</function>
+can generate
+<function>BadCursor</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a pointer button, use
+<function>XUngrabButton</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabButton</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedint<parameter> button</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Bu released -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be (Bu or
+<function>AnyButton</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabButton</function>
+function releases the passive button/key combination on the specified window if
+it was grabbed by this client.
+A modifiers of
+<function>AnyModifier </function>
+is
+equivalent to issuing
+the ungrab request for all possible modifier combinations, including
+the combination of no modifiers.
+A button of
+<function>AnyButton </function>
+is equivalent to issuing the
+request for all possible buttons.
+<function>XUngrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabButton</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Keyboard_Grabbing_">
+<title>Keyboard Grabbing </title>
+<!-- .XS -->
+<!-- (SN Keyboard Grabbing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to grab or ungrab the keyboard
+as well as allow events.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<function>ShiftMask</function>,
+<function>LockMask</function>,
+<function>ControlMask</function>,
+<function>Mod1Mask</function>,
+<function>Mod2Mask</function>,
+<function>Mod3Mask</function>,
+<function>Mod4Mask</function>,
+and
+<function>Mod5Mask</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the keyboard, use
+<function>XGrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGrabKeyboard</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the keyboard events
+are to be reported as usual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKeyboard</function>
+function actively grabs control of the keyboard and generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events.
+Further key events are reported only to the
+grabbing client.
+<function>XGrabKeyboard</function>
+overrides any active keyboard grab by this client.
+If owner_events is
+<function>False</function>,
+all generated key events are reported with
+respect to grab_window.
+If owner_events is
+<function>True </function>
+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
+<function>KeyPress </function>
+and
+<function>KeyRelease </function>
+events are always reported,
+independent of any event selection made by the client.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode argument is
+<function>GrabModeAsync</function>,
+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
+<function>GrabModeSync</function>,
+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
+<function>XAllowEvents </function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If pointer_mode is
+<function>GrabModeAsync</function>,
+pointer event processing is unaffected
+by activation of the grab.
+If pointer_mode is
+<function>GrabModeSync</function>,
+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
+<function>XAllowEvents </function>
+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.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard is actively grabbed by some other client,
+<function>XGrabKeyboard</function>
+fails and returns
+<function>AlreadyGrabbed</function>.
+If grab_window is not viewable,
+it fails and returns
+<function>GrabNotViewable</function>.
+If the keyboard is frozen by an active grab of another client,
+it fails and returns
+<function>GrabFrozen</function>.
+If the specified time is earlier than the last-keyboard-grab time
+or later than the current X server time,
+it fails and returns
+<function>GrabInvalidTime</function>.
+Otherwise, the last-keyboard-grab time is set to the specified time
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKeyboard</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the keyboard, use
+<function>XUngrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabKeyboard</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKeyboard</function>
+function
+releases the keyboard and any queued events if this client has it actively grabbed from
+either
+<function>XGrabKeyboard</function>
+or
+<function>XGrabKey</function>.
+<function>XUngrabKeyboard</function>
+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
+<function>FocusIn </function>
+and
+<function>FocusOut </function>
+events.
+The X server automatically performs an
+<function>UngrabKeyboard </function>
+request if the event window for an
+active keyboard grab becomes not viewable.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To passively grab a single key of the keyboard, use
+<function>XGrabKey</function>.
+<indexterm><primary>Key</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGrabKey</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> keycode</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+ <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+ <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode or
+<function>AnyKey</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the keyboard events
+are to be reported as usual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of pointer events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies further processing of keyboard events.
+You can pass
+<function>GrabModeSync </function>
+or
+<function>GrabModeAsync</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKey</function>
+function establishes a passive grab on the keyboard.
+In the future,
+the keyboard is actively grabbed (as for
+<function>XGrabKeyboard</function>),
+the last-keyboard-grab time is set to the time at which the key was pressed
+(as transmitted in the
+<function>KeyPress</function>
+event), and the
+<function>KeyPress</function>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A passive grab on the same key combination does not exist
+on any ancestor of grab_window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for
+<function>XGrabKeyboard</function>.
+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).
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+A modifiers argument of
+<function>AnyModifier</function>
+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
+<function>AnyKey</function>
+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
+<function>BadValue</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If some other client has issued a
+<function>XGrabKey</function>
+with the same key combination on the same window, a
+<function>BadAccess </function>
+error results.
+When using
+<function>AnyModifier</function>
+or
+<function>AnyKey</function>,
+the request fails completely,
+and a
+<function>BadAccess </function>
+error results (no grabs are established)
+if there is a conflicting grab for any combination.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKey</function>
+can generate
+<function>BadAccess</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a key, use
+<function>XUngrabKey</function>.
+<indexterm><primary>Key</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XUngrabKey</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> keycode</parameter></paramdef>
+ <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+ <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode or
+<function>AnyKey</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the set of keymasks or
+<function>AnyModifier</function>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the grab window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKey</function>
+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
+<function>AnyModifier</function>
+is equivalent to issuing
+the request for all possible modifier combinations
+(including the combination of no modifiers).
+A keycode argument of
+<function>AnyKey</function>
+is equivalent to issuing the request for all possible key codes.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabKey</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Resuming_Event_Processing">
+<title>Resuming Event Processing</title>
+<!-- .XS -->
+<!-- (SN Resuming Event Processing -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allow further events to be processed when the device has been frozen, use
+<function>XAllowEvents</function>.
+<indexterm significance="preferred"><primary>XAllowEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAllowEvents</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_mode</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mode.
+You can pass
+<function>AsyncPointer</function>,
+<function>SyncPointer</function>,
+<function>AsyncKeyboard</function>,
+<function>SyncKeyboard</function>,
+<function>ReplayPointer</function>,
+<function>ReplayKeyboard</function>,
+<function>AsyncBoth</function>,
+or
+<function>SyncBoth</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllowEvents</function>
+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:
+</para>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <tbody>
+ <row>
+ <entry><function>AsyncPointer</function></entry>
+ <entry>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,
+ <function>AsyncPointer </function>
+ thaws for both.
+ <function>AsyncPointer</function>
+ has no effect if the pointer is not frozen by the client,
+ but the pointer need not be grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>SyncPointer </function></entry>
+ <entry>If the pointer is frozen and actively grabbed by the client,
+ pointer event processing continues as usual until the next
+ <function>ButtonPress </function>
+ or
+ <function>ButtonRelease </function>
+ 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.
+ <function>SyncPointer </function>
+ has no effect if the pointer is not frozen by the client
+ or if the pointer is not grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>ReplayPointer</function></entry>
+ <entry>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
+ <function>XGrabButton </function>
+ or from a previous
+ <function>XAllowEvents </function>
+ with mode
+ <function>SyncPointer</function>
+ but not from an
+ <function>XGrabPointer</function>),
+ 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.</entry>
+ </row>
+ <row>
+ <entry><function>AsyncKeyboard </function></entry>
+ <entry>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,
+ <function>AsyncKeyboard </function>
+ thaws for both.
+ <function>AsyncKeyboard </function>
+ has no effect if the keyboard is not frozen by the client,
+ but the keyboard need not be grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>SyncKeyboard</function></entry>
+ <entry>If the keyboard is frozen and actively grabbed by the client,
+ keyboard event processing continues as usual until the next
+ <function>KeyPress </function>
+ or
+ <function>KeyRelease </function>
+ 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.
+ <function>SyncKeyboard </function>
+ has no effect if the keyboard is not frozen by the client
+ or if the keyboard is not grabbed by the client.</entry>
+ </row>
+ <row>
+ <entry><function>ReplayKeyboard</function></entry>
+ <entry>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
+ <function>XGrabKey </function>
+ or from a previous
+ <function>XAllowEvents </function>
+ with mode
+ <function>SyncKeyboard </function>
+ but not from an
+ <function>XGrabKeyboard</function>),
+ 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.</entry>
+ </row>
+ <row>
+ <entry><function>SyncBoth</function></entry>
+ <entry>If both pointer and keyboard are frozen by the client,
+ event processing for both devices continues as usual until the next
+ <function>ButtonPress</function>,
+ <function>ButtonRelease</function>,
+ <function>KeyPress</function>,
+ or
+ <function>KeyRelease </function>
+ 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).
+ <function>SyncBoth</function>
+ 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,
+ <function>SyncBoth </function>
+ thaws for both (but a subsequent freeze for
+ <function>SyncBoth </function>
+ will only freeze each device once).</entry>
+ </row>
+ <row>
+ <entry><function>AsyncBoth</function></entry>
+ <entry>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,
+ <function>AsyncBoth </function>
+ thaws for both.
+ <function>AsyncBoth </function>
+ has no effect unless both
+ pointer and keyboard are frozen by the client.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+<function>AsyncPointer</function>,
+<function>SyncPointer</function>,
+and
+<function>ReplayPointer </function>
+have no effect on the
+processing of keyboard events.
+<function>AsyncKeyboard</function>,
+<function>SyncKeyboard</function>,
+and
+<function>ReplayKeyboard </function>
+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
+<function>AllowEvents</function>
+releases both.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllowEvents</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+</sect1>
+<sect1 id="Moving_the_Pointer">
+<title>Moving the Pointer</title>
+<!-- .XS -->
+<!-- (SN Moving the Pointer -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To move the pointer to an arbitrary point in a window, use
+<function>XWarpPointer</function>.
+<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XWarpPointer</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>
+ <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+ <paramdef>unsignedintsrc_width,<parameter> src_height</parameter></paramdef>
+ <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source window or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination window or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src_height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify a rectangle in the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the x and y coordinates within the destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If dest_w is
+<function>None</function>,
+<function>XWarpPointer</function>
+moves the pointer by the offsets (dest_x, dest_y) relative to the current
+position of the pointer.
+If dest_w is a window,
+<function>XWarpPointer</function>
+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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .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
+<function>XWarpPointer</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+<function>XWarpPointer</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Controlling_Input_Focus">
+<title>Controlling Input Focus</title>
+<!-- .XS -->
+<!-- (SN Controlling Input Focus -->
+<!-- .XE -->
+<para>
+<!-- .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
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>
+for input focus policy.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the input focus, use
+<function>XSetInputFocus</function>.
+<indexterm significance="preferred"><primary>XSetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetInputFocus</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> focus</parameter></paramdef>
+ <paramdef>int<parameter> revert_to</parameter></paramdef>
+ <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>focus</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window,
+<function>PointerRoot</function>,
+or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>revert_to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies where the input focus reverts to if the window becomes not
+viewable.
+You can pass
+<function>RevertToParent</function>,
+<function>RevertToPointerRoot</function>,
+or
+<function>RevertToNone</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time.
+You can pass either a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetInputFocus</function>
+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
+(<function>CurrentTime </function>
+is replaced by the current X server time).
+<function>XSetInputFocus</function>
+causes the X server to generate
+<function>FocusIn </function>
+and
+<function>FocusOut </function>
+events.
+</para>
+<para>
+<!-- .LP -->
+Depending on the focus argument,
+the following occurs:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If focus is
+<function>None</function>,
+all keyboard events are discarded until a new focus window is set,
+and the revert_to argument is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If focus is
+<function>PointerRoot</function>,
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The specified focus window must be viewable at the time
+<function>XSetInputFocus</function>
+is called,
+or a
+<function>BadMatch</function>
+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:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If revert_to is
+<function>RevertToParent</function>,
+the focus reverts to the parent (or the closest viewable ancestor),
+and the new revert_to value is taken to be
+<function>RevertToNone</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If revert_to is
+<function>RevertToPointerRoot </function>
+or
+<function>RevertToNone</function>,
+the focus reverts to
+<function>PointerRoot</function>
+or
+<function>None</function>,
+respectively.
+When the focus reverts,
+the X server generates
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events, but the last-focus-change time is not affected.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetInputFocus</function>
+can generate
+<function>BadMatch</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current input focus, use
+<function>XGetInputFocus</function>.
+<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetInputFocus</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> *focus_return</parameter></paramdef>
+ <paramdef>int<parameter> *revert_to_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>focus_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the focus window,
+<function>PointerRoot</function>,
+or
+<function>None</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>revert_to_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current focus state
+(<function>RevertToParent</function>,
+<function>RevertToPointerRoot</function>,
+or
+<function>RevertToNone</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetInputFocus</function>
+function returns the focus window and the current focus state.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_and_Pointer_Settings">
+<title>Manipulating the Keyboard and Pointer Settings</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard and Pointer Settings -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Keyboard</primary><secondary>bell volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>keyclick volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>bit vector</secondary></indexterm>
+<indexterm><primary>Mouse</primary><secondary>programming</secondary></indexterm>
+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.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XChangeKeyboardControl</function>
+function changes control of a keyboard and operates on a
+<function>XKeyboardControl</function>
+structure:
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+/* Mask bits for ChangeKeyboardControl */
+
+
+#define KBBellPercent (1L<<0)
+#define KBBellPitch (1L<<1)
+#define KBBellDuration (1L<<2)
+#define KBLed (1L<<3)
+#define KBLedMode (1L<<4)
+#define KBKey (1L<<5)
+#define KBAutoRepeatMode (1L<<6)
+
+
+/* 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;
+
+</literallayout>
+
+<para>
+<!-- .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
+<function>BadValue</function>
+error.
+</para>
+<para>
+<!-- .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
+<function>BadValue</function>
+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
+<function>BadValue</function>
+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
+<function>BadValue</function>
+error.
+</para>
+<para>
+<!-- .LP -->
+If both the led_mode and led members are specified,
+the state of that <acronym>LED</acronym> is changed, if possible.
+The led_mode member can be set to
+<function>LedModeOn</function>
+or
+<function>LedModeOff</function>.
+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
+<function>BadMatch</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If both the auto_repeat_mode and key members are specified,
+the auto_repeat_mode of that key is changed (according to
+<function>AutoRepeatModeOn</function>,
+<function>AutoRepeatModeOff</function>,
+or
+<function>AutoRepeatModeDefault</function>),
+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
+<function>BadMatch</function>
+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
+<function>AutoRepeatModeOn</function>,
+keys should obey their individual auto-repeat modes.
+When global mode is
+<function>AutoRepeatModeOff</function>,
+no keys should auto-repeat.
+An auto-repeating key generates alternating
+<function>KeyPress</function>
+and
+<function>KeyRelease</function>
+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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeKeyboardControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedlong<parameter> value_mask</parameter></paramdef>
+ <paramdef>XKeyboardControl<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which controls to change.
+This mask is the bitwise inclusive OR of the valid control mask bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies one value for each bit set to 1 in the mask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardControl</function>
+function controls the keyboard characteristics defined by the
+<function>XKeyboardControl</function>
+structure.
+The value_mask argument specifies which values are to be changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardControl</function>
+can generate
+<function>BadMatch</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current control values for the keyboard, use
+<function>XGetKeyboardControl</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetKeyboardControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XKeyboardState<parameter> *values_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current keyboard controls in the specified
+<function>XKeyboardState </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardControl</function>
+function returns the current control values for the keyboard to the
+<function>XKeyboardState</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XGetKeyboardControl</primary></indexterm>
+<indexterm significance="preferred"><primary>XKeyboardState</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .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;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For the LEDs,
+the least significant bit of led_mask corresponds to <acronym>LED</acronym> one,
+and each bit set to 1 in led_mask indicates an <acronym>LED</acronym> that is lit.
+The global_auto_repeat member can be set to
+<function>AutoRepeatModeOn</function>
+or
+<function>AutoRepeatModeOff</function>.
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn on keyboard auto-repeat, use
+<function>XAutoRepeatOn</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOn</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAutoRepeatOn</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOn</function>
+function turns on auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn off keyboard auto-repeat, use
+<function>XAutoRepeatOff</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOff</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XAutoRepeatOff</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOff</function>
+function turns off auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ring the bell, use
+<function>XBell</function>.
+<indexterm significance="preferred"><primary>XBell</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XBell</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> percent</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>percent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the volume for the bell,
+which can range from -100 to 100 inclusive.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XBell</function>
+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
+<function>BadValue</function>
+error results.
+The volume at which the bell rings
+when the percent argument is nonnegative is:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+base - [(base * percent) / 100] + percent
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The volume at which the bell rings
+when the percent argument is negative is:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+base + [(base * percent) / 100]
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To change the base volume of the bell, use
+<function>XChangeKeyboardControl</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XBell</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a bit vector that describes the state of the keyboard, use
+<function>XQueryKeymap</function>.
+<indexterm significance="preferred"><primary>XQueryKeymap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XQueryKeymap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> keys_return[32]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keys_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns an array of bytes that identifies which keys are pressed down.
+Each bit represents one key of the keyboard.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryKeymap</function>
+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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the mapping of the pointer buttons, use
+<function>XSetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XSetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XSetPointerMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> map[]</parameter></paramdef>
+ <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetPointerMapping</function>
+function sets the mapping of the pointer.
+If it succeeds, the X server generates a
+<function>MappingNotify</function>
+event, and
+<function>XSetPointerMapping</function>
+returns
+<function>MappingSuccess</function>.
+Element map[i] defines the logical button number for the physical button
+i+1.
+The length of the list must be the same as
+<function>XGetPointerMapping</function>
+would return,
+or a
+<function>BadValue</function>
+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
+<function>BadValue</function>
+error results.
+If any of the buttons to be altered are logically in the down state,
+<function>XSetPointerMapping</function>
+returns
+<function>MappingBusy</function>,
+and the mapping is not changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetPointerMapping</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the pointer mapping, use
+<function>XGetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XGetPointerMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef>
+ <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the mapping list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerMapping</function>
+function returns the current mapping of the pointer.
+Pointer buttons are numbered starting from one.
+<function>XGetPointerMapping</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To control the pointer's interactive feel, use
+<function>XChangePointerControl</function>.
+<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangePointerControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Booldo_accel,<parameter> do_threshold</parameter></paramdef>
+ <paramdef>intaccel_numerator,<parameter> accel_denominator</parameter></paramdef>
+ <paramdef>int<parameter> threshold</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_accel</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that controls whether the values for
+the accel_numerator or accel_denominator are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_threshold</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that controls whether the value for the
+threshold is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_numerator</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the numerator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_denominator</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the denominator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>threshold</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the acceleration threshold.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangePointerControl</function>
+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
+<function>True </function>
+for the pointer values to be set,
+or the parameters are unchanged.
+Negative values (other than -1) generate a
+<function>BadValue</function>
+error, as does a zero value
+for the accel_denominator argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangePointerControl</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current pointer parameters, use
+<function>XGetPointerControl</function>.
+<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetPointerControl</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int*accel_numerator_return,<parameter> *accel_denominator_return</parameter></paramdef>
+ <paramdef>int<parameter> *threshold_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_numerator_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the numerator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>accel_denominator_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the denominator for the acceleration multiplier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>threshold_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the acceleration threshold.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerControl</function>
+function returns the pointer's current acceleration multiplier
+and acceleration threshold.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_Encoding">
+<title>Manipulating the Keyboard Encoding</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard Encoding -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .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
+<function>NoSymbol</function>
+entries) is
+a single KeySym ``<emphasis remap='I'>K</emphasis>'',
+then the list is treated as if it were the list
+``<emphasis remap='I'>K</emphasis> NoSymbol <emphasis remap='I'>K</emphasis> NoSymbol''.
+If the list (ignoring trailing
+<function>NoSymbol</function>
+entries) is a pair of KeySyms ``<emphasis remap='I'>K1 K2</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K1 K2</emphasis>''.
+If the list (ignoring trailing
+<function>NoSymbol</function>
+entries) is a triple of KeySyms ``<emphasis remap='I'>K1 K2 K3</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K3</emphasis> NoSymbol''.
+When an explicit ``void'' element is desired in the list,
+the value
+<function>VoidSymbol</function>
+can be used.
+</para>
+<para>
+<!-- .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
+<function>NoSymbol</function>,
+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 ``<emphasis remap='I'>K</emphasis>''
+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 ``<emphasis remap='I'>K</emphasis>'' and the second element were
+the uppercase form of ``<emphasis remap='I'>K</emphasis>''.
+</para>
+<para>
+<!-- .LP -->
+The standard rules for obtaining a KeySym from a
+<function>KeyPress</function>
+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
+<function>Mod1</function>
+through
+<function>Mod5</function>.
+This modifier is called the <emphasis remap='I'>group modifier</emphasis>.
+For any KeyCode,
+Group 1 is used when the group modifier is off,
+and Group 2 is used when the group modifier is on.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>Lock</function>
+modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<function>Lock</function>
+modifier. The
+<function>Lock</function>
+modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<function>Lock </function>
+modifier. If the
+<function>Lock </function>
+modifier could be interpreted as both
+CapsLock and ShiftLock, the CapsLock interpretation is used.
+</para>
+<para>
+<!-- .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
+<function>Mod1 </function>
+through
+<function>Mod5</function>.
+This modifier is called the
+<emphasis remap='I'>numlock modifier</emphasis>. 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.
+</para>
+<para>
+<!-- .LP -->
+Within a group, the choice of KeySym is determined by applying the first
+rule that is satisfied from the following list:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The numlock modifier is on and the second KeySym is a keypad KeySym. In
+this case, if the
+<function>Shift </function>
+modifier is on, or if the
+<function>Lock </function>
+modifier is on and
+is interpreted as ShiftLock, then the first KeySym is used, otherwise the
+second KeySym is used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+and
+<function>Lock </function>
+modifiers are both off. In this case, the first
+KeySym is used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is off, and the
+<function>Lock </function>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is on, and the
+<function>Lock </function>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The
+<function>Shift </function>
+modifier is on, or the
+<function>Lock </function>
+modifier is on and is interpreted
+as ShiftLock, or both. In this case, the second KeySym is used.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .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 -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the legal KeyCodes for a display, use
+<function>XDisplayKeycodes</function>.
+<indexterm significance="preferred"><primary>XDisplayKeycodes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XDisplayKeycodes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int*min_keycodes_return,<parameter> *max_keycodes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum number of KeyCodes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum number of KeyCodes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayKeycodes</function>
+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 -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the symbols for the specified KeyCodes, use
+<function>XGetKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>KeySym<function> *XGetKeyboardMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>KeyCode<parameter> first_keycode</parameter></paramdef>
+ <paramdef>int<parameter> keycode_count</parameter></paramdef>
+ <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Kc returned -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be (Kc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCodes that are to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeySyms per KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardMapping</function>
+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
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results.
+In addition, the following expression must be less than or equal
+to max_keycode as returned by
+<function>XDisplayKeycodes :</function>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + keycode_count - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If this is not the case, a
+<function>BadValue </function>
+error results.
+The number of elements in the KeySyms list is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+keycode_count * keysyms_per_keycode_return
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in the list, counting from zero:
+<literallayout class="monospaced">
+(K - first_code) * keysyms_per_code_return + N
+</literallayout>
+</para>
+<para>
+<!-- .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
+<function>NoSymbol </function>
+is used to fill in unused elements for
+individual KeyCodes.
+To free the storage returned by
+<function>XGetKeyboardMapping</function>,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetKeyboardMapping</function>
+can generate a
+<function>BadValue </function>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the keyboard mapping, use
+<function>XChangeKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XChangeKeyboardMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> first_keycode</parameter></paramdef>
+ <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef>
+ <paramdef>KeySym<parameter> *keysyms</parameter></paramdef>
+ <paramdef>int<parameter> num_codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Kc changed -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be (Kc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeySyms per KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of KeySyms.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_codes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCodes that are to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardMapping</function>
+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:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+num_codes * keysyms_per_keycode
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The specified first_keycode must be greater than or equal to min_keycode
+returned by
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results.
+In addition, the following expression must be less than or equal to
+max_keycode as returned by
+<function>XDisplayKeycodes</function>,
+or a
+<function>BadValue </function>
+error results:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + num_codes - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in keysyms, counting from zero:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(K - first_keycode) * keysyms_per_keycode + N
+</literallayout>
+</para>
+<para>
+<!-- .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
+<function>NoSymbol </function>
+should be used to fill in unused elements
+for individual KeyCodes.
+It is legal for
+<function>NoSymbol </function>
+to appear in nontrailing positions
+of the effective list for a KeyCode.
+<function>XChangeKeyboardMapping</function>
+generates a
+<function>MappingNotify </function>
+event.
+</para>
+<para>
+<!-- .LP -->
+There is no requirement that the X server interpret this mapping.
+It is merely stored for reading and writing by clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardMapping</function>
+can generate
+<function>BadAlloc </function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The next six functions make use of the
+<function>XModifierKeymap</function>
+data structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XModifierKeymap</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .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;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To create an
+<function>XModifierKeymap</function>
+structure, use
+<function>XNewModifiermap</function>.
+<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XNewModifiermap</function></funcdef>
+ <paramdef>int<parameter> max_keys_per_mod</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_keys_per_mod</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of KeyCode entries preallocated to the modifiers
+in the map.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNewModifiermap</function>
+function returns a pointer to
+<function>XModifierKeymap</function>
+structure for later use.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a new entry to an
+<function>XModifierKeymap</function>
+structure, use
+<function>XInsertModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XInsertModifiermapEntry</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+ <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+ <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_entry</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifier.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInsertModifiermapEntry</function>
+function adds the specified KeyCode to the set that controls the specified
+modifier and returns the resulting
+<function>XModifierKeymap</function>
+structure (expanded as needed).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry from an
+<function>XModifierKeymap</function>
+structure, use
+<function>XDeleteModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XDeleteModifiermapEntry</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+ <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+ <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode_entry</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifier.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteModifiermapEntry</function>
+function deletes the specified KeyCode from the set that controls the
+specified modifier and returns a pointer to the resulting
+<function>XModifierKeymap</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an
+<function>XModifierKeymap</function>
+structure, use
+<function>XFreeModifiermap</function>.
+<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFreeModifiermap</function></funcdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeModifiermap</function>
+function frees the specified
+<function>XModifierKeymap</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the KeyCodes to be used as modifiers, use
+<function>XSetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XSetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XSetModifierMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modmap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XModifierKeymap</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetModifierMapping</function>
+function specifies the KeyCodes of the keys (if any) that are to be used
+as modifiers.
+If it succeeds,
+the X server generates a
+<function>MappingNotify</function>
+event, and
+<function>XSetModifierMapping</function>
+returns
+<function>MappingSuccess</function>.
+X permits at most 8 modifier keys.
+If more than 8 are specified in the
+<function>XModifierKeymap</function>
+structure, a
+<function>BadLength</function>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The modifiermap member of the
+<function>XModifierKeymap</function>
+structure contains 8 sets of max_keypermod KeyCodes,
+one for each modifier in the order
+<function>Shift</function>,
+<function>Lock</function>,
+<function>Control</function>,
+<function>Mod1</function>,
+<function>Mod2</function>,
+<function>Mod3</function>,
+<function>Mod4</function>,
+and
+<function>Mod5</function>.
+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
+<function>Display </function>
+structure,
+or a
+<function>BadValue </function>
+error results.
+</para>
+<para>
+<!-- .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
+<function>MappingFailed</function>,
+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,
+<function>XSetModifierMapping</function>
+returns
+<function>MappingBusy</function>,
+and none of the modifiers is changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetModifierMapping</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadValue </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the KeyCodes used as modifiers, use
+<function>XGetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XGetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XModifierKeymap<function> *XGetModifierMapping</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetModifierMapping</function>
+function returns a pointer to a newly created
+<function>XModifierKeymap</function>
+structure that contains the keys being used as modifiers.
+The structure should be freed after use by calling
+<function>XFreeModifiermap</function>.
+If only zero values appear in the set for any modifier,
+that modifier is disabled.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
|