man/xkb/XkbKeyTypesForCoreSymbols.man

   1 '\" t
   2 .\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a
   5 .\" copy of this software and associated documentation files (the "Software"),
   6 .\" to deal in the Software without restriction, including without limitation
   7 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 .\" and/or sell copies of the Software, and to permit persons to whom the
   9 .\" Software is furnished to do so, subject to the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice (including the next
  12 .\" paragraph) shall be included in all copies or substantial portions of the
  13 .\" Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21 .\" DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .TH XkbKeyTypesForCoreSymbols __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbKeyTypesForCoreSymbols \- Determine the Xkb key types appropriate for the
  26 symbols bound to a key in a core keyboard mapping
  27 .SH SYNOPSIS
  28 .HP
  29 .B int XkbKeyTypesForCoreSymbols
  30 .BI "(\^XkbDescPtr " "xkb" "\^,"
  31 .BI "int " "map_width" "\^,"
  32 .BI "KeySym *" "core_syms" "\^,"
  33 .BI "unsigned int " "protected" "\^,"
  34 .BI "int *" "types_inout" "\^,"
  35 .BI "KeySym *" "xkb_syms_rtrn" "\^);"
  36 .if n .ti +5n
  37 .if t .ti +.5i
  38 .SH ARGUMENTS
  39 .TP
  40 .I \- xkb
  41 keyboard description in which to place symbols
  42 .TP
  43 .I \- map_width
  44 width of core protocol keymap in xkb_syms_rtrn
  45 .TP
  46 .I \- core_syms
  47 core protocol format array of KeySyms
  48 .TP
  49 .I \- protected
  50 explicit key types
  51 .TP
  52 .I \- types_inout
  53 backfilled with the canonical types bound to groups one and two for the key
  54 .TP
  55 .I \- xkb_syms_rtrn
  56 backfilled with symbols bound to the key in the Xkb mapping
  57 .SH DESCRIPTION
  58 .LP
  59 .I XkbKeyTypesForCoreSymbols
  60 expands the symbols in
  61 .I core_syms
  62 and types in
  63 .I types_inout,
  64 then chooses canonical key types (canonical key types are
  65 defined The Canonical Key Types) for groups 1 and 2 using the rules specified by
  66 the Xkb protocol and places them in xkb_syms_rtrn, which will be non-NULL.
  67
  68 .B The Canonical Key Types
  69
  70 Xkb allows up to XkbMaxKeyTypes (255) key types to be defined, but requires at
  71 least XkbNumRequiredTypes (4) predefined types to be in a key map. These
  72 predefined key types are referred to as the canonical key types and describe the
  73 types of keys available on most keyboards. The definitions for the canonical key
  74 types are held in the first XkbNumRequiredTypes entries of the
  75 .I types
  76 field of the client map and are indexed using the following constants:
  77 .nf
  78
  79     XkbOneLevelIndex
  80     XkbTwoLevelIndex
  81     XkbAlphabeticIndex
  82     XkbKeypadIndex
  83
  84 .fi
  85
  86 ONE_LEVEL
  87
  88 The ONE_LEVEL key type describes groups that have only one symbol. The default
  89 ONE_LEVEL key type has no map entries and does not pay attention to any
  90 modifiers. A symbolic representation of this key type could look like the
  91 following:
  92 .nf
  93
  94     type "ONE_LEVEL" {
  95          modifiers = None;
  96          map[None]= Level1;
  97          level_name[Level1]= "Any";
  98     };
  99
 100 .fi
 101 The description of the ONE_LEVEL key type is stored in the
 102 types[XkbOneLevelIndex] entry of the client key map.
 103
 104 TWO_LEVEL
 105
 106 The TWO_LEVEL key type describes groups that consist of two symbols but are
 107 neither alphabetic nor numeric keypad keys. The default TWO_LEVEL type uses only
 108 the Shift modifier. It returns shift level two if Shift is set, and level one if
 109 it is not. A symbolic representation of this key type could look like the
 110 following:
 111 .nf
 112
 113     type "TWO_LEVEL" {
 114         modifiers = Shift;
 115         map[Shift]= Level2;
 116         level_name[Level1]= "Base";
 117         level_name[Level2]= "Shift";
 118     };
 119
 120 .fi
 121
 122 The description of the TWO_LEVEL key type is stored in the
 123 types[XkbTwoLevelIndex] entry of the client key map.
 124
 125 ALPHABETIC
 126
 127 The ALPHABETIC key type describes groups consisting of two symbols: the
 128 lowercase form of a symbol followed by the uppercase form of the same symbol.
 129 The default ALPHABETIC type implements locale-sensitive "Shift cancels CapsLock"
 130 behavior using both the Shift and Lock modifiers as follows:
 131
 132 .IP \(bu 5
 133 If Shift and Lock are both set, the default ALPHABETIC type yields level one.
 134 .IP \(bu 5
 135 If Shift alone is set, it yields level two.
 136 .IP \(bu 5
 137 If Lock alone is set, it yields level one, but preserves the Lock modifier so
 138 Xlib notices and applies the appropriate capitalization rules. The Xlib
 139 functions are locale-sensitive and apply different capitalization rules for
 140 different locales.
 141 .IP \(bu 5
 142 If neither Shift nor Lock is set, it yields level one.
 143
 144 A symbolic representation of this key type could look like the following:
 145 .nf
 146
 147     type "ALPHABETIC" {
 148         modifiers = Shift+Lock;
 149         map[Shift]= Level2;
 150         preserve[Lock]= Lock;
 151         level_name[Level1]= "Base";
 152         level_name[Level2]= "Caps";
 153     };
 154
 155 .fi
 156 The description of the ALPHABETIC key type is stored in the
 157 types[XkbAlphabeticIndex] entry of the client key map.
 158
 159 KEYPAD
 160
 161 The KEYPAD key type describes groups that consist of two symbols, at least one
 162 of which is a numeric keypad symbol. The numeric keypad symbol is assumed to
 163 reside at level two. The default KEYPAD key type implements "Shift cancels
 164 NumLock" behavior using the Shift modifier and the real modifier bound to the
 165 virtual modifier named "NumLock," known as the NumLock modifier, as follows:
 166
 167 .IP \(bu 5
 168 If Shift and NumLock are both set, the default KEYPAD type yields level one.
 169 .IP \(bu 5
 170 If Shift alone is set, it yields level two.
 171 .IP \(bu 5
 172 If NumLock alone is set, it yields level two.
 173 .IP \(bu 5
 174 If neither Shift nor NumLock is set, it yields level one.
 175
 176 A symbolic representation of this key type could look like the following:
 177 .nf
 178
 179     type "KEYPAD" {
 180         modifiers = Shift+NumLock;
 181         map[None]= Level1;
 182         map[Shift]= Level2;
 183         map[NumLock]= Level2;
 184         map[Shift+NumLock]= Level1;
 185         level_name[Level1]= "Base";
 186         level_name[Level2]= "Caps";
 187     };
 188
 189 .fi
 190 The description of the KEYPAD key type is stored in the types[XkbKeypadIndex]
 191 entry of the client key map.
 192
 193 A core keymap is a two-dimensional array of keysyms. It has
 194 .I map_width
 195 columns and
 196 .I max_key_code
 197 rows.
 198 .I XkbKeyTypesForCoreSymbols
 199 takes a single row from a core keymap, determines the number of groups
 200 associated with it, the type of each group, and the symbols bound to each group.
 201 The return value is the number of groups,
 202 .I types_inout
 203 has the types for each group, and
 204 .I xkb_syms_rtrn
 205 has the symbols in Xkb order (that is, groups are contiguous, regardless of
 206 size).
 207
 208 .I protected
 209 contains the explicitly protected key types. There is one  explicit override
 210 control associated with each of the four possible groups for each Xkb key,
 211 ExplicitKeyType1 through ExplicitKeyType4;
 212 .I protected
 213 is an inclusive OR of these controls.
 214 .I map_width
 215 is the width of the core keymap and is not dependent on any Xkb definitions.
 216 .I types_inout
 217 is an array of four type indices. On input,
 218 .I types_inout
 219 contains the indices of any types already assigned to the key, in case they are
 220 explicitly protected from change.
 221
 222 Upon return,
 223 .I types_inout
 224 contains any automatically selected (that is, canonical) types plus any
 225 protected types. Canonical types are assigned to all four groups if there are
 226 enough symbols to do so. The four entries in
 227 .I types_inout
 228 correspond to the four groups for the key in question.