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>
|