The X Keyboard Extension:

The core X protocol specifies the ways that the Shift, Control, and Lock modifiers and the modifiers bound to the Mode_switch or Num_Lock keysyms interact to generate keysyms and characters. The core protocol also allows users to specify that a key affects one or more modifiers. This behavior is simple and fairly flexible, but it has a number of limitations that make it difficult or impossible to properly support many common varieties of keyboard behavior. The limitations of core protocol support for keyboards include:

The X Keyboard Extension makes it possible to clearly and explicitly specify most aspects of keyboard behavior on a per-key basis. It adds the notion of a keyboard group to the global keyboard state and provides mechanisms to more closely track the logical and physical state of the keyboard. For keyboard-control clients, Xkb provides descriptions and symbolic names for many aspects of keyboard appearance and behavior.

In addition, the X Keyboard Extension includes additional keyboard controls designed to make keyboards more accessible to people with movement impairments.

The Xkb extension is composed of two parts: a server extension, and a client-side X library extension. These consist of a loadable module that may be activated when an X server is started and a modified version of Xlib. Both server and Xlib versions must be at least X11 R6.

Figure 1.1 shows the overall structure of the Xkb extension:

Overall Xkb Structure

The server portion of the Xkb extension encompasses a database of named keyboard components, in unspecified format, that may be used to configure a keyboard. Internally, the server maintains a keyboard description that includes the keyboard state and configuration (mapping). By "keyboard" we mean the logical keyboard device, which includes not only the physical keys, but also potentially a set of up to 32 indicators (usually LEDs) and bells.

The keyboard description is a composite of several different data structures, each of which may be manipulated separately. When manipulating the server components, the design allows partial components to be transmitted between the server and a client. The individual components are shown in Figure 1.1.

A client application interrogates and manipulates the keyboard by reading and writing portions of the server description for the keyboard. In a typical sequence a client would fetch the current information it is interested in, modify it, and write it back. If a client wishes to track some portion of the keyboard state, it typically maintains a local copy of the portion of the server keyboard description dealing with the items of interest and updates this local copy from events describing state transitions that are sent by the server.

A client may request the server to reconfigure the keyboard either by sending explicit reconfiguration instructions to it, or by telling it to load a new configuration from its database of named components. Partial reconfiguration and incremental reconfiguration are both supported.

This specification differentiates between three different classes of client applications:

Because the Xkb extension allows a keyboard to be configured in ways not foreseen by the core protocol, and because Xkb-unaware clients are allowed to connect to a server using the Xkb extension, there must be a means of converting between the Xkb domain and the core protocol. The Xkb server extension maintains a compatibility map as part of its keyboard description; this map controls the conversion of Xkb generated events to core protocol events and the results of core protocol requests to appropriate Xkb state and configuration.

The Xkb extension adds a single protocol error, BadKeyboard , to the core protocol error set. See section 2.6 for a discussion of the BadKeyboard protocol error.

The X Keyboard Extension replaces the core protocol definition of a keyboard with a more comprehensive one. The X Keyboard Extension library interfaces are included in Xlib.^[1]

Xlib detects the presence of the X Keyboard server extension and uses Xkb protocol to replace some standard X library functions related to the keyboard. If an application uses only standard X library functions to examine the keyboard or process key events, it should not need to be modified when linked with an X library containing the X keyboard extension. All of the keyboard-related X library functions have been modified to automatically use Xkb protocol when the server extension is present.

The Xkb extension adds library interfaces to allow a client application to directly manipulate the new capabilities.

The following include files are part of the Xkb standard:

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

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.

Xkb provides functions, known as allocators, to create and initialize Xkb data structures. In most situations, the Xkb functions that read a keyboard description from the server call these allocators automatically. As a result, you will seldom have to directly allocate or initialize Xkb data structures.

However, if you need to enlarge an existing structure or construct a keyboard definition from scratch, you may need to allocate and initialize Xkb data structures directly. Each major Xkb data structure has its own unique allocator. The allocator functions share common features: allocator functions for structures with optional components take as an input argument a mask of subcomponents to be allocated. Allocators for data structures containing variable-length data take an argument specifying the initial length of the data.

You may call an allocator to change the size of the space allocated for variable-length data. When you call an allocator with an existing data structure as a parameter, the allocator does not change the data in any of the fields, with one exception: variable-length data might be moved. The allocator resizes the allocated memory if the current size is too small. This normally involves allocating new memory, copying existing data to the newly allocated memory, and freeing the original memory. This possible reallocation is important to note because local variables pointing into Xkb data structures might be invalidated by calls to allocator functions.

You should edit most data structures via the Xkb-supplied helper functions and macros, although a few data structures can be edited directly. The helper functions and macros make sure everything is initialized and interdependent values are properly updated for those Xkb structures that have interdependencies. As a general rule, if there is a helper function or macro to edit the data structure, use it. For example, increasing the width of a type requires you to resize every key that uses that type. This is complicated and ugly, which is why there’s an XkbResizeKeyType function.

Many Xkb data structures have arrays whose size is reported by two fields. The first field, whose name is usually prefixed by sz_ , represents the total number of elements that can be stored in the array. The second field, whose name is usually prefixed by num_ , specifies the number of elements currently stored there. These arrays typically represent data whose total size cannot always be determined when the array is created. In these instances, the usual way to allocate space and add data is as follows:

For example, call:

XkbAllocGeomShapes(geom,4)

to say "I’ll need space for four new shapes in this geometry." This makes sure that sz_shapes - num_shapes >= 4, and resizes the shapes array if it isn’t. If this function succeeds, you are guaranteed to have space for the number of shapes you need.

When you call an editing function for a structure, you do not need to check for space, because the function automatically checks the sz_ and num_ fields of the array, resizes the array if necessary, adds the entry to the array, and then updates the num_ field.

In Xkb, as in the core protocol, the client and server have independent copies of the data structures that describe the keyboard. The recommended way to change some aspect of the keyboard mapping in the X server is to edit a local copy of the Xkb keyboard description and then send only the changes to the X server. This method helps eliminate the need to transfer the entire keyboard description or even an entire data structure for only minor changes.

To help you keep track of the changes you make to a local copy of the keyboard description, Xkb provides separate special changes data structures for each major Xkb data structure. These data structures do not contain the actual changed values: they only indicate the changes that have been made to the structures that actually describe the keyboard.

