diff options
Diffstat (limited to 'libX11/man/xkb/XkbGetKeyboardByName.man')
| -rw-r--r-- | libX11/man/xkb/XkbGetKeyboardByName.man | 405 |
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__) + + |