diff options
Diffstat (limited to 'libX11/specs/XKB/ch20.xml')
| -rw-r--r-- | libX11/specs/XKB/ch20.xml | 1188 |
1 files changed, 1188 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch20.xml b/libX11/specs/XKB/ch20.xml new file mode 100644 index 000000000..e58686f35 --- /dev/null +++ b/libX11/specs/XKB/ch20.xml @@ -0,0 +1,1188 @@ +<chapter id='server_database_of_keyboard_components'> +<title>Server Database of Keyboard Components</title> + +<para> +The X server maintains a database of keyboard components, identified by +component type. The database contains all the information necessary to build a +complete keyboard description for a particular device, as well as to assemble +partial descriptions. Table 20.1 identifies the component types and the type of +information they contain. +</para> + +<table frame='none'> +<title>Server Database Keyboard Components</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Component Type</entry> + <entry>Component Primary Contents</entry> + <entry>May also contain</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>Keymap</entry> + <entry> +<para>Complete keyboard description</para> +<para>Normally assembled using a complete component from each of the other types</para> + </entry> + <entry></entry> + </row> + <row rowsep='0'> + <entry>Keycodes</entry> + <entry> +<para>Symbolic name for each key</para> +<para>Minimum and maximum legal keycodes</para> + </entry> + <entry> +<para>Aliases for some keys</para> +<para>Symbolic names for indicators</para> +<para>Description of indicators physically present</para> + </entry> + </row> + <row rowsep='0'> + <entry>Types</entry> + <entry>Key types</entry> + <entry> +Real modifier bindings and symbolic names for some virtual modifiers + </entry> + </row> + <row rowsep='0'> + <entry>Compatibility</entry> + <entry>Rules used to assign actions to keysyms</entry> + <entry> +<para>Maps for some indicators</para> +<para>Real modifier bindings and symbolic names for some virtual modifiers</para> + </entry> + </row> + <row rowsep='0'> + <entry>Symbols</entry> + <entry> +<para>Symbol mapping for keyboard keys</para> +<para>Modifier mapping</para> +<para>Symbolic names for groups</para> + </entry> + <entry> +<para>Explicit actions and behaviors for some keys</para> +<para>Real modifier bindings and symbolic names for some virtual modifiers</para> + </entry> + </row> + <row rowsep='0'> + <entry>Geometry</entry> + <entry>Layout of the keyboard</entry> + <entry> +<para>Aliases for some keys; overrides keycodes component aliases</para> +<para>Symbolic names for some indicators</para> +<para>Description of indicators physically present</para> + </entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +While a keymap is a database entry for a complete keyboard description, and +therefore logically different from the individual component database entries, +the rules for processing keymap entries are identical to those for the +individual components. In the discussion that follows, the term component is +used to refer to either individual components or a keymap. +</para> + +<para> +There may be multiple entries for each of the component types. An entry may be +either <emphasis> +complete</emphasis> + or <emphasis> +partial</emphasis> +. Partial entries describe only a piece of the corresponding keyboard component +and are designed to be combined with other entries of the same type to form a +complete entry. +</para> + +<para> +For example, a partial symbols map might describe the differences between a +common ASCII keyboard and some national layout. Such a partial map is not +useful on its own because it does not include those symbols that are the same +on both the ASCII and national layouts (such as function keys). On the other +hand, this partial map can be used to configure <emphasis> +any</emphasis> + ASCII keyboard to use a national layout. +</para> + +<para> +When a keyboard description is built, the components are processed in the order +in which they appear in Table 20.1; later definitions override earlier ones. +</para> + +<sect1 id='component_names'> +<title>Component Names</title> + +<para> +Component names have the form "<emphasis> +class(member)</emphasis> +" where <emphasis> +class</emphasis> + describes a subset of the available components for a particular type and the +optional <emphasis> +member</emphasis> + identifies a specific component from that subset. For example, the name +"atlantis(acme)" for a symbols component might specify the symbols used for the +atlantis national keyboard layout by the vendor "acme." Each class has an +optional <emphasis> +default</emphasis> + member — references that specify a class but not a member refer to the +default member of the class, if one exists. Xkb places no constraints on the +interpretation of the class and member names used in component names. +</para> + +<para> +The <emphasis> +class</emphasis> + and <emphasis> +member</emphasis> + names are both specified using characters from the Latin-1 character set. Xkb +implementations must accept all alphanumeric characters, minus (‘-’) and +underscore (‘_’) in class or member names, and must not accept parentheses, +plus, vertical bar, percent sign, asterisk, question mark, or white space. The +use of other characters is implementation-dependent. +</para> + +</sect1> +<sect1 id='listing_the_known_keyboard_components'> +<title>Listing the Known Keyboard Components</title> + +<para> +You may ask the server for a list of components for one or more component +types. The request takes the form of a set of patterns, one pattern for each of +the component types, including a pattern for the complete keyboard description. +To obtain this list, use <emphasis> +XkbListComponents</emphasis> +. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +XkbComponentListPtr<emphasis> + XkbListComponents</emphasis> +(<emphasis> +dpy</emphasis> +, <emphasis> +device_spec</emphasis> +, <emphasis> +ptrns</emphasis> +, <emphasis> +max_inout</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbComponentNamesPtr <emphasis> +ptrns</emphasis> +; /* namelist for components of interest */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +max_inout</emphasis> +; /* max # returned names, # left over */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbListComponents</emphasis> + queries the server for a list of component names matching the patterns +specified in <emphasis> +ptrns</emphasis> +. It waits for a reply and returns the matching component names in an <emphasis> +XkbComponentListRec</emphasis> + structure. When you are done using the structure, you should free it using +<emphasis> +XkbFreeComponentList</emphasis> +. <emphasis> +device_spec</emphasis> + indicates a particular device in which the caller is interested. A server is +allowed (but not required) to restrict its reply to portions of the database +that are relevant for that particular device. +</para> + + +<para> +<emphasis> +ptrns</emphasis> + is a pointer to an <emphasis> +XkbComponentNamesRec</emphasis> +, described below. Each of the fields in <emphasis> +ptrns</emphasis> + contains a pattern naming the components of interest. Each of the patterns is +composed of characters from the ISO <emphasis> +Latin1</emphasis> + encoding, but can contain only parentheses, the wildcard characters +‘<emphasis> +?</emphasis> +’ and ‘<emphasis> +*</emphasis> +’, and characters permitted in a component class or member name (see section +20.1). A pattern may be <emphasis> +NULL</emphasis> +, in which case no components for that type is returned. Pattern matches with +component names are case sensitive. The ‘<emphasis> +?</emphasis> +’ wildcard matches any single character, except a left or right parenthesis; +the ‘<emphasis> +*</emphasis> +’ wildcard matches any number of characters, except a left or right +parenthesis. If an implementation allows additional characters in a component +class or member name other than those required by the Xkb extension (see +section 20.1), the result of comparing one of the additional characters to +either of the wildcard characters is implementation-dependent. +</para> + + +<para> +If a pattern contains illegal characters, the illegal characters are ignored. +The matching process is carried out as if the illegal characters were omitted +from the pattern. +</para> + + +<para> +<emphasis> +max_inout</emphasis> + is used to throttle the amount of data passed to and from the server. On +input, it specifies the maximum number of names to be returned (the total +number of names in all component categories). Upon return from <emphasis> +XkbListComponents</emphasis> +, <emphasis> +max_inout</emphasis> + contains the number of names that matched the request but were not returned +because of the limit. +</para> + + +<para> +The component name patterns used to describe the request are passed to +<emphasis> +XkbListComponents</emphasis> + using an <emphasis> +XkbComponentNamesRec</emphasis> + structure. This structure has no special allocation constraints or +interrelationships with other structures; allocate and free this structure +using standard <emphasis> +malloc</emphasis> + and <emphasis> +free</emphasis> + calls or their equivalent: +</para> + +<para><programlisting> +typedef struct _XkbComponentNames { + char * keymap; /* keymap names */ + char * keycodes; /* keycode names */ + char * types; /* type names */ + char * compat; /* compatibility map names */ + char * symbols; /* symbol names */ + char * geometry; /* geometry names */ +} <emphasis>XkbComponentNamesRec</emphasis>, *XkbComponentNamesPtr; +</programlisting></para> + +<para> +<emphasis> +XkbListComponents</emphasis> + returns a pointer to an <emphasis> +XkbComponentListRec</emphasis> +: +</para> + +<para><programlisting> +typedef struct _XkbComponentList { + int num_keymaps; /* number of entries in keymap */ + int num_keycodes; /* number of entries in keycodes */ + int num_types; /* number of entries in types */ + int num_compat; /* number of entries in compat */ + int num_symbols; /* number of entries in symbols */ + int num_geometry; /* number of entries in geometry; + XkbComponentNamePtr keymap; /* keymap names */ + XkbComponentNamePtr keycodes; /* keycode names */ + XkbComponentNamePtr types; /* type names */ + XkbComponentNamePtr compat; /* compatibility map names */ + XkbComponentNamePtr symbols; /* symbol names */ + XkbComponentNamePtr geometry; /* geometry names */ +} <emphasis>XkbComponentListRec</emphasis>, *XkbComponentListPtr; +</programlisting></para> + +<para><programlisting> +typedef struct _XkbComponentName { + unsigned short flags; /* hints regarding component name */ + char * name; /* name of component */ +} <emphasis>XkbComponentNameRec</emphasis>, *XkbComponentNamePtr; +</programlisting></para> + +<para> +Note that the structure used to specify patterns on input is an <emphasis> +XkbComponentNamesRec</emphasis> +, and that used to hold the individual component names upon return is an +<emphasis> +XkbComponentNameRec</emphasis> + (no trailing ‘s’ in Name). +</para> + + +<para> +When you are done using the structure returned by <emphasis> +XkbListComponents</emphasis> +, free it using <emphasis> +XkbFreeComponentList</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +void <emphasis> +XkbFreeComponentList</emphasis> +(list) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbComponentListPtr list; /* pointer to <emphasis> +XkbComponentListRec</emphasis> + to free */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + + +</sect1> +<sect1 id='component_hints'> +<title>Component Hints</title> + +<para> +A set of flags is associated with each component; these flags provide +additional hints about the component’s use. These hints are designated by bit +masks in the flags field of the <emphasis> +XkbComponentNameRec</emphasis> + structures contained in the <emphasis> +XkbComponentListRec</emphasis> + returned from <emphasis> +XkbListComponents</emphasis> +. The least significant byte of the flags field has the same meaning for all +types of keyboard components; the interpretation of the most significant byte +is dependent on the type of component. The flags bits are defined in Table +20.2. The symbols hints in Table 20.2 apply only to partial symbols components +(those with <emphasis> +XkbLC_Partial</emphasis> + also set); full symbols components are assumed to specify all of the pieces. +</para> + + +<para> +The alphanumeric, modifier, keypad or function keys symbols hints should +describe the primary intent of the component designer and should not be simply +an exhaustive list of the kinds of keys that are affected. For example, +national keyboard layouts affect primarily alphanumeric keys, but many affect a +few modifier keys as well; such mappings should set only the <emphasis> +XkbLC_AlphanumericKeys</emphasis> + hint. In general, symbols components should set only one of the four flags +(<emphasis> +XkbLC_AlternateGroup</emphasis> + may be combined with any of the other flags). +</para> + +<table frame='none'> +<title>XkbComponentNameRec Flags Bits</title> +<tgroup cols='4'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Component Type</entry> + <entry>Component Hints (flags)</entry> + <entry>Meaning</entry> + <entry>Value</entry> +</row> +</thead> +<tbody> +<row rowsep='0'> + <entry>All Components</entry> + <entry><para><emphasis>XkbLC_Hidden</emphasis></para></entry> + <entry>Do not present to user</entry> + <entry>(1L<<0)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_Default</emphasis></entry> + <entry>Default member of class</entry> + <entry>(1L<<1)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_Partial</emphasis></entry> + <entry>Partial component</entry> + <entry>(1L<<2)</entry> +</row> +<row rowsep='0'> + <entry>Keymap</entry> + <entry>none</entry> + <entry></entry> + <entry></entry> +</row> +<row rowsep='0'> + <entry>Keycodes</entry> + <entry>none</entry> + <entry></entry> + <entry></entry> +</row> +<row rowsep='0'> + <entry>Types</entry> + <entry>none</entry> + <entry></entry> + <entry></entry> +</row> +<row rowsep='0'> + <entry>Compatibility</entry> + <entry>none</entry> + <entry></entry> + <entry></entry> +</row> +<row rowsep='0'> + <entry>Symbols</entry> + <entry><emphasis>XkbLC_AlphanumericKeys</emphasis></entry> + <entry>Bindings primarily for alphanumeric keyboard section</entry> + <entry>(1L<<8)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_ModifierKeys</emphasis></entry> + <entry>Bindings primarily for modifier keys</entry> + <entry>(1L<<9)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_KeypadKeys</emphasis></entry> + <entry>Bindings primarily for numeric keypad keys</entry> + <entry>(1L<<10)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_FunctionKeys</emphasis></entry> + <entry>Bindings primarily for function keys</entry> + <entry>(1L<<11)</entry> +</row> +<row rowsep='0'> + <entry></entry> + <entry><emphasis>XkbLC_AlternateGroup</emphasis></entry> + <entry>Bindings for an alternate group</entry> + <entry>(1L<<12)</entry> +</row> +<row rowsep='0'> + <entry>Geometry</entry> + <entry>none</entry> + <entry></entry> + <entry></entry> + </row> +</tbody> +</tgroup> +</table> + +</sect1> +<sect1 id='building_a_keyboard_description_using_the_server_database'> +<title>Building a Keyboard Description Using the Server Database</title> + +<para> +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. +</para> + + +<para> +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 <emphasis> +XkbGetKeyboardByName</emphasis> +. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +XkbDescPtr <emphasis> +XkbGetKeyboardByName</emphasis> +(<emphasis> +dpy</emphasis> +, <emphasis> +device_spec</emphasis> +, <emphasis> +names</emphasis> +, <emphasis> +want</emphasis> +, <emphasis> +need</emphasis> +, <emphasis> +load</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbComponentNamesPtr <emphasis> +names</emphasis> +; /* names of components to fetch */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +want</emphasis> +; /* desired structures in returned record */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +need</emphasis> +; /* mandatory structures in returned record */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> +load</emphasis> +; /* <emphasis> +True</emphasis> + => load into <emphasis> +device_spec</emphasis> + */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +names</emphasis> + contains a set of expressions describing the keyboard components the server +should use to build the new keyboard description. <emphasis> +want</emphasis> + and <emphasis> +need</emphasis> + are bit fields describing the parts of the resulting keyboard description that +should be present in the returned <emphasis> +XkbDescRec</emphasis> +. +</para> + + +<para> +The individual fields in <emphasis> +names</emphasis> + are <emphasis> +component expressions</emphasis> + composed of keyboard component names (no wildcarding as may be used in +<emphasis> +XkbListComponents</emphasis> +), the special component name symbol ‘%’, and the special operator +characters ‘<emphasis> ++</emphasis> +’ and ‘<emphasis> +|</emphasis> +’. A component expression is parsed left to right, as follows: +</para> + +<itemizedlist> +<listitem> + <para> +The special component name "<emphasis> +computed</emphasis> +" may be used in <emphasis> +keycodes</emphasis> + component expressions and refers to a component consisting of a set of +keycodes computed automatically by the server as needed. + </para> +</listitem> +<listitem> + <para> +The special component name "<emphasis> +canonical</emphasis> +" may be used in <emphasis> +types</emphasis> + component expressions and refers to a partial component defining the four +standard key types: <emphasis> +ALPHABETIC</emphasis> +, <emphasis> +ONE_LEVEL</emphasis> +, <emphasis> +TWO_LEVEL</emphasis> +, and <emphasis> +KEYPAD</emphasis> +. + </para> +</listitem> +<listitem> + <para> +The special component name ‘<emphasis> +%</emphasis> +’ refers to the keyboard description for the device specified in <emphasis> +device_spec</emphasis> + or the keymap names component. If a keymap names component is specified that +does not begin with ‘+’ or ‘|’ and does not contain ‘<emphasis> +%</emphasis> +’, then ‘<emphasis> +%</emphasis> +’ refers to the description generated by the keymap names component. +Otherwise, it refers to the keyboard description for <emphasis> +device_spec</emphasis> +. + </para> +</listitem> +<listitem> + <para> +The ‘<emphasis> ++</emphasis> +’ operator specifies that the following component should <emphasis> +override</emphasis> + the currently assembled description; any definitions that are present in both +components are taken from the second. + </para> +</listitem> +<listitem> + <para> +The ‘<emphasis> +|</emphasis> +’ operator specifies that the next specified component should <emphasis> +augment</emphasis> + the currently assembled description; any definitions that are present in both +components are taken from the first. + </para> +</listitem> +<listitem> + <para> +If the component expression begins with an operator, a leading ‘<emphasis> +%</emphasis> +’ is implied. + </para> +</listitem> +<listitem> + <para> +If any unknown or illegal characters appear anywhere in the expression, the +entire expression is invalid and is ignored. + </para> +</listitem> +</itemizedlist> + +<para> +For example, if <emphasis> +names->symbols</emphasis> + 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)"). +</para> + + +<para> +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 (<emphasis> +acme(ascii)</emphasis> +), overrides them with definitions for the basic German keyboard (<emphasis> +de(basic)</emphasis> +), and then applies the definitions from the default iso9995-3 keyboard +(<emphasis> +iso9995-3</emphasis> +) 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). +</para> + +<note><para>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.</para></note> + +<para> +Note that the presence of a keymap <emphasis> +names</emphasis> + component that does not contain ‘<emphasis> +%</emphasis> +’ (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 <emphasis> +device_spec</emphasis> +. 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 +‘<emphasis> +%</emphasis> +’. Requests of this form allow you to deal with keyboard definitions +independent of any actual device. +</para> + + +<para> +The server parses all non-<emphasis> +NULL</emphasis> + fields in <emphasis> +names</emphasis> + and uses them to build a keyboard description. However, before parsing the +expressions in <emphasis> +names</emphasis> +, the server ORs the bits in <emphasis> +want</emphasis> + and <emphasis> +need</emphasis> + together and examines the result in relationship to the expressions in +<emphasis> +names</emphasis> +. Table 20.3 identifies the components that are required for each of the +possible bits in <emphasis> +want</emphasis> + or <emphasis> +need</emphasis> +. If a required component has not been specified in the <emphasis> +names</emphasis> + structure (the corresponding field is <emphasis> +NULL</emphasis> +), the server substitutes the expression "<emphasis> +%</emphasis> +", resulting in the component values being taken from <emphasis> +device_spec</emphasis> +. In addition, if <emphasis> +load</emphasis> + is <emphasis> +True</emphasis> +, the server modifies <emphasis> +names</emphasis> + if necessary (again using a "<emphasis> +%</emphasis> +" entry) to ensure all of the following fields are non-<emphasis> +NULL</emphasis> +: <emphasis> +types</emphasis> +, <emphasis> +keycodes</emphasis> +, <emphasis> +symbols</emphasis> +, and <emphasis> +compat</emphasis> +.<emphasis> +</emphasis> +</para> + +<table frame='none'> +<title>Want and Need Mask Bits and Required Names Components</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>want or need mask bit</entry> + <entry>Required names Components</entry> + <entry>value</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbGBN_TypesMask</entry> + <entry>Types</entry> + <entry>(1L<<0)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_CompatMapMask</entry> + <entry>Compat</entry> + <entry>(1L<<1)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_ClientSymbolsMask</entry> + <entry>Types + Symbols + Keycodes</entry> + <entry>(1L<<2)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_ServerSymbolsMask</entry> + <entry>Types + Symbols + Keycodes</entry> + <entry>(1L<<3)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_SymbolsMask</entry> + <entry>Symbols</entry> + <entry>(1L<<1)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_IndicatorMapMask</entry> + <entry>Compat</entry> + <entry>(1L<<4)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_KeyNamesMask</entry> + <entry>Keycodes</entry> + <entry>(1L<<5)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_GeometryMask</entry> + <entry>Geometry</entry> + <entry>(1L<<6)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_OtherNamesMask</entry> + <entry>Types + Symbols + Keycodes + Compat + Geometry</entry> + <entry>(1L<<7)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_AllComponentsMask</entry> + <entry></entry> + <entry>(0xff)</entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +<emphasis> +need</emphasis> + specifies a set of keyboard components that the server must be able to resolve +in order for <emphasis> +XkbGetKeyboardByName</emphasis> + to succeed; if any of the components specified in <emphasis> +need</emphasis> + cannot be successfully resolved, <emphasis> +XkbGetKeyboardByName</emphasis> + fails. +</para> + + +<para> +<emphasis> +want</emphasis> + 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, <emphasis> +XkbGetKeyboardByName</emphasis> + still succeeds. Bits specified in <emphasis> +want</emphasis> + that are also specified in <emphasis> +need</emphasis> + have no effect in the context of <emphasis> +want</emphasis> +. +</para> + + +<para> +If <emphasis> +load</emphasis> + is <emphasis> +True</emphasis> +, the server updates its keyboard description for <emphasis> +device_spec</emphasis> + to match the result of the keyboard description just built. If load is +<emphasis> +False</emphasis> +, the server’s description for device <emphasis> +device_spec</emphasis> + is not updated. In all cases, the parts specified by <emphasis> +want</emphasis> + and <emphasis> +need</emphasis> + from the just-built keyboard description are returned. +</para> + + +<para> +The <emphasis> +names</emphasis> + structure in an <emphasis> +XkbDescRec</emphasis> + keyboard description record (see Chapter 18) 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 <emphasis> +names</emphasis> + structure are set to match the expressions used to build the component. +</para> + + +<para> +The entire process of building a new keyboard description from the server +database of components and returning all or part of it is diagrammed in Figure +20.1: +</para> + +<mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-21.svg"/> + </imageobject> + <caption>Building a New Keyboard Description from the Server Database</caption> +</mediaobject> + +<para> +The information returned to the client in the <emphasis> +XkbDescRec</emphasis> + 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 20.4, together +with the <emphasis> +XkbDescRec</emphasis> + components that are filled in. +</para> + +<table frame='none'> +<title>XkbDescRec Components Returned for Values of Want & Needs</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Request (want+need)</entry> + <entry>Fills in Xkb components</entry> + <entry>Equivalent Function Call</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbGBN_TypesMask</entry> + <entry>map.types</entry> + <entry>XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_ServerSymbolsMask</entry> + <entry>server</entry> + <entry>XkbGetUpdatedMap(dpy, XkbAllClientInfoMask, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_ClientSymbolsMask</entry> + <entry>map, including map.types</entry> + <entry>XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_IndicatorMaps</entry> + <entry>indicators</entry> + <entry>XkbGetIndicatorMap(dpy, XkbAllIndicators, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_CompatMapMask</entry> + <entry>compat</entry> + <entry>XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_GeometryMask</entry> + <entry>geom</entry> + <entry>XkbGetGeometry(dpy, Xkb)</entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_KeyNamesMask</entry> + <entry> +<para>names.keys</para> +<para>names.key_aliases</para> + </entry> + <entry> +XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb) + </entry> + </row> + <row rowsep='0'> + <entry>XkbGBN_OtherNamesMask</entry> + <entry> +<para>names.keycodes</para> +<para>names.geometry</para> +<para>names.symbols</para> +<para>names.types</para> +<para>map.types[*].lvl_names[*]</para> +<para>names.compat</para> +<para>names.vmods</para> +<para>names.indicators</para> +<para>names.groups</para> +<para>names.radio_groups</para> +<para>names.phys_symbols</para> + </entry> + <entry> +<para>XkbGetNames(dpy, XkbAllNamesMask &</para> +<para>~(XkbKeyNamesMask | XkbKeyAliasesMask),</para> +<para>Xkb)</para> + </entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +There is no way to determine which components specified in <emphasis> +want</emphasis> + (but not in <emphasis> +need</emphasis> +) were actually fetched, other than breaking the call into successive calls to +<emphasis> +XkbGetKeyboardByName</emphasis> + and specifying individual components. +</para> + + +<para> +<emphasis> +XkbGetKeyboardByName</emphasis> + always sets <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + in the returned <emphasis> +XkbDescRec</emphasis> + structure. +</para> + + +<para> +<emphasis>XkbGetKeyboardByName</emphasis> +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-<emphasis>NULL</emphasis>. +<emphasis>XkbGetKeyboardByName</emphasis> +generates a <emphasis>BadMatch</emphasis> +protocol error if errors are encountered when building the keyboard +description. +</para> + + +<para> +If you simply want to obtain information about the current keyboard device, +rather than generating a new keyboard description from elements in the server +database, use <emphasis> +XkbGetKeyboard</emphasis> + (see section 6.2). +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +XkbDescPtr <emphasis> +XkbGetKeyboard</emphasis> +(<emphasis> +dpy</emphasis> +, <emphasis> +which</emphasis> +, <emphasis> +device_spec</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask of components of <emphasis> +XkbDescRec</emphasis> + of interest */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + device_spec</emphasis> +; /* device ID */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbGetKeyboard</emphasis> + is used to read the current description for one or more components of a +keyboard device. It calls <emphasis> +XkbGetKeyboardByName</emphasis> + as follows: +</para> + + +<para> +<emphasis> +XkbGetKeyboardByName</emphasis> +(<emphasis> +dpy</emphasis> +, <emphasis> +device_spec</emphasis> +, <emphasis> +NULL</emphasis> +, <emphasis> +which</emphasis> +, <emphasis> +which</emphasis> +, <emphasis> +False</emphasis> +). +</para> + +</sect1> +</chapter> |