When you wish to change the keyboard description in the server, you first modify a local copy of the keyboard description and then flag the modifications in an appropriate changes data structure. When you finish editing the local copy of the keyboard description, you pass your modified version of the keyboard description and the modified changes data structure to an Xkb function. This function uses the modified keyboard description and changes structure to pass only the changed information to the server. Note that modifying the keyboard description but not setting the appropriate flags in the changes data structure causes indeterminate behavior.

The server reports all changes in its keyboard description to any interested clients via special Xkb events. Just as clients use special changes data structures to change the keyboard description in the server, the server uses special changes data structures to tell a client what changed in the server’s keyboard description.

Unlike clients, however, the server does not always pass the new values when it reports changes to its copy of the keyboard description. Instead, the server only passes a changes data structure when it reports changes to its keyboard description. This is done for efficiency reasons — some clients do not always need to update their copy of the keyboard description with every report from the server.

When your client application receives a report from the server indicating the keyboard description has changed, you can determine the set of changes by passing the event to an Xkb function that "notes" event information in the corresponding changes data structure. These "note changes" functions are defined for all major Xkb components, and their names have the form XkbNote{Component}Changes , where Component is the name of a major Xkb component such as Map or Names . When you want to copy these changes from the server into a local copy of the keyboard description, use the corresponding XkbGet{Component}Changes function , passing it the changes structure. The function then retrieves only the changed structures from the server and copies the modified pieces into the local keyboard description.

For the same reasons you should not directly use malloc to allocate Xkb data structures, you should not free Xkb data structures or components directly using free or Xfree . Xkb provides functions to free the various data structures and their components. Always use the free functions supplied by Xkb. There is no guarantee that any particular field can be safely freed by free or Xfree .

The Xkb Extension adds new event types to the X protocol definition. An Xkb event type is defined by two fields in the X event data structure. One is the type field, containing the base event code. This base event code is a value the X server assigns to each X extension at runtime and thatidentifies the extension that generated the event; thus, the event code in the type field identifies the event as an Xkb extension event, rather than an event from another extension or a core X protocol event. You can obtain the base event code via a call to XkbQueryExtension or XkbOpenDisplay . The second field is the Xkb event type, which contains a value uniquely identifying each different Xkb event type. Possible values are defined by constants declared in the header file <X11/extensions/Xkb.h>.

Table 4.1 lists the categories of events defined by Xkb and their associated event types, as defined in Xkb.h . Each event is described in more detail in the section referenced for that event.

Xkb reports each event it generates in a unique structure holding the data values needed to describe the conditions the event is reporting. However, all Xkb events have certain things in common. These common features are contained in the same fields at the beginning of all Xkb event structures and are described in the XkbAnyEvent structure:

typedef struct {
      int                type;        /* Xkb extension base event code */
      unsigned long      serial;      /* X server serial number for event */
      Bool               send_event;  /*  True => synthetically generated */
      Display *          display;     /* server connection where event
generated */
      Time               time;        /* server time when event generated */
      int                xkb_type;    /* Xkb minor event code */
      unsigned int       device;      /* Xkb device ID, will not be
                                         XkbUseCoreKbd */
} XkbAnyEvent
;

For any Xkb event, the type field is set to the base event code for the Xkb extension, assigned by the server to all Xkb extension events. The serial , send_event , and display fields are as described for all X11 events. The time field is set to the time when the event was generated and is expressed in milliseconds. The xkb_type field contains the minor extension event code, which is the extension event type, and is one of the values listed in Table 4.1. The device field contains the keyboard device identifier associated with the event. This is never XkbUseCoreKbd , even if the request that generated the event specified a device of XkbUseCoreKbd . If the request that generated the event specified XkbUseCoreKbd , device contains a value assigned by the server to specify the core keyboard. If the request that generated the event specified an X input extension device, device contains that same identifier.

Other data fields specific to individual Xkb events are described in subsequent chapters where the events are described.

Xkb events are selected using an event mask, much the same as normal core X events are selected. However, unlike selecting core X events, where you must specify the selection status (on or off) for all possible event types whenever you wish to change the selection criteria for any one event, Xkb allows you to restrict the specification to only the event types you wish to change. This means that you do not need to remember the event selection values for all possible types each time you want to change one of them.

Many Xkb event types are generated under several different circumstances. When selecting to receive an Xkb event, you may specify either that you want it delivered under all circumstances, or that you want it delivered only for a subset of the possible circumstances.

You can also deselect an event type that was previously selected for, using the same granularity.

Xkb provides two functions to select and deselect delivery of Xkb events. XkbSelectEvents allows you to select or deselect delivery of more than one Xkb event type at once. Events selected using XkbSelectEvents are delivered to your program under all circumstances that generate the events. To restrict delivery of an event to a subset of the conditions under which it occurs, use XkbSelectEventDetails . XkbSelectEventDetails only allows you to change the selection conditions for a single event at a time, but it provides a means of fine-tuning the conditions under which the event is delivered.

To select and / or deselect for delivery of one or more Xkb events and have them delivered under all conditions, use XkbSelectEvents .

This request changes the Xkb event selection mask for the keyboard specified by device_spec .

Each Xkb event that can be selected is represented by a bit in the bits_to_change and values_for_bits masks. Only the event selection bits specified by the bits_to_change parameter are affected; any unspecified bits are left unchanged. To turn on event selection for an event, set the bit for the event in the bits_to_change parameter and set the corresponding bit in the values_for_bits parameter. To turn off event selection for an event, set the bit for the event in the bits_to_change parameter and do not set the corresponding bit in the values_for_bits parameter. The valid values for both of these parameters are an inclusive bitwise OR of the masks shown in Table 4.2. There is no interface to return your client’s current event selection mask. Clients cannot set other clients’ event selection masks.

If a bit is not set in the bits_to_change parameter, but the corresponding bit is set in the values_for_bits parameter, a BadMatch protocol error results. If an undefined bit is set in either the bits_to_change or the values_for_bits parameter, a BadValue protocol error results.

All event selection bits are initially zero for clients using the Xkb extension. Once you set some bits, they remain set for your client until you clear them via another call to XkbSelectEvents .

XkbSelectEvents returns False if the Xkb extension has not been initilialized and True otherwise.

To select or deselect for a specific Xkb event and optionally place conditions on when events of that type are reported to your client, use XkbSelectEventDetails . This allows you to exercise a finer granularity of control over delivery of Xkb events with XkbSelectEvents .

