842 lines
22 KiB
XML
842 lines
22 KiB
XML
<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 <emphasis>
|
||
XOpenDisplay</emphasis>
|
||
function looks for a compatible version of Xkb on the server. If it finds a
|
||
compatible version, it initializes the extension and enables <emphasis>
|
||
implicit support</emphasis>
|
||
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 <emphasis>
|
||
XOpenDisplay</emphasis>
|
||
initializes Xkb, some events contain an Xkb description of the keyboard state
|
||
instead of that normally used by the core protocol. See section 17.1.1 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>
|
||
|
||
<para>
|
||
When Xkb is missing or disabled, the X library tracks changes to the keyboard
|
||
mapping using <emphasis>
|
||
MappingNotify</emphasis>
|
||
events. Whenever the keyboard mapping is changed, the server sends all clients
|
||
a <emphasis>
|
||
MappingNotify</emphasis>
|
||
event to report the change. When a client receives a <emphasis>
|
||
MappingNotify</emphasis>
|
||
event, it is supposed to call <emphasis>
|
||
XRefreshKeyboardMapping</emphasis>
|
||
to update the keyboard description used internally by the X library.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The X Keyboard Extension uses <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
and <emphasis>
|
||
XkbNewKeyboardNotify</emphasis>
|
||
events to track changes to the keyboard mapping. When an Xkb-aware client
|
||
receives either event, it should call <emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
to update the keyboard description used internally by the X library. To avoid
|
||
duplicate events, the X server does not send core protocol <emphasis>
|
||
MappingNotify</emphasis>
|
||
events to a client that has selected for <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
events.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The implicit support for Xkb selects for <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
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 <emphasis>
|
||
MappingNotify</emphasis>
|
||
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 <emphasis>
|
||
MappingNotify</emphasis>
|
||
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 <emphasis>
|
||
XkbNewKeyboardNotify</emphasis>
|
||
event, it reports events from all keys because it assumes that any client that
|
||
has receieved an <emphasis>
|
||
XkbNewKeyboardNotify</emphasis>
|
||
event expects key events from the new range of keycodes. The implicit support
|
||
for Xkb asks for <emphasis>
|
||
XkbNewKeyboardNotify</emphasis>
|
||
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
|
||
<emphasis>
|
||
XkbLC_IgnoreNewKeyboards</emphasis>
|
||
library control (see section 11.3.1) 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:
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
<emphasis>XKeycodeToKeysym</emphasis>
|
||
<emphasis>XKeysymToKeycode</emphasis>
|
||
<emphasis>XLookupKeysym</emphasis>
|
||
<emphasis>XLookupString</emphasis>
|
||
<emphasis>XRefreshKeyboardMapping</emphasis>
|
||
<emphasis>XRebindKeysym</emphasis>
|
||
</programlisting></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>
|
||
The <emphasis>
|
||
XKeycodeToKeysym</emphasis>
|
||
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 <emphasis>
|
||
GetKeyboardMapping</emphasis>
|
||
request). The order of the symbols in the core mapping does not necessarily
|
||
correspond to the order of the symbols used by Xkb; section 17.1.3 describes
|
||
the differences.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The <emphasis>
|
||
XKeysymToKeycode</emphasis>
|
||
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>
|
||
The <emphasis>
|
||
XLookupKeysym</emphasis>
|
||
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>
|
||
The <emphasis>
|
||
XLookupString</emphasis>
|
||
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, <emphasis>
|
||
XLookupString</emphasis>
|
||
uses the rules specified by the core protocol and reports only ISO Latin-1
|
||
characters. When Xkb is present, <emphasis>
|
||
XLookupString</emphasis>
|
||
uses the explicit keyboard group, key types, and rules specified by Xkb. When
|
||
Xkb is present, <emphasis>
|
||
XLookupString</emphasis>
|
||
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,
|
||
<emphasis>
|
||
XLookupString</emphasis>
|
||
does not use any consumed modifiers (see sections 11.1.2 and 15.2) to
|
||
determine matching bindings.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The <emphasis>
|
||
XRefreshKeyboardMapping</emphasis>
|
||
function updates the X library’s internal representation of the keyboard to
|
||
reflect changes reported via <emphasis>
|
||
MappingNotify</emphasis>
|
||
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 <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
event and updates only those pieces of the keyboard description that have
|
||
changed. If the implicit support has not noted any keyboard mapping changes,
|
||
<emphasis>
|
||
XRefreshKeyboardMapping</emphasis>
|
||
updates the entire keyboard description.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The <emphasis>
|
||
XRebindKeysym</emphasis>
|
||
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 <emphasis>
|
||
XRebindKeysym</emphasis>
|
||
. When Xkb is missing or disabled, <emphasis>
|
||
XLookupString</emphasis>
|
||
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 <emphasis>XkbKeycodeToKeysym</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
KeySym <emphasis>
|
||
XkbKeycodeToKeysym</emphasis>
|
||
(<emphasis>
|
||
dpy, kc, group, level</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * dpy; /* connection to X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeyCode kc; /* key of interest */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int group; /* group of interest */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int level; /* shift level of interest */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbKeycodeToKeysym</emphasis>
|
||
returns the keysym bound to a particular group and shift level for a
|
||
particular key on the core keyboard. If <emphasis>
|
||
kc</emphasis>
|
||
is not a legal keycode for the core keyboard, or if <emphasis>
|
||
group</emphasis>
|
||
or <emphasis>
|
||
level</emphasis>
|
||
are out of range for the specified key, <emphasis>
|
||
XkbKeycodeToKeysym</emphasis>
|
||
returns <emphasis>
|
||
NoSymbol</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To find the set of modifiers bound to a particular keysym on the core keyboard,
|
||
use <emphasis>
|
||
XkbKeysymToModifiers</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
unsigned<emphasis>
|
||
</emphasis>
|
||
int <emphasis>
|
||
XkbKeysymToModifiers</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
ks</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display *<emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeySym <emphasis>
|
||
ks</emphasis>
|
||
; /* keysym of interest */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbKeysymToModifiers</emphasis>
|
||
finds the set of modifiers currently bound to the keysym <emphasis>
|
||
ks</emphasis>
|
||
on the core keyboard. The value returned is the mask of modifiers bound to the
|
||
keysym <emphasis>
|
||
ks</emphasis>
|
||
. If no modifiers are bound to the keysym, <emphasis>
|
||
XkbKeysymToModifiers</emphasis>
|
||
returns zero; otherwise, it returns the inclusive OR of zero or more of the
|
||
following: <emphasis>
|
||
ShiftMask</emphasis>
|
||
, <emphasis>
|
||
ControlMask</emphasis>
|
||
, <emphasis>
|
||
LockMask</emphasis>
|
||
, <emphasis>
|
||
Mod1Mask</emphasis>
|
||
, <emphasis>
|
||
Mod2Mask</emphasis>
|
||
, <emphasis>
|
||
Mod3Mask</emphasis>
|
||
, <emphasis>
|
||
Mod4Mask,</emphasis>
|
||
and <emphasis>
|
||
Mod5Mask</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Use <emphasis>
|
||
XkbLookupKeySym</emphasis>
|
||
to find the symbol associated with a key for a particular state.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Bool <emphasis>
|
||
XkbLookupKeySym</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
key</emphasis>
|
||
,<emphasis>
|
||
state</emphasis>
|
||
,<emphasis>
|
||
mods_rtrn</emphasis>
|
||
,<emphasis>
|
||
sym_rtrn</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * <emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeyCode <emphasis>
|
||
key</emphasis>
|
||
; /* key for which symbols are to be found */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
state</emphasis>
|
||
; /* state for which symbol should be found */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int * <emphasis>
|
||
mods_rtrn</emphasis>
|
||
; /* backfilled with unconsumed modifiers */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeySym *<emphasis>
|
||
sym_rtrn</emphasis>
|
||
; /* backfilled with symbol associated with key + state */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbLookupKeySym</emphasis>
|
||
is the equivalent of the core <emphasis>
|
||
XLookupKeySym</emphasis>
|
||
function. For the core keyboard, given a keycode <emphasis>
|
||
key</emphasis>
|
||
and an Xkb state <emphasis>
|
||
state</emphasis>
|
||
, <emphasis>
|
||
XkbLookupKeySym</emphasis>
|
||
returns the symbol associated with the key in <emphasis>
|
||
sym_rtrn</emphasis>
|
||
and the list of modifiers that should still be applied in <emphasis>
|
||
mods_rtrn</emphasis>
|
||
. The <emphasis>
|
||
state</emphasis>
|
||
parameter is the state from a <emphasis>
|
||
KeyPress</emphasis>
|
||
or <emphasis>
|
||
KeyRelease</emphasis>
|
||
event. <emphasis>
|
||
XkbLookupKeySym</emphasis>
|
||
returns <emphasis>
|
||
True</emphasis>
|
||
if it succeeds.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Use <emphasis>
|
||
XkbLookupKeyBinding</emphasis>
|
||
to find the string bound to a key by <emphasis>
|
||
XRebindKeySym</emphasis>
|
||
. <emphasis>
|
||
XkbLookupKeyBinding</emphasis>
|
||
is the equivalent of the core <emphasis>
|
||
XLookupString</emphasis>
|
||
function.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
int <emphasis>
|
||
XkbLookupKeyBinding</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
sym</emphasis>
|
||
,<emphasis>
|
||
state</emphasis>
|
||
,<emphasis>
|
||
buf</emphasis>
|
||
,<emphasis>
|
||
nbytes</emphasis>
|
||
,<emphasis>
|
||
extra_rtrn</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * <emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeySym<emphasis>
|
||
sym</emphasis>
|
||
; /* symbol to be looked up */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
state</emphasis>
|
||
; /* state for which string is to be looked up */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
buf</emphasis>
|
||
; /* buffer into which returned string is written */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
nbytes</emphasis>
|
||
; /* size of buffer in bytes */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int * <emphasis>
|
||
extra_rtrn</emphasis>
|
||
; /* backfilled with number bytes overflow */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XRebindKeysym</emphasis>
|
||
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. <emphasis>
|
||
XkbLookupKeyBinding</emphasis>
|
||
returns in <emphasis>
|
||
buf</emphasis>
|
||
the string associated with the keysym <emphasis>
|
||
sym</emphasis>
|
||
and modifier state <emphasis>
|
||
state</emphasis>
|
||
. <emphasis>
|
||
buf</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
terminated unless there’s an overflow. If the string returned is larger than
|
||
<emphasis>
|
||
nbytes</emphasis>
|
||
, a count of bytes that does not fit into the buffer is returned in extra_rtrn.
|
||
<emphasis>
|
||
XkbTranslateKeySym</emphasis>
|
||
returns the number of bytes that it placed into <emphasis>
|
||
buf</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To find the string and symbol associated with a keysym for a given keyboard
|
||
state, use <emphasis>
|
||
XkbTranslateKeySym</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
int <emphasis>
|
||
XkbTranslateKeySym</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
sym_inout</emphasis>
|
||
,<emphasis>
|
||
mods</emphasis>
|
||
,<emphasis>
|
||
buf</emphasis>
|
||
,<emphasis>
|
||
nbytes</emphasis>
|
||
, <emphasis>
|
||
extra_rtrn</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * <emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeySym * <emphasis>
|
||
sym_inout</emphasis>
|
||
; /* symbol to be translated; result of translation */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
mods</emphasis>
|
||
; /* modifiers to apply to <emphasis>
|
||
sym_inout</emphasis>
|
||
*/
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
buf</emphasis>
|
||
; /* buffer into which returned string is written */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
nbytes</emphasis>
|
||
; /* size of buffer in bytes */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int *<emphasis>
|
||
extra_rtrn</emphasis>
|
||
; /* number of bytes overflow*/
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbTranslateKeySym</emphasis>
|
||
applies the transformations specified in <emphasis>
|
||
mods</emphasis>
|
||
to the symbol specified by <emphasis>
|
||
sym_inout</emphasis>
|
||
. It returns in <emphasis>
|
||
buf</emphasis>
|
||
the string, if any, associated with the keysym for the current locale. If the
|
||
transformations in <emphasis>
|
||
mods</emphasis>
|
||
changes the keysym, <emphasis>
|
||
sym_inout</emphasis>
|
||
is updated accordingly. If the string returned is larger than <emphasis>
|
||
nbytes</emphasis>
|
||
, a count of bytes that does not fit into the buffer is returned in extra_rtrn.
|
||
<emphasis>
|
||
XkbTranslateKeySym</emphasis>
|
||
returns the number of bytes it placed into <emphasis>
|
||
buf</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To update the keyboard description that is internal to the X library, use
|
||
<emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
(<emphasis>
|
||
event)</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbMapNotifyEvent * <emphasis>
|
||
event</emphasis>
|
||
; /* event initiating remapping */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
is the Xkb equivalent of the core <emphasis>
|
||
XRefreshKeyboardMapping</emphasis>
|
||
function. It requests that the X server send the current key mapping
|
||
information to this client. A client usually invokes <emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
after receiving an <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
event. <emphasis>
|
||
XkbRefreshKeyboardMapping</emphasis>
|
||
returns <emphasis>
|
||
Success</emphasis>
|
||
if it succeeds and <emphasis>
|
||
BadMatch</emphasis>
|
||
if the event is not an Xkb event.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The <emphasis>
|
||
XkbMapNotify</emphasis>
|
||
event can be generated when some client calls <emphasis>
|
||
XkbSetMap</emphasis>
|
||
, <emphasis>
|
||
XkbChangeMap</emphasis>
|
||
, <emphasis>
|
||
XkbGetKeyboardByName</emphasis>
|
||
, 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 <emphasis>
|
||
XkbTranslateKeyCode</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Booll <emphasis>
|
||
XkbTranslateKeyCode</emphasis>
|
||
(<emphasis>
|
||
xkb, key, mods, mods_rtrn, keysym_rtrn)</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbDescPtr <emphasis>
|
||
xkb</emphasis>
|
||
; /* keyboard description to use for translation */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeyCode <emphasis>
|
||
key</emphasis>
|
||
; /* keycode to translate */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
mods</emphasis>
|
||
; /* modifiers to apply when translating <emphasis>
|
||
key</emphasis>
|
||
*/
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int * <emphasis>
|
||
mods_rtrn</emphasis>
|
||
; /* backfilled with unconsumed modifiers */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
KeySym * <emphasis>
|
||
keysym_rtrn</emphasis>
|
||
; /* keysym resulting from translation */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
mods_rtrn</emphasis>
|
||
is backfilled with the modifiers consumed by the translation process.
|
||
<emphasis>
|
||
mods</emphasis>
|
||
is a bitwise inclusive OR of the legal modifier masks: <emphasis>
|
||
ShiftMask</emphasis>
|
||
, <emphasis>
|
||
LockMask</emphasis>
|
||
, <emphasis>
|
||
ControlMask</emphasis>
|
||
, <emphasis>
|
||
Mod1Mask</emphasis>
|
||
, <emphasis>
|
||
Mod2Mask</emphasis>
|
||
, <emphasis>
|
||
Mod3Mask</emphasis>
|
||
, <emphasis>
|
||
Mod4Mask</emphasis>
|
||
, <emphasis>
|
||
Mod5Mask</emphasis>
|
||
.The <emphasis>
|
||
AlwaysConsumeShiftAndLock</emphasis>
|
||
library control (see section 11.1.3), if enabled, causes <emphasis>
|
||
XkbTranslateKeyCode</emphasis>
|
||
to consume shift and lock.<emphasis>
|
||
XkbTranslateKeyCode</emphasis>
|
||
returns <emphasis>
|
||
True</emphasis>
|
||
if the translation resulted in a keysym, and <emphasis>
|
||
False</emphasis>
|
||
if it resulted in <emphasis>
|
||
NoSymbol</emphasis>
|
||
.
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|