plucky (3) XkbGetKeyboardByName.3.gz

Provided by: libx11-doc_1.8.10-2_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)