While XkbSelectEvents allows multiple events to be selected, XkbSelectEventDetails changes the selection criteria for a single type of Xkb event. The interpretation of the bits_to_change and values_for_bits masks depends on the event type in question.

XkbSelectEventDetails changes the Xkb event selection mask for the keyboard specified by device_spec and the Xkb event specified by event_type . To turn on event selection for an event detail, set the bit for the detail in the bits_to_change parameter and set the corresponding bit in the values_for_bits parameter. To turn off event detail selection for a detail, set the bit for the detail in the bits_to_change parameter and do not set the corresponding bit in the values_for_bits parameter.

If an invalid event type is specified, a BadValue protocol error results. If a bit is not set in the bits_to_change parameter, but the corresponding bit is set in the values_for_bits parameter, a BadMatch protocol error results. If an undefined bit is set in either the bits_to_change or the values_for_bits parameter, a BadValue protocol error results.

For each type of Xkb event, the legal event details that you can specify in the XkbSelectEventDetails request are listed in the chapters that describe each event in detail.

The XkbEvent structure is a union of the individual structures declared for each Xkb event type and for the core protocol XEvent type. Given an XkbEvent structure, you may use the type field to determine if the event is an Xkb event ( type equals the Xkb base event code; see section 2.4). If the event is an Xkb event, you may then use the any.xkb_type field to determine the type of Xkb event and thereafter access the event-dependent components using the union member corresponding to the particular Xkb event type.

typedef union _XkbEvent {
      int                            type;
      XkbAnyEvent                    any;
      XkbStateNotifyEvent            state;
      XkbMapNotifyEvent              map;
      XkbControlsNotifyEvent         ctrls;
      XkbIndicatorNotifyEvent        indicators;
      XkbBellNotifyEvent             bell;
      XkbAccessXNotifyEvent          accessx;
      XkbNamesNotifyEvent            names;
      XkbCompatMapNotifyEvent        compat;
      XkbActionMessageEvent          message;
      XkbExtensionDeviceNotifyEvent  device;
      XkbNewKeyboardNotifyEvent      new_kbd;
      XEvent                         core;
} XkbEvent;

This unified Xkb event type includes a normal XEvent as used by the core protocol, so it is straightforward for applications that use Xkb events to call the X library event functions without having to cast every reference. For example, to get the next event, you can simply declare a variable of type XkbEvent and call:

XNextEvent(dpy,&xkbev.core);

The Xkb keyboard state is comprised of the state of all keyboard modifiers, the keyboard group, and the state of the pointer buttons. These are grouped into the following components:

The modifiers are Shift , Lock , Control , and Mod1 - Mod5 , as defined by the core protocol. A modifier can be thought of as a toggle that is either set or unset. All modifiers are initially unset. When a modifier is locked, it is set and remains set for all future key events, until it is explicitly unset. A latched modifier is set, but automatically unsets after the next key event that does not change the keyboard state. Locked and latched modifier state can be changed by keyboard activity or via Xkb extension library functions.

The Xkb extension provides support for keysym groups , as defined by ISO9995:

The Xkb extension supports up to four keysym groups. Groups are named beginning with one and indexed beginning with zero. All group states are indicated using the group index. At any point in time, there is zero or one locked group, zero or one latched group, and one base group. When a group is locked, it supersedes any previous locked group and remains the locked group for all future key events, until a new group is locked. A latched group applies only to the next key event that does not change the keyboard state. The locked and latched group can be changed by keyboard activity or via Xkb extension library functions.

Changing to a different group changes the keyboard state to produce characters from a different group. Groups are typically used to switch between keysyms of different languages and locales.

The pointer buttons are Button1 - Button5 , as defined by the core protocol.

The base group and base modifiers represent keys that are physically or logically down. These and the pointer buttons can be changed by keyboard activity and not by Xkb requests. It is possible for a key to be logically down, but not physically down, and neither latched nor locked. ^[3]

The effective modifiers are the bitwise union of the locked, latched, and the base modifiers.

The effective group is the arithmetic sum of the group indices of the latched group, locked group, and base group, which is then normalized by some function. The result is a meaningful group index.

The function f ensures that the effective group is within range. The precise function is specified for the keyboard and can be retrieved through the keyboard description. It may wrap around, clamp down, or default. Few applications will actually examine the effective group, and far fewer still will examine the locked, latched, and base groups.

There are two circumstances under which groups are normalized:

Each nonmodifier key on a keyboard has zero or more symbols, or keysyms, associated with it. These are the logical symbols that the key can generate when it is pressed. The set of all possible keysyms for a keyboard is divided into groups. Each key is associated with zero or more groups; each group contains one or more symbols. When a key is pressed, the determination of which symbol for the key is selected is based on the effective group and the shift level, which is determined by which modifiers are set.

A client that does not explicitly call Xkb functions, but that otherwise makes use of an X library containing the Xkb extension, will have keyboard state represented in bits 0 - 14 of the state field of events that report modifier and button state. Such a client is said to be Xkb-capable . A client that does explicitly call Xkb functions is an Xkb-aware client. The Xkb keyboard state includes information derived from the effective state and from two server parameters that can be set through the keyboard extension. The following components of keyboard state pertain to Xkb-capable and Xkb-aware clients:

The lookup modifiers and lookup group are represented in the state field of core X events. The modifier state and keycode of a key event are used to determine the symbols associated with the event. For KeyPress and KeyRelease events, the lookup modifiers are computed as:

Otherwise the lookup modifiers are computed as:

The lookup group is the same as the effective group.

When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it should use the lookup state — the lookup group and the lookup modifiers.

The grab state is the state used when matching events to passive grabs. If the event activates a grab, the grab modifiers and grab group are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as:

If the server’s IgnoreGroupLock control (see section 10.7.3) is not set, the grab group is the same as the effective group. Otherwise, the grab group is computed from the base group and latched group, ignoring the locked group.

The final three components of Xkb state are applicable to clients that are not linked with an Xlib containing the X keyboard extension library and therefore are not aware of the keyboard extension ( Xkb-unaware clients):

The X11 protocol interpretation of modifiers does not include direct support for multiple groups. When an Xkb-extended X server connects to an Xkb-unaware client, the compatibility states remap the keyboard group into a core modifier whenever possible. The compatibility state corresponds to the effective modifier and effective group state, with the group remapped to a modifier. The compatibility lookup and grab states correspond to the lookup and grab states, respectively, with the group remapped to a modifier. The compatibility lookup state is reported in events that do not trigger passive grabs; otherwise, the compatibility grab state is reported.

