1XkbGetKeyboardByName(3)          XKB FUNCTIONS         XkbGetKeyboardByName(3)
2
3
4

NAME

6       XkbGetKeyboardByName  -  Build a new keyboard description from a set of
7       named components, and to optionally have the server use  the  resulting
8       description to replace an active one
9

SYNOPSIS

11       XkbDescPtr    XkbGetKeyboardByName    (Display   *dpy,   unsigned   int
12              device_spec,  XkbComponentNamesPtr  names,  unsigned  int  want,
13              unsigned int need, Bool load);
14

ARGUMENTS

16       - dpy  connection to X server
17
18       - device_spec
19              device ID, or XkbUseCoreKbd
20
21       - names
22              names of components to fetch
23
24       - want desired structures in returned record
25
26       - need mandatory structures in returned record
27
28       - load True => load into device_spec
29

DESCRIPTION

31       A  client may request that the server fetch one or more components from
32       its database and use those components to build a  new  server  keyboard
33       description.   The  new keyboard description may be built from scratch,
34       or it may be built starting with the current keyboard description for a
35       particular  device. Once the keyboard description is built, all or part
36       of it may be returned to the client.  The parts returned to the  client
37       need not include all of the parts used to build the description. At the
38       time it requests the server to build  a  new  keyboard  description,  a
39       client  may also request that the server use the new description inter‐
40       nally to replace  the  current  keyboard  description  for  a  specific
41       device, in which case the behavior of the device changes accordingly.
42
43       To build a new keyboard description from a set of named components, and
44       to optionally have the server use the resulting description to  replace
45       an active one, use XkbGetKeyboardByName.
46
47       names  contains a set of expressions describing the keyboard components
48       the server should use to build the new keyboard description.  want  and
49       need  are  bit  fields  describing  the parts of the resulting keyboard
50       description that should be present in the returned XkbDescRec.
51
52       The individual fields in names are component  expressions  composed  of
53       keyboard  component names (no wildcarding as may be used in XkbListCom‐
54       ponents), the special component name symbol `%', and the special opera‐
55       tor  characters  `+'  and `|'. A component expression is parsed left to
56       right, as follows:
57
58
59       ·    The special component name "computed" may be used in keycodes com‐
60            ponent  expressions  and refers to a component consisting of a set
61            of keycodes computed automatically by the server as needed.
62
63       ·    The special component name "canonical" may be used in types compo‐
64            nent  expressions  and  refers to a partial component defining the
65            four standard key types:  ALPHABETIC,  ONE_LEVEL,  TWO_LEVEL,  and
66            KEYPAD.
67
68       ·    The  special component name `%' refers to the keyboard description
69            for the device specified in device_spec or the keymap names compo‐
70            nent. If a keymap names component is specified that does not begin
71            with `+' or `|' and does not contain `%', then `%' refers  to  the
72            description  generated  by the keymap names component.  Otherwise,
73            it refers to the keyboard description for device_spec.
74
75       ·    The `+' operator specifies that  the  following  component  should
76            override the currently assembled description; any definitions that
77            are present in both components are taken from the second.
78
79       ·    The `|' operator  specifies  that  the  next  specified  component
80            should  augment  the  currently assembled description; any defini‐
81            tions that are present in  both  components  are  taken  from  the
82            first.
83
84       ·    If the component expression begins with an operator, a leading `%'
85            is implied.
86
87       ·    If any unknown  or  illegal  characters  appear  anywhere  in  the
88            expression, the entire expression is invalid and is ignored.
89
90            For  example, if names->symbols contained the expression "+de", it
91            specifies that the default member of the  "de"  class  of  symbols
92            should  be applied to the current keyboard mapping, overriding any
93            existing definitions (it could also be written "+de(default)").
94
95            Here  is  a  slightly  more  involved  example:   the   expression
96            "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping
97            for the ASCII keyboard supplied by the "acme" vendor. The new def‐
98            inition  begins  with  the symbols for the ASCII keyboard for Acme
99            (acme(ascii)), overrides them with definitions for the basic  Ger‐
100            man  keyboard  (de(basic)),  and then applies the definitions from
101            the default iso9995-3 keyboard (iso9995-3) to any  undefined  keys
102            or  groups  of  keys (part three of the iso9995 standard defines a
103            common set  of  bindings  for  the  secondary  group,  but  allows
104            national layouts to override those definitions where necessary).
105
106            NOTE  The interpretation of the above expression components (acme,
107            ascii, de, basic, iso9995-3) is not defined by Xkb; only the oper‐
108            ations and their ordering are.
109
110            Note  that  the presence of a keymap names component that does not
111            contain `%' (either explicit or implied by virtue of an expression
112            starting  with  an operator) indicates a description that is inde‐
113            pendent of the keyboard description for the  device  specified  in
114            device_spec.   The  same  is  true of requests in which the keymap
115            names component is empty and all five other names components  con‐
116            tain expressions void of references to `%'.  Requests of this form
117            allow you to deal with keyboard  definitions  independent  of  any
118            actual device.
119
120            The  server  parses  all non-NULL fields in names and uses them to
121            build a keyboard description. However, before parsing the  expres‐
122            sions  in names, the server ORs the bits in want and need together
123            and examines the result in  relationship  to  the  expressions  in
124            names.   Table  1  identifies the components that are required for
125            each of the possible bits in want or need.  If a  required  compo‐
126            nent  has  not  been  specified in the names structure (the corre‐
127            sponding field is NULL), the  server  substitutes  the  expression
128            "%",   resulting   in   the  component  values  being  taken  from
129            device_spec.  In addition, if load is True,  the  server  modifies
130            names  if necessary (again using a "%" entry) to ensure all of the
131            following fields are non-NULL: types, keycodes, symbols, and  com‐
132            pat.
133                       Table 1 Want and Need Mask Bits and Required Names Components
134            ────────────────────────────────────────────────────────────────────────────────────
135            want or need mask bit      Required names Components                        value
136            ────────────────────────────────────────────────────────────────────────────────────
137            XkbGBN_TypesMask           Types                                            (1L<<0)
138            XkbGBN_CompatMapMask       Compat                                           (1L<<1)
139            XkbGBN_ClientSymbolsMask   Types + Symbols + Keycodes                       (1L<<2)
140            XkbGBN_ServerSymbolsMask   Types + Symbols + Keycodes                       (1L<<3)
141            XkbGBN_SymbolsMask         Symbols                                          (1L<<1)
142            XkbGBN_IndicatorMapMask    Compat                                           (1L<<4)
143            XkbGBN_KeyNamesMask        Keycodes                                         (1L<<5)
144            XkbGBN_GeometryMask        Geometry                                         (1L<<6)
145            XkbGBN_OtherNamesMask      Types + Symbols + Keycodes + Compat + Geometry   (1L<<7)
146            XkbGBN_AllComponentsMask                                                    (0xff)
147            need  specifies  a set of keyboard components that the server must
148            be able to resolve in order for XkbGetKeyboardByName  to  succeed;
149            if  any of the components specified in need cannot be successfully
150            resolved, XkbGetKeyboardByName fails.
151            want specifies a set of keyboard components that the server should
152            attempt  to  resolve, but that are not mandatory. If the server is
153            unable to resolve any of  these  components,  XkbGetKeyboardByName
154            still  succeeds. Bits specified in want that are also specified in
155            need have no effect in the context of want.
156            If load is True, the server updates its keyboard  description  for
157            device_spec  to  match the result of the keyboard description just
158            built. If load is  False,  the  server's  description  for  device
159            device_spec  is  not updated. In all cases, the parts specified by
160            want  and  need  from  the  just-built  keyboard  description  are
161            returned.
162            The  names  structure in an XkbDescRec keyboard description record
163            contains one field for each of the five component  types  used  to
164            build a keyboard description. When a keyboard description is built
165            from a set of database components,  the  corresponding  fields  in
166            this  names  structure  are  set  to match the expressions used to
167            build the component.
168            Building a New Keyboard Description from the Server Database
169            The information returned to the client in the XkbDescRec is essen‐
170            tially the result of a series of calls to extract information from
171            a fictitious device whose description matches the one just  built.
172            The calls corresponding to each of the mask bits are summarized in
173            Table 2, together with the XkbDescRec components that  are  filled
174            in.
175                                        Table 2 XkbDescRec Components Returned for Values of Want & Needs
176            ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
177            Request (want+need)                                Fills in Xkb components     Equivalent Function Call
178            ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
179            XkbGBN_TypesMask                                   map.types                   XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)
180            XkbGBN_ServerSymbolsMask                           server                      XkbGetUpdatedMap(dpy,
181            XkbAllClientInfoMask, Xkb)
182            XkbGBN_ClientSymbolsMask                           map, including map.types
183            XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)
184            XkbGBN_IndicatorMaps                               indicators                  XkbGetIndicatorMap(dpy,
185            XkbAllIndicators, Xkb)
186            XkbGBN_CompatMapMask                               compat                      XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)
187            XkbGBN_GeometryMask                                geom                        XkbGetGeometry(dpy, Xkb)
188            XkbGBN_KeyNamesMask                                names.keys                  XkbGetNames(dpy, XkbKeyNamesMask |
189                                                               names.key_aliases           XkbKeyAliasesMask, Xkb)
190            XkbGBN_OtherNamesMask                              names.keycodes              XkbGetNames(dpy, XkbAllNamesMask &
191                                                               names.geometry              ~(XkbKeyNamesMask | XkbKeyAliasesMask),
192                                                               names.symbols               Xkb)
193                                                               names.types
194                                                               map.types[*].lvl_names[*]
195                                                               names.compat
196                                                               names.vmods
197                                                               names.indicators
198                                                               names.groups
199                                                               names.radio_groups
200                                                               names.phys_symbols
201            There  is  no  way to determine which components specified in want
202            (but not in need) were actually fetched, other than  breaking  the
203            call  into successive calls to XkbGetKeyboardByName and specifying
204            individual components.
205            XkbGetKeyboardByName always sets min_key_code and max_key_code  in
206            the returned XkbDescRec structure.
207            XkbGetKeyboardByName  is  synchronous; it sends the request to the
208            server to build a new  keyboard  description  and  waits  for  the
209            reply.  If  successful,  the return value is non-NULL.  XkbGetKey‐
210            boardByName generates a BadMatch  protocol  error  if  errors  are
211            encountered when building the keyboard description.

STRUCTURES

213       The  complete description of an Xkb keyboard is given by an XkbDescRec.
214       The component structures in the XkbDescRec represent the major Xkb com‐
215       ponents outlined in Figure 1.1.
216
217       typedef struct {
218          struct _XDisplay * display;      /∗ connection to X server */
219          unsigned short     flags;        /∗ private to Xkb, do not modify */
220          unsigned short     device_spec;  /∗ device of interest */
221          KeyCode            min_key_code; /∗ minimum keycode for device */
222          KeyCode            max_key_code; /∗ maximum keycode for device */
223          XkbControlsPtr     ctrls;        /∗ controls */
224          XkbServerMapPtr    server;       /∗ server keymap */
225          XkbClientMapPtr    map;          /∗ client keymap */
226          XkbIndicatorPtr    indicators;   /∗ indicator map */
227          XkbNamesPtr        names;        /∗ names for all components */
228          XkbCompatMapPtr    compat;       /∗ compatibility map */
229          XkbGeometryPtr     geom;         /∗ physical geometry of keyboard */
230       } XkbDescRec, *XkbDescPtr;
231
232       The  display field points to an X display structure. The flags field is
233       private  to  the  library:  modifying  flags  may  yield  unpredictable
234       results.  The  device_spec field specifies the device identifier of the
235       keyboard input device, or XkbUseCoreKeyboard, which specifies the  core
236       keyboard  device.  The min_key_code and max_key_code fields specify the
237       least and greatest keycode that can be returned by the keyboard.
238
239       Each structure component has a corresponding mask bit that is  used  in
240       function  calls to indicate that the structure should be manipulated in
241       some manner, such as allocating it or freeing it. These masks and their
242       relationships to the fields in the XkbDescRec are shown in Table 3.
243
244
245               Table 3 Mask Bits for XkbDescRec
246       ──────────────────────────────────────────────────
247
248       Mask Bit               XkbDescRec Field   Value
249       ──────────────────────────────────────────────────
250
251       XkbControlsMask        ctrls              (1L<<0)
252       XkbServerMapMask       server             (1L<<1)
253
254       XkbIClientMapMask      map                (1L<<2)
255       XkbIndicatorMapMask    indicators         (1L<<3)
256
257       XkbNamesMask           names              (1L<<4)
258       XkbCompatMapMask       compat             (1L<<5)
259
260       XkbGeometryMask        geom               (1L<<6)
261       XkbAllComponentsMask   All Fields         (0x7f)
262

DIAGNOSTICS

264       BadMatch       A  compatible  version  of  Xkb was not available in the
265                      server or an argument has correct type and range, but is
266                      otherwise invalid
267

SEE ALSO

269       XkbListComponents(3)
270
271
272
273
274
275X Version 11                     libX11 1.6.4          XkbGetKeyboardByName(3)
Impressum