XkbApplyCompatMapToKey man page on Debian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Debian logo
[printable version]

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

		      Table 1 Explicit Component Masks
       ───────────────────────────────────────────────────────────────
       Bit in Explicit Mask   Value    Protects Against
       ───────────────────────────────────────────────────────────────
       ExplicitKeyType1	      (1<<0)   Automatic determination of the
				       key   type   associated	 with
				       Group1.

       ExplicitKeyType2	      (1<<1)   Automatic determination of the
				       key   type   associated	 with
				       Group2.
       ExplicitKeyType3	      (1<<2)   Automatic determination of the
				       key   type   associated	 with
				       Group3.
       ExplicitKeyType4	      (1<<3)   Automatic determination of the
				       key   type   associated	 with
				       Group4.
       ExplicitInterpret      (1<<4)   Application  of	any  of	  the
				       fields of a symbol interpreta‐
				       tion to the key in question.
       ExplicitAutoRepeat     (1<<5)   Automatic   determination   of
				       auto-repeat   status  for  the
				       key, as specified in a  symbol
				       interpretation.
       ExplicitBehavior	      (1<<6)   Automatic  assignment  of  the
				       XkbKB_Lock  behavior  to	  the
				       key,  if	 the XkbSI_LockingKey
				       flag is set in a symbol inter‐
				       pretation.
       ExplicitVModMap	      (1<<7)   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.

       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.

	      Table 2 Symbol Interpretation Match Criteria
       ───────────────────────────────────────────────────────────
       Match Criteria	   Value   Effect
       ───────────────────────────────────────────────────────────
       XkbSI_NoneOf	   (0)	   None	 of  the bits that are on
				   in mods can be set, but  other
				   bits can be.
       XkbSI_AnyOfOrNone   (1)	   Zero	 or more of the bits that
				   are on in mods can be set,  as
				   well as others.
       XkbSI_AnyOf	   (2)	   One	or  more of the bits that
				   are on in mods can be set,  as
				   well as any others.
       XkbSI_AllOf	   (3)	   All of the bits that are on in
				   mods must be set,  but  others
				   may be set as well.
       XkbSI_Exactly	   (4)	   All of the bits that are on in
				   mods must be set, and no other
				   bits may be set.

       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.3.3	     XkbApplyCompatMapToKey(3)
[top]

List of man pages available for Debian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net