Xkb keyboard state may be represented in an XkbStateRec structure:

typedef struct {
      unsigned char            group;                /* effective group index */
      unsigned char            base_group;           /* base group index */
      unsigned char            latched_group;        /* latched group index */
      unsigned char            locked_group;         /* locked group index */
      unsigned char            mods;                 /* effective modifiers */
      unsigned char            base_mods;            /* base modifiers */
      unsigned char            latched_mods;         /* latched modifiers */
      unsigned char            locked_mods;          /* locked modifiers */
      unsigned char            compat_state;         /* effective group => modifiers */
      unsigned char            grab_mods;            /* modifiers used for grabs */
      unsigned char            compat_grab_mods;     /* mods used for compatibility mode grabs */
      unsigned char            lookup_mods;          /* modifiers used to lookup symbols */
      unsigned char            compat_lookup_mods;   /* mods used for compatibility lookup */
      unsigned short            ptr_buttons;         /* 1 bit => corresponding pointer btn is down */
} 
XkbStateRec
,*XkbStatePtr;

To obtain the keyboard state, use XkbGetState.

The XkbGetState function queries the server for the current keyboard state, waits for a reply, and then backfills state_return with the results.

All group values are expressed as group indices in the range [0..3]. Modifiers and the compatibility modifier state values are expressed as the bitwise union of the core X11 modifier masks. The pointer button state is reported as in the core X11 protocol.

The Xkb extension reports XkbStateNotify events to clients wanting notification whenever the Xkb state changes. The changes reported include changes to any aspect of the keyboard state: when a modifier is set or unset, when the current group changes, or when a pointer button is pressed or released. As with all Xkb events, XkbStateNotify events are reported to all interested clients without regard to the current keyboard input focus or grab state.

There are many different types of Xkb state changes. Xkb defines an event detail mask corresponding to each type of change. The event detail masks are listed in Table 5.3.

To track changes in the keyboard state for a particular device, select to receive XkbStateNotify events by calling either XkbSelectEvents or XkbSelectEventDetails (see section 4.3).

To receive XkbStateNotify events under all possible conditions, use XkbSelectEvents and pass XkbStateNotifyMask in both bits_to_change and values_for_bits .

To receive XkbStateNotify events only under certain conditions, use XkbSelectEventDetails using XkbStateNotify as the event_type and specifying the desired state changes in bits_to_change and values_for_bits using mask bits from Table 5.3.

The structure for XkbStateNotify events is:

typedef struct {
      int            type;            /* Xkb extension base event code */
      unsigned long  serial;          /* X server serial number for event */
      Bool           send_event;      /*  True => synthetically generated */
      Display *      display;         /* server connection where event generated */
      Time           time;            /* server time when event generated */
      int            xkb_type;        /*  XkbStateNotify */
      int            device;          /* Xkb device ID, will not be  XkbUseCoreKbd */
      unsigned int   changed;         /* bits indicating what has changed */
      int            group;           /* group index of effective group */
      int            base_group;      /* group index of base group */
      int            latched_group;   /* group index of latched group */
      int            locked_group;    /* group index of locked group */
      unsigned int   mods;            /* effective modifiers */
      unsigned int   base_mods;       /* base modifiers */
      unsigned int   latched_mods;    /* latched modifiers */
      unsigned int   locked_mods;     /* locked modifiers */
      int            compat_state;    /* computed compatibility state */
      unsigned char  grab_mods;       /* modifiers used for grabs */
      unsigned char  compat_grab_mods;  /* modifiers used for compatibility grabs */
      unsigned char  lookup_mods;     /* modifiers used to lookup symbols */
      unsigned char  compat_lookup_mods;                  /* mods used for compatibility look up */
      int            ptr_buttons;     /* core pointer buttons */
      KeyCode        keycode;         /* keycode causing event, 0 if programmatic */
      char           event_type;      /* core event if  req_major or
                                          req_minor non zero */
      char           req_major;       /* major request code if program trigger, else 0 */
      char           req_minor;       /* minor request code if program trigger, else 0 */
} XkbStateNotifyEvent
;

When you receive an XkbStateNotify event, the changed field indicates which elements of keyboard state have changed. This will be the bitwise inclusive OR of one or more of the XkbStateNotify event detail masks shown in Table 5.3. All fields reported in the event are valid, but only those indicated in changed have changed values.

The group field is the group index of the effective keysym group. The base_group , latched_group , and locked_group fields are set to a group index value representing the base group, the latched group, and the locked group, respectively. The X server can set the modifier and compatibility state fields to a union of the core modifier mask bits; this union represents the corresponding modifier states. The ptr_button field gives the state of the core pointer buttons as a mask composed of an inclusive OR of zero or more of the core pointer button masks.

Xkb state changes can occur either in response to keyboard activity or under application control. If a key event caused the state change, the keycode field gives the keycode of the key event, and the event_type field is set to either KeyPress or KeyRelease . If a pointer button event caused the state change, the keycode field is zero, and the event_type field is set to either ButtonPress or ButtonRelease . Otherwise, the major and minor codes of the request that caused the state change are given in the req_major and req_minor fields, and the keycode field is zero. The req_major value is the same as the major extension opcode.

The complete description of an Xkb keyboard is given by an XkbDescRec . The component structures in the XkbDescRec represent the major Xkb components outlined in Figure 1.1.

typedef struct {
      struct _XDisplay *                  display;            /* connection to
X server */
      unsigned short                  flags;            /* private to Xkb, do
not modify */
      unsigned short                  device_spec;            /* device of
interest */
      KeyCode                  min_key_code;            /* minimum keycode for
device */
      KeyCode                  max_key_code;            /* maximum keycode for
device */
      XkbControlsPtr                  ctrls;            /* controls */
      XkbServerMapPtr                  server;            /* server keymap */
      XkbClientMapPtr                  map;            /* client keymap */
      XkbIndicatorPtr                  indicators;            /* indicator map
*/
      XkbNamesPtr                  names;            /* names for all
components */
      XkbCompatMapPtr                  compat;            /* compatibility map
*/
      XkbGeometryPtr                  geom;            /* physical geometry of
keyboard */
} 
XkbDescRec
, *XkbDescPtr;

The display field points to an X display structure. The flags field is private to the library: modifying flags may yield unpredictable results. The device_spec field specifies the device identifier of the keyboard input device, or XkbUseCoreKeyboard , which specifies the core keyboard device. The min_key_code and max_key_code fields specify the least and greatest keycode that can be returned by the keyboard.

