XkbGetKeyboardByName - Man Page

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

dpy

connection to X server

device_spec

device ID, or XkbUseCoreKbd

names

names of components to fetch

want

desired structures in returned record

need

mandatory structures in returned record

load

True => load into device_spec

A client may request that the server fetch one or more components from its  database and use those components to build a new server keyboard description.  The new keyboard description may be built from scratch, or it may be built  starting with the current keyboard description for a particular device. Once the  keyboard description is built, all or part of it may be returned to the client.  The parts returned to the client need not include all of the parts used to build  the description. At the time it requests the server to build a new keyboard  description, a client may also request that the server use the new description  internally to replace the current keyboard description for a specific device, in  which case the behavior of the device changes accordingly.

To build a new keyboard description from a set of named components, and to  optionally have the server use the resulting description to replace an active  one, use XkbGetKeyboardByName.

names contains a set of expressions describing the keyboard components the  server should use to build the new keyboard description. want and need are bit fields describing the parts of the resulting keyboard description that  should be present in the returned XkbDescRec.
 The individual fields in names are component expressions composed of keyboard component names (no wildcarding as may be used in XkbListComponents), the special component name symbol `%', and the special operator characters `+'  and `|'. A component expression is parsed left to right, as follows:

• The special component name "computed" may be used in keycodes component  expressions and refers to a component consisting of a set of keycodes computed  automatically by the server as needed.
• The special component name "canonical" may be used in types component  expressions and refers to a partial component defining the four standard key  types: ALPHABETIC, ONE_LEVEL, TWO_LEVEL, and KEYPAD.
• The special component name `%' refers to the keyboard description for the device  specified in device_spec or the keymap names component. If a keymap names  component is specified that does not begin with `+' or `|' and does not contain  `%', then `%' refers to the description generated by the keymap names component.  Otherwise, it refers to the keyboard description for device_spec.
• The `+' operator specifies that the following component should override the  currently assembled description; any definitions that are present in both  components are taken from the second.
• The `|' operator specifies that the next specified component should augment the  currently assembled description; any definitions that are present in both  components are taken from the first.
• If the component expression begins with an operator, a leading `%' is implied.

• If any unknown or illegal characters appear anywhere in the expression, the  entire expression is invalid and is ignored.

  For example, if names->symbols contained the expression "+de", it specifies that  the default member of the "de" class of symbols should be applied to the current  keyboard mapping, overriding any existing definitions (it could also be written  "+de(default)").

  Here is a slightly more involved example: the expression  "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the ASCII  keyboard supplied by the "acme" vendor. The new definition begins with the  symbols for the ASCII keyboard for Acme (acme(ascii)), overrides them with definitions for the basic German keyboard (de(basic)), and then applies the definitions from the default iso9995-3 keyboard (iso9995-3) to any undefined keys or groups of keys (part three of the iso9995 standard  defines a common set of bindings for the secondary group, but allows national  layouts to override those definitions where necessary).

  NOTE The interpretation of the above expression components (acme, ascii, de, basic,  iso9995-3) is not defined by Xkb; only the operations and their ordering are.

  Note that the presence of a keymap names component that does not contain `%' (either explicit or implied by virtue of an  expression starting with an operator) indicates a description that is  independent of the keyboard description for the device specified in device_spec. The same is true of requests in which the keymap names component is empty and  all five other names components contain expressions void of references to `%'.  Requests of this form allow you to deal with keyboard definitions independent of  any actual device.

  The server parses all non-NULL fields in names and uses them to build a keyboard description. However, before parsing the  expressions in names, the server ORs the bits in want and need together and examines the result in relationship to the expressions in names. Table 1 identifies the components that are required for each of the possible  bits in want or need. If a required component has not been specified in the names structure (the corresponding field is NULL), the server substitutes the expression "%", resulting in the component values being taken from device_spec. In addition, if load is True, the server modifies names if necessary (again using a "%" entry) to ensure all of the following fields are  non-NULL: types, keycodes, symbols, and compat.

  Table 1 Want and Need Mask Bits and Required Names Components
  want or need mask bit	Required names Components	value
  XkbGBN_TypesMask	Types	(1L<<0)
  XkbGBN_CompatMapMask	Compat	(1L<<1)
  XkbGBN_ClientSymbolsMask	Types + Symbols + Keycodes	(1L<<2)
  XkbGBN_ServerSymbolsMask	Types + Symbols + Keycodes	(1L<<3)
  XkbGBN_SymbolsMask	Symbols	(1L<<1)
  XkbGBN_IndicatorMapMask	Compat	(1L<<4)
  XkbGBN_KeyNamesMask	Keycodes	(1L<<5)
  XkbGBN_GeometryMask	Geometry	(1L<<6)
  XkbGBN_OtherNamesMask	Types + Symbols + Keycodes + Compat + Geometry	(1L<<7)
  XkbGBN_AllComponentsMask		(0xff)

  need specifies a set of keyboard components that the server must be able to  resolve in order for XkbGetKeyboardByName to succeed; if any of the components specified in need cannot be successfully resolved, XkbGetKeyboardByName fails.

  want specifies a set of keyboard components that the server should attempt to  resolve, but that are not mandatory. If the server is unable to resolve any of  these components, XkbGetKeyboardByName still succeeds. Bits specified in want that are also specified in need have no effect in the context of want.

  If load is True, the server updates its keyboard description for device_spec to match the result of the keyboard description just built. If load is False,  the  server's description for device device_spec is not updated. In all cases, the parts specified by want and need from the just-built keyboard description are returned.

  The names structure in an XkbDescRec keyboard description record contains one field for  each of the five component types used to build a keyboard description. When a  keyboard description is built from a set of database components, the  corresponding fields in this names structure are set to match the expressions used to build the component.

  Building a New Keyboard Description from the Server Database

  The information returned to the client in the XkbDescRec is essentially the  result of a series of calls to extract information from a fictitious device  whose description matches the one just built. The calls corresponding to each of  the mask bits are summarized in Table 2, together with the XkbDescRec  components that are filled in.

  Table 2 XkbDescRec Components Returned for Values of Want & Needs
  Request (want+need)	Fills in Xkb components	Equivalent Function Call
  XkbGBN_TypesMask	map.types	XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)
  XkbGBN_ServerSymbolsMask	server	XkbGetUpdatedMap(dpy,
  XkbAllClientInfoMask, Xkb)
  XkbGBN_ClientSymbolsMask	map, including map.types
  XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)
  XkbGBN_IndicatorMaps	indicators	XkbGetIndicatorMap(dpy,
  XkbAllIndicators, Xkb)
  XkbGBN_CompatMapMask	compat	XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)
  XkbGBN_GeometryMask	geom	XkbGetGeometry(dpy, Xkb)
  XkbGBN_KeyNamesMask	names.keys	XkbGetNames(dpy, XkbKeyNamesMask |
  	names.key_aliases	XkbKeyAliasesMask, Xkb)
  XkbGBN_OtherNamesMask	names.keycodes	XkbGetNames(dpy, XkbAllNamesMask &
  	names.geometry	~(XkbKeyNamesMask | XkbKeyAliasesMask),
  	names.symbols	Xkb)
  	names.types
  	map.types[*].lvl_names[*]
  	names.compat
  	names.vmods
  	names.indicators
  	names.groups
  	names.radio_groups
  	names.phys_symbols

  There is no way to determine which components specified in want (but not in need) were actually fetched, other than breaking the call into successive calls to XkbGetKeyboardByName and specifying individual components.

  XkbGetKeyboardByName always sets min_key_code and max_key_code in the returned XkbDescRec structure.

  XkbGetKeyboardByName is synchronous; it sends the request to the server to build a new keyboard  description and waits for the reply. If successful, the return value is  non-NULL. XkbGetKeyboardByName generates a BadMatch protocol error if errors are encountered when building the  keyboard description.

