unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

XkbApplyCompatMapToKey(3)        XKB FUNCTIONS       XkbApplyCompatMapToKey(3)



NAME
       XkbApplyCompatMapToKey  -  Apply  the  new  compatibility mapping to an
       individual key to get its semantics updated

SYNOPSIS
       Bool XkbApplyCompatMapToKey ( xkb, key, changes )
             XkbDescPtr xkb;
             KeyCode key;
             XkbChangesPtr changes;

ARGUMENTS
       - xkb  keyboard description to be updated

       - key  key to be updated

       - changes
              notes changes to the Xkb keyboard description

DESCRIPTION
       XkbApplyCompatMapToKey essentially performs the operation described  in
       Core  Keyboard Mapping to Xkb Keyboard Mapping Transformation to a spe-
       cific key. This updates the behavior, actions, repeat status, and  vir-
       tual modifier bindings of the key.

       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 explic-
       itly configured some of the Xkb keyboard mapping in  the  server,  this
       automatic regeneration of the Xkb keyboard mapping from the core proto-
       col keyboard mapping should not modify any components of the  Xkb  key-
       board 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:

       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  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.


       c  s  s  l  l  l l l lw(3i).  Table 1 Explicit Component Masks _ Bit in
       Explicit     Mask Value     Protects     Against     _     ExplicitKey-
       Type1    (1<<0)    T{  Automatic  determination of the key type associ-
       ated with Group1.  T} ExplicitKeyType2    (1<<1)    T{ Automatic deter-
       mination  of  the  key  type  associated  with Group2.  T} ExplicitKey-
       Type3    (1<<2)    T{ Automatic determination of the key  type  associ-
       ated with Group3.  T} ExplicitKeyType4    (1<<3)    T{ Automatic deter-
       mination of the key type associated  with  Group4.   T}  ExplicitInter-
       pret   (1<<4)    T{ Application of any of the fields of a symbol inter-
       pretation 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{  Auto-
       matic  assignment  of  the  XkbKB_Lock  behavior  to  the  key,  if the
       XkbSI_LockingKey flag is set in a symbol interpretation.  T} ExplicitV-
       ModMap     (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}

       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 map-
           ping  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 partition-
           ing 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.

       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.

       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.

       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 exam-
           ple, if the core map contained eight symbols per key, and a partic-
           ular  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):

                         G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3

           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:

              G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3

           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.

       1d. For  each  group on each changed key, assign a key type appropriate
           for the symbols in the group.

       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.

       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).

       2a. For each symbol on each changed key, attempt to  match  the  symbol
           and  modifiers from the Xkb map to a symbol interpretation describ-
           ing how to generate the symbol.

       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.

       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.

       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:

           Virtual modifier map
           Auto repeat
           Key behavior (may be set to XkbKB_Lock)
           Key action

       The XkbSymInterpretRec structure specifies a symbol interpretation:

       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;

       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 mods and match.  If sym is NULL, the interpreta-
       tion may be applied to any symbol selected on a key when the  modifiers
       match the criteria specified by mods and match.

       match  must be one of the values shown in Table 2 and specifies how the
       real modifiers specified in mods are to be interpreted.


       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}

       In addition to the above bits, match may contain the XkbSI_LevelOneOnly
       bit, in which case the modifier match criteria specified  by  mods  and
       match applies only if sym is in level one of its group; otherwise, mods
       and match are ignored and the symbol matches a condition where no modi-
       fiers are set.

       #define XkbSI_LevelOneOnly  (0x80)  /* use mods + match only if sym is level 1 */

       If  no  matching  symbol  interpretation  is  found,  the server uses a
       default interpretation where:

           sym =           0
           flags =         XkbSI_AutoRepeat
           match =         XkbSI_AnyOfOrNone
           mods =          0
           virtual_mod =   XkbNoModifier
           act =           SA_NoAction

       When a matching symbol interpretation is found in step 2a,  the  inter-
       pretation is applied to modify the Xkb map as follows.

       The act field specifies a single action to be bound to the symbol posi-
       tion; 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  exam-
       ined.  If  the XkbSI_LevelOneOnly bit is not set in match or the symbol
       is in position G1L1, the virtual_mod field is examined. If  virtual_mod
       is  not  XkbNoModifier, virtual_mod specifies a single virtual modifier
       to be added to the virtual modifier map for the  key.   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:

       #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 */

       If the Xkb keyboard map for the key does not have  its  ExplicitAutoRe-
       peat 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.

SEE ALSO
       XkbKeyAction(3), XkbKeyActionEntry(3), XkbKeyActionsPtr(3),  XkbKeyHas-
       Actions(3), XkbKeyNumActions(3)



X Version 11                     libX11 1.1.5        XkbApplyCompatMapToKey(3)