377 lines
15 KiB
Groff
377 lines
15 KiB
Groff
'\" t
|
|
.\" Copyright (c) 1999 - Sun Microsystems, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a
|
|
.\" copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, and/or sell copies of the Software, and to permit persons
|
|
.\" to whom the Software is furnished to do so, provided that the above
|
|
.\" copyright notice(s) and this permission notice appear in all copies of
|
|
.\" the Software and that both the above copyright notice(s) and this
|
|
.\" permission notice appear in supporting documentation.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
|
.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
|
|
.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
|
|
.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
|
|
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
|
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
|
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of a copyright holder
|
|
.\" shall not be used in advertising or otherwise to promote the sale, use
|
|
.\" or other dealings in this Software without prior written authorization
|
|
.\" of the copyright holder.
|
|
.\"
|
|
.TH XkbApplyCompatMapToKey __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
|
|
.SH NAME
|
|
XkbApplyCompatMapToKey \- Apply the new compatibility mapping to an individual
|
|
key to get its semantics updated
|
|
.SH SYNOPSIS
|
|
.B Bool XkbApplyCompatMapToKey
|
|
(
|
|
.I xkb,
|
|
.I key,
|
|
.I changes
|
|
)
|
|
.br
|
|
XkbDescPtr \fIxkb\fP\^;
|
|
.br
|
|
KeyCode \fIkey\fP\^;
|
|
.br
|
|
XkbChangesPtr \fIchanges\fP\^;
|
|
.if n .ti +5n
|
|
.if t .ti +.5i
|
|
.SH ARGUMENTS
|
|
.TP
|
|
.I \- xkb
|
|
keyboard description to be updated
|
|
.TP
|
|
.I \- key
|
|
key to be updated
|
|
.TP
|
|
.I \- changes
|
|
notes changes to the Xkb keyboard description
|
|
.SH DESCRIPTION
|
|
.LP
|
|
.I XkbApplyCompatMapToKey
|
|
essentially performs the operation described in Core Keyboard Mapping to Xkb
|
|
Keyboard Mapping Transformation to a specific key. This updates the behavior,
|
|
actions, repeat status, and virtual modifier bindings of the key.
|
|
|
|
.B Core Keyboard Mapping to Xkb Keyboard Mapping Transformation
|
|
|
|
When a core protocol keyboard mapping request is received by the server, the
|
|
server's core keyboard map is updated, and then the Xkb map maintained by the
|
|
server is updated. Because a client may have explicitly configured some of the
|
|
Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
|
|
keyboard mapping from the core protocol keyboard mapping should not modify any
|
|
components of the Xkb keyboard mapping that were explicitly set by a client. The
|
|
client must set explicit override controls to prevent this from happening (see
|
|
Explicit Components-Avoiding Automatic Remapping by the Server). The core-to-Xkb
|
|
mapping is done as follows:
|
|
|
|
.B Explicit Components-Avoiding Automatic Remapping by the Server
|
|
|
|
Whenever a client remaps the keyboard using core protocol requests, Xkb examines
|
|
the map to determine likely default values for the components that cannot be
|
|
specified using the core protocol.
|
|
|
|
This automatic remapping might replace definitions explicitly requested by an
|
|
application, so the Xkb keyboard description defines an explicit components mask
|
|
for each key. Any aspects of the automatic remapping listed in the explicit
|
|
components mask for a key are not changed by the automatic keyboard mapping.
|
|
|
|
The explicit components masks are held in the
|
|
.I explicit
|
|
field of the server map, which is an array indexed by keycode. Each entry in
|
|
this array is a mask that is a bitwise inclusive OR of the values shown in Table
|
|
1.
|
|
|
|
.TS
|
|
c s s
|
|
l l l
|
|
l l lw(3i).
|
|
Table 1 Explicit Component Masks
|
|
_
|
|
Bit in Explicit Mask Value Protects Against
|
|
_
|
|
ExplicitKeyType1 (1<<0) T{
|
|
Automatic determination of the key type associated with Group1.
|
|
T}
|
|
ExplicitKeyType2 (1<<1) T{
|
|
Automatic determination of the key type associated with Group2.
|
|
T}
|
|
ExplicitKeyType3 (1<<2) T{
|
|
Automatic determination of the key type associated with Group3.
|
|
T}
|
|
ExplicitKeyType4 (1<<3) T{
|
|
Automatic determination of the key type associated with Group4.
|
|
T}
|
|
ExplicitInterpret (1<<4) T{
|
|
Application of any of the fields of a symbol interpretation to the key in
|
|
question.
|
|
T}
|
|
ExplicitAutoRepeat (1<<5) T{
|
|
Automatic determination of auto-repeat status for the key, as specified in a
|
|
symbol interpretation.
|
|
T}
|
|
ExplicitBehavior (1<<6) T{
|
|
Automatic assignment of the XkbKB_Lock behavior to the key, if the
|
|
XkbSI_LockingKey flag is set in a symbol interpretation.
|
|
T}
|
|
ExplicitVModMap (1<<7) T{
|
|
Automatic determination of the virtual modifier map for the key based on the
|
|
actions assigned to the key and the symbol interpretations that match the key.
|
|
T}
|
|
.TE
|
|
.TP 4
|
|
1.
|
|
Map the symbols from the keys in the core keyboard map to groups and symbols on
|
|
keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
|
|
each key in the core mapping has the same number of symbols associated with it.
|
|
The Xkb mapping allows a different number of symbols to be associated with each
|
|
key; those symbols may be divided into a different number of groups (1-4) for
|
|
each key. For each key, this process therefore involves partitioning the fixed
|
|
number of symbols from the core mapping into a set of variable-length groups
|
|
with a variable number of symbols in each group. For example, if the core
|
|
protocol map is of width five, the partition for one key might result in one
|
|
group with two symbols and another with three symbols. A different key might
|
|
result in two groups with two symbols plus a third group with one symbol. The
|
|
core protocol map requires at least two symbols in each of the first two groups.
|
|
.TP 4
|
|
1a.
|
|
For each changed key, determine the number of groups represented in the new core
|
|
keyboard map. This results in a tentative group count for each key in the Xkb
|
|
map.
|
|
.TP 4
|
|
1b.
|
|
For each changed key, determine the number of symbols in each of the groups
|
|
found in step 1a. There is one explicit override control associated with each of
|
|
the four possible groups for each Xkb key, ExplicitKeyType1 through
|
|
ExplicitKeyType4. If no explicit override control is set for a group, the number
|
|
of symbols used for that group from the core map is two. If the explicit
|
|
override control is set for a group on the key, the number of symbols used for
|
|
that Xkb group from the core map is the width of the Xkb group with one
|
|
exception: because of the core protocol requirement for at least two symbols in
|
|
each of groups one and two, the number of symbols used for groups one and two is
|
|
the maximum of 2 or the width of the Xkb group.
|
|
.TP 4
|
|
1c.
|
|
For each changed key, assign the symbols in the core map to the appropriate
|
|
group on the key. If the total number of symbols required by the Xkb map for a
|
|
particular key needs more symbols than the core protocol map contains, the
|
|
additional symbols are taken to be NoSymbol keysyms appended to the end of the
|
|
core set. If the core map contains more symbols than are needed by the Xkb map,
|
|
trailing symbols in the core map are discarded. In the absence of an explicit
|
|
override for group one or two, symbols are assigned in order by group; the first
|
|
symbols in the core map are assigned to group one, in order, followed by group
|
|
two, and so on. For example, if the core map contained eight symbols per key,
|
|
and a particular Xkb map contained 2 symbols for G1 and G2 and three for G3, the
|
|
symbols would be assigned as (G is group, L is shift level):
|
|
.nf
|
|
|
|
G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
|
|
|
|
.fi
|
|
If an explicit override control is set for group one or two, the symbols are
|
|
taken from the core set in a somewhat different order. The first four symbols
|
|
from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If group
|
|
one requires more symbols, they are taken next, and then any additional symbols
|
|
needed by group two. Group three and four symbols are taken in complete sequence
|
|
after group two. For example, a key with four groups and three symbols in each
|
|
group would take symbols from the core set in the following order:
|
|
.nf
|
|
|
|
G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
|
|
|
|
.fi
|
|
As previously noted, the core protocol map requires at lease two symbols in
|
|
groups one and two. Because of this, if an explicit override control for an Xkb
|
|
key is set and group one and / or group two is of width one, it is not possible
|
|
to generate the symbols taken from the core protocol set and assigned to
|
|
position G1L2 and / or G2L2.
|
|
.TP 4
|
|
1d.
|
|
For each group on each changed key, assign a key type appropriate for the
|
|
symbols in the group.
|
|
.TP 4
|
|
1e.
|
|
For each changed key, remove any empty or redundant groups.
|
|
|
|
At this point, the groups and their associated symbols have been assigned to the
|
|
corresponding key definitions in the Xkb map.
|
|
.TP 4
|
|
2.
|
|
Apply symbol interpretations to modify key operation. This phase is completely
|
|
skipped if the ExplicitInterpret override control bit is set in the explicit
|
|
controls mask for the Xkb key (see Explicit Components-Avoiding Automatic
|
|
Remapping by the Server).
|
|
.TP 4
|
|
2a.
|
|
For each symbol on each changed key, attempt to match the symbol and modifiers
|
|
from the Xkb map to a symbol interpretation describing how to generate the
|
|
symbol.
|
|
.TP 4
|
|
2b.
|
|
When a match is found in step 2a, apply the symbol interpretation to change the
|
|
semantics associated with the symbol in the Xkb key map. If no match is found,
|
|
apply a default interpretation.
|
|
.LP
|
|
The symbol interpretations used in step 2 are configurable and may be specified
|
|
using XkbSymInterpretRec structures referenced by the sym_interpret field of an
|
|
XkbCompatMapRec.
|
|
|
|
.B Symbol Interpretations - the XkbSymInterpretRec Structure
|
|
|
|
Symbol interpretations are used to guide the X server when it modifies the Xkb
|
|
keymap in step 2. An initial set of symbol interpretations is loaded by the
|
|
server when it starts. A client may add new ones using XkbSetCompatMap.
|
|
|
|
Symbol interpretations result in key semantics being set. When a symbol
|
|
interpretation is applied, the following components of server key event
|
|
processing may be modified for the particular key involved:
|
|
.nf
|
|
|
|
Virtual modifier map
|
|
Auto repeat
|
|
Key behavior (may be set to XkbKB_Lock)
|
|
Key action
|
|
|
|
.fi
|
|
The XkbSymInterpretRec structure specifies a symbol interpretation:
|
|
.nf
|
|
|
|
typedef struct {
|
|
KeySym sym; /\(** keysym of interest or NULL */
|
|
unsigned char flags; /\(** XkbSI_AutoRepeat, XkbSI_LockingKey */
|
|
unsigned char match; /\(** specifies how mods is interpreted */
|
|
unsigned char mods; /\(** modifier bits, correspond to eight real modifiers */
|
|
unsigned char virtual_mod; /\(** 1 modifier to add to key virtual mod map */
|
|
XkbAnyAction act; /\(** action to bind to symbol position on key */
|
|
} XkbSymInterpretRec,*XkbSymInterpretPtr;
|
|
|
|
.fi
|
|
If sym is not NULL, it limits the symbol interpretation to keys on which that
|
|
particular keysym is selected by the modifiers matching the criteria specified
|
|
by
|
|
.I mods
|
|
and
|
|
.I match.
|
|
If
|
|
.I sym
|
|
is NULL, the interpretation may be applied to any symbol selected on a key when
|
|
the modifiers match the criteria specified by
|
|
.I mods
|
|
and
|
|
.I match.
|
|
|
|
.I match
|
|
must be one of the values shown in Table 2 and specifies how the real modifiers
|
|
specified in
|
|
.I mods
|
|
are to be interpreted.
|
|
|
|
.TS
|
|
c s s
|
|
l l l
|
|
l l lw(3i).
|
|
Table 2 Symbol Interpretation Match Criteria
|
|
_
|
|
Match Criteria Value Effect
|
|
_
|
|
XkbSI_NoneOf (0) T{
|
|
None of the bits that are on in mods can be set, but other bits can be.
|
|
T}
|
|
XkbSI_AnyOfOrNone (1) T{
|
|
Zero or more of the bits that are on in mods can be set, as well as others.
|
|
T}
|
|
XkbSI_AnyOf (2) T{
|
|
One or more of the bits that are on in mods can be set, as well as any others.
|
|
T}
|
|
XkbSI_AllOf (3) T{
|
|
All of the bits that are on in mods must be set, but others may be set as well.
|
|
T}
|
|
XkbSI_Exactly (4) T{
|
|
All of the bits that are on in mods must be set, and no other bits may be set.
|
|
T}
|
|
.TE
|
|
|
|
In addition to the above bits,
|
|
.I match
|
|
may contain the XkbSI_LevelOneOnly bit, in which case the modifier match
|
|
criteria specified by
|
|
.I mods
|
|
and
|
|
.I match
|
|
applies only if
|
|
.I sym
|
|
is in level one of its group; otherwise,
|
|
.I mods
|
|
and
|
|
.I match
|
|
are ignored and the symbol matches a condition where no modifiers are set.
|
|
.nf
|
|
|
|
\&#define XkbSI_LevelOneOnly (0x80) /\(** use mods + match only if sym is level 1 */
|
|
|
|
.fi
|
|
If no matching symbol interpretation is found, the server uses a default
|
|
interpretation where:
|
|
.nf
|
|
|
|
sym = 0
|
|
flags = XkbSI_AutoRepeat
|
|
match = XkbSI_AnyOfOrNone
|
|
mods = 0
|
|
virtual_mod = XkbNoModifier
|
|
act = SA_NoAction
|
|
|
|
.fi
|
|
When a matching symbol interpretation is found in step 2a, the interpretation is
|
|
applied to modify the Xkb map as follows.
|
|
|
|
The
|
|
.I act
|
|
field specifies a single action to be bound to the symbol position; any key event that selects the symbol
|
|
causes the action to be taken. Valid actions are defined in Key Actions.
|
|
|
|
If the Xkb keyboard map for the key does not have its ExplicitVModMap control set, the XkbSI_LevelOneOnly bit
|
|
and symbol position are examined. If the XkbSI_LevelOneOnly bit is not set in
|
|
.I match
|
|
or the symbol is in position G1L1, the
|
|
.I virtual_mod
|
|
field is examined. If
|
|
.I virtual_mod
|
|
is not XkbNoModifier,
|
|
.I virtual_mod
|
|
specifies a single virtual modifier to be added to the virtual modifier map for the key.
|
|
.I virtual_mod
|
|
is specified as an index in the range [0..15].
|
|
|
|
If the matching symbol is in position G1L1 of the key, two bits in the flags field potentially specify
|
|
additional behavior modifications:
|
|
.nf
|
|
|
|
\&#define XkbSI_AutoRepeat (1<<0) /\(** key repeats if sym is in position G1L1 */
|
|
\&#define XkbSI_LockingKey (1<<1) /\(** set KB_Lock behavior if sym is in psn G1L1 */
|
|
|
|
.fi
|
|
If the Xkb keyboard map for the key does not have its ExplicitAutoRepeat control set, its auto repeat behavior
|
|
is set based on the value of the XkbSI_AutoRepeat bit. If the XkbSI_AutoRepeat bit is set, the auto-repeat
|
|
behavior of the key is turned on; otherwise, it is turned off.
|
|
|
|
If the Xkb keyboard map for the key does not have its ExplicitBehavior control set, its locking behavior is
|
|
set based on the value of the XkbSI_LockingKey bit. If XkbSI_LockingKey is set, the key behavior is set to
|
|
KB_Lock; otherwise, it is turned off.
|
|
.SH "SEE ALSO"
|
|
.BR XkbKeyAction (__libmansuffix__),
|
|
.BR XkbKeyActionEntry (__libmansuffix__),
|
|
.BR XkbKeyActionsPtr (__libmansuffix__),
|
|
.BR XkbKeyHasActions (__libmansuffix__),
|
|
.BR XkbKeyNumActions (__libmansuffix__)
|