man/xkb/XkbSetNames.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 XkbSetNames __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbSetNames \- Change the symbolic names in the server
  26 .SH SYNOPSIS
  27 .HP
  28 .B Bool XkbSetNames
  29 .BI "(\^Display *" "dpy" "\^,"
  30 .BI "unsigned int " "which" "\^,"
  31 .BI "unsigned int " "first_type" "\^,"
  32 .BI "unsigned int " "num_types" "\^,"
  33 .BI "XkbDescPtr " "xkb" "\^);"
  34 .if n .ti +5n
  35 .if t .ti +.5i
  36 .SH ARGUMENTS
  37 .TP
  38 .I \- dpy
  39 connection to the X server
  40 .TP
  41 .I \- which
  42 mask of names or map components to be changed
  43 .TP
  44 .I \- first_type
  45 first type whose name is to be changed
  46 .TP
  47 .I \- num_types
  48 number of types for which names are to be changed
  49 .TP
  50 .I \- xkb
  51 keyboard description from which names are to be taken
  52 .SH DESCRIPTION
  53 .LP
  54 To change the symbolic names in the server, first modify a local copy of the
  55 keyboard description and then
  56 use either
  57 .I XkbSetNames,
  58 or, to save network traffic, use a XkbNameChangesRecstructure and call
  59 .I XkbChangeNames
  60 to download the changes to the server.
  61 .I XkbSetNames
  62 and
  63 .I XkbChangeNames
  64 can generate BadAlloc, BadAtom, BadLength, BadMatch, and BadImplementation
  65 errors.
  66
  67 Use
  68 .I XkbSetNames
  69 to change many names at the same time. For each bit set in
  70 .I which, XkbSetNames
  71 takes the corresponding value (or values in the case of arrays) from the
  72 keyboard description
  73 .I xkb
  74 and sends it to the server.
  75
  76 The
  77 .I first_type
  78 and
  79 .I num_types
  80 arguments are used only if XkbKeyTypeNamesMask or XkbKTLevelNamesMask is set in
  81 .I which
  82 and specify a subset of the types for which the corresponding names are to be
  83 changed. If either or both of
  84 these mask bits are set but the specified types are illegal,
  85 .I XkbSetNames
  86 returns False and does not update any of the names specified in
  87 .I which.
  88 The specified types are illegal if
  89 .I xkb
  90 does not include a map component or if
  91 .I first_type
  92 and
  93 .I num_types
  94 specify types that are not defined in the keyboard description.
  95 .SH STRUCTURES
  96 .LP
  97 The XkbNameChangesRec allows applications to identify small modifications to the
  98 symbolic names and
  99 effectively reduces the amount of traffic sent to the server:
 100 .nf
 101
 102     typedef struct _XkbNameChanges {
 103         unsigned int   changed;          /\(** name components that have changed */
 104         unsigned char  first_type;       /\(** first key type with a new name */
 105         unsigned char  num_types;        /\(** number of types with new names */
 106         unsigned char  first_lvl;        /\(** first key type with new level names
 107 */
 108         unsigned char  num_lvls;         /\(** number of key types with new level
 109 names */
 110         unsigned char  num_aliases;      /\(** if key aliases changed, total number
 111 of key aliases */
 112         unsigned char  num_rg;           /\(** if radio groups changed, total
 113 number of radio groups */
 114         unsigned char  first_key;        /\(** first key with a new name */
 115         unsigned char  num_keys;         /\(** number of keys with new names */
 116         unsigned short changed_vmods;    /\(** mask of virtual modifiers for which
 117 names have changed */
 118         unsigned long  changed_indicators; /\(** mask of indicators for which names
 119 were changed */
 120         unsigned char  changed_groups;     /\(** mask of groups for which names
 121 were changed */
 122     } XkbNameChangesRec, *XkbNameChangesPtr
 123
 124 .fi
 125 The
 126 .I changed
 127 field specifies the name components that have changed and is the bitwise
 128 inclusive OR of the valid names
 129 mask bits defined in Table 1. The rest of the fields in the structure specify
 130 the ranges that have changed
 131 for the various kinds of symbolic names, as shown in Table 2.
 132
 133 Xkb provides several functions that work with symbolic names. Each of these
 134 functions uses a mask to
 135 specify individual fields of the structures described above. These masks and
 136 their relationships to the
 137 fields in a keyboard description are shown in Table 1.
 138
 139 .TS
 140 c s s s
 141 l l l l.
 142 Table 1 Symbolic Names Masks
 143 _
 144 Mask Bit        Value   Keyboard        Field
 145                 Component
 146 _
 147 XkbKeycodesNameMask     (1<<0)  Xkb->names      keycodes
 148 XkbGeometryNameMask     (1<<1)  Xkb->names      geometry
 149 XkbSymbolsNameMask      (1<<2)  Xkb->names      symbols
 150 XkbPhysSymbolsNameMask  (1<<3)  Xkb->names      phys_symbols
 151 XkbTypesNameMask        (1<<4)  Xkb->names      type
 152 XkbCompatNameMask       (1<<5)  Xkb->names      compat
 153 XkbKeyTypeNamesMask     (1<<6)  Xkb->map        type[*].name
 154 XkbKTLevelNamesMask     (1<<7)  Xkb->map        type[*].lvl_names[*]
 155 XkbIndicatorNamesMask   (1<<8)  Xkb->names      indicators[*]
 156 XkbKeyNamesMask (1<<9)  Xkb->names      keys[*], num_keys
 157 XkbKeyAliasesMask       (1<<10) Xkb->names      key_aliases[*], num_key_aliases
 158 XkbVirtualModNamesMask  (1<<11) Xkb->names      vmods[*]
 159 XkbGroupNamesMask       (1<<12) Xkb->names      groups[*]
 160 XkbRGNamesMask  (1<<13) Xkb->names      radio_groups[*], num_rg
 161 XkbComponentNamesMask   (0x3f)  Xkb->names      keycodes,
 162                         geometry,
 163                         symbols,
 164                         physical symbols,
 165                         types, and
 166                         compatibility map
 167 XkbAllNamesMask (0x3fff)        Xkb->names      all name components
 168 .TE
 169
 170 .TS
 171 c s s s
 172 l l l l.
 173 Table 2 XkbNameChanges Fields
 174 _
 175 Mask    Fields  Component       Field
 176 _
 177 XkbKeyTypeNamesMask     first_type,     Xkb->map        type[*].name
 178         num_types
 179 XkbKTLevelNamesMask     first_lvl,      Xkb->map        type[*].lvl_names[*]
 180         num_lvls
 181 XkbKeyAliasesMask       num_aliases     Xkb->names      key_aliases[*]
 182 XkbRGNamesMask  num_rg  Xkb->names      radio_groups[*]
 183 XkbKeyNamesMask first_key,      Xkb->names      keys[*]
 184         num_keys
 185 XkbVirtualModNamesMask  changed_vmods   Xkb->names      vmods[*]
 186 XkbIndicatorNamesMask   changed_indicators      Xkb->names      indicators[*]
 187 XkbGroupNamesMask       changed_groups  Xkb->names      groups[*]
 188 .TE
 189 .SH DIAGNOSTICS
 190 .TP 15
 191 .B BadAlloc
 192 Unable to allocate storage
 193 .TP 15
 194 .B BadAtom
 195 A name is neither a valid Atom or None
 196 .TP 15
 197 .B BadImplementation
 198 Invalid reply from server
 199 .TP 15
 200 .B BadLength
 201 The length of a request is shorter or longer than that required to minimally
 202 contain the arguments
 203 .TP 15
 204 .B BadMatch
 205 A compatible version of Xkb was not available in the server or an argument has
 206 correct type and range, but is otherwise invalid
 207 .SH "SEE ALSO"
 208 .BR XkbChangeNames (__libmansuffix__)