The complete description of an Xkb keyboard is given by an XkbDescRec. The  component  structures in the XkbDescRec represent the major Xkb components outlined in  Figure 1.1.

typedef struct {
   struct _XDisplay * display;      /* connection to X server */
   unsigned short     flags;        /* private to Xkb, do not modify */
   unsigned short     device_spec;  /* device of interest */
   KeyCode            min_key_code; /* minimum keycode for device */
   KeyCode            max_key_code; /* maximum keycode for device */
   XkbControlsPtr     ctrls;        /* controls */
   XkbServerMapPtr    server;       /* server keymap */
   XkbClientMapPtr    map;          /* client keymap */
   XkbIndicatorPtr    indicators;   /* indicator map */
   XkbNamesPtr        names;        /* names for all components */
   XkbCompatMapPtr    compat;       /* compatibility map */
   XkbGeometryPtr     geom;         /* physical geometry of keyboard */
} XkbDescRec, *XkbDescPtr;

The display field points to an X display structure. The flags field is private to the library: modifying flags may yield unpredictable results. The device_spec field specifies the device identifier of the keyboard input device, or  XkbUseCoreKeyboard, which specifies the core keyboard device. The min_key_code and max_key_code fields specify the least and greatest keycode that can be returned by the  keyboard.

Each structure component has a corresponding mask bit that is used in function  calls to  indicate that the structure should be manipulated in some manner, such as  allocating it  or freeing it. These masks and their relationships to the fields in the  XkbDescRec are  shown in Table 3.

BadMatch

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

XkbListComponents(3)

XkbGetKeyboard(3), XkbRefreshKeyboardMapping(3).