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

NAME

6       XkbGetMap  -  Allocate an XkbDescRec structure and populate it with the
7       server's keyboard client map and server map
8

SYNOPSIS

10       XkbDescPtr XkbGetMap (Display *display, unsigned  int  which,  unsigned
11              int device_spec);
12

ARGUMENTS

14       - display
15              connection to X server
16
17       - which
18              mask selecting subcomponents to populate
19
20       - device_spec
21              device_id, or XkbUseCoreKbd
22

DESCRIPTION

24       Xkb  provides  two  functions to obtain the keyboard mapping components
25       from the server. The first function, XkbGetMap, allocates an XkbDescRec
26       structure,  retrieves  mapping  components  from the server, and stores
27       them in the XkbDescRec structure it just allocated.  The  second  func‐
28       tion,  XkbGetUpdatedMap,  retrieves  mapping components from the server
29       and stores them in an XkbDescRec structure  that  has  previously  been
30       allocated.
31
32       To  allocate  an XkbDescRec structure and populate it with the server's
33       keyboard client map and server map, use XkbGetMap. XkbGetMap is similar
34       to  XkbGetKeyboard,  but  is  used only for obtaining the address of an
35       XkbDescRec structure that is populated  with  keyboard  mapping  compo‐
36       nents. It allows finer control over which substructures of the keyboard
37       mapping components are to be populated.  XkbGetKeyboard always  returns
38       fully populated components, while XkbGetMap can be instructed to return
39       a partially populated component.
40
41       The which mask is a bitwise inclusive OR of the masks defined in  Table
42       14.1.  Only  those portions of the keyboard server map and the keyboard
43       client maps that are specified in which are allocated and populated.
44
45       In addition to allocating and obtaining the server map and  the  client
46       map,  XkbGetMap  also  sets  the  device_spec,  the  min_key_code,  and
47       max_key_code fields of the keyboard description.
48
49       XkbGetMap is synchronous; it queries the server for the desired  infor‐
50       mation,  waits  for a reply, and then returns. If successful, XkbGetMap
51       returns a pointer to the XkbDescRec structure it allocated.  If  unsuc‐
52       cessful,  XkbGetMap returns NULL. When unsuccessful, one of the follow‐
53       ing protocol errors is also generated: BadAlloc (unable to allocate the
54       XkbDescRec  structure),  BadValue  (some  mask  bits in which are unde‐
55       fined), or BadImplementation (a compatible version of the Xkb extension
56       is  not  available  in  the  server).  To  free  the returned data, use
57       XkbFreeKeyboard.
58
59       Xkb also provides convenience functions to get partial component  defi‐
60       nitions  from  the server. These functions are specified in the "conve‐
61       nience functions" column in Table 1. Refer to the  sections  listed  in
62       the table for more information on these functions.
63
64
65                                     Table 1 Xkb Mapping Component Masks
66
67                                          and Convenience Functions
68       ────────────────────────────────────────────────────────────────────────────────────────────────
69       Mask                             Value    Map      Fields        Convenience
70                                                                        Functions
71       ────────────────────────────────────────────────────────────────────────────────────────────────
72       XkbKeyTypesMask                  (1<<0)   client   types         XkbGetKeyTypes
73                                                          size_types    XkbResizeKeyType
74                                                          num_types     XkbCopyKeyType
75                                                                        XkbCopyKeyTypes
76       XkbKeySymsMask                   (1<<1)   client   syms          XkbGetKeySyms
77                                                          size_syms     XkbResizeKeySyms
78                                                          num_syms      XkbChangeTypesOfKey
79                                                          key_sym_map
80       XkbModifierMapMask               (1<<2)   client   modmap        XkbGetKeyModifierMap
81       XkbExplicitComponentsMask        (1<<3)   server   explicit      XkbGetKeyExplicitComponents
82       XkbKeyActionsMask                (1<<4)   server   key_acts      XkbGetKeyActions
83                                                          acts          XkbResizeKeyActions
84                                                          num_acts
85                                                          size_acts
86       XkbKeyBehaviorsMask              (1<<5)   server   behaviors     XkbGetKeyBehaviors
87       XkbVirtualModsMask               (1<<6)   server   vmods         XkbGetVirtualMods
88       XkbVirtualModMapMask             (1<<7)   server   vmodmap       XkbGetVirtualModMap
89
90       Xkb defines combinations of these masks for convenience:
91
92          #define XkbResizableInfoMask   (XkbKeyTypesMask)
93          #define XkbAllClientInfoMask   (XkbKeyTypesMask | XkbKeySymsMask |
94                                          XkbModifierMapMask)
95          #define XkbAllServerInfoMask   (XkbExplicitComponentsMask |
96                                          XkbKeyActionsMask |
97                                          XkbKeyBehaviorsMask |
98                                          XkbVirtualModsMask |
99                                          XkbVirtualModMapMask)
100          #define XkbAllMapComponentsMask XkbAllClientInfoMask |
101                                          XkbAllServerInfoMask)
102
103       Key types, symbol maps, and actions are all  interrelated:  changes  in
104       one  require  changes  in the others. The convenience functions make it
105       easier to edit these components and handle the interdependencies.
106
107