The other fields specify structure components of the keyboard description and are described in detail in other sections of this document. Table 6.1 identifies the subsequent sections of this document that discuss the individual components of the XkbDescRec .

Each structure component has a corresponding mask bit that is used in function calls to indicate that the structure should be manipulated in some manner, such as allocating it or freeing it. These masks and their relationships to the fields in the XkbDescRec are shown in Table 6.2.

To retrieve one or more components of a keyboard device description, use XkbGetKeyboard (see also XkbGetKeyboardbyName ).

XkbGetKeyboard allocates and returns a pointer to a keyboard description. It queries the server for those components specified in the which parameter for device device_spec and copies the results to the XkbDescRec it allocated. The remaining fields in the keyboard description are set to NULL . The valid masks for which are those listed in Table 6.2.

XkbGetKeyboard can generate BadAlloc protocol errors.

To free the returned keyboard description, use XkbFreeKeyboard (see section 6.4).

The server can generate events whenever its copy of the keyboard description for a device changes. Refer to section 14.4 for detailed information on tracking changes to the keyboard description.

Applications seldom need to directly allocate a keyboard description; calling XkbGetKeyboard usually suffices. In the event you need to create a keyboard description from scratch, however, use XkbAllocKeyboard rather than directly calling malloc or Xmalloc .

If XkbAllocKeyboard fails to allocate the keyboard description, it returns NULL . Otherwise, it returns a pointer to an empty keyboard description structure. The device_spec field will have been initialized to XkbUseCoreKbd . You may then either fill in the structure components or use Xkb functions to obtain values for the structure components from a keyboard device.

To destroy either an entire an XkbDescRec or just some of its members, use XkbFreeKeyboard.

XkbFreeKeyboard frees the components of xkb specified by which and sets the corresponding values to NULL . If free_all is True , XkbFreeKeyboard frees every non- NULL component of xkb and then frees the xkb structure itself.

Virtual modifiers are named by converting their string name to an X Atom and storing the Atom in the names.vmods array in an XkbDescRec structure (see section 6.1). The position of a name Atom in the names.vmods array defines the bit position used to represent the virtual modifier and also the index used when accessing virtual modifier information in arrays: the name in the i-th (0 relative) entry of names.vmods is the i-th virtual modifier, represented by the mask (1<<i). Throughout Xkb, various functions have a parameter that is a mask representing virtual modifier choices. In each case, the i-th bit (0 relative) of the mask represents the i-th virtual modifier.

To set the name of a virtual modifier, use XkbSetNames , using XkbVirtualModNamesMask in which and the name in the xkb argument; to retrieve indicator names, use XkbGetNames . These functions are discussed in Chapter 18.

An Xkb modifier definition enumerates a collection of real and virtual modifiers but does not in itself bind those modifiers to any particular key or to each other. Modifier definitions are included in a number of structures in the keyboard description to define the collection of modifiers that affect or are affected by some other entity. A modifier definition is relevant only in the context of some other entity such as an indicator map, a control, or a key type. (See sections 8.2.2, 10.8, and 15.2.)

typedef struct _XkbMods {
      unsigned char            mask;            /* real_mods | vmods mapped to
real modifiers */
      unsigned char            real_mods;            /* real modifier bits */
      unsigned short             vmods;            /* virtual modifier bits */
} 
XkbModsRec
,*XkbModsPtr;

An Xkb modifier definition consists of a set of bit masks corresponding to the eight real modifiers ( real_mods ); a similar set of bitmasks corresponding to the 16 named virtual modifiers ( vmods ); and an effective mask ( mask ). The effective mask represents the set of all real modifiers that can logically be set either by setting any of the real modifiers or by setting any of the virtual modifiers in the definition. mask is derived from the real and virtual modifiers and should never be explicitly changed — it contains all of the real modifiers specified in the definition ( real_mods ) plus any real modifiers that are bound to the virtual modifiers specified in the definition ( vmods ). The binding of the virtual modifiers to real modifiers is exterior to the modifier definition. Xkb automatically recomputes the mask field of modifier definitions as necessary. Whenever you access a modifier definition that has been retrieved using an Xkb library function, the mask field will be correct for the keyboard mapping of interest.

The binding of virtual modifiers to real modifiers is defined by the server.vmods array in an XkbDescRec structure. Each entry contains the real modifier bits that are bound to the virtual modifier corresponding to the entry. The overall relationship of fields dealing with virtual modifiers in the server keyboard description are shown in Figure 16.2.

Xkb maintains a virtual modifier mapping , which lists the virtual modifiers associated with, or bound to, each key. The real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual modifier mapping. The server.vmodmap array indicates which virtual modifiers are bound to each key; each entry is a bitmask for the virtual modifier bits. The server.vmodmap array is indexed by keycode.

The vmodmap and vmods members of the server map are the "master" virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that use virtual modifier mappings (see section 16.4).

For example, if Mod3 is bound to the Num_Lock key by the core protocol modifier mapping, and the NumLock virtual modifier is bound to they Num_Lock key by the virtual modifier mapping, Mod3 is added to the set of modifiers associated with NumLock .

The virtual modifier mapping is normally updated whenever actions are automatically applied to symbols (see section 16.4 for details), and few applications should need to change the virtual modifier mapping explicitly.

Use XkbGetMap (see section 14.2) to get the virtual modifiers from the server or use XkbGetVirtualMods (see section 16.4.1) to update a local copy of the virtual modifiers bindings from the server. To set the binding of a virtual modifier to a real modifier, use XkbSetMap (see section 14.3 ).

To determine the mapping of virtual modifiers to core X protocol modifiers, use XkbVirtualModsToReal .

If the keyboard description defined by xkb includes bindings for virtual modifiers, XkbVirtualModsToReal uses those bindings to determine the set of real modifiers that correspond to the set of virtual modifiers specified in virtual_mask . The virtual_mask parameter is a mask specifying the virtual modifiers to translate; the i-th bit (0 relative) of the mask represents the i-th virtual modifier. If mask_rtrn is non- NULL , XkbVirtualModsToReal backfills it with the resulting real modifier mask. If the keyboard description in xkb does not include virtual modifier bindings, XkbVirtualModsToReal returns False ; otherwise, it returns True .

The Xkb extension does not require any specific virtual modifier names. However, everyone benefits if the same names are used for common modifiers. The following names are suggested:

     
     NumLock
     ScrollLock
     Alt
     Meta
     AltGr
     LevelThree

