mirror of
https://gitlab.freedesktop.org/xorg/lib/libx11.git
synced 2025-12-20 04:40:10 +01:00
8b77c86a06
Performed with: `git ls-files | xargs perl -i -p -e 's{[ \t]+$}{}'`
`git diff -w` & `git diff -b` show no diffs from this change
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Part-of: <https://gitlab.freedesktop.org/xorg/lib/libx11/-/merge_requests/287>
3946 lines
112 KiB
XML
3946 lines
112 KiB
XML
<?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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>).
|
|
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
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>).
|
|
<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
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <parameter>event_mask</parameter></paramdef>
|
|
<paramdef>int <parameter>pointer_mode</parameter></paramdef>
|
|
<paramdef>int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
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.
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadCursor</errorname>,
|
|
<errorname>BadValue</errorname>,
|
|
and
|
|
<errorname>BadWindow</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To ungrab the pointer, use
|
|
<xref linkend='XUngrabPointer' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
|
|
function releases the pointer and any queued events
|
|
if this client has actively grabbed the pointer from
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>,
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>,
|
|
or from a normal button press.
|
|
<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>.
|
|
The interpretation of event_mask and cursor is the same as described in
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadCursor</errorname>
|
|
and
|
|
<errorname>BadValue</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To grab a pointer button, use
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <parameter>button</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
|
|
<paramdef>Window <parameter>grab_window</parameter></paramdef>
|
|
<paramdef>Bool <parameter>owner_events</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
|
|
<paramdef>int <parameter>pointer_mode</parameter></paramdef>
|
|
<paramdef>int <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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>button</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the pointer button that is to be grabbed 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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>
|
|
function establishes a passive grab.
|
|
In the future,
|
|
the pointer is actively grabbed (as for
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>),
|
|
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
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
|
|
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
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>
|
|
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.
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>
|
|
has no effect on an active grab.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadCursor</errorname>,
|
|
<errorname>BadValue</errorname>,
|
|
and
|
|
<errorname>BadWindow</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To ungrab a pointer button, use
|
|
<xref linkend='XUngrabButton' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <parameter>button</parameter></paramdef>
|
|
<paramdef>unsigned int <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'>button</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the pointer button that is to be released 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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XUngrabButton' xrefstyle='select: title'/>
|
|
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.
|
|
<xref linkend='XUngrabButton' xrefstyle='select: title'/>
|
|
has no effect on an active grab.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XUngrabButton' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>int <parameter>pointer_mode</parameter></paramdef>
|
|
<paramdef>int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
|
|
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.
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadValue</errorname>
|
|
and
|
|
<errorname>BadWindow</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To ungrab the keyboard, use
|
|
<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
|
|
function
|
|
releases the keyboard and any queued events if this client has it actively grabbed from
|
|
either
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
|
|
or
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>.
|
|
<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <parameter>modifiers</parameter></paramdef>
|
|
<paramdef>Window <parameter>grab_window</parameter></paramdef>
|
|
<paramdef>Bool <parameter>owner_events</parameter></paramdef>
|
|
<paramdef>int <parameter>pointer_mode</parameter></paramdef>
|
|
<paramdef>int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>
|
|
function establishes a passive grab on the keyboard.
|
|
In the future,
|
|
the keyboard is actively grabbed (as for
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>),
|
|
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
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>.
|
|
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
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadAccess</errorname>,
|
|
<errorname>BadValue</errorname>,
|
|
and
|
|
<errorname>BadWindow</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To ungrab a key, use
|
|
<xref linkend='XUngrabKey' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>unsigned int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XUngrabKey' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XUngrabKey' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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 frame='none'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colname='c1' colwidth='1.0*'/>
|
|
<colspec colname='c2' colwidth='4.0*'/>
|
|
<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
|
|
<xref linkend='XGrabButton' xrefstyle='select: title'/>
|
|
or from a previous
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
with mode
|
|
<symbol>SyncPointer</symbol>
|
|
but not from an
|
|
<xref linkend='XGrabPointer' xrefstyle='select: title'/>),
|
|
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
|
|
<xref linkend='XGrabKey' xrefstyle='select: title'/>
|
|
or from a previous
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
with mode
|
|
<symbol>SyncKeyboard</symbol>
|
|
but not from an
|
|
<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>),
|
|
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
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
releases both.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XAllowEvents' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XWarpPointer' xrefstyle='select: title'/>.
|
|
</para>
|
|
<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>
|
|
<!-- .sM -->
|
|
<funcsynopsis id='XWarpPointer'>
|
|
<funcprototype>
|
|
<funcdef><function>XWarpPointer</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>Window <parameter>src_w</parameter></paramdef>
|
|
<paramdef>Window <parameter>dest_w</parameter></paramdef>
|
|
<paramdef>int <parameter>src_x</parameter></paramdef>
|
|
<paramdef>int <parameter>src_y</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>src_width</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>src_height</parameter></paramdef>
|
|
<paramdef>int <parameter>dest_x</parameter></paramdef>
|
|
<paramdef>int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
If dest_w is
|
|
<symbol>None</symbol>,
|
|
<xref linkend='XWarpPointer' xrefstyle='select: title'/>
|
|
moves the pointer by the offsets (dest_x, dest_y) relative to the current
|
|
position of the pointer.
|
|
If dest_w is a window,
|
|
<xref linkend='XWarpPointer' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XWarpPointer' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XWarpPointer' xrefstyle='select: title'/>
|
|
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
|
|
<olink targetdoc='icccm' targetptr='Input_Focus'><citetitle>Inter-Client Communication Conventions Manual</citetitle></olink>
|
|
for input focus policy.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To set the input focus, use
|
|
<xref linkend='XSetInputFocus' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
|
|
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).
|
|
<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadMatch</errorname>,
|
|
<errorname>BadValue</errorname>,
|
|
and
|
|
<errorname>BadWindow</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To obtain the current input focus, use
|
|
<xref linkend='XGetInputFocus' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetInputFocus' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
|
|
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 -->
|
|
</para>
|
|
<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>
|
|
<!-- .sM -->
|
|
<funcsynopsis id='XChangeKeyboardControl'>
|
|
<funcprototype>
|
|
<funcdef><function>XChangeKeyboardControl</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>unsigned long <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadMatch</errorname>
|
|
and
|
|
<errorname>BadValue</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To obtain the current control values for the keyboard, use
|
|
<xref linkend='XGetKeyboardControl' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetKeyboardControl' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XAutoRepeatOn' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XAutoRepeatOn' xrefstyle='select: title'/>
|
|
function turns on auto-repeat for the keyboard on the specified display.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To turn off keyboard auto-repeat, use
|
|
<xref linkend='XAutoRepeatOff' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XAutoRepeatOff' xrefstyle='select: title'/>
|
|
function turns off auto-repeat for the keyboard on the specified display.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To ring the bell, use
|
|
<xref linkend='XBell' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XBell' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XBell' xrefstyle='select: title'/>
|
|
can generate a
|
|
<errorname>BadValue</errorname>
|
|
error.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To obtain a bit vector that describes the state of the keyboard, use
|
|
<xref linkend='XQueryKeymap' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XQueryKeymap' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
|
|
function sets the mapping of the pointer.
|
|
If it succeeds, the X server generates a
|
|
<symbol>MappingNotify</symbol>
|
|
event, and
|
|
<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
|
|
returns
|
|
<symbol>MappingBusy</symbol>,
|
|
and the mapping is not changed.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
|
|
can generate a
|
|
<errorname>BadValue</errorname>
|
|
error.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To get the pointer mapping, use
|
|
<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
|
|
function returns the current mapping of the pointer.
|
|
Pointer buttons are numbered starting from one.
|
|
<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XChangePointerControl' xrefstyle='select: title'/>.
|
|
</para>
|
|
<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>
|
|
<!-- .sM -->
|
|
<funcsynopsis id='XChangePointerControl'>
|
|
<funcprototype>
|
|
<funcdef><function>XChangePointerControl</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>Bool <parameter>do_accel</parameter></paramdef>
|
|
<paramdef>Bool <parameter>do_threshold</parameter></paramdef>
|
|
<paramdef>int <parameter>accel_numerator</parameter></paramdef>
|
|
<paramdef>int <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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XChangePointerControl' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XChangePointerControl' xrefstyle='select: title'/>
|
|
can generate a
|
|
<errorname>BadValue</errorname>
|
|
error.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To get the current pointer parameters, use
|
|
<xref linkend='XGetPointerControl' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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 *<parameter>accel_numerator_return</parameter></paramdef>
|
|
<paramdef>int *<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetPointerControl' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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 *<parameter>min_keycodes_return</parameter></paramdef>
|
|
<paramdef>int *<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>first_keycode</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the first KeyCode that is to be returned.
|
|
</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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
|
|
or a
|
|
<errorname>BadValue</errorname>
|
|
error results.
|
|
In addition, the following expression must be less than or equal
|
|
to max_keycode as returned by
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>:
|
|
</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
|
|
<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>,
|
|
use
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>
|
|
can generate a
|
|
<errorname>BadValue</errorname>
|
|
error.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To change the keyboard mapping, use
|
|
<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>first_keycode</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the first KeyCode that is to be changed.
|
|
</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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
|
|
or a
|
|
<errorname>BadValue</errorname>
|
|
error results.
|
|
In addition, the following expression must be less than or equal to
|
|
max_keycode as returned by
|
|
<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
|
|
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.
|
|
<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XNewModifiermap' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XNewModifiermap' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XInsertModifiermapEntry' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XInsertModifiermapEntry' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XDeleteModifiermapEntry' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XDeleteModifiermapEntry' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>
|
|
function frees the specified
|
|
<structname>XModifierKeymap</structname>
|
|
structure.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To set the KeyCodes to be used as modifiers, use
|
|
<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
|
|
returns
|
|
<symbol>MappingBusy</symbol>,
|
|
and none of the modifiers is changed.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
|
|
can generate
|
|
<errorname>BadAlloc</errorname>
|
|
and
|
|
<errorname>BadValue</errorname>
|
|
errors.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To obtain the KeyCodes used as modifiers, use
|
|
<xref linkend='XGetModifierMapping' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetModifierMapping' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>.
|
|
If only zero values appear in the set for any modifier,
|
|
that modifier is disabled.
|
|
<!-- .bp -->
|
|
|
|
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|