2 .\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
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:
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
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.
23 .TH XkbSetNames __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
25 XkbSetNames \- Change the symbolic names in the server
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" "\^);"
39 connection to the X server
42 mask of names or map components to be changed
45 first type whose name is to be changed
48 number of types for which names are to be changed
51 keyboard description from which names are to be taken
54 To change the symbolic names in the server, first modify a local copy of the
55 keyboard description and then
58 or, to save network traffic, use a XkbNameChangesRecstructure and call
60 to download the changes to the server.
64 can generate BadAlloc, BadAtom, BadLength, BadMatch, and BadImplementation
69 to change many names at the same time. For each bit set in
71 takes the corresponding value (or values in the case of arrays) from the
74 and sends it to the server.
80 arguments are used only if XkbKeyTypeNamesMask or XkbKTLevelNamesMask is set in
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,
86 returns False and does not update any of the names specified in
88 The specified types are illegal if
90 does not include a map component or if
94 specify types that are not defined in the keyboard description.
97 The XkbNameChangesRec allows applications to identify small modifications to the
99 effectively reduces the amount of traffic sent to the server:
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
108 unsigned char num_lvls; /\(** number of key types with new level
110 unsigned char num_aliases; /\(** if key aliases changed, total number
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
120 unsigned char changed_groups; /\(** mask of groups for which names
122 } XkbNameChangesRec, *XkbNameChangesPtr
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.
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.
142 Table 1 Symbolic Names Masks
144 Mask Bit Value Keyboard Field
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,
167 XkbAllNamesMask (0x3fff) Xkb->names all name components
173 Table 2 XkbNameChanges Fields
175 Mask Fields Component Field
177 XkbKeyTypeNamesMask first_type, Xkb->map type[*].name
179 XkbKTLevelNamesMask first_lvl, Xkb->map type[*].lvl_names[*]
181 XkbKeyAliasesMask num_aliases Xkb->names key_aliases[*]
182 XkbRGNamesMask num_rg Xkb->names radio_groups[*]
183 XkbKeyNamesMask first_key, Xkb->names keys[*]
185 XkbVirtualModNamesMask changed_vmods Xkb->names vmods[*]
186 XkbIndicatorNamesMask changed_indicators Xkb->names indicators[*]
187 XkbGroupNamesMask changed_groups Xkb->names groups[*]
192 Unable to allocate storage
195 A name is neither a valid Atom or None
198 Invalid reply from server
201 The length of a request is shorter or longer than that required to minimally
202 contain the arguments
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
208 .BR XkbChangeNames (__libmansuffix__)