If the second (0-relative) entry in names.vmods contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier bit for the NumLock virtual modifier. If server.vmods [2] contains Mod3Mask , then the NumLock virtual modifier is bound to the Mod3 real modifier.

A virtual modifier definition for this example would have:

     real_mods = 0
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x20 (Mod3Mask)

Continuing the example, if the keyboard has a Num_Lock keysym bound to the key with keycode 14, and the NumLock virtual modifier is bound to this key, server.vmodmap [14] contains 0x4.

Finally, if the keyboard also used the real Mod1 modifier for numeric lock operations, the modifier definition below would represent the situation where either the key bound to Mod1 or the NumLock virtual modifier could be used for this purpose:

     real_mods = 0x8 (Mod1Mask)
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x28 (Mod1Mask | Mod3Mask)

Xkb provides the capability of symbolically naming indicators. Xkb itself doesn’t use these symbolic names for anything; they are there only to help make the keyboard description comprehensible to humans. To set the names of specific indicators, use XkbSetNames as discussed in Chapter 18. Then set the map using XkbSetMap (see section 14.3) or XkbSetNamedIndicator (below). To retrieve indicator names, use XkbGetNames (Chapter 18).

Use the indicator description record, XkbIndicatorRec , and its indicator map, XkbIndicatorMapRec , to inquire about and control most indicator properties and behaviors.

#define      XkbNumIndicators      32

typedef struct {
      unsigned long                   phys_indicators;        /* LEDs existence */
      XkbIndicatorMapRec              maps[XkbNumIndicators]; /* indicator maps */
} XkbIndicatorRec,*XkbIndicatorPtr;

typedef struct {
      unsigned char    flags;         /* how the indicator can be changed */
      unsigned char    which_groups;  /* match criteria for groups */
      unsigned char    groups;        /* which keyboard groups the indicator watches */
      unsigned char    which_mods;    /* match criteria for modifiers */
      XkbModsRec       mods;          /* which modifiers the indicator watches */
      unsigned int     ctrls;         /* which controls the indicator watches */
} XkbIndicatorMapRec, *XkbIndicatorMapPtr;

#define XkbIM_UseNone             0
#define XkbIM_UseBase             (1L << 0)
#define XkbIM_UseLatched          (1L << 1)
#define XkbIM_UseLocked           (1L << 2)
#define XkbIM_UseEffective        (1L << 3)
#define XkbIM_UseAnyGroup         XkbIM_UseLatched | XkbIM_UseLocked |
                                  XkbIM_UseEffective

#define XkbGroup1Mask            (1<<0)
#define XkbGroup2Mask            (1<<1)
#define XkbGroup3Mask            (1<<2)
#define XkbGroup4Mask            (1<<3)
#define XkbAnyGroupMask          (1<<7)
#define XkbAllGroupsMask         (0xf)

#define XkbIM_UseNone             0
#define XkbIM_UseBase             (1L << 0)
#define XkbIM_UseLatched          (1L << 1)
#define XkbIM_UseLocked           (1L << 2)
#define XkbIM_UseEffective        (1L << 3)
#define XkbIM_UseCompat           (1L << 4)
#define XkbIM_UseAnyMods          XkbIM_UseBase | XkbIM_UseLatched |
                                  XkbIM_UseLocked | XkbIM_UseEffective |
                                  XkbIM_UseCompat

#define XkbRepeatKeysMask           (1L << 0)
#define XkbSlowKeysMask             (1L << 1)
#define XkbBounceKeysMask           (1L << 2)
#define XkbStickyKeysMask           (1L << 3)
#define XkbMouseKeysMask            (1L << 4)
#define XkbMouseKeysAccelMask       (1L << 5)
#define XkbAccessXKeysMask          (1L << 6)
#define XkbAccessXTimeoutMask       (1L << 7)
#define XkbAccessXFeedbackMask      (1L << 8)
#define XkbAudibleBellMask          (1L << 9)
#define XkbOverlay1Mask             (1L << 10)
#define XkbOverlay2Mask             (1L << 11)
#define XkbAllBooleanCtrlsMask      (0x00001FFF)

Xkb allows applications to obtain information about indicators using two different methods. The first method, which is similar to the core X implementation, uses a mask to specify the indicators. The second method, which is more suitable for applications concerned with interoperability, uses indicator names. The correspondence between the indicator name and the bit position in masks is as follows: one of the parameters returned from XkbGetNamedIndicators is an index that is the bit position to use in any function call that requires a mask of indicator bits, as well as the indicator’s index into the XkbIndicatorRec array of indicator maps.

Just as you can get the indicator map using a mask or using an indicator name, so you can change it using a mask or a name.

There are two ways to make changes to indicator maps and state: either change a local copy of the indicator maps and use XkbSetIndicatorMap or XkbSetNamedIndicator , or, to reduce network traffic, use an XkbIndicatorChangesRec structure and use XkbChangeIndicators.

typedef struct _XkbIndicatorChanges {
      unsigned int             state_changes;
      unsigned int             map_changes;
}
XkbIndicatorChangesRec,*XkbIndicatorChangesPtr;

Whenever an indicator changes state, the server sends XkbIndicatorStateNotify events to all interested clients. Similarly, whenever an indicator’s map changes, the server sends XkbIndicatorMapNotify events to all interested clients.

To receive XkbIndicatorStateNotify events, use XkbSelectEvents (see section 4.3) with both the bits_to_change and values_for_bits parameters containing XkbIndicatorStateNotifyMask . To receive XkbIndicatorMapNotify events, use XkbSelectEvents with XkbIndicatorMapNotifyMask .

To receive events for only specific indicators, use XkbSelectEventDetails . Set the event_type parameter to XkbIndicatorStateNotify or XkbIndicatorMapNotify , and set both the bits_to_change and values_for_bits detail parameters to a mask where each bit specifies one indicator, turning on those bits that specify the indicators for which you want to receive events.

Both types of indicator events use the same structure:

typedef struct _XkbIndicatorNotify {
      int            type;        /* Xkb extension base event code */
      unsigned long  serial;      /* X server serial number for event */
      Bool           send_event;  /*  True => synthetically generated */
      Display *      display;     /* server connection where event generated */
      Time           time;        /* server time when event generated */
      int            xkb_type;    /* specifies state or map notify */
      int            device;      /* Xkb device ID, will not be  XkbUseCoreKbd */
      unsigned int   changed;     /* mask of indicators with new state or map */
      unsigned int   state;       /* current state of all indicators */
} XkbIndicatorNotifyEvent;

