diff options
Diffstat (limited to 'libX11/specs/libX11/CH12.xml')
| -rw-r--r-- | libX11/specs/libX11/CH12.xml | 7874 |
1 files changed, 3937 insertions, 3937 deletions
diff --git a/libX11/specs/libX11/CH12.xml b/libX11/specs/libX11/CH12.xml index bfde8d927..2a688bdc5 100644 --- a/libX11/specs/libX11/CH12.xml +++ b/libX11/specs/libX11/CH12.xml @@ -1,3937 +1,3937 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<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>
-<symbol>CurrentTime</symbol>,
-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
-<symbol>CurrentTime</symbol>,
-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:
-<symbol>ButtonPressMask</symbol>,
-<symbol>ButtonReleaseMask</symbol>,
-<symbol>EnterWindowMask</symbol>,
-<symbol>LeaveWindowMask</symbol>,
-<symbol>PointerMotionMask</symbol>,
-<symbol>PointerMotionHintMask</symbol>,
-<symbol>Button1MotionMask</symbol>,
-<symbol>Button2MotionMask</symbol>,
-<symbol>Button3MotionMask</symbol>,
-<symbol>Button4MotionMask</symbol>,
-<symbol>Button5MotionMask</symbol>,
-<symbol>ButtonMotionMask</symbol>,
-and
-<symbol>KeymapStateMask</symbol>.
-For other functions in this section,
-you pass keymask bits.
-The valid keymask bits are:
-<symbol>ShiftMask</symbol>,
-<symbol>LockMask</symbol>,
-<symbol>ControlMask</symbol>,
-<symbol>Mod1Mask</symbol>,
-<symbol>Mod2Mask</symbol>,
-<symbol>Mod3Mask</symbol>,
-<symbol>Mod4Mask</symbol>,
-and
-<symbol>Mod5Mask</symbol>.
-</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
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>keyboard_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies further processing of keyboard events.
-You can pass
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>confine_to</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window to confine the pointer in or
-<symbol>None</symbol>.
- </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
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>time</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the time.
-You can pass either a timestamp or
-<symbol>CurrentTime</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGrabPointer</function>
-function actively grabs control of the pointer and returns
-<symbol>GrabSuccess</symbol>
-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
-<symbol>False</symbol>,
-all generated pointer events
-are reported with respect to grab_window and are reported only if
-selected by event_mask.
-If owner_events is
-<symbol>True</symbol>
-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
-<symbol>GrabModeAsync</symbol>,
-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
-<symbol>GrabModeSync</symbol>,
-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
-<symbol>GrabModeAsync</symbol>,
-keyboard event processing is unaffected by activation of the grab.
-If the keyboard_mode is
-<symbol>GrabModeSync</symbol>,
-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
-<symbol>None</symbol>
-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
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-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
-<symbol>GrabNotViewable</symbol>.
-If the pointer is actively grabbed by some other client,
-it fails and returns
-<symbol>AlreadyGrabbed</symbol>.
-If the pointer is frozen by an active grab of another client,
-it fails and returns
-<symbol>GrabFrozen</symbol>.
-If the specified time is earlier than the last-pointer-grab time or later
-than the current X server time, it fails and returns
-<symbol>GrabInvalidTime</symbol>.
-Otherwise, the last-pointer-grab time is set to the specified time
-(<symbol>CurrentTime</symbol>
-is replaced by the current X server time).
-</para>
-<para>
-<!-- .LP -->
-<function>XGrabPointer</function>
-can generate
-<errorname>BadCursor</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-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
-<symbol>CurrentTime</symbol>.
- </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
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events.
-The X server performs an
-<systemitem>UngrabPointer</systemitem>
-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
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>time</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the time.
-You can pass either a timestamp or
-<symbol>CurrentTime</symbol>.
- </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
-<errorname>BadCursor</errorname>
-and
-<errorname>BadValue</errorname>
-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
-<symbol>AnyButton</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>modifiers</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the set of keymasks or
-<symbol>AnyModifier</symbol>.
-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
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>keyboard_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies further processing of keyboard events.
-You can pass
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>confine_to</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window to confine the pointer in or
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>cursor</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the cursor that is to be displayed or
-<symbol>None</symbol>.
- </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
-<symbol>ButtonPress</symbol>
-event), and the
-<symbol>ButtonPress</symbol>
-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
-<symbol>AnyModifier</symbol>
-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
-<symbol>AnyButton</symbol>
-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
-<errorname>BadAccess</errorname>
-error results.
-When using
-<symbol>AnyModifier</symbol>
-or
-<symbol>AnyButton</symbol>,
-the request fails completely,
-and a
-<errorname>BadAccess</errorname>
-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
-<errorname>BadCursor</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-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
-<symbol>AnyButton</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>modifiers</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the set of keymasks or
-<symbol>AnyModifier</symbol>.
-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
-<symbol>AnyModifier</symbol>
-is
-equivalent to issuing
-the ungrab request for all possible modifier combinations, including
-the combination of no modifiers.
-A button of
-<symbol>AnyButton</symbol>
-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
-<errorname>BadValue</errorname>
-and
-<errorname>BadWindow</errorname>
-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:
-<symbol>ShiftMask</symbol>,
-<symbol>LockMask</symbol>,
-<symbol>ControlMask</symbol>,
-<symbol>Mod1Mask</symbol>,
-<symbol>Mod2Mask</symbol>,
-<symbol>Mod3Mask</symbol>,
-<symbol>Mod4Mask</symbol>,
-and
-<symbol>Mod5Mask</symbol>.
-</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
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>keyboard_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies further processing of keyboard events.
-You can pass
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>time</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the time.
-You can pass either a timestamp or
-<symbol>CurrentTime</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGrabKeyboard</function>
-function actively grabs control of the keyboard and generates
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-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
-<symbol>False</symbol>,
-all generated key events are reported with
-respect to grab_window.
-If owner_events is
-<symbol>True</symbol>
-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
-<symbol>KeyPress</symbol>
-and
-<symbol>KeyRelease</symbol>
-events are always reported,
-independent of any event selection made by the client.
-</para>
-<para>
-<!-- .LP -->
-If the keyboard_mode argument is
-<symbol>GrabModeAsync</symbol>,
-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
-<symbol>GrabModeSync</symbol>,
-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
-<symbol>GrabModeAsync</symbol>,
-pointer event processing is unaffected
-by activation of the grab.
-If pointer_mode is
-<symbol>GrabModeSync</symbol>,
-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
-<symbol>AlreadyGrabbed</symbol>.
-If grab_window is not viewable,
-it fails and returns
-<symbol>GrabNotViewable</symbol>.
-If the keyboard is frozen by an active grab of another client,
-it fails and returns
-<symbol>GrabFrozen</symbol>.
-If the specified time is earlier than the last-keyboard-grab time
-or later than the current X server time,
-it fails and returns
-<symbol>GrabInvalidTime</symbol>.
-Otherwise, the last-keyboard-grab time is set to the specified time
-(<symbol>CurrentTime</symbol>
-is replaced by the current X server time).
-</para>
-<para>
-<!-- .LP -->
-<function>XGrabKeyboard</function>
-can generate
-<errorname>BadValue</errorname>
-and
-<errorname>BadWindow</errorname>
-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
-<symbol>CurrentTime</symbol>.
- </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
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-events.
-The X server automatically performs an
-<systemitem>UngrabKeyboard</systemitem>
-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
-<symbol>AnyKey</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>modifiers</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the set of keymasks or
-<symbol>AnyModifier</symbol>.
-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
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>keyboard_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies further processing of keyboard events.
-You can pass
-<symbol>GrabModeSync</symbol>
-or
-<symbol>GrabModeAsync</symbol>.
- </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
-<symbol>KeyPress</symbol>
-event), and the
-<symbol>KeyPress</symbol>
-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
-<symbol>AnyModifier</symbol>
-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
-<symbol>AnyKey</symbol>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadAccess</errorname>
-error results.
-When using
-<symbol>AnyModifier</symbol>
-or
-<symbol>AnyKey</symbol>,
-the request fails completely,
-and a
-<errorname>BadAccess</errorname>
-error results (no grabs are established)
-if there is a conflicting grab for any combination.
-</para>
-<para>
-<!-- .LP -->
-<function>XGrabKey</function>
-can generate
-<errorname>BadAccess</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-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
-<symbol>AnyKey</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>modifiers</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the set of keymasks or
-<symbol>AnyModifier</symbol>.
-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
-<symbol>AnyModifier</symbol>
-is equivalent to issuing
-the request for all possible modifier combinations
-(including the combination of no modifiers).
-A keycode argument of
-<symbol>AnyKey</symbol>
-is equivalent to issuing the request for all possible key codes.
-</para>
-<para>
-<!-- .LP -->
-<function>XUngrabKey</function>
-can generate
-<errorname>BadValue</errorname>
-and
-<errorname>BadWindow</errorname>
-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
-<symbol>AsyncPointer</symbol>,
-<symbol>SyncPointer</symbol>,
-<symbol>AsyncKeyboard</symbol>,
-<symbol>SyncKeyboard</symbol>,
-<symbol>ReplayPointer</symbol>,
-<symbol>ReplayKeyboard</symbol>,
-<symbol>AsyncBoth</symbol>,
-or
-<symbol>SyncBoth</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>time</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the time.
-You can pass either a timestamp or
-<symbol>CurrentTime</symbol>.
- </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><symbol>AsyncPointer</symbol></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,
- <symbol>AsyncPointer</symbol>
- thaws for both.
- <symbol>AsyncPointer</symbol>
- 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><symbol>SyncPointer</symbol></entry>
- <entry>If the pointer is frozen and actively grabbed by the client,
- pointer event processing continues as usual until the next
- <symbol>ButtonPress</symbol>
- or
- <symbol>ButtonRelease</symbol>
- 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.
- <symbol>SyncPointer</symbol>
- 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><symbol>ReplayPointer</symbol></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
- <symbol>SyncPointer</symbol>
- 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><symbol>AsyncKeyboard</symbol></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,
- <symbol>AsyncKeyboard</symbol>
- thaws for both.
- <symbol>AsyncKeyboard</symbol>
- 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><symbol>SyncKeyboard</symbol></entry>
- <entry>If the keyboard is frozen and actively grabbed by the client,
- keyboard event processing continues as usual until the next
- <symbol>KeyPress</symbol>
- or
- <symbol>KeyRelease</symbol>
- 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.
- <symbol>SyncKeyboard</symbol>
- 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><symbol>ReplayKeyboard</symbol></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
- <symbol>SyncKeyboard</symbol>
- 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><symbol>SyncBoth</symbol></entry>
- <entry>If both pointer and keyboard are frozen by the client,
- event processing for both devices continues as usual until the next
- <symbol>ButtonPress</symbol>,
- <symbol>ButtonRelease</symbol>,
- <symbol>KeyPress</symbol>,
- or
- <symbol>KeyRelease</symbol>
- 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).
- <symbol>SyncBoth</symbol>
- 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,
- <symbol>SyncBoth</symbol>
- thaws for both (but a subsequent freeze for
- <symbol>SyncBoth</symbol>
- will only freeze each device once).</entry>
- </row>
- <row>
- <entry><symbol>AsyncBoth</symbol></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,
- <symbol>AsyncBoth</symbol>
- thaws for both.
- <symbol>AsyncBoth</symbol>
- has no effect unless both
- pointer and keyboard are frozen by the client.</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-<symbol>AsyncPointer</symbol>,
-<symbol>SyncPointer</symbol>,
-and
-<symbol>ReplayPointer</symbol>
-have no effect on the
-processing of keyboard events.
-<symbol>AsyncKeyboard</symbol>,
-<symbol>SyncKeyboard</symbol>,
-and
-<symbol>ReplayKeyboard</symbol>
-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>XAllowEvents</function>
-releases both.
-</para>
-<para>
-<!-- .LP -->
-<function>XAllowEvents</function>
-can generate a
-<errorname>BadValue</errorname>
-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
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the destination window or
-<symbol>None</symbol>.
- </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
-<symbol>None</symbol>,
-<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
-<errorname>BadWindow</errorname>
-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,
-<symbol>PointerRoot</symbol>,
-or
-<symbol>None</symbol>.
- </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
-<symbol>RevertToParent</symbol>,
-<symbol>RevertToPointerRoot</symbol>,
-or
-<symbol>RevertToNone</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>time</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the time.
-You can pass either a timestamp or
-<symbol>CurrentTime</symbol>.
- </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
-(<symbol>CurrentTime</symbol>
-is replaced by the current X server time).
-<function>XSetInputFocus</function>
-causes the X server to generate
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-events.
-</para>
-<para>
-<!-- .LP -->
-Depending on the focus argument,
-the following occurs:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-If focus is
-<symbol>None</symbol>,
-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
-<symbol>PointerRoot</symbol>,
-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
-<errorname>BadMatch</errorname>
-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
-<symbol>RevertToParent</symbol>,
-the focus reverts to the parent (or the closest viewable ancestor),
-and the new revert_to value is taken to be
-<symbol>RevertToNone</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If revert_to is
-<symbol>RevertToPointerRoot</symbol>
-or
-<symbol>RevertToNone</symbol>,
-the focus reverts to
-<symbol>PointerRoot</symbol>
-or
-<symbol>None</symbol>,
-respectively.
-When the focus reverts,
-the X server generates
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-events, but the last-focus-change time is not affected.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-<function>XSetInputFocus</function>
-can generate
-<errorname>BadMatch</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-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,
-<symbol>PointerRoot</symbol>,
-or
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>revert_to_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the current focus state
-(<symbol>RevertToParent</symbol>,
-<symbol>RevertToPointerRoot</symbol>,
-or
-<symbol>RevertToNone</symbol>).
- </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
-<structname>XKeyboardControl</structname>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-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
-<symbol>LedModeOn</symbol>
-or
-<symbol>LedModeOff</symbol>.
-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
-<errorname>BadMatch</errorname>
-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
-<symbol>AutoRepeatModeOn</symbol>,
-<symbol>AutoRepeatModeOff</symbol>,
-or
-<symbol>AutoRepeatModeDefault</symbol>),
-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
-<errorname>BadMatch</errorname>
-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
-<symbol>AutoRepeatModeOn</symbol>,
-keys should obey their individual auto-repeat modes.
-When global mode is
-<symbol>AutoRepeatModeOff</symbol>,
-no keys should auto-repeat.
-An auto-repeating key generates alternating
-<symbol>KeyPress</symbol>
-and
-<symbol>KeyRelease</symbol>
-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
-<structname>XKeyboardControl</structname>
-structure.
-The value_mask argument specifies which values are to be changed.
-</para>
-<para>
-<!-- .LP -->
-<function>XChangeKeyboardControl</function>
-can generate
-<errorname>BadMatch</errorname>
-and
-<errorname>BadValue</errorname>
-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
-<structname>XKeyboardState</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetKeyboardControl</function>
-function returns the current control values for the keyboard to the
-<structname>XKeyboardState</structname>
-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
-<symbol>AutoRepeatModeOn</symbol>
-or
-<symbol>AutoRepeatModeOff</symbol>.
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-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
-<symbol>MappingNotify</symbol>
-event, and
-<function>XSetPointerMapping</function>
-returns
-<symbol>MappingSuccess</symbol>.
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-error results.
-If any of the buttons to be altered are logically in the down state,
-<function>XSetPointerMapping</function>
-returns
-<symbol>MappingBusy</symbol>,
-and the mapping is not changed.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetPointerMapping</function>
-can generate a
-<errorname>BadValue</errorname>
-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
-<symbol>True</symbol>
-for the pointer values to be set,
-or the parameters are unchanged.
-Negative values (other than -1) generate a
-<errorname>BadValue</errorname>
-error, as does a zero value
-for the accel_denominator argument.
-</para>
-<para>
-<!-- .LP -->
-<function>XChangePointerControl</function>
-can generate a
-<errorname>BadValue</errorname>
-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
-<filename class="headerfile"><X11/keysymdef.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm>
-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
-<filename class="headerfile"><X11/keysym.h></filename>,
-<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysym.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysym.h></filename></secondary></indexterm>
-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
-<symbol>NoSymbol</symbol>
-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
-<symbol>NoSymbol</symbol>
-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
-<symbol>NoSymbol</symbol>
-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
-<symbol>VoidSymbol</symbol>
-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
-<symbol>NoSymbol</symbol>,
-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
-<symbol>KeyPress</symbol>
-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
-<symbol>Mod1</symbol>
-through
-<symbol>Mod5</symbol>.
-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
-<symbol>Lock</symbol>
-modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
-is attached to some KeyCode and that KeyCode is attached to the
-<symbol>Lock</symbol>
-modifier. The
-<symbol>Lock</symbol>
-modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
-is attached to some KeyCode and that KeyCode is attached to the
-<symbol>Lock</symbol>
-modifier. If the
-<symbol>Lock</symbol>
-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
-<symbol>Mod1</symbol>
-through
-<symbol>Mod5</symbol>.
-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
-<symbol>Shift</symbol>
-modifier is on, or if the
-<symbol>Lock</symbol>
-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
-<symbol>Shift</symbol>
-and
-<symbol>Lock</symbol>
-modifiers are both off. In this case, the first
-KeySym is used.
- </para>
- </listitem>
- <listitem>
- <para>
-The
-<symbol>Shift</symbol>
-modifier is off, and the
-<symbol>Lock</symbol>
-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
-<symbol>Shift</symbol>
-modifier is on, and the
-<symbol>Lock</symbol>
-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
-<symbol>Shift</symbol>
-modifier is on, or the
-<symbol>Lock</symbol>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-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
-<symbol>NoSymbol</symbol>
-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
-<errorname>BadValue</errorname>
-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
-<errorname>BadValue</errorname>
-error results.
-In addition, the following expression must be less than or equal to
-max_keycode as returned by
-<function>XDisplayKeycodes</function>,
-or a
-<errorname>BadValue</errorname>
-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
-<symbol>NoSymbol</symbol>
-should be used to fill in unused elements
-for individual KeyCodes.
-It is legal for
-<symbol>NoSymbol</symbol>
-to appear in nontrailing positions
-of the effective list for a KeyCode.
-<function>XChangeKeyboardMapping</function>
-generates a
-<symbol>MappingNotify</symbol>
-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
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-The next six functions make use of the
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-structure for later use.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a new entry to an
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-structure (expanded as needed).
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To delete an entry from an
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-structure.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To destroy an
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeModifiermap</function>
-function frees the specified
-<structname>XModifierKeymap</structname>
-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
-<structname>XModifierKeymap</structname>
-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
-<symbol>MappingNotify</symbol>
-event, and
-<function>XSetModifierMapping</function>
-returns
-<symbol>MappingSuccess</symbol>.
-X permits at most 8 modifier keys.
-If more than 8 are specified in the
-<structname>XModifierKeymap</structname>
-structure, a
-<errorname>BadLength</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-The modifiermap member of the
-<structname>XModifierKeymap</structname>
-structure contains 8 sets of max_keypermod KeyCodes,
-one for each modifier in the order
-<symbol>Shift</symbol>,
-<symbol>Lock</symbol>,
-<symbol>Control</symbol>,
-<symbol>Mod1</symbol>,
-<symbol>Mod2</symbol>,
-<symbol>Mod3</symbol>,
-<symbol>Mod4</symbol>,
-and
-<symbol>Mod5</symbol>.
-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
-<type>Display</type>
-structure,
-or a
-<errorname>BadValue</errorname>
-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
-<symbol>MappingFailed</symbol>,
-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
-<symbol>MappingBusy</symbol>,
-and none of the modifiers is changed.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetModifierMapping</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadValue</errorname>
-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
-<structname>XModifierKeymap</structname>
-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>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<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> +<symbol>CurrentTime</symbol>, +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 +<symbol>CurrentTime</symbol>, +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: +<symbol>ButtonPressMask</symbol>, +<symbol>ButtonReleaseMask</symbol>, +<symbol>EnterWindowMask</symbol>, +<symbol>LeaveWindowMask</symbol>, +<symbol>PointerMotionMask</symbol>, +<symbol>PointerMotionHintMask</symbol>, +<symbol>Button1MotionMask</symbol>, +<symbol>Button2MotionMask</symbol>, +<symbol>Button3MotionMask</symbol>, +<symbol>Button4MotionMask</symbol>, +<symbol>Button5MotionMask</symbol>, +<symbol>ButtonMotionMask</symbol>, +and +<symbol>KeymapStateMask</symbol>. +For other functions in this section, +you pass keymask bits. +The valid keymask bits are: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. +</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 id='xgrabpointer'> +<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 +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keyboard_mode</emphasis> + </term> + <listitem> + <para> +Specifies further processing of keyboard events. +You can pass +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>confine_to</emphasis> + </term> + <listitem> + <para> +Specifies the window to confine the pointer in or +<symbol>None</symbol>. + </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 +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. +You can pass either a timestamp or +<symbol>CurrentTime</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGrabPointer</function> +function actively grabs control of the pointer and returns +<symbol>GrabSuccess</symbol> +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 +<symbol>False</symbol>, +all generated pointer events +are reported with respect to grab_window and are reported only if +selected by event_mask. +If owner_events is +<symbol>True</symbol> +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 +<symbol>GrabModeAsync</symbol>, +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 +<symbol>GrabModeSync</symbol>, +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 +<symbol>GrabModeAsync</symbol>, +keyboard event processing is unaffected by activation of the grab. +If the keyboard_mode is +<symbol>GrabModeSync</symbol>, +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 +<symbol>None</symbol> +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 +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +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 +<symbol>GrabNotViewable</symbol>. +If the pointer is actively grabbed by some other client, +it fails and returns +<symbol>AlreadyGrabbed</symbol>. +If the pointer is frozen by an active grab of another client, +it fails and returns +<symbol>GrabFrozen</symbol>. +If the specified time is earlier than the last-pointer-grab time or later +than the current X server time, it fails and returns +<symbol>GrabInvalidTime</symbol>. +Otherwise, the last-pointer-grab time is set to the specified time +(<symbol>CurrentTime</symbol> +is replaced by the current X server time). +</para> +<para> +<!-- .LP --> +<function>XGrabPointer</function> +can generate +<errorname>BadCursor</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +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 id='xungrabpointer'> +<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 +<symbol>CurrentTime</symbol>. + </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 +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events. +The X server performs an +<systemitem>UngrabPointer</systemitem> +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 id='xchangeactivepointergrab'> +<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 +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. +You can pass either a timestamp or +<symbol>CurrentTime</symbol>. + </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 +<errorname>BadCursor</errorname> +and +<errorname>BadValue</errorname> +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 id='xgrabbutton'> +<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 +<symbol>AnyButton</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks or +<symbol>AnyModifier</symbol>. +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 +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keyboard_mode</emphasis> + </term> + <listitem> + <para> +Specifies further processing of keyboard events. +You can pass +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>confine_to</emphasis> + </term> + <listitem> + <para> +Specifies the window to confine the pointer in or +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cursor</emphasis> + </term> + <listitem> + <para> +Specifies the cursor that is to be displayed or +<symbol>None</symbol>. + </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 +<symbol>ButtonPress</symbol> +event), and the +<symbol>ButtonPress</symbol> +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 +<symbol>AnyModifier</symbol> +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 +<symbol>AnyButton</symbol> +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 +<errorname>BadAccess</errorname> +error results. +When using +<symbol>AnyModifier</symbol> +or +<symbol>AnyButton</symbol>, +the request fails completely, +and a +<errorname>BadAccess</errorname> +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 +<errorname>BadCursor</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +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 id='xungrabbutton'> +<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 +<symbol>AnyButton</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks or +<symbol>AnyModifier</symbol>. +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 +<symbol>AnyModifier</symbol> +is +equivalent to issuing +the ungrab request for all possible modifier combinations, including +the combination of no modifiers. +A button of +<symbol>AnyButton</symbol> +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 +<errorname>BadValue</errorname> +and +<errorname>BadWindow</errorname> +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: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. +</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 id='xgrabkeyboard'> +<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 +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keyboard_mode</emphasis> + </term> + <listitem> + <para> +Specifies further processing of keyboard events. +You can pass +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. +You can pass either a timestamp or +<symbol>CurrentTime</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGrabKeyboard</function> +function actively grabs control of the keyboard and generates +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +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 +<symbol>False</symbol>, +all generated key events are reported with +respect to grab_window. +If owner_events is +<symbol>True</symbol> +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 +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are always reported, +independent of any event selection made by the client. +</para> +<para> +<!-- .LP --> +If the keyboard_mode argument is +<symbol>GrabModeAsync</symbol>, +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 +<symbol>GrabModeSync</symbol>, +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 +<symbol>GrabModeAsync</symbol>, +pointer event processing is unaffected +by activation of the grab. +If pointer_mode is +<symbol>GrabModeSync</symbol>, +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 +<symbol>AlreadyGrabbed</symbol>. +If grab_window is not viewable, +it fails and returns +<symbol>GrabNotViewable</symbol>. +If the keyboard is frozen by an active grab of another client, +it fails and returns +<symbol>GrabFrozen</symbol>. +If the specified time is earlier than the last-keyboard-grab time +or later than the current X server time, +it fails and returns +<symbol>GrabInvalidTime</symbol>. +Otherwise, the last-keyboard-grab time is set to the specified time +(<symbol>CurrentTime</symbol> +is replaced by the current X server time). +</para> +<para> +<!-- .LP --> +<function>XGrabKeyboard</function> +can generate +<errorname>BadValue</errorname> +and +<errorname>BadWindow</errorname> +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 id='xungrabkeyboard'> +<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 +<symbol>CurrentTime</symbol>. + </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 +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +events. +The X server automatically performs an +<systemitem>UngrabKeyboard</systemitem> +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 id='xgrabkey'> +<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 +<symbol>AnyKey</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks or +<symbol>AnyModifier</symbol>. +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 +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keyboard_mode</emphasis> + </term> + <listitem> + <para> +Specifies further processing of keyboard events. +You can pass +<symbol>GrabModeSync</symbol> +or +<symbol>GrabModeAsync</symbol>. + </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 +<symbol>KeyPress</symbol> +event), and the +<symbol>KeyPress</symbol> +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 +<symbol>AnyModifier</symbol> +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 +<symbol>AnyKey</symbol> +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 +<errorname>BadValue</errorname> +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 +<errorname>BadAccess</errorname> +error results. +When using +<symbol>AnyModifier</symbol> +or +<symbol>AnyKey</symbol>, +the request fails completely, +and a +<errorname>BadAccess</errorname> +error results (no grabs are established) +if there is a conflicting grab for any combination. +</para> +<para> +<!-- .LP --> +<function>XGrabKey</function> +can generate +<errorname>BadAccess</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +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 id='xungrabkey'> +<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 +<symbol>AnyKey</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks or +<symbol>AnyModifier</symbol>. +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 +<symbol>AnyModifier</symbol> +is equivalent to issuing +the request for all possible modifier combinations +(including the combination of no modifiers). +A keycode argument of +<symbol>AnyKey</symbol> +is equivalent to issuing the request for all possible key codes. +</para> +<para> +<!-- .LP --> +<function>XUngrabKey</function> +can generate +<errorname>BadValue</errorname> +and +<errorname>BadWindow</errorname> +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 id='xallowevents'> +<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 +<symbol>AsyncPointer</symbol>, +<symbol>SyncPointer</symbol>, +<symbol>AsyncKeyboard</symbol>, +<symbol>SyncKeyboard</symbol>, +<symbol>ReplayPointer</symbol>, +<symbol>ReplayKeyboard</symbol>, +<symbol>AsyncBoth</symbol>, +or +<symbol>SyncBoth</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. +You can pass either a timestamp or +<symbol>CurrentTime</symbol>. + </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><symbol>AsyncPointer</symbol></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, + <symbol>AsyncPointer</symbol> + thaws for both. + <symbol>AsyncPointer</symbol> + 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><symbol>SyncPointer</symbol></entry> + <entry>If the pointer is frozen and actively grabbed by the client, + pointer event processing continues as usual until the next + <symbol>ButtonPress</symbol> + or + <symbol>ButtonRelease</symbol> + 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. + <symbol>SyncPointer</symbol> + 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><symbol>ReplayPointer</symbol></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 + <symbol>SyncPointer</symbol> + 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><symbol>AsyncKeyboard</symbol></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, + <symbol>AsyncKeyboard</symbol> + thaws for both. + <symbol>AsyncKeyboard</symbol> + 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><symbol>SyncKeyboard</symbol></entry> + <entry>If the keyboard is frozen and actively grabbed by the client, + keyboard event processing continues as usual until the next + <symbol>KeyPress</symbol> + or + <symbol>KeyRelease</symbol> + 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. + <symbol>SyncKeyboard</symbol> + 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><symbol>ReplayKeyboard</symbol></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 + <symbol>SyncKeyboard</symbol> + 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><symbol>SyncBoth</symbol></entry> + <entry>If both pointer and keyboard are frozen by the client, + event processing for both devices continues as usual until the next + <symbol>ButtonPress</symbol>, + <symbol>ButtonRelease</symbol>, + <symbol>KeyPress</symbol>, + or + <symbol>KeyRelease</symbol> + 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). + <symbol>SyncBoth</symbol> + 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, + <symbol>SyncBoth</symbol> + thaws for both (but a subsequent freeze for + <symbol>SyncBoth</symbol> + will only freeze each device once).</entry> + </row> + <row> + <entry><symbol>AsyncBoth</symbol></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, + <symbol>AsyncBoth</symbol> + thaws for both. + <symbol>AsyncBoth</symbol> + has no effect unless both + pointer and keyboard are frozen by the client.</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +<symbol>AsyncPointer</symbol>, +<symbol>SyncPointer</symbol>, +and +<symbol>ReplayPointer</symbol> +have no effect on the +processing of keyboard events. +<symbol>AsyncKeyboard</symbol>, +<symbol>SyncKeyboard</symbol>, +and +<symbol>ReplayKeyboard</symbol> +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>XAllowEvents</function> +releases both. +</para> +<para> +<!-- .LP --> +<function>XAllowEvents</function> +can generate a +<errorname>BadValue</errorname> +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 id='xwarppointer'> +<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 +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_w</emphasis> + </term> + <listitem> + <para> +Specifies the destination window or +<symbol>None</symbol>. + </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 +<symbol>None</symbol>, +<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 +<errorname>BadWindow</errorname> +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 id='xsetinputfocus'> +<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, +<symbol>PointerRoot</symbol>, +or +<symbol>None</symbol>. + </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 +<symbol>RevertToParent</symbol>, +<symbol>RevertToPointerRoot</symbol>, +or +<symbol>RevertToNone</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. +You can pass either a timestamp or +<symbol>CurrentTime</symbol>. + </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 +(<symbol>CurrentTime</symbol> +is replaced by the current X server time). +<function>XSetInputFocus</function> +causes the X server to generate +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +events. +</para> +<para> +<!-- .LP --> +Depending on the focus argument, +the following occurs: +</para> +<itemizedlist> + <listitem> + <para> +If focus is +<symbol>None</symbol>, +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 +<symbol>PointerRoot</symbol>, +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 +<errorname>BadMatch</errorname> +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 +<symbol>RevertToParent</symbol>, +the focus reverts to the parent (or the closest viewable ancestor), +and the new revert_to value is taken to be +<symbol>RevertToNone</symbol>. + </para> + </listitem> + <listitem> + <para> +If revert_to is +<symbol>RevertToPointerRoot</symbol> +or +<symbol>RevertToNone</symbol>, +the focus reverts to +<symbol>PointerRoot</symbol> +or +<symbol>None</symbol>, +respectively. +When the focus reverts, +the X server generates +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +events, but the last-focus-change time is not affected. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>XSetInputFocus</function> +can generate +<errorname>BadMatch</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the current input focus, use +<function>XGetInputFocus</function>. +<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetinputfocus'> +<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, +<symbol>PointerRoot</symbol>, +or +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>revert_to_return</emphasis> + </term> + <listitem> + <para> +Returns the current focus state +(<symbol>RevertToParent</symbol>, +<symbol>RevertToPointerRoot</symbol>, +or +<symbol>RevertToNone</symbol>). + </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 +<structname>XKeyboardControl</structname> +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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +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 +<symbol>LedModeOn</symbol> +or +<symbol>LedModeOff</symbol>. +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 +<errorname>BadMatch</errorname> +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 +<symbol>AutoRepeatModeOn</symbol>, +<symbol>AutoRepeatModeOff</symbol>, +or +<symbol>AutoRepeatModeDefault</symbol>), +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 +<errorname>BadMatch</errorname> +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 +<symbol>AutoRepeatModeOn</symbol>, +keys should obey their individual auto-repeat modes. +When global mode is +<symbol>AutoRepeatModeOff</symbol>, +no keys should auto-repeat. +An auto-repeating key generates alternating +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +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 id='xchangekeyboardcontrol'> +<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 +<structname>XKeyboardControl</structname> +structure. +The value_mask argument specifies which values are to be changed. +</para> +<para> +<!-- .LP --> +<function>XChangeKeyboardControl</function> +can generate +<errorname>BadMatch</errorname> +and +<errorname>BadValue</errorname> +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 id='xgetkeyboardcontrol'> +<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 +<structname>XKeyboardState</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetKeyboardControl</function> +function returns the current control values for the keyboard to the +<structname>XKeyboardState</structname> +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 +<symbol>AutoRepeatModeOn</symbol> +or +<symbol>AutoRepeatModeOff</symbol>. +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 id='xautorepeaton'> +<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 id='xautorepeatoff'> +<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 id='xbell'> +<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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +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 id='xquerykeymap'> +<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 id='xsetpointermapping'> +<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 +<symbol>MappingNotify</symbol> +event, and +<function>XSetPointerMapping</function> +returns +<symbol>MappingSuccess</symbol>. +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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +error results. +If any of the buttons to be altered are logically in the down state, +<function>XSetPointerMapping</function> +returns +<symbol>MappingBusy</symbol>, +and the mapping is not changed. +</para> +<para> +<!-- .LP --> +<function>XSetPointerMapping</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the pointer mapping, use +<function>XGetPointerMapping</function>. +<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetpointermapping'> +<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 id='xchangepointercontrol'> +<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 +<symbol>True</symbol> +for the pointer values to be set, +or the parameters are unchanged. +Negative values (other than -1) generate a +<errorname>BadValue</errorname> +error, as does a zero value +for the accel_denominator argument. +</para> +<para> +<!-- .LP --> +<function>XChangePointerControl</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the current pointer parameters, use +<function>XGetPointerControl</function>. +<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetpointercontrol'> +<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 +<filename class="headerfile"><X11/keysymdef.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm> +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 +<filename class="headerfile"><X11/keysym.h></filename>, +<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysym.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysym.h></filename></secondary></indexterm> +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 +<symbol>NoSymbol</symbol> +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 +<symbol>NoSymbol</symbol> +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 +<symbol>NoSymbol</symbol> +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 +<symbol>VoidSymbol</symbol> +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 +<symbol>NoSymbol</symbol>, +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 +<symbol>KeyPress</symbol> +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 +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>. +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 +<symbol>Lock</symbol> +modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock +is attached to some KeyCode and that KeyCode is attached to the +<symbol>Lock</symbol> +modifier. The +<symbol>Lock</symbol> +modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock +is attached to some KeyCode and that KeyCode is attached to the +<symbol>Lock</symbol> +modifier. If the +<symbol>Lock</symbol> +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 +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>. +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 +<symbol>Shift</symbol> +modifier is on, or if the +<symbol>Lock</symbol> +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 +<symbol>Shift</symbol> +and +<symbol>Lock</symbol> +modifiers are both off. In this case, the first +KeySym is used. + </para> + </listitem> + <listitem> + <para> +The +<symbol>Shift</symbol> +modifier is off, and the +<symbol>Lock</symbol> +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 +<symbol>Shift</symbol> +modifier is on, and the +<symbol>Lock</symbol> +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 +<symbol>Shift</symbol> +modifier is on, or the +<symbol>Lock</symbol> +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 id='xdisplaykeycodes'> +<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 id='xgetkeyboardmapping'> +<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 +<errorname>BadValue</errorname> +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 +<errorname>BadValue</errorname> +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 +<symbol>NoSymbol</symbol> +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 +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To change the keyboard mapping, use +<function>XChangeKeyboardMapping</function>. +<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xchangekeyboardmapping'> +<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 +<errorname>BadValue</errorname> +error results. +In addition, the following expression must be less than or equal to +max_keycode as returned by +<function>XDisplayKeycodes</function>, +or a +<errorname>BadValue</errorname> +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 +<symbol>NoSymbol</symbol> +should be used to fill in unused elements +for individual KeyCodes. +It is legal for +<symbol>NoSymbol</symbol> +to appear in nontrailing positions +of the effective list for a KeyCode. +<function>XChangeKeyboardMapping</function> +generates a +<symbol>MappingNotify</symbol> +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 +<errorname>BadAlloc</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +The next six functions make use of the +<structname>XModifierKeymap</structname> +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 +<structname>XModifierKeymap</structname> +structure, use +<function>XNewModifiermap</function>. +<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xnewmodifiermap'> +<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 +<structname>XModifierKeymap</structname> +structure for later use. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add a new entry to an +<structname>XModifierKeymap</structname> +structure, use +<function>XInsertModifiermapEntry</function>. +<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xinsertmodifiermapentry'> +<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 +<structname>XModifierKeymap</structname> +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 +<structname>XModifierKeymap</structname> +structure (expanded as needed). +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To delete an entry from an +<structname>XModifierKeymap</structname> +structure, use +<function>XDeleteModifiermapEntry</function>. +<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdeletemodifiermapentry'> +<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 +<structname>XModifierKeymap</structname> +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 +<structname>XModifierKeymap</structname> +structure. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To destroy an +<structname>XModifierKeymap</structname> +structure, use +<function>XFreeModifiermap</function>. +<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreemodifiermap'> +<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 +<structname>XModifierKeymap</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeModifiermap</function> +function frees the specified +<structname>XModifierKeymap</structname> +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 id='xsetmodifiermapping'> +<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 +<structname>XModifierKeymap</structname> +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 +<symbol>MappingNotify</symbol> +event, and +<function>XSetModifierMapping</function> +returns +<symbol>MappingSuccess</symbol>. +X permits at most 8 modifier keys. +If more than 8 are specified in the +<structname>XModifierKeymap</structname> +structure, a +<errorname>BadLength</errorname> +error results. +</para> +<para> +<!-- .LP --> +The modifiermap member of the +<structname>XModifierKeymap</structname> +structure contains 8 sets of max_keypermod KeyCodes, +one for each modifier in the order +<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +<symbol>Mod1</symbol>, +<symbol>Mod2</symbol>, +<symbol>Mod3</symbol>, +<symbol>Mod4</symbol>, +and +<symbol>Mod5</symbol>. +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 +<type>Display</type> +structure, +or a +<errorname>BadValue</errorname> +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 +<symbol>MappingFailed</symbol>, +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 +<symbol>MappingBusy</symbol>, +and none of the modifiers is changed. +</para> +<para> +<!-- .LP --> +<function>XSetModifierMapping</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadValue</errorname> +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 id='xgetmodifiermapping'> +<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 +<structname>XModifierKeymap</structname> +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> |