Provided by: libx11-doc_1.7.5-1ubuntu0.3_all bug

NAME

       XkbGetKeyboardByName  -  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

SYNOPSIS

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

ARGUMENTS

       - 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

DESCRIPTION

       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.

STRUCTURES

       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.

               Table 3 Mask Bits for XkbDescRec
       ──────────────────────────────────────────────────
       Mask Bit               XkbDescRec Field   Value
       ──────────────────────────────────────────────────
       XkbControlsMask        ctrls              (1L<<0)
       XkbServerMapMask       server             (1L<<1)
       XkbIClientMapMask      map                (1L<<2)
       XkbIndicatorMapMask    indicators         (1L<<3)
       XkbNamesMask           names              (1L<<4)
       XkbCompatMapMask       compat             (1L<<5)
       XkbGeometryMask        geom               (1L<<6)
       XkbAllComponentsMask   All Fields         (0x7f)

DIAGNOSTICS

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

SEE ALSO

       XkbListComponents(3)