XkbListComponents(3)      XKB FUNCTIONS      XkbListComponents(3)



NAME
       XkbListComponents  -  List  of  components for one or more
       component types

SYNOPSIS
       XkbComponentListPtr XkbListComponents ( dpy,  device_spec,
       ptrns, max_inout )
             Display * dpy;
             unsigned int device_spec;
             XkbComponentNamesPtr ptrnst;
             int * max_inout;

ARGUMENTS
       - dpy  connection to X server

       - device_spec
              device ID, or XkbUseCoreKbd

       - ptrns
              namelist for components of interest

       - max_inout
              max # returned names, # left over

DESCRIPTION
       You may ask the server for a list of components for one or
       more component types. The request takes the form of a  set
       of  patterns, one pattern for each of the component types,
       including a pattern for the complete keyboard description.
       To obtain this list, use XkbListComponents.

       XkbListComponents  queries the server for a list of compo-
       nent names matching the patterns specified in  ptrns.   It
       waits for a reply and returns the matching component names
       in an XkbComponentListRec structure.  When  you  are  done
       using  the structure, you should free it using XkbFreeCom-
       ponentList. device_spec indicates a particular  device  in
       which  the  caller is interested. A server is allowed (but
       not required) to restrict its reply  to  portions  of  the
       database that are relevant for that particular device.

       ptrns is a pointer to an XkbComponentNamesRec. Each of the
       fields in ptrns contains a pattern naming  the  components
       of  interest.  Each of the patterns is composed of charac-
       ters from the ISO Latin1 encoding, but  can  contain  only
       parentheses,  the  wildcard  characters  `?'  and `*', and
       characters permitted in a component class or member  name.
       A  pattern  may  be  NULL, in which case no components for
       that type is  returned.  Pattern  matches  with  component
       names  are  case  sensitive. The `?'  wildcard matches any
       single character, except a left or right parenthesis;  the
       `*'  wildcard  matches  any number of characters, except a
       left or right parenthesis.  If  an  implementation  allows
       additional  characters in a component class or member name
       other than those required by the Xkb extension, the result
       of comparing one of the additional characters to either of
       the wildcard characters is implementation-dependent.

       If a pattern  contains  illegal  characters,  the  illegal
       characters  are  ignored.  The matching process is carried
       out as if the illegal characters  were  omitted  from  the
       pattern.

       max_inout is used to throttle the amount of data passed to
       and from the server. On input, it  specifies  the  maximum
       number  of names to be returned (the total number of names
       in all component categories). Upon return from XkbListCom-
       ponents,  max_inout  contains  the  number  of  names that
       matched the request but were not returned because  of  the
       limit.

       Component Names

       Component  names  have  the form class(member) where class
       describes a subset of the available components for a  par-
       ticular type and the optional member identifies a specific
       component  from  that  subset.  For  example,   the   name
       "atlantis(acme)" for a symbols component might specify the
       symbols used for the atlantis national keyboard layout  by
       the vendor "acme." Each class has an optional default mem-
       ber - references that specify a class  but  not  a  member
       refer  to  the default member of the class, if one exists.
       Xkb places no constraints on  the  interpretation  of  the
       class and member names used in component names.

       The  class and member names are both specified using char-
       acters from the Latin-1 character set. Xkb implementations
       must  accept  all alphanumeric characters, minus (`-') and
       underscore (`_') in class or member names,  and  must  not
       accept  parentheses,  plus,  vertical  bar,  percent sign,
       asterisk, question mark, or white space. The use of  other
       characters is implementation-dependent.

STRUCTURES
       The  component  name patterns used to describe the request
       are passed to  XkbListComponents  using  an  XkbComponent-
       NamesRec  structure. This structure has no special alloca-
       tion constraints or interrelationships with  other  struc-
       tures;  allocate  and  free  this structure using standard
       malloc and free calls or their equivalent:

           typedef struct _XkbComponentNames {
               char *         keymap;           /* keymap names */
               char *         keycodes;         /* keycode names */
               char *         types;            /* type names */
               char *         compat;           /* compatibility map names */
               char *         symbols;          /* symbol names */
               char *         geometry;         /* geometry names */
           } XkbComponentNamesRec, *XkbComponentNamesPtr;

       XkbListComponents  returns  a  pointer  to  an   XkbCompo-
       nentListRec:

           typedef struct _XkbComponentList {
               int                      num_keymaps;  /* number of entries in keymap */
               int                      num_keycodes; /* number of entries in keycodes */
               int                      num_types;    /* number of entries in types */
               int                      num_compat;   /* number of entries in compat */
               int                      num_symbols;  /* number of entries in symbols */
               int                      num_geometry; /* number of entries in geometry;
               XkbComponentNamePtr      keymap;       /* keymap names */
               XkbComponentNamePtr      keycodes;     /* keycode names */
               XkbComponentNamePtr      types;        /* type names */
               XkbComponentNamePtr      compat;       /* compatibility map names */
               XkbComponentNamePtr      symbols;      /* symbol names */
               XkbComponentNamePtr      geometry;     /* geometry names */
           } XkbComponentListRec, *XkbComponentListPtr;

           typedef struct _XkbComponentName {
               unsigned short           flags;        /* hints regarding component name */
               char *                   name;         /* name of component */
           } XkbComponentNameRec, *XkbComponentNamePtr;


SEE ALSO
       XkbFreeComponentList(3)

NOTES
       Note  that the structure used to specify patterns on input
       is an XkbComponentNamesRec, and  that  used  to  hold  the
       individual component names upon return is an XkbComponent-
       NameRec (no trailing `s' in Name).



X Version 11               libX11 1.1.5      XkbListComponents(3)