STRUCTURES

109       The complete description of an Xkb keyboard is given by an  XkbDescRec.
110       The component structures in the XkbDescRec represent the major Xkb com‐
111       ponents.
112
113       typedef struct {
114          struct _XDisplay * display;      /∗ connection to X server */
115          unsigned short     flags;        /∗ private to Xkb, do not modify */
116          unsigned short     device_spec;  /∗ device of interest */
117          KeyCode            min_key_code; /∗ minimum keycode for device */
118          KeyCode            max_key_code; /∗ maximum keycode for device */
119          XkbControlsPtr     ctrls;        /∗ controls */
120          XkbServerMapPtr    server;       /∗ server keymap */
121          XkbClientMapPtr    map;          /∗ client keymap */
122          XkbIndicatorPtr    indicators;   /∗ indicator map */
123          XkbNamesPtr        names;        /∗ names for all components */
124          XkbCompatMapPtr    compat;       /∗ compatibility map */
125          XkbGeometryPtr     geom;         /∗ physical geometry of keyboard */
126       } XkbDescRec, *XkbDescPtr;
127
128       The display field points to an X display structure. The flags field  is
129       private  to  the  library:  modifying  flags  may  yield  unpredictable
130       results. The device_spec field specifies the device identifier  of  the
131       keyboard  input device, or XkbUseCoreKeyboard, which specifies the core
132       keyboard device. The min_key_code and max_key_code fields  specify  the
133       least and greatest keycode that can be returned by the keyboard.
134
135       Each  structure  component has a corresponding mask bit that is used in
136       function calls to indicate that the structure should be manipulated  in
137       some manner, such as allocating it or freeing it. These masks and their
138       relationships to the fields in the XkbDescRec are shown in Table 2.
139
140
141               Table 2 Mask Bits for XkbDescRec
142       ──────────────────────────────────────────────────
143       Mask Bit               XkbDescRec Field   Value
144       ──────────────────────────────────────────────────
145       XkbControlsMask        ctrls              (1L<<0)
146       XkbServerMapMask       server             (1L<<1)
147       XkbIClientMapMask      map                (1L<<2)
148       XkbIndicatorMapMask    indicators         (1L<<3)
149       XkbNamesMask           names              (1L<<4)
150       XkbCompatMapMask       compat             (1L<<5)
151       XkbGeometryMask        geom               (1L<<6)
152       XkbAllComponentsMask   All Fields         (0x7f)
153

SEE ALSO

155       XkbChangeTypesOfKey(3),     XkbCopyKeyType(3),      XkbCopyKeyTypes(3),
156       XkbFreeClientMap(3),     XkbGetKeyActions(3),    XkbGetKeyBehaviors(3),
157       XkbGetKeyboard(3),    XkbGetKeyExplicitComponents(3),    XkbGetKeyModi‐
158       fierMap(3),  XkbGetKeySyms(3),  XkbGetKeyTypes(3), XkbGetUpdatedMap(3),
159       XkbGetVirtualModMap(3),  XkbGetVirtualMods(3),  XkbResizeKeyActions(3),
160       XkbResizeKeySyms(3), XkbResizeKeyType(3)
161
162
163
164
165
166
167
168
169X Version 11                     libX11 1.6.4                     XkbGetMap(3)
Impressum