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    (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 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
	    KEYPAD.

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

       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-
	    pat.
		       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 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
	    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.  XkbGetKey-
	    boardByName 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 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.


	       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)





X Version 11			 libX11 1.6.0	       XkbGetKeyboardByName(3)