Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Apropos / Subsearch:
optional field

XkbGetKeyboardByName(3)          XKB FUNCTIONS         XkbGetKeyboardByName(3)

       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

       XkbDescPtr  XkbGetKeyboardByName ( dpy, device_spec, names, want, need,
       load )
             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  inter-
       nally  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  XkbListCom-
       ponents), the special component name symbol `%', and the special opera-
       tor characters `+' and `|'. A component expression is  parsed  left  to
       right, as follows:

       o    The special component name "computed" may be used in keycodes com-
            ponent expressions and refers to a component consisting of  a  set
            of keycodes computed automatically by the server as needed.

       o    The special component name "canonical" may be used in types compo-
            nent expressions and refers to a partial  component  defining  the
            four  standard  key  types:  ALPHABETIC, ONE_LEVEL, TWO_LEVEL, and

       o    The special component name `%' refers to the keyboard  description
            for the device specified in device_spec or the keymap names compo-
            nent. 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.

       o    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.

       o    The  `|'  operator  specifies  that  the  next specified component
            should augment the currently assembled  description;  any  defini-
            tions  that  are  present  in  both  components are taken from the

       o    If the component expression begins with an operator, a leading `%'
            is implied.

       o    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 def-
            inition begins with the symbols for the ASCII  keyboard  for  Acme
            (acme(ascii)),  overrides them with definitions for the basic Ger-
            man 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 oper-
            ations 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  inde-
            pendent  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 con-
            tain 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 expres-
            sions 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 compo-
            nent has not been specified in the  names  structure  (the  corre-
            sponding  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 com-

            c s s l l l.  Table 1 Want and Need Mask Bits and  Required  Names
            Components  _  want  or  need  mask  bit    Required  names Compo-
            nents     value      _       XkbGBN_TypesMask    Types     (1L<<0)
            XkbGBN_CompatMapMask     Compat    (1L<<1)   XkbGBN_ClientSymbols-
            Mask Types  +  Symbols  +  Keycodes (1L<<2)  XkbGBN_ServerSymbols-
            Mask Types + Symbols + Keycodes   (1L<<3) XkbGBN_SymbolsMask  Sym-
            bols   (1L<<1)          XkbGBN_IndicatorMapMask  Compat    (1L<<4)
            XkbGBN_KeyNamesMask Keycodes  (1L<<5)   XkbGBN_GeometryMask Geome-
            try  (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

            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 essen-
            tially 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

            c s s l l l.  Table 2 XkbDescRec Components Returned for Values of
            Want & Needs _ Request (want+need) Fills in Xkb components  Equiv-
            alent  Function  Call _ XkbGBN_TypesMask    map.types XkbGetUpdat-
            edMap(dpy,      XkbTypesMask,      Xkb)      XkbGBN_ServerSymbols-
            Mask server    XkbGetUpdatedMap(dpy,   XkbAllClientInfoMask,  Xkb)
            XkbGBN_ClientSymbolsMask map, including map.types     XkbGetUpdat-
            edMap(dpy,      XkbAllServerInfoMask,      Xkb)     XkbGBN_Indica-
            torMaps     indicators     XkbGetIndicatorMap(dpy,   XkbAllIndica-
            tors, Xkb) XkbGBN_CompatMapMask     compat    XkbGetCompatMap(dpy,
            XkbAllCompatMask,    Xkb)    XkbGBN_GeometryMask geom XkbGetGeome-
            try(dpy,  Xkb) XkbGBN_KeyNamesMask names.keys     XkbGetNames(dpy,
            XkbKeyNamesMask |      names.key_aliases   XkbKeyAliasesMask, Xkb)
            XkbGBN_OtherNamesMask    names.keycodes XkbGetNames(dpy,   XkbAll-
            NamesMask    &              names.geometry ~(XkbKeyNamesMask     |
            XkbKeyAliasesMask),         names.symbols  Xkb)        names.types
                 map.types[*].lvl_names[*]      names.compat       names.vmods
                 names.indicators        names.groups       names.radio_groups

            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.   XkbGetKey-
            boardByName  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 com-
       ponents 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.

       c s s l l l l l l.  Table 3 Mask Bits for XkbDescRec _ Mask Bit  XkbDe-
       scRec   Field   Value   _   XkbControlsMask     ctrls     (1L<<0)  Xkb-
       ServerMapMask    server    (1L<<1)     XkbIClientMapMask   map  (1L<<2)
       XkbIndicatorMapMask indicators     (1L<<3)                    XkbNames-
       Mask   names     (1L<<4) XkbCompatMapMask    compat    (1L<<5) XkbGeom-
       etryMask     geom (1L<<6)                  XkbAllComponentsMask     All
       Fields     (0x7f)

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


X Version 11                     libX11 1.1.5          XkbGetKeyboardByName(3)