aboutsummaryrefslogtreecommitdiff
path: root/libX11/man/xkb/XkbGetKeyboardByName.man
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/man/xkb/XkbGetKeyboardByName.man')
-rw-r--r--libX11/man/xkb/XkbGetKeyboardByName.man405
1 files changed, 405 insertions, 0 deletions
diff --git a/libX11/man/xkb/XkbGetKeyboardByName.man b/libX11/man/xkb/XkbGetKeyboardByName.man
new file mode 100644
index 000000000..b27b07c7f
--- /dev/null
+++ b/libX11/man/xkb/XkbGetKeyboardByName.man
@@ -0,0 +1,405 @@
+'\" t
+.\" Copyright (c) 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, and/or sell copies of the Software, and to permit persons
+.\" to whom the Software is furnished to do so, provided that the above
+.\" copyright notice(s) and this permission notice appear in all copies of
+.\" the Software and that both the above copyright notice(s) and this
+.\" permission notice appear in supporting documentation.
+.\"
+.\" 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
+.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
+.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
+.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of a copyright holder
+.\" shall not be used in advertising or otherwise to promote the sale, use
+.\" or other dealings in this Software without prior written authorization
+.\" of the copyright holder.
+.\"
+.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
+.B XkbDescPtr XkbGetKeyboardByName
+(
+.I dpy,
+.I device_spec,
+.I names,
+.I want,
+.I need,
+.I load
+)
+.br
+ Display * \fIdpy\fP\^;
+.br
+ unsigned int \fIdevice_spec\fP\^;
+.br
+ XkbComponentNamesPtr \fInames\fP\^;
+.br
+ unsigned int \fIwant\fP\^;
+.br
+ unsigned int \fIneed\fP\^;
+.br
+ Bool \fIload\fP\^;
+.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__)
+
+