Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

X11R7.4 - man page for xkbgetkeyboardbyname (x11r4 section 3)

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  key-
       board  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 XkbGetKeyboardBy-
       Name.

       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  XkbDe-
       scRec.

       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  special operator characters `+' and `|'. A component expression is
       parsed left to right, as follows:

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

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

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

       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  cur-
	    rently assembled description; any definitions 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 key-
	    board supplied by the "acme" vendor. The new definition 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 components 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 expres-
	    sions  in names.  Table 1 identifies 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 expres-
	    sion "%", resulting in the component values being taken from device_spec.	In  addi-
	    tion,  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 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 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 sum-
	    marized 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 XkbDe-
	    scRec 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.	XkbGetKeyboardByName  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 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: 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.2.1 		  XkbGetKeyboardByName(3)


All times are GMT -4. The time now is 11:02 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password