From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch02.xml | 818 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 818 insertions(+) create mode 100644 libX11/specs/XKB/ch02.xml (limited to 'libX11/specs/XKB/ch02.xml') 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 @@ + +Initialization and General Programming Information + +Extension Header Files + +The following include files are part of the Xkb standard: + + + + +<X11/XKBlib.h> + + XKBlib.h +is the main header file for Xkb; it declares constants, types, and +functions. + + + + +<X11/extensions/XKBstr.h> + + +XKBstr.h declares types and +constants for Xkb. It is included automatically from +<X11/XKBlib.h> +; you should never need to reference it directly in your application code. + + + + +<X11/extensions/XKB.h> + + +XKB.h +defines constants for Xkb. It is included automatically from +<X11/XKBstr.h> +; you should never need to reference it directly in your application code. + + + + +<X11/extensions/XKBgeom.h> + + XKBgeom.h +declares types, symbolic constants, and functions for manipulating +keyboard geometry descriptions. + + + + + +Extension Name + +The name of the Xkb extension is given in +<X11/extensions/Xkb.h>: + + + + +#define XkbName "XKEYBOARD" + + + +Most extensions to the X protocol are initialized by calling +XInitExtension + 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 +XInitExtension + directly. + + + +Determining Library Compatibility + +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. + + +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.) + + +To determine the compatibility of a library at runtime, call +XkbLibraryVersion. + + + + + + + +Bool +XkbLibraryVersion +( +lib_major_in_out +, +lib_minor_in_out +) + + + + +int * +lib_major_in_out; + /* specifies and returns the major Xkb library version. */ + + + + +int * +lib_minor_in_out; + /* specifies and returns the minor Xkb library version. */ + + + + + + + +Pass the symbolic value +XkbMajorVersion + in +lib_major_in_out + and +XkbMinorVersion + in +lib_minor_in_out +. These arguments represent the version of the library used at compile time. +The +XkbLibraryVersion +function backfills the major and minor version numbers of the library used at +run time in +lib_major_in_out + and +lib_minor_in_out +. If the versions of the compile time and run time libraries are compatible, + +XkbLibraryVersion +returns +True +, otherwise, it returns +False. + + + +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 +XkbQueryExtension + to do this, as described in the next section. + + + + +Initializing the Keyboard Extension + +Call +XkbQueryExtension + 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 ( +XQueryExtension +and + XInitExtension +) for checking for the presence of, and initializing the Xkb extension. + + + +You must call +XkbQueryExtension + or +XkbOpenDisplay + before using any other Xkb library interfaces, unless such usage is explicitly +allowed in the interface description in this document. The exceptions are: + +XkbIgnoreExtension +, +XkbLibraryVersion +, 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 +BadAccess + protocol errors. + + + + +XkbQueryExtension + both determines whether a compatible Xkb extension is present in the X server +and initializes the extension when it is present. + + + + + + + + +Bool +XkbQueryExtension +( +dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out +) + + + + +Display * +dpy; + /* connection to the X server */ + + + + +int * +opcode_rtrn +; /* backfilled with the major extension opcode */ + + + + +int * +event_rtrn +; /* backfilled with the extension base event code */ + + + + +int * +error_rtrn +; /* backfilled with the extension base error code */ + + + + +int * +major_in_out +; /* compile time lib major version in, server major version out */ + + + + +int * +minor_in_out; + /* compile time lib min version in, server minor version out */ + + + + + + + +The +XkbQueryExtension + function determines whether a compatible version of the X Keyboard Extension +is present in the server. If a compatible extension is present, +XkbQueryExtension + returns +True +; otherwise, it returns +False +. + + + +If a compatible version of Xkb is present, +XkbQueryExtension + initializes the extension. It backfills the major opcode for the keyboard +extension in +opcode_rtrn +, the base event code in +event_rtrn + +, the base error code + in +error_rtrn +, and the major and minor version numbers of the extension in +major_in_out + and +minor_in_out +. The major opcode is reported in the +req_major + fields of some Xkb events. For a discussion of the base event code, see +section 4.1. + + + +As a convenience, you can use the function +XkbOpenDisplay + 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. + + + + + + + + +Display * +XkbOpenDisplay +( +display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out, +reason_rtrn) + + + + +char * +display_name +; /* hardware display name, which determines the display and +communications domain to be used */ + + + + +int * +event_rtrn +; /* backfilled with the extension base event code */ + + + + +int * +error_rtrn +; /* backfilled with the extension base error code */ + + + + +int * +major_in_out +; /* compile time lib major version in, server major version out */ + + + + +int * +minor_in_out +; /* compile time lib minor version in, server minor version out */ + + + + +int * +reason_rtrn +; /* backfilled with a status code */ + + + + + + + + +XkbOpenDisplay +is a convenience function that opens an X display connection and initializes +the X keyboard extension. In all cases, upon return +reason_rtrn + contains a status value indicating success or the type of failure. If + +major_in_out + and +minor_in_out + are not +NULL +, +XkbOpenDisplay + first calls +XkbLibraryVersion + to determine whether the client library is compatible, passing it the values +pointed to by +major_in_out + and +minor_in_out +. If the library is incompatible, +XkbOpenDisplay + backfills +major_in_out + and +minor_in_out + with the major and minor extension versions of the library being used and +returns +NULL +. If the library is compatible, + XkbOpenDisplay +next calls +XOpenDisplay + with the +display_name +. If this fails, the function returns +NULL +. If successful, +XkbOpenDisplay +calls +XkbQueryExtension + and + +backfills the major and minor Xkb server extension version numbers in +major_in_out + and +minor_in_out +. + +If the server extension version is not compatible with the library extension +version or if the server extension is not present, +XkbOpenDisplay +closes the display and returns +NULL +. When successful, the function returns the display connection +. + + + +The possible values for +reason_rtrn are: + + + + + + +XkbOD_BadLibraryVersion + indicates +XkbLibraryVersion +returned +False. + + + + + +XkbOD_ConnectionRefused + indicates the display could not be opened. + + + + + +XkbOD_BadServerVersion + indicates the library and the server have incompatible extension versions. + + + + + +XkbOD_NonXkbServer + indicates the extension is not present in the X server. + + + + + +XkbOD_Success + indicates that the function succeeded. + + + + + + +Disabling the Keyboard Extension + +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. + + + +Call +XkbIgnoreExtension + to prevent core X library keyboard functions from using the X Keyboard +Extension. You must call +XkbIgnoreExtension + 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. + + + + + + + + +Bool + XkbIgnoreExtension +( +ignore +) + + + + +Bool +ignore +; /* +True + means ignore the extension */ + + + + + + + + +XkbIgnoreExtension + tells the X library whether to use the X Keyboard Extension on any +subsequently opened X display connections. If ignore is +True +, 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 + +False +, the library treats subsequent calls to +XOpenDisplay + normally and uses Xkb extension requests, events, and state. Do not explicitly +use Xkb on a connection for which it is disabled. + XkbIgnoreExtension + returns +False + if it was unable to apply the ignore request. + + + + +Protocol Errors + +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 + +BadXxx + protocol error, where +Xxx + 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. + + + +Table 2.1 lists the protocol errors that can be generated, and their causes. + + + +Xkb Protocol Errors + + + + + + Error + Cause + + + + + BadAccess + + +The Xkb extension has not been properly initialized + + + + + BadKeyboard + + +The device specified was not a valid core or input extension device + + + + + BadImplementation + + +Invalid reply from server + + + + + BadAlloc + + +Unable to allocate storage + + + + + BadMatch + + +A compatible version of Xkb was not available in the server or an argument has +correct type and range, but is otherwise invalid + + + + + BadValue + + +An argument is out of range + + + + + BadAtom + + +A name is neither a valid Atom or +None + + + + + BadDevice + + +Device, Feedback Class, or Feedback ID invalid + + + + + +
+ + +The Xkb extension adds a single protocol error, +BadKeyboard +, to the core protocol error set. This error code will be reported as the + +error_rtrn + when +XkbQueryExtension + is called. When a +BadKeyboard + error is reported in an +XErrorEvent +, additional information is reported in the +resource_id + field. The most significant byte of the +resource_id + 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. + + + +BadKeyboard Protocol Error resource_id Values + + + + + + + + high-order byte + value + meaning + low-order byte + + + + + XkbErr_BadDevice + 0xff + + +device not found + + + device ID + + + XkbErr_BadClass + 0xfe + + +device found, but it is of the wrong class + + + class ID + + + XkbErr_BadId + 0xfd + + +device found, class ok, but device does not contain a feedback with the +indicated ID + + + feedback ID + + + +
+ + + +Display and Device Specifications in Function Calls + +Where a connection to the server is passed as an argument (Display*) and an + +XkbDescPtr + is also passed as an argument, the Display* argument must match the +dpy + field of the +XkbDescRec + pointed to by the +XkbDescPtr + argument, or else the +dpy + field of the +XkbDescRec + must be +NULL +. If they don’t match or the +dpy + field is not +NULL +, a +BadMatch + error is returned (either in the return value or a backfilled +Status + variable). Upon successful return, the +dpy + field of the +XkbDescRec + always contains the Display* value passed in. + + + +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 * +dpy +) and a device identifier (unsigned int +device_spec +). In some cases, the device identifier is implicit and is taken as the + +device_spec + field of an +XkbDescRec + structure passed as an argument. + + + +The device identifier can specify any X input extension device with a +KeyClass + component, or it can specify the constant, +XkbUseCoreKbd +. The use of +XkbUseCoreKbd + allows applications to indicate the core keyboard without having to determine +its device identifier. + + + +Where an Xkb device identifier is passed as an argument and an +XkbDescPtr + is also passed as an argument, if either the argument or the +XkbDescRec + +device_spec + field is +XkbUseCoreKbd +, and if the function returns successfully, the +XkbDescPtr + +device_spec + field will have been converted from +XkbUseCoreKbd + to a real Xkb device ID. If the function does not complete successfully, the + +device_spec + field remains unchanged. Subsequently, the device id argument must match the + +device_spec + field of the +XkbDescPtr + argument. If they don’t match, a +BadMatch + error is returned (either in the return value or a backfilled +Status + variable). + + + +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 +XkbUseCoreKbd +, +XkbUseCoreKbd + will work and the identifier returned by the server will refer to the core +keyboard device. + + + -- cgit v1.2.3