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 2a688bdc5..01549f659 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 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> +<?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>
|