This manual page is for Mac OS X version 10.6.3

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • For more information about the manual page format, see the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Reference Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



XkbGetKeyboardByName(3)                         XKB FUNCTIONS                        XkbGetKeyboardByName(3)



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 ( dpy, device_spec, names, want, need, load )
             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 spe-cial special
       cial 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 assem-bled assembled
            bled  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,  overrid-ing overriding
            ing 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" con-structs constructs
            structs a German (de) mapping for the ASCII keyboard supplied by the "acme" vendor. The new def-inition definition
            inition  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 compo-nents components
            nents 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 identi-fies identifies
            fies 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 -----------------------------------------------------------------------------------want
            want or need mask bit      Required names Components                        value
            ------------------------------------------------------------------------------------XkbGBN_TypesMask -----------------------------------------------------------------------------------XkbGBN_TypesMask
            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  success-
            fully 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, XkbGetKeyboardBy-Name XkbGetKeyboardByName
            Name  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 justbuilt
            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 --------------------------------------------------------------------------------------------------------------------------Request
            Request (want+need)                                Fills in Xkb components     Equivalent Function Call
            ---------------------------------------------------------------------------------------------------------------------------XkbGBN_TypesMask --------------------------------------------------------------------------------------------------------------------------XkbGBN_TypesMask
            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 specify-ing specifying
            ing individual components.

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

            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 XkbGetKeyboardByName
            boardByName generates a BadMatch protocol error if errors are encountered when building the key-board keyboard
            board 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:  modi-fying modifying
       fying 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 -------------------------------------------------Mask
       Mask Bit               XkbDescRec Field   Value
       --------------------------------------------------XkbControlsMask -------------------------------------------------XkbControlsMask
       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)





X Version 11                                    libX11 1.2.1                         XkbGetKeyboardByName(3)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Did this document help you? Yes It's good, but... Not helpful...