819 lines
22 KiB
XML
819 lines
22 KiB
XML
|
<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>
|