t
Copyright (c) 1999, Oracle and/or its affiliates.
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.
Copyright (c) 1999, Oracle and/or its affiliates.
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.
XkbGetKeyboardByName __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
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 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 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 XkbListComponents), the special component name symbol `%', and the special operator characters `+' and `|'. A component expression is parsed left to right, as follows:
\(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.
\(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.
\(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.
\(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.
\(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.
\(bu 5
If the component expression begins with an operator, a leading `%' is implied.
\(bu 5
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 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 expressions 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 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
compat. .bp
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 summarized in Table 2, together with the XkbDescRec
components that are filled in.
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.
DIAGNOSTICS 15 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 (__libmansuffix__)
|