xkb_type is either XkbIndicatorStateNotify or XkbIndicatorMapNotify , depending on whether the event is a kbIndicatorStateNotify event or kbIndicatorMapNotify event.

The changed parameter is a mask that is the bitwise inclusive OR of the indicators that have changed. If the event is of type XkbIndicatorMapNotify , changed reports the maps that changed. If the event is of type XkbIndicatorStateNotify , changed reports the indicators that have changed state. state is a mask that specifies the current state of all indicators, whether they have changed or not, for both XkbIndicatorStateNotify and IndicatorMapNotify events.

When your client application receives either a XkbIndicatorStateNotify event or XkbIndicatorMapNotify event, you can note the changes in a changes structure by calling XkbNoteIndicatorChanges.

The wanted parameter is the bitwise inclusive OR of XkbIndicatorMapMask and XkbIndicatorStateMask . XkbNoteIndicatorChanges copies any changes reported in new and specified in wanted into the changes record specified by old.

To update a local copy of the keyboard description with the actual values, pass the results of one or more calls to XkbNoteIndicatorChanges to XkbGetIndicatorChanges:

XkbGetIndicatorChanges examines the changes parameter, pulls over the necessary information from the server, and copies the results into the xkb keyboard description. If any bits are set in the state_changes field of changes , XkbGetIndicatorChanges also places the state of those indicators in state . If the indicators field of xkb is NULL , XkbGetIndicatorChanges allocates and initializes it. To free the indicators field, use XkbFreeIndicators (see section 8.6).

XkbGetIndicatorChanges can generate BadAlloc , BadImplementation, and BadMatch errors.

Most applications do not need to directly allocate the indicators member of the keyboard description record (the keyboard description record is described in Chapter 6). If the need arises, however, use XkbAllocIndicatorMaps.

The xkb parameter must point to a valid keyboard description. If it doesn’t, XkbAllocIndicatorMaps returns a BadMatch error. Otherwise, XkbAllocIndicatorMaps allocates and initializes the indicators member of the keyboard description record and returns Success . If XkbAllocIndicatorMaps was unable to allocate the indicators record, it reports a Bad Alloc error.

To free memory used by the indicators member of an XkbDescRec structure, use XkbFreeIndicatorMaps.

If the indicators member of the keyboard description record pointed to by xkb is not NULL , XkbFreeIndicatorMaps frees the memory associated with the indicators member of xkb.

You can associate a name to an act of ringing a bell by converting the name to an Atom and then using this name when you call the functions listed in this chapter. If an event is generated as a result, the name is then passed to all other clients interested in receiving XkbBellNotify events. Note that these are arbitrary names and that there is no binding to any sounds. Any sounds or other effects (such as visual bells on the screen) must be generated by a client application upon receipt of the bell event containing the name. There is no default name for the default keyboard bell. The server does generate some predefined bells for the AccessX controls (see section 10.6.3). These named bells are shown in Table 9.1; the name is included in any bell event sent to clients that have requested to receive XkbBellNotify events.

Using Xkb you can generate bell events that do not necessarily ring the system bell. This is useful if you need to use an audio server instead of the system beep. For example, when an audio client starts, it could disable the audible bell (the system bell) and then listen for XkbBellNotify events (see section 9.4). When it receives a XkbBellNotify event, the audio client could then send a request to an audio server to play a sound.

You can control the audible bells feature by passing the XkbAudibleBellMask to XkbChangeEnabledControls (see section 10.1.1). If you set XkbAudibleBellMask on, the server rings the system bell when a bell event occurs. This is the default. If you set XkbAudibleBellMask off and a bell event occurs, the server does not ring the system bell unless you call XkbForceDeviceBell or XkbForceBell (see section 9.3.3).

Audible bells are also part of the per-client auto-reset controls. For more information on auto-reset controls, see section 10.1.2.

Use the functions described in this section to ring bells and to generate bell events.

The input extension has two types of feedbacks that can generate bells — bell feedback and keyboard feedback. Some of the functions in this section have bell_class and bell_id parameters; set them as follows: Set bell_class to BellFeedbackClass or KbdFeedbackClass . A device can have more than one feedback of each type; set bell_id to the particular bell feedback of bell_class type.

Table 9.2 shows the conditions that cause a bell to sound or an XkbBellNotifyEvent to be generated when a bell function is called.

Xkb generates XkbBellNotify events for all bells except for those resulting from calls to XkbForceDeviceBell and XkbForceBell . To receive XkbBellNotify events under all possible conditions, pass XkbBellNotifyMask in both the bits_to_change and values_for_bits parameters to XkbSelectEvents (see section 4.3).

The XkbBellNotify event has no event details. It is either selected or it is not. However, you can call XkbSelectEventDetails using XkbBellNotify as the event_type and specifying XkbAllBellNotifyMask in bits_to_change and values_for_bits. This has the same effect as a call to XkbSelectEvents.

The structure for the XkbBellNotify event type contains:

typedef struct _XkbBellNotify {
      int             type;        /* Xkb extension base event code */
      unsigned long   serial;      /* X server serial number for event */
      Bool            send_event;  /*  True => synthetically generated */
      Display *       display;     /* server connection where event generated */
      Time            time;        /* server time when event generated */
      int             xkb_type;    /*  XkbBellNotify */
      unsigned int    device;      /* Xkb device ID, will not be  XkbUseCoreKbd */
      int             percent;     /* requested volume as % of max */
      int             pitch;       /* requested pitch in Hz */
      int             duration;    /* requested duration in microseconds */
      unsigned int    bell_class;  /* X input extension feedback class */
      unsigned int    bell_id;     /* X input extension feedback ID */
      Atom            name;        /* "name" of requested bell */
      Window          window;      /* window associated with event */
      Bool            event_only;  /*  False -> the server did not produce a beep */
} XkbBellNotifyEvent;

If your application needs to generate visual bell feedback on the screen when it receives a bell event, use the window ID in the XkbBellNotifyEvent , if present.

Enable and disable the boolean controls under program control by using the EnabledControls control; enable and disable them upon program exit by configuring the AutoReset control.

ok = XkbSetAutoResetControls(dpy, 0, 0, 0);

ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0);

ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0);

ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask,
XkbStickyKeysMask);

The X server’s generation of sounds is controlled by the AudibleBell control. Configuration of different bell sounds is discussed in Chapter 9.

