aboutsummaryrefslogtreecommitdiff
path: root/libX11/man/xkb/XkbGetKeyboardByName.man
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2010-09-04 16:22:11 +0000
committermarha <marha@users.sourceforge.net>2010-09-04 16:22:11 +0000
commita0fa440dee24b4b39d30c1b04579691d42efba65 (patch)
tree871ba76fa2620c406a09c0529312691d40f37495 /libX11/man/xkb/XkbGetKeyboardByName.man
parent28d9e16b745a3127287215888b0b5f12acb255af (diff)
downloadvcxsrv-a0fa440dee24b4b39d30c1b04579691d42efba65.tar.gz
vcxsrv-a0fa440dee24b4b39d30c1b04579691d42efba65.tar.bz2
vcxsrv-a0fa440dee24b4b39d30c1b04579691d42efba65.zip
libx11 git update 4/9/2010
Diffstat (limited to 'libX11/man/xkb/XkbGetKeyboardByName.man')
-rw-r--r--libX11/man/xkb/XkbGetKeyboardByName.man770
1 files changed, 385 insertions, 385 deletions
diff --git a/libX11/man/xkb/XkbGetKeyboardByName.man b/libX11/man/xkb/XkbGetKeyboardByName.man
index 6c0eeee16..463a0b369 100644
--- a/libX11/man/xkb/XkbGetKeyboardByName.man
+++ b/libX11/man/xkb/XkbGetKeyboardByName.man
@@ -1,385 +1,385 @@
-'\" t
-.\" Copyright 1999 Sun Microsystems, Inc. All rights reserved.
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining a
-.\" copy of this software and associated documentation files (the "Software"),
-.\" to deal in the Software without restriction, including without limitation
-.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
-.\" and/or sell copies of the Software, and to permit persons to whom the
-.\" Software is furnished to do so, subject to the following conditions:
-.\"
-.\" The above copyright notice and this permission notice (including the next
-.\" paragraph) shall be included in all copies or substantial portions of the
-.\" Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-.\" DEALINGS IN THE SOFTWARE.
-.\"
-.TH XkbGetKeyboardByName __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
-.SH 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
-.SH SYNOPSIS
-.HP
-.B XkbDescPtr XkbGetKeyboardByName
-.BI "(\^Display *" "dpy" "\^,"
-.BI "unsigned int " "device_spec" "\^,"
-.BI "XkbComponentNamesPtr " "names" "\^,"
-.BI "unsigned int " "want" "\^,"
-.BI "unsigned int " "need" "\^,"
-.BI "Bool " "load" "\^);"
-.if n .ti +5n
-.if t .ti +.5i
-.SH ARGUMENTS
-.TP
-.I \- dpy
-connection to X server
-.TP
-.I \- device_spec
-device ID, or XkbUseCoreKbd
-.TP
-.I \- names
-names of components to fetch
-.TP
-.I \- want
-desired structures in returned record
-.TP
-.I \- need
-mandatory structures in returned record
-.TP
-.I \- load
-True => load into
-.I device_spec
-.SH DESCRIPTION
-.LP
-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
-.I XkbGetKeyboardByName.
-
-.I names
-contains a set of expressions describing the keyboard components the
-server should use to build the new keyboard description.
-.I want
-and
-.I need
-are bit fields describing the parts of the resulting keyboard description that
-should be present in the returned XkbDescRec.
-
-The individual fields in
-.I names
-are
-.I component expressions
-composed of keyboard component names (no wildcarding as may be used in
-.I XkbListComponents),
-the special component name symbol `%', and the special operator characters `+'
-and `|'. A component expression is parsed left to right, as follows:
-
-.IP \(bu 5
-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.
-.IP \(bu 5
-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.
-.IP \(bu 5
-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.
-.IP \(bu 5
-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.
-.IP \(bu 5
-The `|' operator specifies that the next specified component should augment the
-currently assembled description; any definitions that are present in both
-components are taken from the first.
-.IP \(bu 5
-If the component expression begins with an operator, a leading `%' is implied.
-.IP \(bu 5
-If any unknown or illegal characters appear anywhere in the expression, the
-entire expression is invalid and is ignored.
-
-For example, if
-.I 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 definition begins with the
-symbols for the ASCII keyboard for Acme
-.I (acme(ascii)),
-overrides them with definitions for the basic German keyboard
-.I (de(basic)),
-and then applies the definitions from the default iso9995-3 keyboard
-.I (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).
-
-.B 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
-.I 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
-.I 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
-.I names
-and uses them to build a keyboard description. However, before parsing the
-expressions in
-.I names,
-the server ORs the bits in
-.I want
-and
-.I need
-together and examines the result in relationship to the expressions in
-.I names.
-Table 1 identifies the components that are required for each of the possible
-bits in
-.I want
-or
-.I need.
-If a required component has not been specified in the
-.I names structure (the corresponding field is NULL), the server substitutes the
-expression "%", resulting in the component values being taken from
-.I device_spec.
-In addition, if
-.I load
-is True, the server modifies
-.I names
-if necessary (again using a "%" entry) to ensure all of the following fields are
-non-NULL:
-.I types, keycodes, symbols,
-and
-.I compat.
-.bp
-.TS
-c s s
-l l l.
-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)
-.TE
-
-.I need
-specifies a set of keyboard components that the server must be able to
-resolve in order for
-.I XkbGetKeyboardByName
-to succeed; if any of the components specified in
-.I need
-cannot be successfully resolved,
-.I XkbGetKeyboardByName
-fails.
-
-.I 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,
-.I XkbGetKeyboardByName
-still succeeds. Bits specified in
-.I want
-that are also specified in
-.I need
-have no effect in the context of
-.I want.
-
-If
-.I load
-is True, the server updates its keyboard description for
-.I device_spec
-to match the result of the keyboard description just built. If load is False,
-the
-server's description for device
-.I device_spec
-is not updated. In all cases, the parts specified by
-.I want
-and
-.I need
-from the just-built keyboard description are returned.
-
-The
-.I 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
-.I 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.
-
-.TS
-c s s
-l l l.
-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
-.TE
-
-There is no way to determine which components specified in
-.I want
-(but not in
-.I need)
-were actually fetched, other than breaking the call into successive calls to
-.I XkbGetKeyboardByName
-and specifying individual components.
-
-.I XkbGetKeyboardByName
-always sets
-.I min_key_code
-and
-.I max_key_code
-in the returned XkbDescRec structure.
-
-.I 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.
-.I XkbGetKeyboardByName
-generates a BadMatch protocol error if errors are encountered when building the
-keyboard description.
-.SH STRUCTURES
-.LP
-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.
-
-.nf
-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;
-
-.fi
-The
-.I display
-field points to an X display structure. The
-.I flags field is private to the library: modifying
-.I flags
-may yield unpredictable results. The
-.I device_spec
-field specifies the device identifier of the keyboard input device, or
-XkbUseCoreKeyboard, which specifies the core keyboard device. The
-.I min_key_code
-and
-.I 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.
-
-.TS
-c s s
-l l l
-l l l.
-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)
-.TE
-.SH DIAGNOSTICS
-.TP 15
-.B BadMatch
-A compatible version of Xkb was not available in the server or an argument has
-correct type and range, but is otherwise invalid
-.SH "SEE ALSO"
-.BR XkbListComponents (__libmansuffix__)
-
-
+'\" t
+.\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the "Software"),
+.\" to deal in the Software without restriction, including without limitation
+.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
+.\" and/or sell copies of the Software, and to permit persons to whom the
+.\" Software is furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice (including the next
+.\" paragraph) shall be included in all copies or substantial portions of the
+.\" Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+.\" DEALINGS IN THE SOFTWARE.
+.\"
+.TH XkbGetKeyboardByName __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
+.SH 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
+.SH SYNOPSIS
+.HP
+.B XkbDescPtr XkbGetKeyboardByName
+.BI "(\^Display *" "dpy" "\^,"
+.BI "unsigned int " "device_spec" "\^,"
+.BI "XkbComponentNamesPtr " "names" "\^,"
+.BI "unsigned int " "want" "\^,"
+.BI "unsigned int " "need" "\^,"
+.BI "Bool " "load" "\^);"
+.if n .ti +5n
+.if t .ti +.5i
+.SH ARGUMENTS
+.TP
+.I \- dpy
+connection to X server
+.TP
+.I \- device_spec
+device ID, or XkbUseCoreKbd
+.TP
+.I \- names
+names of components to fetch
+.TP
+.I \- want
+desired structures in returned record
+.TP
+.I \- need
+mandatory structures in returned record
+.TP
+.I \- load
+True => load into
+.I device_spec
+.SH DESCRIPTION
+.LP
+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
+.I XkbGetKeyboardByName.
+
+.I names
+contains a set of expressions describing the keyboard components the
+server should use to build the new keyboard description.
+.I want
+and
+.I need
+are bit fields describing the parts of the resulting keyboard description that
+should be present in the returned XkbDescRec.
+
+The individual fields in
+.I names
+are
+.I component expressions
+composed of keyboard component names (no wildcarding as may be used in
+.I XkbListComponents),
+the special component name symbol `%', and the special operator characters `+'
+and `|'. A component expression is parsed left to right, as follows:
+
+.IP \(bu 5
+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.
+.IP \(bu 5
+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.
+.IP \(bu 5
+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.
+.IP \(bu 5
+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.
+.IP \(bu 5
+The `|' operator specifies that the next specified component should augment the
+currently assembled description; any definitions that are present in both
+components are taken from the first.
+.IP \(bu 5
+If the component expression begins with an operator, a leading `%' is implied.
+.IP \(bu 5
+If any unknown or illegal characters appear anywhere in the expression, the
+entire expression is invalid and is ignored.
+
+For example, if
+.I 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 definition begins with the
+symbols for the ASCII keyboard for Acme
+.I (acme(ascii)),
+overrides them with definitions for the basic German keyboard
+.I (de(basic)),
+and then applies the definitions from the default iso9995-3 keyboard
+.I (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).
+
+.B 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
+.I 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
+.I 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
+.I names
+and uses them to build a keyboard description. However, before parsing the
+expressions in
+.I names,
+the server ORs the bits in
+.I want
+and
+.I need
+together and examines the result in relationship to the expressions in
+.I names.
+Table 1 identifies the components that are required for each of the possible
+bits in
+.I want
+or
+.I need.
+If a required component has not been specified in the
+.I names structure (the corresponding field is NULL), the server substitutes the
+expression "%", resulting in the component values being taken from
+.I device_spec.
+In addition, if
+.I load
+is True, the server modifies
+.I names
+if necessary (again using a "%" entry) to ensure all of the following fields are
+non-NULL:
+.I types, keycodes, symbols,
+and
+.I compat.
+.bp
+.TS
+c s s
+l l l.
+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)
+.TE
+
+.I need
+specifies a set of keyboard components that the server must be able to
+resolve in order for
+.I XkbGetKeyboardByName
+to succeed; if any of the components specified in
+.I need
+cannot be successfully resolved,
+.I XkbGetKeyboardByName
+fails.
+
+.I 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,
+.I XkbGetKeyboardByName
+still succeeds. Bits specified in
+.I want
+that are also specified in
+.I need
+have no effect in the context of
+.I want.
+
+If
+.I load
+is True, the server updates its keyboard description for
+.I device_spec
+to match the result of the keyboard description just built. If load is False,
+the
+server's description for device
+.I device_spec
+is not updated. In all cases, the parts specified by
+.I want
+and
+.I need
+from the just-built keyboard description are returned.
+
+The
+.I 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
+.I 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.
+
+.TS
+c s s
+l l l.
+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
+.TE
+
+There is no way to determine which components specified in
+.I want
+(but not in
+.I need)
+were actually fetched, other than breaking the call into successive calls to
+.I XkbGetKeyboardByName
+and specifying individual components.
+
+.I XkbGetKeyboardByName
+always sets
+.I min_key_code
+and
+.I max_key_code
+in the returned XkbDescRec structure.
+
+.I 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.
+.I XkbGetKeyboardByName
+generates a BadMatch protocol error if errors are encountered when building the
+keyboard description.
+.SH STRUCTURES
+.LP
+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.
+
+.nf
+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;
+
+.fi
+The
+.I display
+field points to an X display structure. The
+.I flags field is private to the library: modifying
+.I flags
+may yield unpredictable results. The
+.I device_spec
+field specifies the device identifier of the keyboard input device, or
+XkbUseCoreKeyboard, which specifies the core keyboard device. The
+.I min_key_code
+and
+.I 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.
+
+.TS
+c s s
+l l l
+l l l.
+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)
+.TE
+.SH DIAGNOSTICS
+.TP 15
+.B BadMatch
+A compatible version of Xkb was not available in the server or an argument has
+correct type and range, but is otherwise invalid
+.SH "SEE ALSO"
+.BR XkbListComponents (__libmansuffix__)
+
+