man/xkb/XkbSetMap.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 XkbSetMap __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbSetMap \- Send a complete new set of values for entire components to the
  26 server.
  27 .SH SYNOPSIS
  28 .HP
  29 .B Bool XkbSetMap
  30 .BI "(\^Display *" "dpy" "\^,"
  31 .BI "unsigned int " "which" "\^,"
  32 .BI "XkbDescPtr " "xkb" "\^);"
  33 .if n .ti +5n
  34 .if t .ti +.5i
  35 .SH ARGUMENTS
  36 .TP
  37 .I \- dpy
  38 connection to X server
  39 .TP
  40 .I \- which
  41 mask selecting subcomponents to update
  42 .TP
  43 .I \- xkb
  44 description from which new values are taken
  45 .SH DESCRIPTION
  46 .LP
  47 There are two ways to make changes to map components: either change a local copy
  48 of the keyboard map and
  49 call
  50 .I XkbSetMap
  51 to send the modified map to the server, or, to reduce network traffic, use an
  52 XkbMapChangesRec structure
  53 and call
  54 .I XkbChangeMap.
  55
  56 Use
  57 .I XkbSetMap
  58 to send a complete new set of values for entire components (for example, all
  59 symbols, all actions, and so
  60 on) to the server. The
  61 .I which
  62 parameter specifies the components to be sent to the server, and is a bitwise
  63 inclusive OR of the masks
  64 listed in Table 1. The
  65 .I xkb
  66 parameter is a pointer to an XkbDescRec structure and contains the information
  67 to be copied to the server.
  68 For each bit set in the
  69 .I which
  70 parameter,
  71 .I XkbSetMap
  72 takes the corresponding structure values from the
  73 .I xkb
  74 parameter and sends it to the server specified by
  75 .I dpy.
  76
  77 If any components specified by
  78 .I which
  79 are not present in the
  80 .I xkb
  81 parameter,
  82 .I XkbSetMap
  83 returns False. Otherwise, it sends the update request to the server and returns
  84 True.
  85 .I XkbSetMap
  86 can generate BadAlloc, BadLength, and BadValue protocol errors.
  87
  88 Key types, symbol maps, and actions are all interrelated; changes in one require
  89 changes in the others. Xkb
  90 provides functions to make it easier to edit these components and handle the
  91 interdependencies. Table 1
  92 lists these helper functions and provides a pointer to where they are defined.
  93
  94 .TS
  95 c s s s s
  96 c s s s s
  97 l l l l l
  98 l l l l l
  99 lw(2i) l l lw(1i) lw(3i).
 100 Table 1 Xkb Mapping Component Masks
 101 and Convenience Functions
 102 _
 103 Mask    Value   Map     Fields  Convenience
 104                                 Functions
 105 _
 106 T{
 107 XkbKeyTypesMask
 108 T}      (1<<0)  client  T{
 109 types
 110 .br
 111 size_types
 112 .br
 113 num_types
 114 T}      T{
 115 XkbGetKeyTypes
 116 .br
 117 XkbResizeKeyType
 118 .br
 119 XkbCopyKeyType
 120 .br
 121 XkbCopyKeyTypes
 122 T}
 123 T{
 124 XkbKeySymsMask
 125 T}      (1<<1)  client  T{
 126 syms
 127 .br
 128 size_syms
 129 .br
 130 num_syms
 131 .br
 132 key_sym_map
 133 T}      T{
 134 XkbGetKeySyms
 135 .br
 136 XkbResizeKeySyms
 137 .br
 138 XkbChangeTypesOfKey
 139 T}
 140 T{
 141 XkbModifierMapMask
 142 T}      (1<<2)  client  modmap  T{
 143 XkbGetKeyModifierMap
 144 T}
 145 T{
 146 XkbExplicitComponentsMask
 147 T}      (1<<3)  server  T{
 148 explicit
 149 T}      T{
 150 XkbGetKeyExplicitComponents
 151 T}
 152 T{
 153 XkbKeyActionsMask
 154 T}      (1<<4)  server  T{
 155 key_acts
 156 .br
 157 acts
 158 .br
 159 num_acts
 160 .br
 161 size_acts
 162 T}      T{
 163 XkbGetKeyActions
 164 .br
 165 XkbResizeKeyActions
 166 T}
 167 T{
 168 XkbKeyBehaviorsMask
 169 T}      (1<<5)  server  T{
 170 behaviors
 171 T}      T{
 172 XkbGetKeyBehaviors
 173 T}
 174 T{
 175 XkbVirtualModsMask
 176 T}      (1<<6)  server  T{
 177 vmods
 178 T}      T{
 179 XkbGetVirtualMods
 180 T}
 181 T{
 182 XkbVirtualModMapMask
 183 T}      (1<<7)  server  T{
 184 vmodmap
 185 T}      T{
 186 XkbGetVirtualModMap
 187 T}
 188 .TE
 189
 190 The
 191 .I changed
 192 field identifies the map components that have changed in an XkbDescRec structure
 193 and may contain any of the
 194 bits in Table 1, which are also shown in Table 2. Every 1 bit in
 195 .I changed
 196 also identifies which other fields in the XkbMapChangesRec structure contain
 197 valid values, as indicated in
 198 Table 2. The
 199 .I min_key_code
 200 and
 201 .I max_key_code
 202 fields are for reference only; they are ignored on any requests sent to the
 203 server and are always updated
 204 by the server whenever it returns the data for an XkbMapChangesRec.
 205 .bp
 206 .TS
 207 c s s
 208 l l l
 209 l l l
 210 l l l
 211 l lw(2i) lw(3i).
 212 Table 2 XkbMapChangesRec Masks
 213 _
 214         Valid
 215 Mask    XkbMapChangesRec        XkbDescRec Field Containing
 216         Fields  Changed Data
 217 _
 218 XkbKeyTypesMask first_type,     map->type[first_type] ..
 219         num_types       map->type[first_type + num_types - 1]
 220 .sp
 221 XkbKeySymsMask  first_key_sym,  map->key_sym_map[first_key_sym] ..
 222         num_key_syms    map->key_sym_map[first_key_sym +
 223                 num_key_syms - 1]
 224 XkbModifierMapMask      first_modmap_key,       map->modmap[first_modmap_key] ..
 225         num_modmap_keys map->modmap[first_modmap_key +
 226                 num_modmap_keys-1]
 227 XkbExplicitComponentsMask       first_key_explicit,
 228 server->explicit[first_key_explicit] ..
 229         num_key_explicit        server->explicit[first_key_explicit +
 230                 num_key_explicit - 1]
 231 XkbKeyActionsMask       first_key_act,  server->key_acts[first_key_act] ..
 232         num_key_acts    server->key_acts[first_key_act +
 233                 num_key_acts - 1]
 234 XkbKeyBehaviorsMask     first_key_behavior,
 235 server->behaviors[first_key_behavior] ..
 236         num_key_behaviors       server->behaviors[first_key_behavior +
 237                 num_key_behaviors - 1]
 238 XkbVirtualModsMask      vmods   server->vmods[*]
 239 XkbVirtualModMapMask    first_vmodmap_key,
 240 server->vmodmap[first_vmodmap_key]
 241         num_vmodmap_keys         ..
 242                 server->vmodmap[first_vmodmap_key
 243                 + num_vmodmap_keys - 1]
 244 .TE
 245 .SH "RETURN VALUES"
 246 .TP 15
 247 True
 248 The
 249 .I XkbSetMap
 250 function returns True all components specified by
 251 .I which
 252 are present in the
 253 .I xkb
 254 parameter.
 255 .TP 15
 256 False
 257 The
 258 .I XkbSetMap
 259 function returns False if any component specified by
 260 .I which
 261 is not present in the
 262 .I xkb
 263 parameter.
 264 .SH STRUCTURES
 265 .LP
 266
 267 Use the XkbMapChangesRec structure to identify and track partial modifications
 268 to the mapping components
 269 and to reduce the amount of traffic between the server and clients.
 270 .nf
 271
 272 typedef struct _XkbMapChanges {
 273     unsigned short   changed;            /\(** identifies valid components in structure */
 274     KeyCode          min_key_code;       /\(** lowest numbered keycode for device */
 275     KeyCode          max_key_code;       /\(** highest numbered keycode for device */
 276     unsigned char    first_type;         /\(** index of first key type modified */
 277     unsigned char    num_types;          /\(** # types modified */
 278     KeyCode          first_key_sym;      /\(** first key whose key_sym_map changed */
 279     unsigned char    num_key_syms;       /\(** # key_sym_map entries changed */
 280     KeyCode          first_key_act;      /\(** first key whose key_acts entry changed */
 281     unsigned char    num_key_acts;       /\(** # key_acts entries changed */
 282     KeyCode          first_key_behavior; /\(** first key whose behaviors changed */
 283     unsigned char    num_key_behaviors;  /\(** # behaviors entries changed */
 284     KeyCode          first_key_explicit; /\(** first key whose explicit entry changed */
 285     unsigned char    num_key_explicit;   /\(** # explicit entries changed */
 286     KeyCode          first_modmap_key;   /\(** first key whose modmap entry changed */
 287     unsigned char    num_modmap_keys;    /\(** # modmap entries changed */
 288     KeyCode          first_vmodmap_key;  /\(** first key whose vmodmap changed */
 289     unsigned char    num_vmodmap_keys;   /\(** # vmodmap entries changed */
 290     unsigned char    pad1;               /\(** reserved */
 291     unsigned short   vmods;              /\(** mask indicating which vmods changed */
 292 } XkbMapChangesRec,*XkbMapChangesPtr;
 293
 294 .fi
 295
 296 The complete description of an Xkb keyboard is given by an XkbDescRec. The
 297 component
 298 structures in the XkbDescRec represent the major Xkb components.
 299
 300 .nf
 301 typedef struct {
 302    struct _XDisplay * display;      /\(** connection to X server */
 303    unsigned short     flags;        /\(** private to Xkb, do not modify */
 304    unsigned short     device_spec;  /\(** device of interest */
 305    KeyCode            min_key_code; /\(** minimum keycode for device */
 306    KeyCode            max_key_code; /\(** maximum keycode for device */
 307    XkbControlsPtr     ctrls;        /\(** controls */
 308    XkbServerMapPtr    server;       /\(** server keymap */
 309    XkbClientMapPtr    map;          /\(** client keymap */
 310    XkbIndicatorPtr    indicators;   /\(** indicator map */
 311    XkbNamesPtr        names;        /\(** names for all components */
 312    XkbCompatMapPtr    compat;       /\(** compatibility map */
 313    XkbGeometryPtr     geom;         /\(** physical geometry of keyboard */
 314 } XkbDescRec, *XkbDescPtr;
 315
 316 .fi
 317 The
 318 .I display
 319 field points to an X display structure. The
 320 .I flags field is private to the library: modifying
 321 .I flags
 322 may yield unpredictable results. The
 323 .I device_spec
 324 field specifies the device identifier of the keyboard input device, or
 325 XkbUseCoreKeyboard, which specifies the core keyboard device. The
 326 .I min_key_code
 327 and
 328 .I max_key_code
 329 fields specify the least and greatest keycode that can be returned by the
 330 keyboard.
 331
 332 Each structure component has a corresponding mask bit that is used in function
 333 calls to
 334 indicate that the structure should be manipulated in some manner, such as
 335 allocating it
 336 or freeing it. These masks and their relationships to the fields in the
 337 XkbDescRec are
 338 shown in Table 3.
 339 .bp
 340 .TS
 341 c s s
 342 l l l
 343 l l l.
 344 Table 3 Mask Bits for XkbDescRec
 345 _
 346 Mask Bit        XkbDescRec Field        Value
 347 _
 348 XkbControlsMask ctrls   (1L<<0)
 349 XkbServerMapMask        server  (1L<<1)
 350 XkbIClientMapMask       map     (1L<<2)
 351 XkbIndicatorMapMask     indicators      (1L<<3)
 352 XkbNamesMask    names   (1L<<4)
 353 XkbCompatMapMask        compat  (1L<<5)
 354 XkbGeometryMask geom    (1L<<6)
 355 XkbAllComponentsMask    All Fields      (0x7f)
 356 .TE
 357 .SH DIAGNOSTICS
 358 .TP 15
 359 .B BadAlloc
 360 Unable to allocate storage
 361 .TP 15
 362 .B BadLength
 363 The length of a request is shorter or longer than that required to minimally
 364 contain the arguments
 365 .TP 15
 366 .B BadValue
 367 An argument is out of range
 368 .SH "SEE ALSO"
 369 .BR XkbChangeMap (__libmansuffix__),
 370 .BR XkbChangeTypesOfKey (__libmansuffix__),
 371 .BR XkbCopyKeyType (__libmansuffix__),
 372 .BR XkbCopyKeyTypes (__libmansuffix__),
 373 .BR XkbGetKeyActions (__libmansuffix__),
 374 .BR XkbGetKeyBehaviors (__libmansuffix__),
 375 .BR XkbGetKeyExplicitComponents (__libmansuffix__),
 376 .BR XkbGetKeyModifierMap (__libmansuffix__),
 377 .BR XkbGetKeySyms (__libmansuffix__),
 378 .BR XkbGetKeyTypes (__libmansuffix__),
 379 .BR XkbResizeKeyActions (__libmansuffix__),
 380 .BR XkbResizeKeySyms (__libmansuffix__),
 381 .BR XkbResizeKeyType (__libmansuffix__),
 382 .BR XkbGetVirtualModMap (__libmansuffix__),
 383 .BR XkbGetVirtualMods (__libmansuffix__)