The repeating behavior of keyboard keys is governed by three controls, the PerKeyRepeat control, which is always active, and the RepeatKeys and DetectableAutorepeat controls, which are boolean controls that may be enabled and disabled. PerKeyRepeat determines which keys are allowed to repeat. RepeatKeys governs the behavior of an individual key when it is repeating. DetectableAutorepeat allows a client to detect when a key is repeating as a result of being held down.

A keyboard overlay allows some subset of the keyboard to report alternate keycodes when the overlay is enabled. For example, a keyboard overlay can be used to simulate a numeric or editing keypad on a keyboard that does not actually have one by reusing some portion of the keyboard as an overlay. This technique is very common on portable computers and embedded systems with small keyboards.

Xkb includes direct support for two keyboard overlays, using the Overlay1 and Overlay2 controls. When Overlay1 is enabled, all of the keys that are members of the first keyboard overlay generate an alternate keycode. When Overlay2 is enabled, all of the keys that are members of the second keyboard overlay generate an alternate keycode. The two overlays are mutually exclusive; any particular key may be in at most one overlay. Overlay1 and Overlay2 are boolean controls. As such, you may enable and disable them using either the EnabledControls control or the AutoReset control discussed in section 10.1.1.

To specify the overlay to which a key belongs and the alternate keycode it should generate when that overlay is enabled, assign it either the XkbKB_Overlay1 or XkbKB_Overlay2 key behaviors, as described in section 16.2.

Using Xkb, it is possible to configure the keyboard to allow simulation of the X pointer device. This simulation includes both movement of the pointer itself and press and release events associated with the buttons on the pointer. Two controls affect this behavior: the MouseKeys control determines whether or not simulation of the pointer device is active, as well as configuring the default button; the MouseKeysAccel control determines the movement characteristics of the pointer when simulated via the keyboard. Both of them are boolean controls; as such, you may enable and disable them using either the EnabledControls control or the AutoReset control discussed in section 10.1.1. The individual keys that simulate different aspects of the pointer device are determined by the keyboard mapping, discussed in Chapter 16.

The MouseKeysAccel Control

When the MouseKeysAccel control is enabled, the effect of a key-activated pointer motion action changes as a key is held down. If the control is disabled, pressing a mouse-pointer key yields one mouse event. When MouseKeysAccel is enabled, mouse movement is defined by an initial distance specified in the XkbSA_MovePtr action and the following fields in the XkbControlsRec structure (see section 10.8).

Table 11.2. MouseKeysAccel Fields

Field	Function
mk_delay	Time (ms) between the initial key press and the first repeated motion event
mk_interval	Time (ms) between repeated motion events
mk_time_to_max	Number of events (count) before the pointer reaches maximum speed
mk_max_speed	The maximum speed (in pixels per event) the pointer reaches
mk_curve	The ramp used to reach maximum pointer speed

There are no convenience functions to query or change the attributes of the MouseKeysAccel control; instead use XkbGetControls and XkbSetControls (see sections 10.9 and 10.10).

The effects of the attributes of the MouseKeysAccel control depend on whether the XkbSA_MovePtr action (see section 16.1) specifies relative or absolute pointer motion.

Absolute Pointer Motion

If an XkbSA_MovePtr action specifies an absolute position for one of the coordinates but still allows acceleration, all repeated events contain any absolute coordinates specified in the action. For example, if the XkbSA_MovePtr action specifies an absolute position for the X direction, but a relative motion for the Y direction, the pointer accelerates in the Y direction, but stays at the same X position.

Relative Pointer Motion

If the XkbSA_MovePtr action specifies relative motion, the initial event always moves the cursor the distance specified in the action. After mk_delay milliseconds, a second motion event is generated, and another occurs every mk_interval milliseconds until the user releases the key.

Between the time of the second motion event and mk_time_to_max intervals, the change in pointer distance per interval increases with each interval. After mk_time_to_max intervals have elapsed, the change in pointer distance per interval remains the same and is calculated by multiplying the original distance specified in the action by mk_max_speed .

For example, if the XkbSA_MovePtr action specifies a relative motion in the X direction of 5, mk_delay =160, mk_interval =40, mk_time_to_max =30, and mk_max_speed =30, the following happens when the user presses the key:

• The pointer immediately moves 5 pixels in the X direction when the key is pressed.

• After 160 milliseconds ( mk_delay ), and every 40 milliseconds thereafter ( mk_interval ), the pointer moves in the X direction.

• The distance in the X direction increases with each interval until 30 intervals ( mk_time_to_max ) have elapsed.

• After 30 intervals, the pointer stops accelerating, and moves 150 pixels ( mk_max_speed * the original distance) every interval thereafter, until the key is released.

The increase in pointer difference for each interval is a function of mk_curve. Events after the first but before maximum acceleration has been achieved are accelerated according to the formula:

Where action_delta is the relative motion specified by the XkbSA_MovePtr action, mk_max_speed and mk_time_to_max are parameters to the MouseKeysAccel control, and the curveFactor is computed using the MouseKeysAccel mk_curve parameter as follows:

With the result that a mk_curve of zero causes the distance moved to increase linearly from action_delta to

. A negative mk_curve causes an initial sharp increase in acceleration that tapers off, and a positive curve yields a slower initial increase in acceleration followed by a sharp increase as the number of pointer events generated by the action approaches mk_time_to_max . The legal values for mk_curve are between -1000 and 1000.

A distance vs. time graph of the pointer motion is shown in Figure 10.1.

MouseKeys Acceleration

The Xkb extension includes several controls specifically aimed at making keyboard use more effective for physically impaired people. All of these controls are boolean controls and may be individually enabled and disabled, as well as configured to tune their specific behavior. The behavior of these controls is based on the AccessDOS package ^[4].

typedef struct {
      int             type;            /* Xkb extension base event code */
      unsigned long   serial;          /* X server serial number for event */
      Bool            send_event;      /*  True => synthetically generated */
      Display *       display;         /* server connection where event generated */
      Time            time;            /* server time when event generated */
      int             xkb_type;        /*  XkbAccessXNotify */
      int             device;          /* Xkb device ID, will not be  XkbUseCoreKbd */
      int             detail;          /* XkbAXN_* */
      KeyCode         keycode;         /* key of event */
      int             slowKeysDelay;   /* current SlowKeys delay */
      int             debounceDelay;   /* current debounce delay */
} XkbAccessXNotifyEvent;