diff options
Diffstat (limited to 'specs/XKB/ch02.xml')
| -rw-r--r-- | specs/XKB/ch02.xml | 158 |
1 files changed, 79 insertions, 79 deletions
diff --git a/specs/XKB/ch02.xml b/specs/XKB/ch02.xml index a5790022..ca0616e6 100644 --- a/specs/XKB/ch02.xml +++ b/specs/XKB/ch02.xml @@ -26,7 +26,7 @@ functions. <filename class="headerfile">XKBstr.h</filename> declares types and constants for Xkb. It is included automatically from <filename class="headerfile"><X11/XKBlib.h></filename>; - you should never need to reference it directly in your application code. +you should never need to reference it directly in your application code. </para> </listitem> <listitem> @@ -37,7 +37,7 @@ constants for Xkb. It is included automatically from <filename class="headerfile">XKB.h</filename> defines constants for Xkb. It is included automatically from <filename class="headerfile"><X11/XKBstr.h></filename>; - you should never need to reference it directly in your application code. +you should never need to reference it directly in your application code. </para> </listitem> <listitem> @@ -66,11 +66,11 @@ The name of the Xkb extension is given in <para> Most extensions to the X protocol are initialized by calling <function>XInitExtension</function> - and passing the extension name. However, as explained in <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>, Xkb +and passing the extension name. However, as explained in <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>, Xkb requires a more complex initialization sequence, and a client program should not call <function>XInitExtension</function> - directly. +directly. </para> </sect1> <sect1 id='Determining_Library_Compatibility'> @@ -134,11 +134,11 @@ To determine the compatibility of a library at runtime, call <para> Pass the symbolic value <symbol>XkbMajorVersion</symbol> - in +in <parameter>lib_major_in_out</parameter> - and +and <symbol>XkbMinorVersion</symbol> - in +in <parameter>lib_minor_in_out</parameter>. These arguments represent the version of the library used at compile time. The @@ -146,7 +146,7 @@ The function backfills the major and minor version numbers of the library used at run time in <parameter>lib_major_in_out</parameter> - and +and <parameter>lib_minor_in_out</parameter>. If the versions of the compile time and run time libraries are compatible, <function>XkbLibraryVersion</function> @@ -161,7 +161,7 @@ In addition, in order to use the Xkb extension, you must ensure that the extension is present in the server and that the server supports the version of the extension expected by the client. Use <function>XkbQueryExtension</function> - to do this, as described in the next section. +to do this, as described in the next section. </para> </sect1> @@ -170,21 +170,21 @@ the extension expected by the client. Use <para> Call <function>XkbQueryExtension</function> - to check for the presence and compatibility of the extension in the server and +to check for the presence and compatibility of the extension in the server and to initialize the extension. Because of potential version mismatches, you cannot use the generic extension mechanism functions (<function>XQueryExtension</function> and <function>XInitExtension</function>) - for checking for the presence of, and initializing the Xkb extension. +for checking for the presence of, and initializing the Xkb extension. </para> <para> You must call <function>XkbQueryExtension</function> - or +or <function>XkbOpenDisplay</function> - before using any other Xkb library interfaces, unless such usage is explicitly +before using any other Xkb library interfaces, unless such usage is explicitly allowed in the interface description in this document. The exceptions are: <function>XkbIgnoreExtension</function>, <function>XkbLibraryVersion</function>, @@ -193,7 +193,7 @@ functions if the extension is not present or is uninitialized. In general, calls to Xkb library functions made prior to initializing the Xkb extension cause <errorname>BadAccess</errorname> - protocol errors. +protocol errors. <indexterm zone="Initializing_the_Keyboard_Extension"><primary>errors</primary> <secondary><errorname>BadAccess</errorname></secondary></indexterm> <indexterm zone="Initializing_the_Keyboard_Extension"> @@ -202,7 +202,7 @@ cause <para> <function>XkbQueryExtension</function> - both determines whether a compatible Xkb extension is present in the X server +both determines whether a compatible Xkb extension is present in the X server and initializes the extension when it is present. </para> @@ -288,19 +288,19 @@ and initializes the extension when it is present. <para> The <function>XkbQueryExtension</function> - function determines whether a compatible version of the X Keyboard Extension +function determines whether a compatible version of the X Keyboard Extension is present in the server. If a compatible extension is present, <function>XkbQueryExtension</function> - returns +returns <symbol>True</symbol>; - otherwise, it returns +otherwise, it returns <symbol>False</symbol>. </para> <para> If a compatible version of Xkb is present, <function>XkbQueryExtension</function> - initializes the extension. It backfills the major opcode for the keyboard +initializes the extension. It backfills the major opcode for the keyboard extension in <parameter>opcode_rtrn</parameter>, the base event code in @@ -309,18 +309,18 @@ the base error code in <parameter>error_rtrn</parameter>, and the major and minor version numbers of the extension in <parameter>major_in_out</parameter> - and +and <parameter>minor_in_out</parameter>. The major opcode is reported in the <structfield>req_major</structfield> - fields of some Xkb events. For a discussion of the base event code, see +fields of some Xkb events. For a discussion of the base event code, see <link linkend="Xkb_Event_Types">section 4.1</link>. </para> <para> As a convenience, you can use the function <function>XkbOpenDisplay</function> - to perform these three tasks at once: open a connection to an X server, check +to perform these three tasks at once: open a connection to an X server, check for a compatible version of the Xkb extension in both the library and the server, and initialize the extension for use. </para> @@ -410,34 +410,34 @@ reason_rtrn)</parameter> --> is a convenience function that opens an X display connection and initializes the X keyboard extension. In all cases, upon return <parameter>reason_rtrn</parameter> - contains a status value indicating success or the type of failure. If +contains a status value indicating success or the type of failure. If <parameter>major_in_out</parameter> - and +and <parameter>minor_in_out</parameter> - are not +are not <symbol>NULL</symbol>, <function>XkbOpenDisplay</function> - first calls +first calls <function>XkbLibraryVersion</function> - to determine whether the client library is compatible, passing it the values +to determine whether the client library is compatible, passing it the values pointed to by <parameter>major_in_out</parameter> - and +and <parameter>minor_in_out</parameter>. If the library is incompatible, <function>XkbOpenDisplay</function> - backfills +backfills <parameter>major_in_out</parameter> - and +and <parameter>minor_in_out</parameter> - with the major and minor extension versions of the library being used and +with the major and minor extension versions of the library being used and returns <symbol>NULL</symbol>. If the library is compatible, <function>XkbOpenDisplay</function> next calls <function>XOpenDisplay</function> - with the +with the <parameter>display_name</parameter>. If this fails, the function returns <symbol>NULL</symbol>. @@ -445,10 +445,10 @@ If successful, <function>XkbOpenDisplay</function> calls <function>XkbQueryExtension</function> - and +and backfills the major and minor Xkb server extension version numbers in <parameter>major_in_out</parameter> - and +and <parameter>minor_in_out</parameter>. If the server extension version is not compatible with the library extension version or if the server extension is not present, @@ -467,7 +467,7 @@ The possible values for <listitem> <para> <errorname>XkbOD_BadLibraryVersion</errorname> - indicates +indicates <function>XkbLibraryVersion</function> returned <symbol>False</symbol>. @@ -476,25 +476,25 @@ returned <listitem> <para> <errorname>XkbOD_ConnectionRefused</errorname> - indicates the display could not be opened. +indicates the display could not be opened. </para> </listitem> <listitem> <para> <errorname>XkbOD_BadServerVersion</errorname> - indicates the library and the server have incompatible extension versions. +indicates the library and the server have incompatible extension versions. </para> </listitem> <listitem> <para> <errorname>XkbOD_NonXkbServer</errorname> - indicates the extension is not present in the X server. +indicates the extension is not present in the X server. </para> </listitem> <listitem> <para> <errorname>XkbOD_Success</errorname> - indicates that the function succeeded. +indicates that the function succeeded. </para> </listitem> </itemizedlist> @@ -514,10 +514,10 @@ functionality. <para> Call <function>XkbIgnoreExtension</function> - to prevent core X library keyboard functions from using the X Keyboard +to prevent core X library keyboard functions from using the X Keyboard Extension. You must call <function>XkbIgnoreExtension</function> - before you open a server connection; Xkb does not provide a way to enable or +before you open a server connection; Xkb does not provide a way to enable or disable use of the extension once a connection is established. </para> @@ -547,7 +547,7 @@ disable use of the extension once a connection is established. <para> <function>XkbIgnoreExtension</function> - tells the X library whether to use the X Keyboard Extension on any +tells the X library whether to use the X Keyboard Extension on any subsequently opened X display connections. If ignore is <symbol>True</symbol>, the library does not initialize the Xkb extension when it opens a new @@ -556,12 +556,12 @@ with the client using only core protocol requests and events. If ignore is <symbol>False</symbol>, the library treats subsequent calls to <function>XOpenDisplay</function> - normally and uses Xkb extension requests, events, and state. Do not explicitly +normally and uses Xkb extension requests, events, and state. Do not explicitly use Xkb on a connection for which it is disabled. <function>XkbIgnoreExtension</function> - returns +returns <symbol>False</symbol> - if it was unable to apply the ignore request. +if it was unable to apply the ignore request. </para> </sect1> @@ -574,9 +574,9 @@ use Xkb on a connection for which it is disabled. Many of the Xkb extension library functions described in this document can cause the X server to report an error, referred to in this document as a <errorname>Bad<replaceable>Xxx</replaceable></errorname> - protocol error, where +protocol error, where <replaceable>Xxx</replaceable> - is some name. These errors are fielded in the normal manner, by the default +is some name. These errors are fielded in the normal manner, by the default Xlib error handler or one replacing it. Note that X protocol errors are not necessarily reported immediately because of the buffering of X protocol requests in Xlib and the server. @@ -679,17 +679,17 @@ The Xkb extension adds a single protocol error, <errorname>BadKeyboard</errorname>, to the core protocol error set. This error code will be reported as the <parameter>error_rtrn</parameter> - when +when <function>XkbQueryExtension</function> - is called. When a +is called. When a <errorname>BadKeyboard</errorname> - error is reported in an +error is reported in an <structname>XErrorEvent</structname>, additional information is reported in the <structfield>resourceid</structfield> - field. The most significant byte of the +field. The most significant byte of the <structfield>resource_id</structfield> - is a further refinement of the error cause, as defined in +is a further refinement of the error cause, as defined in <link linkend="table2.2">Table 2.2</link>. The least significant byte will contain the device, class, or feedback ID as indicated in the table. @@ -753,31 +753,31 @@ indicated ID <para> Where a connection to the server is passed as an argument (Display*) and an <type>XkbDescPtr</type> - is also passed as an argument, the Display* argument must match the +is also passed as an argument, the Display* argument must match the <structfield>dpy</structfield> - field of the +field of the <structname>XkbDescRec</structname> - pointed to by the +pointed to by the <type>XkbDescPtr</type> - argument, or else the +argument, or else the <structfield>dpy</structfield> - field of the +field of the <structname>XkbDescRec</structname> - must be +must be <symbol>NULL</symbol>. If they don’t match or the <structfield>dpy</structfield> - field is not +field is not <symbol>NULL</symbol>, a <errorname>BadMatch</errorname> - error is returned (either in the return value or a backfilled +error is returned (either in the return value or a backfilled <type>Status</type> - variable). Upon successful return, the +variable). Upon successful return, the <structfield>dpy</structfield> - field of the +field of the <structname>XkbDescRec</structname> - always contains the Display* value passed in. +always contains the Display* value passed in. </para> <para> @@ -786,51 +786,51 @@ Consequently, there can potentially be more than one input device connected to the server. Most Xkb library calls that require communicating with the server involve both a server connection (Display * <structfield>dpy</structfield>) - and a device identifier (unsigned int +and a device identifier (unsigned int <structfield>device_spec</structfield>). - In some cases, the device identifier is implicit and is taken as the +In some cases, the device identifier is implicit and is taken as the <structfield>device_spec</structfield> - field of an +field of an <structname>XkbDescRec</structname> - structure passed as an argument. +structure passed as an argument. </para> <para id='XkbUseCoreKbd'> <indexterm significance="preferred" zone="XkbUseCoreKbd"><primary><symbol>XkbUseCoreKbd</symbol></primary></indexterm> The device identifier can specify any X input extension device with a <symbol>KeyClass</symbol> - component, or it can specify the constant, +component, or it can specify the constant, <symbol>XkbUseCoreKbd</symbol>. The use of <symbol>XkbUseCoreKbd</symbol> - allows applications to indicate the core keyboard without having to determine +allows applications to indicate the core keyboard without having to determine its device identifier. </para> <para> Where an Xkb device identifier is passed as an argument and an <type>XkbDescPtr</type> - is also passed as an argument, if either the argument or the +is also passed as an argument, if either the argument or the <structname>XkbDescRec</structname> <structfield>device_spec</structfield> - field is +field is <symbol>XkbUseCoreKbd</symbol>, and if the function returns successfully, the <type>XkbDescPtr</type> <structfield>device_spec</structfield> - field will have been converted from +field will have been converted from <symbol>XkbUseCoreKbd</symbol> - to a real Xkb device ID. If the function does not complete successfully, the +to a real Xkb device ID. If the function does not complete successfully, the <structfield>device_spec</structfield> - field remains unchanged. Subsequently, the device id argument must match the +field remains unchanged. Subsequently, the device id argument must match the <structfield>device_spec</structfield> - field of the +field of the <type>XkbDescPtr</type> - argument. If they don’t match, a +argument. If they don’t match, a <errorname>BadMatch</errorname> - error is returned (either in the return value or a backfilled +error is returned (either in the return value or a backfilled <type>Status</type> - variable). +variable). </para> <para> @@ -841,7 +841,7 @@ support the input extension, the meaning of the identifier is undefined — the only guarantee is that when you use <symbol>XkbUseCoreKbd</symbol>, <symbol>XkbUseCoreKbd</symbol> - will work and the identifier returned by the server will refer to the core +will work and the identifier returned by the server will refer to the core keyboard device. </para> </sect1> |