diff options
Diffstat (limited to 'libX11/specs/XKB/ch02.xml')
| -rw-r--r-- | libX11/specs/XKB/ch02.xml | 818 |
1 files changed, 818 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch02.xml b/libX11/specs/XKB/ch02.xml new file mode 100644 index 000000000..55f15a322 --- /dev/null +++ b/libX11/specs/XKB/ch02.xml @@ -0,0 +1,818 @@ +<chapter id='initialization_and_general_programming_information'> +<title>Initialization and General Programming Information</title> +<sect1 id='extension_header_files'> +<title>Extension Header Files</title> +<para> +The following include files are part of the Xkb standard: +</para> +<itemizedlist> + <listitem> + <para> +<emphasis><X11/XKBlib.h></emphasis> + </para> + <para><emphasis>XKBlib.h</emphasis> +is the main header file for Xkb; it declares constants, types, and +functions. + </para> + </listitem> + <listitem> + <para> +<emphasis><X11/extensions/XKBstr.h></emphasis> + </para> + <para> +<emphasis>XKBstr.h</emphasis> declares types and +constants for Xkb. It is included automatically from +<emphasis><X11/XKBlib.h></emphasis> +; you should never need to reference it directly in your application code. + </para> + </listitem> + <listitem> + <para> +<emphasis><X11/extensions/XKB.h></emphasis> + </para> + <para> +<emphasis>XKB.h</emphasis> +defines constants for Xkb. It is included automatically from <emphasis> +<X11/XKBstr.h></emphasis> +; you should never need to reference it directly in your application code. + </para> + </listitem> + <listitem> + <para> +<emphasis><X11/extensions/XKBgeom.h></emphasis> + </para> + <para><emphasis>XKBgeom.h</emphasis> +declares types, symbolic constants, and functions for manipulating +keyboard geometry descriptions. + </para> + </listitem> +</itemizedlist> +</sect1> +<sect1 id='extension_name'> +<title>Extension Name</title> +<para> +The name of the Xkb extension is given in <emphasis> +<X11/extensions/Xkb.h>:</emphasis> +</para> + +<para> +<emphasis> +#define XkbName "XKEYBOARD"</emphasis> +</para> + +<para> +Most extensions to the X protocol are initialized by calling <emphasis> +XInitExtension</emphasis> + and passing the extension name. However, as explained in section 2.4, Xkb +requires a more complex initialization sequence, and a client program should +not call <emphasis> +XInitExtension</emphasis> + directly. +</para> +</sect1> +<sect1 id='determining_library_compatibility'> +<title>Determining Library Compatibility</title> +<para> +If an application is dynamically linked, both the X server and the client-side +X library must contain the Xkb extension in order for the client to use the Xkb +extension capabilities. Therefore a dynamically linked application must check +both the library and the server for compatibility before using Xkb function +calls. A properly written program must check for compatibility between the +version of the Xkb library that is dynamically loaded and the one used when the +application was built. It must then check the server version for compatibility +with the version of Xkb in the library. +</para> +<para> +If your application is statically linked, you must still check for server +compatibility and may check library compatibility. (It is possible to compile +against one set of header files and link against a different, incompatible, +version of the library, although this should not normally occur.) +</para> +<para> +To determine the compatibility of a library at runtime, call <emphasis> +XkbLibraryVersion</emphasis>. +</para> +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbLibraryVersion</emphasis> +(<emphasis> +lib_major_in_out</emphasis> +, <emphasis> +lib_minor_in_out</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +lib_major_in_out;</emphasis> + /* specifies and returns the major Xkb library version. */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +lib_minor_in_out;</emphasis> + /* specifies and returns the minor Xkb library version. */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +Pass the symbolic value <emphasis> +XkbMajorVersion</emphasis> + in <emphasis> +lib_major_in_out</emphasis> + and <emphasis> +XkbMinorVersion</emphasis> + in <emphasis> +lib_minor_in_out</emphasis> +. These arguments represent the version of the library used at compile time. +The <emphasis> +XkbLibraryVersion </emphasis> +function backfills the major and minor version numbers of the library used at +run time in <emphasis> +lib_major_in_out</emphasis> + and <emphasis> +lib_minor_in_out</emphasis> +. If the versions of the compile time and run time libraries are compatible, +<emphasis> +XkbLibraryVersion </emphasis> +returns <emphasis> +True</emphasis> +, otherwise, it returns <emphasis> +False.</emphasis> +</para> + +<para> +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 <emphasis> +XkbQueryExtension</emphasis> + to do this, as described in the next section. +</para> + +</sect1> +<sect1 id='initializing_the_keyboard_extension'> +<title>Initializing the Keyboard Extension</title> +<para> +Call <emphasis> +XkbQueryExtension</emphasis> + 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 (<emphasis> +XQueryExtension </emphasis> +and<emphasis> + XInitExtension</emphasis> +) for checking for the presence of, and initializing the Xkb extension. +</para> + +<para> +You must call <emphasis> +XkbQueryExtension</emphasis> + or <emphasis> +XkbOpenDisplay</emphasis> + before using any other Xkb library interfaces, unless such usage is explicitly +allowed in the interface description in this document. The exceptions are: +<emphasis> +XkbIgnoreExtension</emphasis> +, <emphasis> +XkbLibraryVersion</emphasis> +, and a handful of audible-bell functions. You should not use any other Xkb +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 <emphasis> +BadAccess</emphasis> + protocol errors. +</para> + +<para> +<emphasis> +XkbQueryExtension</emphasis> + both determines whether a compatible Xkb extension is present in the X server +and initializes the extension when it is present. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbQueryExtension</emphasis> +(<emphasis> +dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy; </emphasis> + /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +opcode_rtrn</emphasis> +; /* backfilled with the major extension opcode */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +event_rtrn</emphasis> +; /* backfilled with the extension base event code */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +error_rtrn</emphasis> +; /* backfilled with the extension base error code */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +major_in_out</emphasis> +; /* compile time lib major version in, server major version out */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +minor_in_out; </emphasis> + /* compile time lib min version in, server minor version out */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +XkbQueryExtension</emphasis> + function determines whether a compatible version of the X Keyboard Extension +is present in the server. If a compatible extension is present, <emphasis> +XkbQueryExtension</emphasis> + returns <emphasis> +True</emphasis> +; otherwise, it returns <emphasis> +False</emphasis> +. +</para> + +<para> +If a compatible version of Xkb is present, <emphasis> +XkbQueryExtension</emphasis> + initializes the extension. It backfills the major opcode for the keyboard +extension in <emphasis> +opcode_rtrn</emphasis> +, the base event code in <emphasis> +event_rtrn</emphasis> +<emphasis> +, the base error code</emphasis> + in <emphasis> +error_rtrn</emphasis> +, and the major and minor version numbers of the extension in <emphasis> +major_in_out</emphasis> + and <emphasis> +minor_in_out</emphasis> +. The major opcode is reported in the <emphasis> +req_major</emphasis> + fields of some Xkb events. For a discussion of the base event code, see +section 4.1. <!-- xref --> +</para> + +<para> +As a convenience, you can use the function <emphasis> +XkbOpenDisplay</emphasis> + 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> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Display *<emphasis> +XkbOpenDisplay</emphasis> +(<emphasis> +display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out, +reason_rtrn)</emphasis> + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +char * <emphasis> +display_name</emphasis> +; /* hardware display name, which determines the display and +communications domain to be used */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +event_rtrn</emphasis> +; /* backfilled with the extension base event code */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +error_rtrn</emphasis> +; /* backfilled with the extension base error code */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +major_in_out</emphasis> +; /* compile time lib major version in, server major version out */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +minor_in_out</emphasis> +; /* compile time lib minor version in, server minor version out */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +reason_rtrn</emphasis> +; /* backfilled with a status code */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbOpenDisplay </emphasis> +is a convenience function that opens an X display connection and initializes +the X keyboard extension. In all cases, upon return <emphasis> +reason_rtrn</emphasis> + contains a status value indicating success or the type of failure. If +<emphasis> +major_in_out</emphasis> + and <emphasis> +minor_in_out</emphasis> + are not <emphasis> +NULL</emphasis> +, <emphasis> +XkbOpenDisplay</emphasis> + first calls <emphasis> +XkbLibraryVersion</emphasis> + to determine whether the client library is compatible, passing it the values +pointed to by <emphasis> +major_in_out</emphasis> + and <emphasis> +minor_in_out</emphasis> +. If the library is incompatible, <emphasis> +XkbOpenDisplay</emphasis> + backfills <emphasis> +major_in_out</emphasis> + and <emphasis> +minor_in_out</emphasis> + with the major and minor extension versions of the library being used and +returns <emphasis> +NULL</emphasis> +. If the library is compatible,<emphasis> + XkbOpenDisplay </emphasis> +next calls <emphasis> +XOpenDisplay</emphasis> + with the <emphasis> +display_name</emphasis> +. If this fails, the function returns <emphasis> +NULL</emphasis> +. If successful, <emphasis> +XkbOpenDisplay </emphasis> +calls <emphasis> +XkbQueryExtension</emphasis> + and<emphasis> + </emphasis> +backfills the major and minor Xkb server extension version numbers in <emphasis> +major_in_out</emphasis> + and <emphasis> +minor_in_out</emphasis> +.<emphasis> + </emphasis> +If the server extension version is not compatible with the library extension +version or if the server extension is not present, <emphasis> +XkbOpenDisplay </emphasis> +closes the display and returns <emphasis> +NULL</emphasis> +. When successful, the function returns the display connection<emphasis> +.</emphasis> +</para> + +<para> +The possible values for <emphasis> +reason_rtrn</emphasis> are: +</para> + +<itemizedlist> +<listitem> + <para> +<emphasis> +XkbOD_BadLibraryVersion</emphasis> + indicates <emphasis> +XkbLibraryVersion </emphasis> +returned <emphasis> +False</emphasis>. + </para> +</listitem> +<listitem> + <para> +<emphasis> +XkbOD_ConnectionRefused</emphasis> + indicates the display could not be opened. + </para> +</listitem> +<listitem> + <para> +<emphasis> +XkbOD_BadServerVersion</emphasis> + indicates the library and the server have incompatible extension versions. + </para> +</listitem> +<listitem> + <para> +<emphasis> +XkbOD_NonXkbServer</emphasis> + indicates the extension is not present in the X server. + </para> +</listitem> +<listitem> + <para> +<emphasis> +XkbOD_Success</emphasis> + indicates that the function succeeded. + </para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id='disabling_the_keyboard_extension'> +<title>Disabling the Keyboard Extension</title> +<para> +If a server supports the Xkb extension, the X library normally implements +preXkb keyboard functions using the Xkb keyboard description and state. The +server Xkb keyboard state may differ from the preXkb keyboard state. This +difference does not affect most clients, but there are exceptions. To allow +these clients to work properly, you may instruct the extension not to use Xkb +functionality. +</para> + +<para> +Call <emphasis> +XkbIgnoreExtension</emphasis> + to prevent core X library keyboard functions from using the X Keyboard +Extension. You must call <emphasis> +XkbIgnoreExtension</emphasis> + 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> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool<emphasis> + XkbIgnoreExtension</emphasis> +(<emphasis> +ignore</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> +ignore</emphasis> +; /* <emphasis> +True</emphasis> + means ignore the extension */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbIgnoreExtension</emphasis> + tells the X library whether to use the X Keyboard Extension on any +subsequently opened X display connections. If ignore is <emphasis> +True</emphasis> +, the library does not initialize the Xkb extension when it opens a new +display. This forces the X server to use compatibility mode and communicate +with the client using only core protocol requests and events. If ignore is +<emphasis> +False</emphasis> +, the library treats subsequent calls to <emphasis> +XOpenDisplay</emphasis> + normally and uses Xkb extension requests, events, and state. Do not explicitly +use Xkb on a connection for which it is disabled.<emphasis> + XkbIgnoreExtension</emphasis> + returns <emphasis> +False</emphasis> + if it was unable to apply the ignore request. +</para> + +</sect1> +<sect1 id='protocol_errors'> +<title>Protocol Errors</title> +<para> +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 +<emphasis> +BadXxx</emphasis> + protocol error, where <emphasis> +Xxx</emphasis> + 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. +</para> + +<para> +Table 2.1 lists the protocol errors that can be generated, and their causes. <!-- xref --> +</para> + +<table frame='none'> +<title>Xkb Protocol Errors</title> +<tgroup cols='2'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> + <row rowsep='1'> + <entry>Error</entry> + <entry>Cause</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>BadAccess</entry> + <entry> +<para> +The Xkb extension has not been properly initialized +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadKeyboard</entry> + <entry> +<para> +The device specified was not a valid core or input extension device +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadImplementation</entry> + <entry> +<para> +Invalid reply from server +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadAlloc</entry> + <entry> +<para> +Unable to allocate storage +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadMatch</entry> + <entry> +<para> +A compatible version of Xkb was not available in the server or an argument has +correct type and range, but is otherwise invalid +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadValue</entry> + <entry> +<para> +An argument is out of range +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadAtom</entry> + <entry> +<para> +A name is neither a valid Atom or <emphasis> +None</emphasis> +</para> + </entry> + </row> + <row rowsep='0'> + <entry>BadDevice</entry> + <entry> +<para> +Device, Feedback Class, or Feedback ID invalid +</para> + </entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +The Xkb extension adds a single protocol error, <emphasis> +BadKeyboard</emphasis> +, to the core protocol error set. This error code will be reported as the +<emphasis> +error_rtrn</emphasis> + when <emphasis> +XkbQueryExtension</emphasis> + is called. When a <emphasis> +BadKeyboard</emphasis> + error is reported in an <emphasis> +XErrorEvent</emphasis> +, additional information is reported in the <emphasis> +resource_id</emphasis> + field. The most significant byte of the <emphasis> +resource_id</emphasis> + is a further refinement of the error cause, as defined in Table 2.2. The least +significant byte will contain the device, class, or feedback ID as indicated in +the table. +</para> + +<table frame='none'> +<title>BadKeyboard Protocol Error resource_id Values</title> +<tgroup cols='4'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> + <row rowsep='0'> + <entry>high-order byte</entry> + <entry>value</entry> + <entry>meaning</entry> + <entry>low-order byte</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbErr_BadDevice</entry> + <entry>0xff</entry> + <entry> +<para> +device not found +</para> + </entry> + <entry>device ID</entry> + </row> + <row rowsep='0'> + <entry>XkbErr_BadClass</entry> + <entry>0xfe</entry> + <entry> +<para> +device found, but it is of the wrong class +</para> + </entry> + <entry>class ID</entry> + </row> + <row rowsep='0'> + <entry>XkbErr_BadId</entry> + <entry>0xfd</entry> + <entry> +<para> +device found, class ok, but device does not contain a feedback with the +indicated ID +</para> + </entry> + <entry>feedback ID</entry> + </row> +</tbody> +</tgroup> +</table> +</sect1> + +<sect1 id='display_and_device_specifications_in_function_calls'> +<title>Display and Device Specifications in Function Calls</title> +<para> +Where a connection to the server is passed as an argument (Display*) and an +<emphasis> +XkbDescPtr</emphasis> + is also passed as an argument, the Display* argument must match the <emphasis> +dpy</emphasis> + field of the <emphasis> +XkbDescRec</emphasis> + pointed to by the <emphasis> +XkbDescPtr</emphasis> + argument, or else the <emphasis> +dpy</emphasis> + field of the <emphasis> +XkbDescRec</emphasis> + must be <emphasis> +NULL</emphasis> +. If they don’t match or the <emphasis> +dpy</emphasis> + field is not <emphasis> +NULL</emphasis> +, a <emphasis> +BadMatch</emphasis> + error is returned (either in the return value or a backfilled <emphasis> +Status</emphasis> + variable). Upon successful return, the <emphasis> +dpy</emphasis> + field of the <emphasis> +XkbDescRec</emphasis> + always contains the Display* value passed in. +</para> + +<para> +The Xkb extension can communicate with the X input extension if it is present. +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 * <emphasis> +dpy</emphasis> +) and a device identifier (unsigned int <emphasis> +device_spec</emphasis> +). In some cases, the device identifier is implicit and is taken as the +<emphasis> +device_spec</emphasis> + field of an <emphasis> +XkbDescRec</emphasis> + structure passed as an argument. +</para> + +<para> +The device identifier can specify any X input extension device with a <emphasis> +KeyClass</emphasis> + component, or it can specify the constant, <emphasis> +XkbUseCoreKbd</emphasis> +. The use of <emphasis> +XkbUseCoreKbd</emphasis> + 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 <emphasis> +XkbDescPtr</emphasis> + is also passed as an argument, if either the argument or the <emphasis> +XkbDescRec</emphasis> + <emphasis> +device_spec</emphasis> + field is <emphasis> +XkbUseCoreKbd</emphasis> +, and if the function returns successfully, the <emphasis> +XkbDescPtr</emphasis> + <emphasis> +device_spec</emphasis> + field will have been converted from <emphasis> +XkbUseCoreKbd</emphasis> + to a real Xkb device ID. If the function does not complete successfully, the +<emphasis> +device_spec</emphasis> + field remains unchanged. Subsequently, the device id argument must match the +<emphasis> +device_spec</emphasis> + field of the <emphasis> +XkbDescPtr</emphasis> + argument. If they don’t match, a <emphasis> +BadMatch</emphasis> + error is returned (either in the return value or a backfilled <emphasis> +Status</emphasis> + variable). +</para> + +<para> +When the Xkb extension in the server hands an application a device identifier +to use for the keyboard, that ID is the input extension identifier for the +device if the server supports the X Input Extension. If the server does not +support the input extension, the meaning of the identifier is undefined — the +only guarantee is that when you use <emphasis> +XkbUseCoreKbd</emphasis> +, <emphasis> +XkbUseCoreKbd</emphasis> + will work and the identifier returned by the server will refer to the core +keyboard device. +</para> +</sect1> +</chapter> |