Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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   (Display  *dpy,  unsigned  int  de-
	      vice_spec, XkbComponentNamesPtr names, unsigned  int  want,  un-
	      signed 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  de-
       vice, 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 de-
       scription 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  ex-
	    pression, 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  na-
	    tional 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 ac-
	    tual 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 de-
	    vice_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-
		       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  de-
	    vice_spec  is  not	updated.  In all cases,	the parts specified by
	    want and need from the just-built  keyboard	 description  are  re-
	    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
					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)
	    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  re-
	    ply. If successful,	the return value is non-NULL.  XkbGetKeyboard-
	    ByName generates a BadMatch	protocol error if errors  are  encoun-
	    tered 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  re-
       sults.  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)

       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.6.12	       XkbGetKeyboardByName(3)


Want to link to this manual page? Use this URL:

home | help