887 lines
26 KiB
XML
887 lines
26 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='Interpreting_Key_Events'>
|
||
<title>Interpreting Key Events</title>
|
||
|
||
<para>
|
||
Xkb provides functions to help developers interpret key events without having
|
||
to directly interpret Xkb data structures. Xkb also modifies the behavior of
|
||
several core X library functions.
|
||
</para>
|
||
|
||
<sect1 id='Effects_of_Xkb_on_the_Core_X_Library'>
|
||
<title>Effects of Xkb on the Core X Library</title>
|
||
|
||
<para>
|
||
When support for Xkb is built into the X library, the
|
||
<function>XOpenDisplay</function>
|
||
function looks for a compatible version of Xkb on the server. If it finds a
|
||
compatible version, it initializes the extension and enables
|
||
<firstterm>implicit support</firstterm>
|
||
for Xkb in a number of X library functions. This makes it possible for clients
|
||
to take advantage of nearly all Xkb features without having to be rewritten or
|
||
even recompiled, if they are built with shared libraries. This implicit support
|
||
is invisible to most clients, but it can have side effects, so the extension
|
||
includes ways to control or disable it.
|
||
</para>
|
||
|
||
|
||
<sect2 id='Effects_of_Xkb_on_Event_State'>
|
||
<title>Effects of Xkb on Event State</title>
|
||
|
||
<para>
|
||
Because
|
||
<function>XOpenDisplay</function>
|
||
initializes Xkb, some events contain an Xkb description of the keyboard state
|
||
instead of that normally used by the core protocol. See <link linkend="Xkb_State_to_Core_Protocol_State_Transformation">section 17.1.1</link> for more
|
||
information about the differences between Xkb keyboard state and that reported
|
||
by the core protocol.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Effects_of_Xkb_on_MappingNotify_Events'>
|
||
<title>Effects of Xkb on MappingNotify Events</title>
|
||
|
||
<indexterm zone="Effects_of_Xkb_on_MappingNotify_Events">
|
||
<primary>events</primary><secondary><symbol>MappingNotify</symbol></secondary></indexterm>
|
||
|
||
<para>
|
||
When Xkb is missing or disabled, the X library tracks changes to the keyboard
|
||
mapping using
|
||
<symbol>MappingNotify</symbol>
|
||
events. Whenever the keyboard mapping is changed, the server sends all clients
|
||
a
|
||
<symbol>MappingNotify</symbol>
|
||
event to report the change. When a client receives a
|
||
<symbol>MappingNotify</symbol>
|
||
event, it is supposed to call
|
||
<function>XRefreshKeyboardMapping</function>
|
||
to update the keyboard description used internally by the X library.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The X Keyboard Extension uses
|
||
<symbol>XkbMapNotify</symbol>
|
||
and
|
||
<symbol>XkbNewKeyboardNotify</symbol>
|
||
events to track changes to the keyboard mapping. When an Xkb-aware client
|
||
receives either event, it should call
|
||
<function>XkbRefreshKeyboardMapping</function>
|
||
to update the keyboard description used internally by the X library. To avoid
|
||
duplicate events, the X server does not send core protocol
|
||
<symbol>MappingNotify</symbol>
|
||
events to a client that has selected for
|
||
<symbol>XkbMapNotify</symbol>
|
||
events.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The implicit support for Xkb selects for
|
||
<symbol>XkbMapNotify</symbol>
|
||
events. This means that clients that do not explicitly use Xkb but that are
|
||
using a version of the X library that has implicit support for Xkb do not
|
||
receive
|
||
<symbol>MappingNotify</symbol>
|
||
events over the wire. Clients that were not written with Xkb in mind do not
|
||
recognize or properly handle the new Xkb events, so the implicit support
|
||
converts them to
|
||
<symbol>MappingNotify</symbol>
|
||
events that report approximately the same information, unless the client has
|
||
explicitly selected for the Xkb version of the event.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
An Xkb-capable X server does not send events from keys that fall outside the
|
||
legal range of keycodes expected by that client. Once the server sends a client
|
||
an
|
||
<symbol>XkbNewKeyboardNotify</symbol>
|
||
event, it reports events from all keys because it assumes that any client that
|
||
has received an
|
||
<symbol>XkbNewKeyboardNotify</symbol>
|
||
event expects key events from the new range of keycodes. The implicit support
|
||
for Xkb asks for
|
||
<symbol>XkbNewKeyboardNotify</symbol>
|
||
events, so the range of keycodes reported to the client might vary without the
|
||
client’s knowledge. Most clients don’t really care about the range of legal
|
||
keycodes, but some clients maintain information about each key and might have
|
||
problems with events that come from unexpected keys. Such clients can set the
|
||
<symbol>XkbLC_IgnoreNewKeyboards</symbol>
|
||
library control (see <link linkend="IgnoreNewKeyboards">section 11.3.1</link>) to prevent the implicit support from
|
||
requesting notification of changes to the legal range of keycodes.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='X_Library_Functions_Affected_by_Xkb'>
|
||
<title>X Library Functions Affected by Xkb</title>
|
||
|
||
<para>
|
||
The following X library functions are modified by Xkb:
|
||
|
||
<simplelist type='vert' columns='1'>
|
||
<member><function>XKeycodeToKeysym</function></member>
|
||
<member><function>XKeysymToKeycode</function></member>
|
||
<member><function>XLookupKeysym</function></member>
|
||
<member><function>XLookupString</function></member>
|
||
<member><function>XRefreshKeyboardMapping</function></member>
|
||
<member><function>XRebindKeysym</function></member>
|
||
</simplelist>
|
||
</para>
|
||
|
||
<para>
|
||
The implicit support for Xkb replaces a number of X library functions with
|
||
versions that understand and use the X Keyboard Extension. In most cases, the
|
||
semantics of the new versions are identical to those of the old, but there are
|
||
occasional visible differences. This section lists all of the functions that
|
||
are affected and the differences in behavior, if any, that are visible to
|
||
clients.
|
||
</para>
|
||
|
||
|
||
<para id='XKeycodeToKeysym'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XKeycodeToKeysym'><function>XKeycodeToKeysym</function></olink>
|
||
<indexterm significance="preferred" zone="XKeycodeToKeysym"><primary><function>XKeycodeToKeysym</function></primary></indexterm>
|
||
function reports the keysym associated with a particular index for a single
|
||
key. The index specifies a column of symbols in the core keyboard mapping (that
|
||
is, as reported by the core protocol
|
||
<systemitem>GetKeyboardMapping</systemitem>
|
||
request). The order of the symbols in the core mapping does not necessarily
|
||
correspond to the order of the symbols used by Xkb; <link linkend="Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">section 17.1.3</link> describes
|
||
the differences.
|
||
</para>
|
||
|
||
|
||
<para id='XKeysymToKeycode'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XKeysymToKeycode'><function>XKeysymToKeycode</function></olink>
|
||
<indexterm significance="preferred" zone="XKeysymToKeycode"><primary><function>XKeysymToKeycode</function></primary></indexterm>
|
||
function reports a keycode to which a particular keysym is bound. When Xkb is
|
||
missing or disabled, this function looks in each column of the core keyboard
|
||
mapping in turn and returns the lowest numbered key that matches in the lowest
|
||
numbered group. When Xkb is present, this function uses the Xkb ordering for
|
||
symbols instead.
|
||
</para>
|
||
|
||
|
||
<para id='XLookupKeysym'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XLookupKeysym'><function>XLookupKeysym</function></olink>
|
||
<indexterm significance="preferred" zone="XLookupKeysym"><primary><function>XLookupKeysym</function></primary></indexterm>
|
||
function reports the symbol in a specific column of the key associated with an
|
||
event. Whether or not Xkb is present, the column specifies an index into the
|
||
core symbol mapping.
|
||
</para>
|
||
|
||
|
||
<para id='XLookupString'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink>
|
||
<indexterm significance="preferred" zone="XLookupString"><primary><function>XLookupString</function></primary></indexterm>
|
||
function reports the symbol and string associated with a key event, taking
|
||
into account the keycode and keyboard state as reported in the event. When Xkb
|
||
is disabled or missing,
|
||
<function>XLookupString</function>
|
||
uses the rules specified by the core protocol and reports only ISO Latin-1
|
||
characters. When Xkb is present,
|
||
<function>XLookupString</function>
|
||
uses the explicit keyboard group, key types, and rules specified by Xkb. When
|
||
Xkb is present,
|
||
<function>XLookupString</function>
|
||
is allowed, but not required, to return strings in character sets other than
|
||
ISO Latin-1, depending on the current locale. If any key bindings are defined,
|
||
<function>XLookupString</function>
|
||
does not use any consumed modifiers (see <link linkend="ConsumeLookupMods">section 11.1.2</link> and <link linkend="Key_Types">section 15.2</link>) to
|
||
determine matching bindings.
|
||
</para>
|
||
|
||
|
||
<para id='XRefreshKeyboardMapping'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XRefreshKeyboardMapping'><function>XRefreshKeyboardMapping</function></olink>
|
||
<indexterm significance="preferred" zone="XRefreshKeyboardMapping"><primary><function>XRefreshKeyboardMapping</function></primary></indexterm>
|
||
function updates the X library’s internal representation of the keyboard to
|
||
reflect changes reported via
|
||
<symbol>MappingNotify</symbol>
|
||
events. When Xkb is missing or disabled, this function reloads the entire
|
||
modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support
|
||
keeps track of the changed components reported by each
|
||
<symbol>XkbMapNotify</symbol>
|
||
event and updates only those pieces of the keyboard description that have
|
||
changed. If the implicit support has not noted any keyboard mapping changes,
|
||
<function>XRefreshKeyboardMapping</function>
|
||
updates the entire keyboard description.
|
||
</para>
|
||
|
||
|
||
<para id='XRebindKeysym'>
|
||
The
|
||
<olink targetdoc='libX11' targetptr='XRebindKeysym'><function>XRebindKeysym</function></olink>
|
||
<indexterm significance="preferred" zone="XRebindKeysym"><primary><function>XRebindKeysym</function></primary></indexterm>
|
||
function associates a string with a keysym and a set of modifiers. Xkb does
|
||
not directly change this function, but it does affect the way that the state
|
||
reported in the event is compared to the state specified to
|
||
<function>XRebindKeysym</function>.
|
||
When Xkb is missing or disabled,
|
||
<function>XLookupString</function>
|
||
returns the specified string if the modifiers in the event exactly match the
|
||
modifiers from this call. When Xkb is present, any modifiers used to determine
|
||
the keysym are consumed and are not used to look up the string.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<sect1 id='Xkb_Event_and_Keymap_Functions'>
|
||
<title>Xkb Event and Keymap Functions</title>
|
||
|
||
<para>
|
||
To find the keysym bound to a particular key at a specified group and shift
|
||
level, use <function>XkbKeycodeToKeysym</function>.
|
||
</para>
|
||
|
||
<indexterm significance="preferred" zone="XkbKeycodeToKeysym"><primary><function>XkbKeycodeToKeysym</function></primary></indexterm>
|
||
<funcsynopsis id="XkbKeycodeToKeysym">
|
||
<funcprototype>
|
||
<funcdef>KeySym <function>XkbKeycodeToKeysym</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy, kc, group, level</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>KeyCode <parameter>kc</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>group</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>level</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>kc</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
key of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>group</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
group of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>level</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
shift level of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbKeycodeToKeysym</function>
|
||
returns the keysym bound to a particular group and shift level for a
|
||
particular key on the core keyboard. If
|
||
<parameter>kc</parameter>
|
||
is not a legal keycode for the core keyboard, or if
|
||
<parameter>group</parameter>
|
||
or
|
||
<parameter>level</parameter>
|
||
are out of range for the specified key,
|
||
<function>XkbKeycodeToKeysym</function>
|
||
returns
|
||
<symbol>NoSymbol</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To find the set of modifiers bound to a particular keysym on the core keyboard,
|
||
use
|
||
<function>XkbKeysymToModifiers</function>.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbKeysymToModifiers"><primary><function>XkbKeysymToModifiers</function></primary></indexterm>
|
||
<funcsynopsis id="XkbKeysymToModifiers">
|
||
<funcprototype>
|
||
<funcdef>unsigned int <function>XkbKeysymToModifiers</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>ks</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>KeySym <parameter>ks</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>ks</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
keysym of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbKeysymToModifiers</function>
|
||
finds the set of modifiers currently bound to the keysym
|
||
<parameter>ks</parameter>
|
||
on the core keyboard. The value returned is the mask of modifiers bound to the
|
||
keysym
|
||
<parameter>ks</parameter>.
|
||
If no modifiers are bound to the keysym,
|
||
<function>XkbKeysymToModifiers</function>
|
||
returns zero; otherwise, it returns the inclusive OR of zero or more of the
|
||
following:
|
||
<symbol>ShiftMask</symbol>,
|
||
<symbol>ControlMask</symbol>,
|
||
<symbol>LockMask</symbol>,
|
||
<symbol>Mod1Mask</symbol>,
|
||
<symbol>Mod2Mask</symbol>,
|
||
<symbol>Mod3Mask</symbol>,
|
||
<symbol>Mod4Mask</symbol>,
|
||
and
|
||
<symbol>Mod5Mask</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Use
|
||
<function>XkbLookupKeySym</function>
|
||
to find the symbol associated with a key for a particular state.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbLookupKeySym"><primary><function>XkbLookupKeySym</function></primary></indexterm>
|
||
<funcsynopsis id="XkbLookupKeySym">
|
||
<funcprototype>
|
||
<funcdef>Bool <function>XkbLookupKeySym</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>key</parameter>,
|
||
<parameter>state</parameter>,
|
||
<parameter>mods_rtrn</parameter>,
|
||
<parameter>sym_rtrn</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>KeyCode <parameter>key</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>state</parameter></paramdef>
|
||
<paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef>
|
||
<paramdef>KeySym *<parameter>sym_rtrn</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>key</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
key for which symbols are to be found
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>state</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
state for which symbol should be found
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>mods_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
backfilled with consumed modifiers
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>sym_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
backfilled with symbol associated with key + state
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbLookupKeySym</function>
|
||
is the equivalent of the core
|
||
<symbol>XLookupKeySym</symbol>
|
||
function. For the core keyboard, given a keycode
|
||
<parameter>key</parameter>
|
||
and an Xkb state
|
||
<parameter>state</parameter>,
|
||
<function>XkbLookupKeySym</function>
|
||
returns the symbol associated with the key in
|
||
<parameter>sym_rtrn</parameter>
|
||
and the list of modifiers that should still be applied in
|
||
<parameter>mods_rtrn</parameter>.
|
||
The
|
||
<parameter>state</parameter>
|
||
parameter is the state from a
|
||
<symbol>KeyPress</symbol>
|
||
or
|
||
<symbol>KeyRelease</symbol>
|
||
event.
|
||
<function>XkbLookupKeySym</function>
|
||
returns
|
||
<symbol>True</symbol>
|
||
if it succeeds.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Use
|
||
<function>XkbLookupKeyBinding</function>
|
||
to find the string bound to a key by
|
||
<function>XRebindKeysym</function>.
|
||
<function>XkbLookupKeyBinding</function>
|
||
is the equivalent of the core
|
||
<function>XLookupString</function>
|
||
function.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbLookupKeyBinding"><primary><function>XkbLookupKeyBinding</function></primary></indexterm>
|
||
<funcsynopsis id="XkbLookupKeyBinding">
|
||
<funcprototype>
|
||
<funcdef>int <function>XkbLookupKeyBinding</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>sym</parameter>,
|
||
<parameter>state</parameter>,
|
||
<parameter>buf</parameter>,
|
||
<parameter>nbytes</parameter>,
|
||
<parameter>extra_rtrn</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>KeySym <parameter>sym</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>state</parameter></paramdef>
|
||
<paramdef>char *<parameter>buf</parameter></paramdef>
|
||
<paramdef>int <parameter>nbytes</parameter></paramdef>
|
||
<paramdef>int *<parameter>extra_rtrn</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>sym</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
symbol to be looked up
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>state</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
state for which string is to be looked up
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>buf</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
buffer into which returned string is written
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>nbytes</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
size of buffer in bytes
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>extra_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
backfilled with number bytes overflow
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XRebindKeysym</function>
|
||
binds an ASCII string to a specified keysym, so that the string and keysym are
|
||
returned when the key is pressed and a specified list of modifiers are also
|
||
being held down.
|
||
<function>XkbLookupKeyBinding</function>
|
||
returns in
|
||
<parameter>buf</parameter>
|
||
the string associated with the keysym
|
||
<parameter>sym</parameter>
|
||
and modifier state
|
||
<parameter>state</parameter>.
|
||
<parameter>buf</parameter>
|
||
is
|
||
<symbol>NULL</symbol>
|
||
terminated unless there’s an overflow. If the string returned is larger than
|
||
<parameter>nbytes</parameter>,
|
||
a count of bytes that does not fit into the buffer is returned in extra_rtrn.
|
||
<function>XkbTranslateKeySym</function>
|
||
returns the number of bytes that it placed into
|
||
<parameter>buf</parameter>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To find the string and symbol associated with a keysym for a given keyboard
|
||
state, use
|
||
<function>XkbTranslateKeySym</function>.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbTranslateKeySym"><primary><function>XkbTranslateKeySym</function></primary></indexterm>
|
||
<funcsynopsis id="XkbTranslateKeySym">
|
||
<funcprototype>
|
||
<funcdef>int <function>XkbTranslateKeySym</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>sym_inout</parameter>,
|
||
<parameter>mods</parameter>,
|
||
<parameter>buf</parameter>,
|
||
<parameter>nbytes</parameter>,
|
||
<parameter>extra_rtrn</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>KeySym *<parameter>sym_inout</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>mods</parameter></paramdef>
|
||
<paramdef>char *<parameter>buf</parameter></paramdef>
|
||
<paramdef>int <parameter>nbytes</parameter></paramdef>
|
||
<paramdef>int *<parameter>extra_rtrn</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>sym_inout</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
symbol to be translated; result of translation
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>mods</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
modifiers to apply to <parameter>sym_inout</parameter>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>buf</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
buffer into which returned string is written
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>nbytes</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
size of buffer in bytes
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>extra_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
number of bytes overflow
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbTranslateKeySym</function>
|
||
applies the transformations specified in
|
||
<parameter>mods</parameter>
|
||
to the symbol specified by
|
||
<parameter>sym_inout</parameter>.
|
||
It returns in
|
||
<parameter>buf</parameter>
|
||
the string, if any, associated with the keysym for the current locale. If the
|
||
transformations in
|
||
<parameter>mods</parameter>
|
||
changes the keysym,
|
||
<parameter>sym_inout</parameter>
|
||
is updated accordingly. If the string returned is larger than
|
||
<parameter>nbytes</parameter>,
|
||
a count of bytes that does not fit into the buffer is returned in extra_rtrn.
|
||
<function>XkbTranslateKeySym</function>
|
||
returns the number of bytes it placed into
|
||
<parameter>buf</parameter>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To update the keyboard description that is internal to the X library, use
|
||
<function>XkbRefreshKeyboardMapping</function>.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbRefreshKeyboardMapping"><primary><function>XkbRefreshKeyboardMapping</function></primary></indexterm>
|
||
<funcsynopsis id="XkbRefreshKeyboardMapping">
|
||
<funcprototype>
|
||
<funcdef>Status <function>XkbRefreshKeyboardMapping</function></funcdef>
|
||
<!-- (
|
||
<parameter>event)</parameter> -->
|
||
|
||
<paramdef>XkbMapNotifyEvent *<parameter>event</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>event</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
event initiating remapping
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbRefreshKeyboardMapping</function>
|
||
is the Xkb equivalent of the core
|
||
<function>XRefreshKeyboardMapping</function>
|
||
function. It requests that the X server send the current key mapping
|
||
information to this client. A client usually invokes
|
||
<function>XkbRefreshKeyboardMapping</function>
|
||
after receiving an
|
||
<symbol>XkbMapNotify</symbol>
|
||
event.
|
||
<function>XkbRefreshKeyboardMapping</function>
|
||
returns
|
||
<symbol>Success</symbol>
|
||
if it succeeds and
|
||
<errorname>BadMatch</errorname>
|
||
if the event is not an Xkb event.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The
|
||
<symbol>XkbMapNotify</symbol>
|
||
event can be generated when some client calls
|
||
<function>XkbSetMap</function>,
|
||
<function>XkbChangeMap</function>,
|
||
<function>XkbGetKeyboardByName</function>,
|
||
or any of the standard X library functions that change the keyboard mapping
|
||
or modifier mapping.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To translate a keycode to a key symbol and modifiers, use
|
||
<function>XkbTranslateKeyCode</function>.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbTranslateKeyCode"><primary><function>XkbTranslateKeyCode</function></primary></indexterm>
|
||
<funcsynopsis id="XkbTranslateKeyCode">
|
||
<funcprototype>
|
||
<funcdef>Bool <function>XkbTranslateKeyCode</function></funcdef>
|
||
<!-- (
|
||
<parameter>xkb, key, mods, mods_rtrn, keysym_rtrn)</parameter> -->
|
||
|
||
<paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
|
||
<paramdef>KeyCode <parameter>key</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>mods</parameter></paramdef>
|
||
<paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef>
|
||
<paramdef>KeySym *<parameter>keysym_rtrn</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>xkb</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
keyboard description to use for translation
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>key</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
keycode to translate
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>mods</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
modifiers to apply when translating <parameter>key</parameter>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>mods_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
backfilled with consumed modifiers
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>keysym_rtrn</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
keysym resulting from translation
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<parameter>mods_rtrn</parameter>
|
||
is backfilled with the modifiers consumed by the translation process.
|
||
<parameter>mods</parameter>
|
||
is a bitwise inclusive OR of the legal modifier masks:
|
||
<symbol>ShiftMask</symbol>,
|
||
<symbol>LockMask</symbol>,
|
||
<symbol>ControlMask</symbol>,
|
||
<symbol>Mod1Mask</symbol>,
|
||
<symbol>Mod2Mask</symbol>,
|
||
<symbol>Mod3Mask</symbol>,
|
||
<symbol>Mod4Mask</symbol>,
|
||
<symbol>Mod5Mask</symbol>.
|
||
The
|
||
<emphasis>AlwaysConsumeShiftAndLock</emphasis>
|
||
library control (see <link linkend="AlwaysConsumeShiftAndLock">section 11.1.3</link>), if enabled, causes
|
||
<function>XkbTranslateKeyCode</function>
|
||
to consume shift and lock.
|
||
<function>XkbTranslateKeyCode</function>
|
||
returns
|
||
<symbol>True</symbol>
|
||
if the translation resulted in a keysym, and
|
||
<symbol>False</symbol>
|
||
if it resulted in
|
||
<symbol>NoSymbol</symbol>.
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|