From 9c0be82017f513e2eb63d59b095f1cf1955f2e2b Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Sat, 19 Jul 2014 23:53:48 -0700 Subject: specs/XKB: Trim leading spaces off text lines perl -i -p -e 's{/\*(\S)}{/* \1}g;' *.xml Signed-off-by: Alan Coopersmith --- specs/XKB/ch01.xml | 10 +- specs/XKB/ch02.xml | 158 +++--- specs/XKB/ch03.xml | 28 +- specs/XKB/ch04.xml | 126 ++--- specs/XKB/ch05.xml | 150 +++--- specs/XKB/ch06.xml | 58 +-- specs/XKB/ch07.xml | 114 ++--- specs/XKB/ch08.xml | 514 ++++++++++---------- specs/XKB/ch09.xml | 176 +++---- specs/XKB/ch10.xml | 1260 ++++++++++++++++++++++++------------------------ specs/XKB/ch11.xml | 112 ++--- specs/XKB/ch12.xml | 170 +++---- specs/XKB/ch13.xml | 406 ++++++++-------- specs/XKB/ch14.xml | 378 +++++++-------- specs/XKB/ch15.xml | 598 +++++++++++------------ specs/XKB/ch16.xml | 1174 ++++++++++++++++++++++---------------------- specs/XKB/ch17.xml | 384 +++++++-------- specs/XKB/ch18.xml | 206 ++++---- specs/XKB/ch19.xml | 108 ++--- specs/XKB/ch20.xml | 166 +++---- specs/XKB/ch21.xml | 520 ++++++++++---------- specs/XKB/ch22.xml | 46 +- specs/XKB/glossary.xml | 82 ++-- 23 files changed, 3472 insertions(+), 3472 deletions(-) (limited to 'specs') diff --git a/specs/XKB/ch01.xml b/specs/XKB/ch01.xml index 0cce431f..79aed476 100644 --- a/specs/XKB/ch01.xml +++ b/specs/XKB/ch01.xml @@ -128,7 +128,7 @@ keyboard. Internally, the server maintains a keyboard description keyboard description - that includes the keyboard state and configuration (mapping). By +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. @@ -249,7 +249,7 @@ key is logically released. Consequently, at most one key in a radio group can be logically depressed at one time. A radio group is defined by a radio group index, an optional name, and by assigning each key in the radio group XkbKB_RadioGroup - behavior and the radio group index. +behavior and the radio group index. @@ -322,7 +322,7 @@ 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. +protocol error. @@ -369,9 +369,9 @@ and server versions are incompatible, these functions return an error indication as shown in Table 1.1. Because of this test, BadAccess - and +and BadMatch - (due to incompatible versions) protocol errors should normally not be +(due to incompatible versions) protocol errors should normally not be generated. diff --git a/specs/XKB/ch02.xml b/specs/XKB/ch02.xml index a5790022..ca0616e6 100644 --- a/specs/XKB/ch02.xml +++ b/specs/XKB/ch02.xml @@ -26,7 +26,7 @@ functions. 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. +you should never need to reference it directly in your application code. @@ -37,7 +37,7 @@ constants for Xkb. It is included automatically from 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. +you should never need to reference it directly in your application code. @@ -66,11 +66,11 @@ The name of the Xkb extension is given in Most extensions to the X protocol are initialized by calling XInitExtension - and passing the extension name. However, as explained in section 2.4, Xkb +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. +directly. @@ -134,11 +134,11 @@ To determine the compatibility of a library at runtime, call Pass the symbolic value XkbMajorVersion - in +in lib_major_in_out - and +and XkbMinorVersion - in +in lib_minor_in_out. These arguments represent the version of the library used at compile time. The @@ -146,7 +146,7 @@ The function backfills the major and minor version numbers of the library used at run time in lib_major_in_out - and +and lib_minor_in_out. If the versions of the compile time and run time libraries are compatible, XkbLibraryVersion @@ -161,7 +161,7 @@ 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. +to do this, as described in the next section. @@ -170,21 +170,21 @@ the extension expected by the client. Use Call XkbQueryExtension - to check for the presence and compatibility of the extension in the server and +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. +for checking for the presence of, and initializing the Xkb extension. You must call XkbQueryExtension - or +or XkbOpenDisplay - before using any other Xkb library interfaces, unless such usage is explicitly +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, @@ -193,7 +193,7 @@ 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. +protocol errors. errors BadAccess @@ -202,7 +202,7 @@ cause XkbQueryExtension - both determines whether a compatible Xkb extension is present in the X server +both determines whether a compatible Xkb extension is present in the X server and initializes the extension when it is present. @@ -288,19 +288,19 @@ and initializes the extension when it is present. The XkbQueryExtension - function determines whether a compatible version of the X Keyboard Extension +function determines whether a compatible version of the X Keyboard Extension is present in the server. If a compatible extension is present, XkbQueryExtension - returns +returns True; - otherwise, it returns +otherwise, it returns False. If a compatible version of Xkb is present, XkbQueryExtension - initializes the extension. It backfills the major opcode for the keyboard +initializes the extension. It backfills the major opcode for the keyboard extension in opcode_rtrn, the base event code in @@ -309,18 +309,18 @@ the base error code in error_rtrn, and the major and minor version numbers of the extension in major_in_out - and +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 +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 +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. @@ -410,34 +410,34 @@ reason_rtrn) --> 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 +contains a status value indicating success or the type of failure. If major_in_out - and +and minor_in_out - are not +are not NULL, XkbOpenDisplay - first calls +first calls XkbLibraryVersion - to determine whether the client library is compatible, passing it the values +to determine whether the client library is compatible, passing it the values pointed to by major_in_out - and +and minor_in_out. If the library is incompatible, XkbOpenDisplay - backfills +backfills major_in_out - and +and minor_in_out - with the major and minor extension versions of the library being used and +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 +with the display_name. If this fails, the function returns NULL. @@ -445,10 +445,10 @@ If successful, XkbOpenDisplay calls XkbQueryExtension - and +and backfills the major and minor Xkb server extension version numbers in major_in_out - and +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, @@ -467,7 +467,7 @@ The possible values for XkbOD_BadLibraryVersion - indicates +indicates XkbLibraryVersion returned False. @@ -476,25 +476,25 @@ returned XkbOD_ConnectionRefused - indicates the display could not be opened. +indicates the display could not be opened. XkbOD_BadServerVersion - indicates the library and the server have incompatible extension versions. +indicates the library and the server have incompatible extension versions. XkbOD_NonXkbServer - indicates the extension is not present in the X server. +indicates the extension is not present in the X server. XkbOD_Success - indicates that the function succeeded. +indicates that the function succeeded. @@ -514,10 +514,10 @@ functionality. Call XkbIgnoreExtension - to prevent core X library keyboard functions from using the X Keyboard +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 +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. @@ -547,7 +547,7 @@ disable use of the extension once a connection is established. XkbIgnoreExtension - tells the X library whether to use the X Keyboard Extension on any +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 @@ -556,12 +556,12 @@ 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 +normally and uses Xkb extension requests, events, and state. Do not explicitly use Xkb on a connection for which it is disabled. XkbIgnoreExtension - returns +returns False - if it was unable to apply the ignore request. +if it was unable to apply the ignore request. @@ -574,9 +574,9 @@ use Xkb on a connection for which it is disabled. 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 +protocol error, where Xxx - is some name. These errors are fielded in the normal manner, by the default +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. @@ -679,17 +679,17 @@ 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 +when XkbQueryExtension - is called. When a +is called. When a BadKeyboard - error is reported in an +error is reported in an XErrorEvent, additional information is reported in the resourceid - field. The most significant byte of the +field. The most significant byte of the resource_id - is a further refinement of the error cause, as defined in +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. @@ -753,31 +753,31 @@ indicated ID 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 +is also passed as an argument, the Display* argument must match the dpy - field of the +field of the XkbDescRec - pointed to by the +pointed to by the XkbDescPtr - argument, or else the +argument, or else the dpy - field of the +field of the XkbDescRec - must be +must be NULL. If they don’t match or the dpy - field is not +field is not NULL, a BadMatch - error is returned (either in the return value or a backfilled +error is returned (either in the return value or a backfilled Status - variable). Upon successful return, the +variable). Upon successful return, the dpy - field of the +field of the XkbDescRec - always contains the Display* value passed in. +always contains the Display* value passed in. @@ -786,51 +786,51 @@ 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 +and a device identifier (unsigned int device_spec). - In some cases, the device identifier is implicit and is taken as the +In some cases, the device identifier is implicit and is taken as the device_spec - field of an +field of an XkbDescRec - structure passed as an argument. +structure passed as an argument. XkbUseCoreKbd The device identifier can specify any X input extension device with a KeyClass - component, or it can specify the constant, +component, or it can specify the constant, XkbUseCoreKbd. The use of XkbUseCoreKbd - allows applications to indicate the core keyboard without having to determine +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 +is also passed as an argument, if either the argument or the XkbDescRec device_spec - field is +field is XkbUseCoreKbd, and if the function returns successfully, the XkbDescPtr device_spec - field will have been converted from +field will have been converted from XkbUseCoreKbd - to a real Xkb device ID. If the function does not complete successfully, the +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 +field remains unchanged. Subsequently, the device id argument must match the device_spec - field of the +field of the XkbDescPtr - argument. If they don’t match, a +argument. If they don’t match, a BadMatch - error is returned (either in the return value or a backfilled +error is returned (either in the return value or a backfilled Status - variable). +variable). @@ -841,7 +841,7 @@ 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 +will work and the identifier returned by the server will refer to the core keyboard device. diff --git a/specs/XKB/ch03.xml b/specs/XKB/ch03.xml index 2981e9a2..3aeb81b4 100644 --- a/specs/XKB/ch03.xml +++ b/specs/XKB/ch03.xml @@ -78,7 +78,7 @@ 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. +function. @@ -105,7 +105,7 @@ Call the allocator function with some arbitrary size, as a hint. For those arrays that have an Xkb...Add... - function, call it each time you want to add new data to the array. The +function, call it each time you want to add new data to the array. The function expands the array if necessary. @@ -121,9 +121,9 @@ 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 +>= 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. @@ -132,12 +132,12 @@ 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 +and num_ - fields of the array, resizes the array if necessary, adds the entry to the +fields of the array, resizes the array if necessary, adds the entry to the array, and then updates the num_ - field. +field. @@ -161,7 +161,7 @@ description, Xkb provides separate special changes changes data structures - data structures for each major Xkb data structure. These data structures do +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. @@ -213,14 +213,14 @@ 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 +is the name of a major Xkb component such as Map - or +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, +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. @@ -233,16 +233,16 @@ 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 +to allocate Xkb data structures, you should not free Xkb data structures or components directly using free - or +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 +or Xfree. diff --git a/specs/XKB/ch04.xml b/specs/XKB/ch04.xml index 745c5705..dee00b32 100644 --- a/specs/XKB/ch04.xml +++ b/specs/XKB/ch04.xml @@ -31,14 +31,14 @@ The X server reports the events defined by the Xkb extension to your client application only if you have requested them. You may request Xkb events by calling either XkbSelectEvents - or +or XkbSelectEventDetails. XkbSelectEvents - requests Xkb events by their event type and causes them to be reported to your +requests Xkb events by their event type and causes them to be reported to your client application under all circumstances. You can specify a finer granularity for event reporting by using XkbSelectEventDetails; - in this case events are reported only when the specific detail conditions you +in this case events are reported only when the specific detail conditions you specify have been met. @@ -49,17 +49,17 @@ specify have been met. 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 +field, containing the base event code. - This base event code is a value the X server assigns to each X extension at +This base event code is a value the X server assigns to each X extension at runtime and that identifies 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 +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 +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 @@ -171,7 +171,7 @@ 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: +structure: typedef struct { @@ -188,22 +188,22 @@ typedef struct { For any Xkb event, the type - field is set to the base event code for the Xkb extension, assigned by the +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 +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 +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 +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 +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 @@ -211,10 +211,10 @@ even if the request that generated the event specified a device of If the request that generated the event specified XkbUseCoreKbd, device - contains a value assigned by the server to specify the core keyboard. If the +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. +contains that same identifier. @@ -258,15 +258,15 @@ 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 +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 +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 +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. @@ -344,21 +344,21 @@ This request changes the Xkb event selection mask for the keyboard specified by Each Xkb event that can be selected is represented by a bit in the bits_to_change - and +and values_for_bits - masks. Only the event selection bits specified by the +masks. Only the event selection bits specified by the bits_to_change - parameter are affected; any unspecified bits are left unchanged. To turn on +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 +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 +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 +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 +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 @@ -369,17 +369,17 @@ clients’ event selection masks. If a bit is not set in the bits_to_change - parameter, but the corresponding bit is set in the +parameter, but the corresponding bit is set in the values_for_bits - parameter, a +parameter, a BadMatch - protocol error results. If an undefined bit is set in either the +protocol error results. If an undefined bit is set in either the bits_to_change - or the +or the values_for_bits - parameter, a +parameter, a BadValue - protocol error results. +protocol error results. @@ -393,11 +393,11 @@ clear them via another call to XkbSelectEvents - returns +returns False - if the Xkb extension has not been initialized and +if the Xkb extension has not been initialized and True - otherwise. +otherwise. @@ -483,60 +483,60 @@ Xkb events with While XkbSelectEvents - allows multiple events to be selected, +allows multiple events to be selected, XkbSelectEventDetails - changes the selection criteria for a single type of Xkb event. The +changes the selection criteria for a single type of Xkb event. The interpretation of the bits_to_change - and +and values_for_bits - masks depends on the event type in question. +masks depends on the event type in question. XkbSelectEventDetails - changes the Xkb event selection mask for the keyboard specified by +changes the Xkb event selection mask for the keyboard specified by device_spec - and the Xkb event specified by +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 +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 +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 +parameter and do not set the corresponding bit in the values_for_bits - parameter. +parameter. If an invalid event type is specified, a BadValue - protocol error results. If a bit is not set in the +protocol error results. If a bit is not set in the bits_to_change - parameter, but the corresponding bit is set in the +parameter, but the corresponding bit is set in the values_for_bits - parameter, a +parameter, a BadMatch - protocol error results. If an undefined bit is set in either the +protocol error results. If an undefined bit is set in either the bits_to_change - or the +or the values_for_bits - parameter, a +parameter, a BadValue - protocol error results. +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. +request are listed in the chapters that describe each event in detail. @@ -547,7 +547,7 @@ For each type of Xkb event, the legal event details that you can specify in the The X server reports the events defined by Xkb to your client application only if you have requested them via a call to XkbSelectEvents - or +or XkbSelectEventDetails. Specify the event types in which you are interested in a mask, as described in section 4.3. @@ -556,9 +556,9 @@ in section 4.3. Table 4.2 - lists the event mask constants that can be specified with the +lists the event mask constants that can be specified with the XkbSelectEvents - request and the circumstances in which the mask should be specified. +request and the circumstances in which the mask should be specified. @@ -683,19 +683,19 @@ in section 4.3. The XkbEvent - structure is a union of the individual structures declared for each Xkb event +structure is a union of the individual structures declared for each Xkb event type and for the core protocol XEvent - type. Given an +type. Given an XkbEvent - structure, you may use the +structure, you may use the type - field to determine if the event is an Xkb event +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 +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 +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. @@ -722,12 +722,12 @@ typedef union _XkbEvent { This unified Xkb event type includes a normal XEvent - as used by the core protocol, so it is straightforward for applications that +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: +and call: XNextEvent(dpy,&xkbev.core); diff --git a/specs/XKB/ch05.xml b/specs/XKB/ch05.xml index c3190fcc..77d1995e 100644 --- a/specs/XKB/ch05.xml +++ b/specs/XKB/ch05.xml @@ -57,7 +57,7 @@ The modifiers modifiers - are +are Shift, Lock, Control, @@ -110,7 +110,7 @@ Changing to a different group changes the keyboard state to produce characters f The pointer buttons - are +are Button1 – Button5, @@ -125,13 +125,13 @@ The base group groupbase - and +and base modifiers base modifiers modifiersbase - represent keys that are physically or logically down. These +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. @@ -151,7 +151,7 @@ The effective modifiers modifierseffective - are the bitwise union of the locked, latched, and the base modifiers. +are the bitwise union of the locked, latched, and the base modifiers. @@ -162,7 +162,7 @@ The effective group groupeffective - 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. +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. @@ -192,17 +192,17 @@ There are two circumstances under which groups are normalized: The global locked or effective group changes. In this case, the changed group is normalized into range according to the settings of the groups_wrap - field of the +field of the XkbControlsRec - structure for the keyboard (see section 10.7.1). +structure for the keyboard (see section 10.7.1). The Xkb library is interpreting an event with an effective group that is legal for the keyboard as a whole, but not for the key in question. In this case, the group to use for this event only is determined using the group_info - field of the key symbol mapping +field of the key symbol mapping (XkbSymMapRec) - for the event key. +for the event key. @@ -221,7 +221,7 @@ A client that does explicitly call Xkb functions is an Xkb-aware Xkb-aware client - 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: +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: @@ -244,17 +244,17 @@ The lookup modifiers modifierslookup - and +and lookup group lookup group grouplookup - 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 +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 +and KeyRelease - events, the lookup modifiers are computed as: +events, the lookup modifiers are computed as: ((base | latched | locked) & ~server_internal_modifiers) @@ -277,7 +277,7 @@ When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it lookup state statelookup - — the lookup group and the lookup modifiers. +— the lookup group and the lookup modifiers. @@ -288,19 +288,19 @@ The grab state stategrab - is the state used when matching events to passive grabs. If the event activates a grab, the +is the state used when matching events to passive grabs. If the event activates a grab, the grab modifiers grab modifiers modifiersgrab - and +and grab group grab group groupgrab - are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as: +are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as: (((base | latched | (locked & ~ignore_locks)) & ~server_internal_modifiers) @@ -308,7 +308,7 @@ The 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. +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. @@ -462,20 +462,20 @@ To lock and unlock any of the eight real keyboard modifiers, use XkbLockModifiers - sends a request to the server to lock the real modifiers selected by both +sends a request to the server to lock the real modifiers selected by both affect - and +and values - and to unlock the real modifiers selected by +and to unlock the real modifiers selected by affect - but not selected by +but not selected by values. XkbLockModifiers - does not wait for a reply from the server. It returns +does not wait for a reply from the server. It returns True - if the request was sent, and +if the request was sent, and False - otherwise. +otherwise. @@ -544,20 +544,20 @@ To latch and unlatch any of the eight real keyboard modifiers, use XkbLatchModifiers - sends a request to the server to latch the real modifiers selected by both +sends a request to the server to latch the real modifiers selected by both affect - and +and values - and to unlatch the real modifiers selected by +and to unlatch the real modifiers selected by affect - but not selected by +but not selected by values. XkbLatchModifiers - does not wait for a reply from the server. It returns +does not wait for a reply from the server. It returns True - if the request was sent, and +if the request was sent, and False - otherwise. +otherwise. @@ -658,13 +658,13 @@ To lock the keysym group, use XkbLockGroup - sends a request to the server to lock the specified +sends a request to the server to lock the specified group and does not wait for a reply. It returns True - if the request was sent and +if the request was sent and False - otherwise. +otherwise. @@ -722,11 +722,11 @@ To latch the keysym group, use XkbLatchGroup - sends a request to the server to latch the specified group and does not wait for a reply. It returns +sends a request to the server to latch the specified group and does not wait for a reply. It returns True - if the request was sent and +if the request was sent and False - otherwise. +otherwise. @@ -741,7 +741,7 @@ To latch the keysym group, use Xkb keyboard state may be represented in an XkbStateRec - structure: +structure: typedef struct { @@ -823,7 +823,7 @@ The XkbGetState function queries the server for the current keyboard state, waits for a reply, and then backfills state_return - with the results. +with the results. @@ -846,7 +846,7 @@ 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. +events are reported to all interested clients without regard to the current keyboard input focus or grab state. @@ -936,24 +936,24 @@ listed in Table 5.3. To track changes in the keyboard state for a particular device, select to receive XkbStateNotify - events by calling either +events by calling either XkbSelectEvents - or +or XkbSelectEventDetails - (see section 4.3). +(see section 4.3). To receive XkbStateNotify - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - and pass +and pass XkbStateNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -961,24 +961,24 @@ To receive To receive XkbStateNotify - events only under certain conditions, use +events only under certain conditions, use XkbSelectEventDetails - using +using XkbStateNotify - as the +as the event_type - and specifying the desired state changes in +and specifying the desired state changes in bits_to_change - and +and values_for_bits - using mask bits from Table 5.3. +using mask bits from Table 5.3. The structure for XkbStateNotify - events is: +events is: typedef struct { @@ -1019,32 +1019,32 @@ typedef struct { When you receive an XkbStateNotify - event, the +event, the changed - field indicates which elements of keyboard state have 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 +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. +have changed values. The group - field is the group index of the effective keysym group. The +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, +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_buttons - field gives the state of the core pointer buttons as a +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. @@ -1055,26 +1055,26 @@ 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 +field gives the keycode of the key event, and the event_type - field is set to either KeyPress - or +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. +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 +and req_minor - fields, and the +fields, and the keycode - field is zero. The +field is zero. The req_major - value is the same as the major extension opcode. +value is the same as the major extension opcode. diff --git a/specs/XKB/ch06.xml b/specs/XKB/ch06.xml index 48afc4c6..b3b58da2 100644 --- a/specs/XKB/ch06.xml +++ b/specs/XKB/ch06.xml @@ -22,7 +22,7 @@ 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. +represent the major Xkb components outlined in Figure 1.1. @@ -45,19 +45,19 @@ typedef struct { The display - field points to an X display structure. The +field points to an X display structure. The flags - field is private to the library: modifying +field is private to the library: modifying flags - may yield unpredictable results. The +may yield unpredictable results. The device_spec - field specifies the device identifier of the keyboard input device, or +field specifies the device identifier of the keyboard input device, or XkbUseCoreKbd, which specifies the core keyboard device. The min_key_code - and +and max_key_code - fields specify the least and greatest keycode that can be returned by the +fields specify the least and greatest keycode that can be returned by the keyboard. @@ -122,7 +122,7 @@ 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. +are shown in Table 6.2.
@@ -191,7 +191,7 @@ fields in the To retrieve one or more components of a keyboard device description, use XkbGetKeyboard - (see also +(see also XkbGetKeyboardByName). @@ -248,30 +248,30 @@ To retrieve one or more components of a keyboard device description, use allocates and returns a pointer to a keyboard description. It queries the server for those components specified in the which - parameter for device +parameter for device device_spec - and copies the results to the +and copies the results to the XkbDescRec - it allocated. The remaining fields in the keyboard description are set to +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. +are those listed in Table 6.2. XkbGetKeyboard - can generate +can generate BadAlloc - protocol errors. +protocol errors. To free the returned keyboard description, use XkbFreeKeyboard - (see section 6.4). +(see section 6.4). @@ -293,10 +293,10 @@ 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 +usually suffices. In the event you need to create a keyboard description from scratch, however, use XkbAllocKeyboard - rather than directly calling +rather than directly calling malloc or Xmalloc. @@ -314,12 +314,12 @@ or If XkbAllocKeyboard - fails to allocate the keyboard description, it returns +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 +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. @@ -329,7 +329,7 @@ obtain values for the structure components from a keyboard device. To destroy either an entire an XkbDescRec - or just some of its members, use +or just some of its members, use XkbFreeKeyboard. @@ -382,24 +382,24 @@ To destroy either an entire an XkbFreeKeyboard - frees the components of +frees the components of xkb - specified by +specified by which - and sets the corresponding values to +and sets the corresponding values to NULL. If free_all - is +is True, XkbFreeKeyboard - frees every non- +frees every non- NULL - component of +component of xkb - and then frees the +and then frees the xkb - structure itself. +structure itself. diff --git a/specs/XKB/ch07.xml b/specs/XKB/ch07.xml index b69ce854..cbb549ce 100644 --- a/specs/XKB/ch07.xml +++ b/specs/XKB/ch07.xml @@ -9,16 +9,16 @@ The core protocol specifies that certain keysyms, when bound to modifiers, affect the rules of keycode to keysym interpretation for all keys; for example, when the Num_Lock - keysym is bound to some modifier, that modifier is used to select between +keysym is bound to some modifier, that modifier is used to select between shifted and unshifted state for the numeric keypad keys. The core protocol does not provide a convenient way to determine the mapping of modifier bits (in particular Mod1 - through +through Mod5) - to keysyms such as +to keysyms such as Num_Lock - and +and Mode_switch. Using the core protocol only, a client application must retrieve and search the modifier map to determine the keycodes bound to each modifier, and then @@ -47,7 +47,7 @@ Each virtual modifier can be bound to any set of the real modifiers Shift, Lock, Control, - and +and Mod1 – Mod5). @@ -60,11 +60,11 @@ The separation of function from physical modifier bindings makes it easier to specify more clearly the intent of a binding. X servers do not all assign modifiers the same way — for example, Num_Lock - might be bound to +might be bound to Mod2 - for one vendor and to +for one vendor and to Mod4 - for another. This makes it cumbersome to automatically remap the keyboard to a +for another. This makes it cumbersome to automatically remap the keyboard to a desired configuration without some kind of prior knowledge about the keyboard layout and bindings. With XKB, applications can use virtual modifiers to specify the desired behavior, without regard for the actual physical bindings @@ -77,17 +77,17 @@ in effect. Virtual modifiers are named by converting their string name to an X Atom - and storing the Atom in the +and storing the Atom in the names.vmods - array in an +array in an XkbDescRec - structure (see section 6.1). The position of a name Atom in the +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 +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 +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. @@ -99,11 +99,11 @@ To set the name of a virtual modifier, use XkbSetNames, using XkbVirtualModNamesMask - in +in which - and the name in the +and the name in the xkb - argument; to retrieve indicator names, use +argument; to retrieve indicator names, use XkbGetNames. These functions are discussed in . @@ -121,7 +121,7 @@ An Xkb modifier definition modifier definition - enumerates a collection of real and virtual modifiers but does not in itself +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 @@ -144,22 +144,22 @@ typedef struct _XkbMods { 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 +a similar set of bitmasks corresponding to the 16 named virtual modifiers (vmods); - and an effective mask +and an effective mask (mask). - The effective mask represents the set of all real modifiers that can +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 +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 +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 +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 @@ -174,9 +174,9 @@ for the keyboard mapping of interest. The binding of virtual modifiers to real modifiers is defined by the server.vmods - array in an +array in an XkbDescRec - structure. Each entry contains the real modifier bits that are bound to the +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. @@ -199,19 +199,19 @@ 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 +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. +array is indexed by keycode. The vmodmap - and +and vmods - members of the server map are the master virtual modifier definitions. Xkb +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). @@ -220,15 +220,15 @@ use virtual modifier mappings (see sect For example, if Mod3 - is bound to the +is bound to the Num_Lock - key by the core protocol modifier mapping, and the +key by the core protocol modifier mapping, and the NumLock - virtual modifier is bound to they +virtual modifier is bound to they Num_Lock - key by the virtual modifier mapping, +key by the virtual modifier mapping, Mod3 - is added to the set of modifiers associated with +is added to the set of modifiers associated with NumLock. @@ -245,11 +245,11 @@ 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 +(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 +(see section 14.3). @@ -308,33 +308,33 @@ To determine the mapping of virtual modifiers to core X protocol modifiers, use If the keyboard description defined by xkb - includes bindings for virtual modifiers, +includes bindings for virtual modifiers, XkbVirtualModsToReal - uses those bindings to determine the set of real modifiers that correspond to +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 +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- +is non- NULL, XkbVirtualModsToReal - backfills it with the resulting real modifier mask. If the keyboard +backfills it with the resulting real modifier mask. If the keyboard description in xkb - does not include virtual modifier bindings, +does not include virtual modifier bindings, XkbVirtualModsToReal - returns +returns False; - otherwise, it returns +otherwise, it returns True. It is possible for a local (client-side) keyboard description (the xkb - parameter) to not contain any virtual modifier information (simply because the +parameter) to not contain any virtual modifier information (simply because the client has not requested it) while the server’s corresponding definition may contain virtual modifier information. @@ -362,12 +362,12 @@ are unbound. Consider this example: If the NumLock - virtual modifier is not bound to any real modifiers, the effective masks for +virtual modifier is not bound to any real modifiers, the effective masks for these two cases are identical (that is, contain only Shift). - When it is essential to distinguish between +When it is essential to distinguish between OneThing - and Another, Xkb considers only those modifier definitions for which all +and Another, Xkb considers only those modifier definitions for which all virtual modifiers are bound. @@ -402,18 +402,18 @@ following names are suggested: If the second (0-relative) entry in names.vmods - contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier +contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier bit for the NumLock - virtual modifier. If +virtual modifier. If server.vmods [2] contains Mod3Mask, then the NumLock - virtual modifier is bound to the +virtual modifier is bound to the Mod3 - real modifier. +real modifier. @@ -430,9 +430,9 @@ A virtual modifier definition for this example would have: Continuing the example, if the keyboard has a Num_Lock - keysym bound to the key with keycode 14, and the +keysym bound to the key with keycode 14, and the NumLock - virtual modifier is bound to this key, +virtual modifier is bound to this key, server.vmodmap[14] contains 0x4. @@ -441,12 +441,12 @@ contains 0x4. Finally, if the keyboard also used the real Mod1 - modifier for numeric lock operations, the modifier definition below would +modifier for numeric lock operations, the modifier definition below would represent the situation where either the key bound to Mod1 - or the +or the NumLock - virtual modifier could be used for this purpose: +virtual modifier could be used for this purpose: diff --git a/specs/XKB/ch08.xml b/specs/XKB/ch08.xml index a65d366a..3bb6be62 100644 --- a/specs/XKB/ch08.xml +++ b/specs/XKB/ch08.xml @@ -12,10 +12,10 @@ Although the core X implementation supports up to 32 LEDs on an input device, it does not provide any linkage between the state of the LEDs and the logical state of the input device. For example, most keyboards have a CapsLock - LED, but X does not provide a mechanism to make the LED automatically follow +LED, but X does not provide a mechanism to make the LED automatically follow the logical state of the CapsLock - key. +key. @@ -23,16 +23,16 @@ the logical state of the Furthermore, the core X implementation does not provide clients with the ability to determine what bits in the led_mask - field of the +field of the XKeyboardState - map to the particular LEDs on the keyboard. For example, X does not provide a +map to the particular LEDs on the keyboard. For example, X does not provide a method for a client to determine what bit to set in the led_mask - field to turn on the +field to turn on the Scroll Lock LED or whether the keyboard even has a Scroll Lock - LED. +LED. @@ -58,14 +58,14 @@ 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 . Then set the map using +as discussed in . Then set the map using XkbSetMap - (see section 14.3) - or +(see section 14.3) +or XkbSetNamedIndicator - (below). To retrieve indicator names, use +(below). To retrieve indicator names, use XkbGetNames - (). +(). @@ -91,7 +91,7 @@ to inquire about and control most indicator properties and behaviors. The description for all the Xkb indicators is held in the indicators - field of the complete keyboard description (see ), which is defined +field of the complete keyboard description (see ), which is defined as follows: @@ -106,7 +106,7 @@ typedef struct { This structure contains the phys_indicators - field, which relates some information about the correspondence between +field, which relates some information about the correspondence between indicators and physical LEDs on the keyboard, and an array of indicator maps, one map per indicator. @@ -115,7 +115,7 @@ one map per indicator. The phys_indicators - field indicates which indicators are bound to physical LEDs on the keyboard; +field indicates which indicators are bound to physical LEDs on the keyboard; if a bit is set in phys_indicators, then the associated indicator has a physical LED associated with it. This @@ -126,13 +126,13 @@ the state of but most keyboards do not have an LED that indicates the current group. Because phys_indicators - describes a physical characteristic of the keyboard, you cannot directly +describes a physical characteristic of the keyboard, you cannot directly change it under program control. However, if a client program loads a completely new keyboard description via XkbGetKeyboardByName, or if a new keyboard is attached and the X implementation notices, phys_indicators - changes if the indicators for the new keyboard are different. +changes if the indicators for the new keyboard are different. @@ -148,9 +148,9 @@ Each indicator has its own set of attributes that specify whether clients can explicitly set its state and whether it tracks the keyboard state. The attributes of each indicator are held in the maps - array, which is an array of +array, which is an array of XkbIndicatorRec - structures: +structures: typedef struct { @@ -189,7 +189,7 @@ indicator The effect (if any) of attempts to explicitly change the state of the indicator using the functions XkbSetControls - or +or XChangeKeyboardControl @@ -207,10 +207,10 @@ relationship to the indicator map, see Table 8.1. +and their effects are shown in Table 8.1.
@@ -253,62 +253,62 @@ state of the keyboard to change. Note that if XkbIM_NoAutomatic - is not set, by default the indicator follows the keyboard state. +is not set, by default the indicator follows the keyboard state. If XkbIM_LEDDrivesKB - is set and +is set and XkbIM_NoExplicit - is not, and if you call a function which updates the server’s image of the +is not, and if you call a function which updates the server’s image of the indicator map (such as XkbSetIndicatorMap - or +or XkbSetNamedIndicator), - Xkb changes the keyboard state and controls to reflect the other fields of +Xkb changes the keyboard state and controls to reflect the other fields of the indicator map, as described in the remainder of this section. If you attempt to explicitly change the value of an indicator for which XkbIM_LEDDrivesKB - is absent or for which +is absent or for which XkbIM_NoExplicit - is present, keyboard state or controls are unaffected. +is present, keyboard state or controls are unaffected. For example, a keyboard designer may want to make the CapsLock - LED controllable only by the server, but allow the +LED controllable only by the server, but allow the Scroll Lock - LED to be controlled by client applications. To do so, the keyboard designer +LED to be controlled by client applications. To do so, the keyboard designer could set the XkbIM_NoExplicit - flag for the +flag for the CapsLock LED, but not set it for the Scroll Lock - LED. Or the keyboard designer may wish to allow the +LED. Or the keyboard designer may wish to allow the CapsLock - LED to be controlled by both the server and client applications and also have +LED to be controlled by both the server and client applications and also have the server to automatically change the CapsLock modifier state whenever a client application changes the CapsLock - LED. To do so, the keyboard designer would not set the +LED. To do so, the keyboard designer would not set the XkbIM_NoExplicit - flag, but would instead set the +flag, but would instead set the XkbIM_LEDDrivesKB - flag. +flag. The remaining fields in the indicator map specify the conditions under which Xkb automatically turns an indicator on or off (only if XkbIM_NoAutomatic - is not set). If these conditions match the keyboard state, Xkb turns the +is not set). If these conditions match the keyboard state, Xkb turns the indicator on. If the conditions do not match, Xkb turns the indicator off. @@ -320,14 +320,14 @@ indicator on. If the conditions do not match, Xkb turns the indicator off. The which_groups - and the +and the groups - fields of an indicator map determine how the keyboard group state affects the +fields of an indicator map determine how the keyboard group state affects the corresponding indicator. The which_groups - field controls the interpretation of +field controls the interpretation of groups - and may contain any one of the following values: +and may contain any one of the following values: #define XkbIM_UseNone 0 @@ -357,11 +357,11 @@ inclusive OR of the following valid values: If XkbIM_NoAutomatic - is not set (the keyboard drives the indicator), the effect of +is not set (the keyboard drives the indicator), the effect of which_groups - and +and groups - is shown in Table 8.2. +is shown in Table 8.2.
@@ -383,7 +383,7 @@ Indicator The groups - field and the current keyboard group state are ignored. +field and the current keyboard group state are ignored. @@ -391,10 +391,10 @@ The If groups - is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +is nonzero, the indicator is lit whenever the base keyboard group is nonzero. If groups - is zero, the indicator is lit whenever the base keyboard group is zero. +is zero, the indicator is lit whenever the base keyboard group is zero. @@ -402,10 +402,10 @@ If If groups - is nonzero, the indicator is lit whenever the latched keyboard group is +is nonzero, the indicator is lit whenever the latched keyboard group is nonzero. If groups - is zero, the indicator is lit whenever the latched keyboard group is zero. +is zero, the indicator is lit whenever the latched keyboard group is zero. @@ -413,7 +413,7 @@ nonzero. If The groups - field is interpreted as a mask. The indicator is lit when the current locked +field is interpreted as a mask. The indicator is lit when the current locked keyboard group matches one of the bits that are set in groups. @@ -423,7 +423,7 @@ keyboard group matches one of the bits that are set in The groups - field is interpreted as a mask. The indicator is lit when the current +field is interpreted as a mask. The indicator is lit when the current effective keyboard group matches one of the bits that are set in groups. @@ -435,11 +435,11 @@ effective keyboard group matches one of the bits that are set in The effect of which_groups - and +and groups - when you change an indicator for which +when you change an indicator for which XkbIM_LEDDrivesKB - is set (the indicator drives the keyboard) is shown in +is set (the indicator drives the keyboard) is shown in Table 8.3. The New State column refers to the new state to which you set the indicator. @@ -476,12 +476,12 @@ Keyboard The groups - field is treated as a group mask. The keyboard group latch is changed to the +field is treated as a group mask. The keyboard group latch is changed to the lowest numbered group specified in groups; - if +if groups - is empty, the keyboard group latch is changed to zero. +is empty, the keyboard group latch is changed to zero. @@ -490,12 +490,12 @@ lowest numbered group specified in The groups - field is treated as a group mask. If the indicator is explicitly extinguished, +field is treated as a group mask. If the indicator is explicitly extinguished, keyboard group latch is changed to the lowest numbered group not specified in groups; - if +if groups - is zero, the keyboard group latch is set to the index of the highest legal +is zero, the keyboard group latch is set to the index of the highest legal keyboard group. @@ -505,7 +505,7 @@ keyboard group. If the groups - mask is empty, group is not changed; otherwise, the locked keyboard group is +mask is empty, group is not changed; otherwise, the locked keyboard group is changed to the lowest numbered group specified in groups. @@ -517,11 +517,11 @@ changed to the lowest numbered group specified in Locked keyboard group is changed to the lowest numbered group that is not specified in the groups - mask, or to +mask, or to Group1 - if the +if the groups - mask contains all keyboard groups. +mask contains all keyboard groups. @@ -537,49 +537,49 @@ The mods field specifies what modifiers an indicator watches. The mods - field is an Xkb modifier definition, +field is an Xkb modifier definition, XkbModsRec, as described in section 7.2, which can specify both real and virtual modifiers. The mods - field takes effect even if some or all of the virtual indicators specified in +field takes effect even if some or all of the virtual indicators specified in mods - are unbound. To specify the mods field, in general, assign the modifiers of +are unbound. To specify the mods field, in general, assign the modifiers of interest to mods.real_mods - and the virtual modifiers of interest to +and the virtual modifiers of interest to mods.vmods. You can disregard the mods.mask - field unless your application needs to interpret the indicator map directly +field unless your application needs to interpret the indicator map directly (that is, to simulate automatic indicator behavior on its own). Relatively few applications need to do so, but if you find it necessary, you can either read the indicator map back from the server after you update it (the server automatically updates the mask field whenever any of the real or virtual modifiers are changed in the modifier definition) or you can use XkbVirtualModsToReal - to determine the proper contents for the mask field, assuming that the +to determine the proper contents for the mask field, assuming that the XkbDescRec - contains the virtual modifier definitions. +contains the virtual modifier definitions. which_mods - specifies what criteria Xkb uses to determine a match with the corresponding +specifies what criteria Xkb uses to determine a match with the corresponding mods - field by specifying one or more components of the Xkb keyboard state. If +field by specifying one or more components of the Xkb keyboard state. If XkbIM_NoAutomatic - is not set (the keyboard drives the indicator), the indicator is lit whenever +is not set (the keyboard drives the indicator), the indicator is lit whenever any of the modifiers specified in the mask - field of the +field of the mods - modifier definition are also set in any of the current keyboard state +modifier definition are also set in any of the current keyboard state components specified by which_mods. Remember that the mask - field is comprised of all of the real modifiers specified in the definition +field is comprised of all of the real modifiers specified in the definition plus any real modifiers that are bound to the virtual modifiers specified in the definition. (See for more information on the keyboard state and for more information on virtual modifiers.) Use a bitwise inclusive @@ -601,11 +601,11 @@ OR of the following values to compose a value for If XkbIM_NoAutomatic - is not set (the keyboard drives the indicator), the effect of +is not set (the keyboard drives the indicator), the effect of which_mods - and +and mods - is shown in Table 8.4 +is shown in Table 8.4
@@ -631,13 +631,13 @@ ignored. The indicator is lit when any of the modifiers specified in the mask - field of +field of mods - are on in the keyboard base state. If both +are on in the keyboard base state. If both mods.real_mods - and +and mods.vmods - are zero, the indicator is lit when the base keyboard state contains no +are zero, the indicator is lit when the base keyboard state contains no modifiers. @@ -646,13 +646,13 @@ modifiers. The indicator is lit when any of the modifiers specified in the mask - field of +field of mods - are latched. If both +are latched. If both mods.real_mods - and +and mods.vmods - are zero, the indicator is lit when none of the modifier keys are latched. +are zero, the indicator is lit when none of the modifier keys are latched. @@ -660,13 +660,13 @@ The indicator is lit when any of the modifiers specified in the The indicator is lit when any of the modifiers specified in the mask - field of +field of mods - are locked. If both +are locked. If both mods.real_mods - and +and mods.vmods - are zero, the indicator is lit when none of the modifier keys are locked. +are zero, the indicator is lit when none of the modifier keys are locked. @@ -674,13 +674,13 @@ The indicator is lit when any of the modifiers specified in the The indicator is lit when any of the modifiers specified in the mask - field of +field of mods - are in the effective keyboard state. If both +are in the effective keyboard state. If both mods.real_mods - and +and mods.vmods - are zero, the indicator is lit when the effective keyboard state contains no +are zero, the indicator is lit when the effective keyboard state contains no modifiers. @@ -689,13 +689,13 @@ modifiers. The indicator is lit when any of the modifiers specified in the mask - field of +field of mods - are in the keyboard compatibility state. If both +are in the keyboard compatibility state. If both mods.real_mods - and +and mods.vmods - are zero, the indicator is lit when the keyboard compatibility state contains +are zero, the indicator is lit when the keyboard compatibility state contains no modifiers. @@ -706,11 +706,11 @@ no modifiers. The effect on the keyboard modifiers of which_mods - and +and mods - when you change an indicator for which +when you change an indicator for which XkbIM_LEDDrivesKB - is set (the indicator drives the keyboard) is shown in +is set (the indicator drives the keyboard) is shown in Table 8.5. The New State column refers to the new state to which you set the indicator. @@ -741,9 +741,9 @@ column refers to the new state to which you set the indicator. Any modifiers specified in the mask - field of +field of mods - are added to the latched modifiers. +are added to the latched modifiers. @@ -752,9 +752,9 @@ Any modifiers specified in the Any modifiers specified in the mask - field of +field of mods - are removed from the latched modifiers. +are removed from the latched modifiers. @@ -763,9 +763,9 @@ Any modifiers specified in the Any modifiers specified in the mask - field of +field of mods - are added to the locked modifiers. +are added to the locked modifiers. @@ -774,9 +774,9 @@ Any modifiers specified in the Any modifiers specified in the mask - field of +field of mods - are removed from the locked modifiers. +are removed from the locked modifiers. @@ -785,9 +785,9 @@ Any modifiers specified in the Any modifiers specified in the mask - field of +field of mods - are removed from both the locked and latched modifiers. +are removed from both the locked and latched modifiers. @@ -801,7 +801,7 @@ Any modifiers specified in the The ctrls - field specifies what controls (see ) the indicator watches and is +field specifies what controls (see ) the indicator watches and is composed using the bitwise inclusive OR of the following values: @@ -823,7 +823,7 @@ composed using the bitwise inclusive OR of the following values: Xkb lights the indicator whenever any of the boolean controls specified in ctrls - is enabled. +is enabled. @@ -841,10 +841,10 @@ 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 XkbGetNamedIndicator - is an index that is the bit position to use in any function call that requires +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. +array of indicator maps. @@ -908,25 +908,25 @@ current state of the keyboard indicators, use XkbGetIndicatorState - queries the +queries the display - for the state of the indicators on the device specified by the +for the state of the indicators on the device specified by the device_spec. For each indicator that is turned on on the device, the associated bit is set in state_return. If a compatible version of the Xkb extension is not available in the server, XkbGetIndicatorState - returns a +returns a BadMatch - error. Otherwise, it sends the request to the X server, places the state of +error. Otherwise, it sends the request to the X server, places the state of the indicators into state_return, - and returns +and returns Success. Thus the value reported by XkbGetIndicatorState - is identical to the value reported by the core protocol. +is identical to the value reported by the core protocol. @@ -990,37 +990,37 @@ indicators, use XkbGetIndicatorMap - obtains the maps from the server for only those indicators specified by the +obtains the maps from the server for only those indicators specified by the which - mask and copies the values into the keyboard description specified by +mask and copies the values into the keyboard description specified by desc. If the indicators - field of the +field of the desc - parameter is +parameter is NULL, XkbGetIndicatorMap - allocates and initializes it. +allocates and initializes it. XkbGetIndicatorMap - can generate +can generate BadAlloc, BadLength, BadMatch, and BadImplementation - errors. +errors. To free the indicator maps, use XkbFreeIndicatorMaps - (see section 8.6). +(see section 8.6). @@ -1031,21 +1031,21 @@ To free the indicator maps, use Xkb also allows applications to refer to indicators by name. Use XkbGetNames - to get the indicator names (see ). Using names eliminates the need +to get the indicator names (see ). Using names eliminates the need for hard-coding bitmask values for particular keyboards. For example, instead of using vendor-specific constants such as WSKBLed_ScrollLock - mask on Digital workstations or +mask on Digital workstations or XLED_SCROLL_LOCK - on Sun workstations, you can instead use +on Sun workstations, you can instead use XkbGetNamedIndicator - to look up information on the indicator named Scroll Lock. +to look up information on the indicator named Scroll Lock. Use XkbGetNamedIndicator - to look up the indicator map and other information for an indicator by name. +to look up the indicator map and other information for an indicator by name. XkbGetNamedIndicator @@ -1148,15 +1148,15 @@ Use If the device specified by device_spec - has an indicator named +has an indicator named name, XkbGetNamedIndicator - returns +returns True - and populates the rest of the parameters with information about the indicator. +and populates the rest of the parameters with information about the indicator. Otherwise, XkbGetNamedIndicator - returns +returns False. @@ -1164,22 +1164,22 @@ Otherwise, The ndx_rtrn - field returns the zero-based index of the named indicator. This index is the +field returns the zero-based index of the named indicator. This index 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. +array of indicator maps. state_rtrn - returns the current state of the named indicator +returns the current state of the named indicator (True - = on, += on, False - = off). += off). map_rtrn - returns the indicator map for the named indicator. In addition, if the +returns the indicator map for the named indicator. In addition, if the indicator is mapped to a physical LED, the real_rtrn - parameter is set to +parameter is set to True. @@ -1187,17 +1187,17 @@ indicator is mapped to a physical LED, the Each of the "_rtrn" arguments is optional; you can pass NULL - for any unneeded "_rtrn" arguments. +for any unneeded "_rtrn" arguments. XkbGetNamedIndicator - can generate +can generate BadAtom - and +and BadImplementation - errors. +errors. @@ -1213,19 +1213,19 @@ so you can change it using a mask or a name. You cannot change the phys_indicators - field of the indicators structure. The only way to change the +field of the indicators structure. The only way to change the phys_indicators - field is to change the keyboard map. +field is to change the keyboard map. 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 +or XkbSetNamedIndicator, or, to reduce network traffic, use an XkbIndicatorChangesRec - structure and use +structure and use XkbChangeIndicators. @@ -1246,29 +1246,29 @@ are made. If XkbIM_LEDDrivesKB - is set and +is set and XkbIM_NoExplicit - is not, and if you call a function that updates the server’s image of the +is not, and if you call a function that updates the server’s image of the indicator map (such as XkbSetIndicatorMap - or +or XkbSetNamedIndicator), - Xkb changes the keyboard state and controls to reflect the other fields of +Xkb changes the keyboard state and controls to reflect the other fields of the indicator map. If you attempt to explicitly change the value of an indicator for which XkbIM_LEDDrivesKB - is absent or for which +is absent or for which XkbIM_NoExplicit - is present, keyboard state or controls are unaffected. +is present, keyboard state or controls are unaffected. If neither XkbIM_NoAutomatic - nor +nor XkbIM_NoExplicit - is set in an indicator map, Xkb honors any request to change the state of the +is set in an indicator map, Xkb honors any request to change the state of the indicator, but the new state might be immediately superseded by automatic changes to the indicator state if the keyboard state or controls change. @@ -1284,9 +1284,9 @@ controls simultaneously. If you change an indicator for which both the XkbIM_LEDDrivesKB - and +and XkbIM_NoAutomatic - flags are specified, Xkb applies the keyboard changes specified in the other +flags are specified, Xkb applies the keyboard changes specified in the other indicator map fields and changes the indicator to reflect the state that was explicitly requested. The indicator remains in the new state until it is explicitly changed again. @@ -1296,33 +1296,33 @@ explicitly changed again. If the XkbIM_NoAutomatic - flag is not set and +flag is not set and XkbIM_LEDDrivesKB - is set, Xkb applies the changes specified in the other indicator map fields +is set, Xkb applies the changes specified in the other indicator map fields and sets the state of the indicator to the values specified by the indicator map. Note that it is possible in this case for the indicator to end up in a different state than the one that was explicitly requested. For example, Xkb does not extinguish an indicator with which_mods - of +of XkbIM_UseBase - and +and mods - of +of Shift - if, at the time Xkb processes the request to extinguish the indicator, one of +if, at the time Xkb processes the request to extinguish the indicator, one of the Shift - keys is physically depressed. +keys is physically depressed. If you explicitly light an indicator for which XkbIM_LEDDrivesKB - is set, Xkb enables all of the boolean controls specified in the +is set, Xkb enables all of the boolean controls specified in the ctrls - field of its indicator map. Explicitly extinguishing such an indicator causes +field of its indicator map. Explicitly extinguishing such an indicator causes Xkb to disable all of the boolean controls specified in ctrls. @@ -1336,7 +1336,7 @@ Xkb to disable all of the boolean controls specified in To update the maps for one or more indicators, first modify a local copy of the keyboard description, then use XkbSetIndicatorMap - to download the changes to the server: +to download the changes to the server: XkbSetIndicatorMap @@ -1393,9 +1393,9 @@ bit set in the which parameter, XkbSetIndicatorMap - sends the corresponding indicator map from the +sends the corresponding indicator map from the desc - parameter to the server. +parameter to the server. @@ -1405,7 +1405,7 @@ parameter, XkbSetNamedIndicator - can do several related things: +can do several related things: @@ -1530,12 +1530,12 @@ Set the indicator map for the indicator If a compatible version of the Xkb extension is not available in the server, XkbSetNamedIndicator - returns +returns False. Otherwise, it sends a request to the X server to change the indicator specified by name - and returns +and returns True. @@ -1543,14 +1543,14 @@ specified by If change_state - is +is True, and the optional parameter, state, is not NULL, XkbSetNamedIndicator - tells the server to change the state of the named indicator to the value +tells the server to change the state of the named indicator to the value specified by state. @@ -1559,11 +1559,11 @@ specified by If an indicator with the name specified by name - does not already exist, the +does not already exist, the create_new - parameter tells the server whether it should create a new named indicator. If +parameter tells the server whether it should create a new named indicator. If create_new - is +is True, the server finds the first indicator that doesn’t have a name and gives it the name specified by @@ -1577,23 +1577,23 @@ If the optional parameter, is not NULL, XkbSetNamedIndicator - tells the server to change the indicator’s map to the values specified +tells the server to change the indicator’s map to the values specified in map. XkbSetNamedIndicator - can generate +can generate BadAtom - and +and BadImplementation - errors. In addition, it can also generate +errors. In addition, it can also generate XkbIndicatorStateNotify - (see section 8.5), +(see section 8.5), XkbIndicatorMapNotify, and XkbNamesNotify - events (see section 18.5). +events (see section 18.5). @@ -1607,9 +1607,9 @@ and The XkbIndicatorChangesRec - identifies small modifications to the indicator map. Use it with the function +identifies small modifications to the indicator map. Use it with the function XkbChangeIndicators - to reduce the amount of traffic sent to the server. +to reduce the amount of traffic sent to the server. @@ -1622,9 +1622,9 @@ typedef struct _XkbIndicatorChanges { The state_changes - field is a mask that specifies the indicators that have changed state, and +field is a mask that specifies the indicators that have changed state, and map_changes - is a mask that specifies the indicators whose maps have changed. +is a mask that specifies the indicators whose maps have changed. @@ -1693,36 +1693,36 @@ description, use XkbChangeIndicators - copies any maps specified by +copies any maps specified by changes - from the keyboard description, +from the keyboard description, xkb, to the server specified by dpy. If any bits are set in the state_changes - field of +field of changes, XkbChangeIndicators - also sets the state of those indicators to the values specified in the +also sets the state of those indicators to the values specified in the state - mask. A 1 bit in +mask. A 1 bit in state - turns the corresponding indicator on, a 0 bit turns it off. +turns the corresponding indicator on, a 0 bit turns it off. XkbChangeIndicators - can generate +can generate BadAtom - and +and BadImplementation - errors. In addition, it can also generate +errors. In addition, it can also generate XkbIndicatorStateNotify - and +and XkbIndicatorMapNotify - events (see section 8.5). +events (see section 8.5). @@ -1744,29 +1744,29 @@ If any bits are set in the Whenever an indicator changes state, the server sends XkbIndicatorStateNotify - events to all interested clients. Similarly, whenever an indicator’s map +events to all interested clients. Similarly, whenever an indicator’s map changes, the server sends XkbIndicatorMapNotify - events to all interested clients. +events to all interested clients. To receive XkbIndicatorStateNotify - events, use +events, use XkbSelectEvents - (see section 4.3) with both the +(see section 4.3) with both the bits_to_change and values_for_bits - parameters containing +parameters containing XkbIndicatorStateNotifyMask. To receive XkbIndicatorMapNotify - events, use +events, use XkbSelectEvents - with +with XkbIndicatorMapNotifyMask. @@ -1776,15 +1776,15 @@ To receive events for only specific indicators, use XkbSelectEventDetails. Set the event_type - parameter to +parameter to XkbIndicatorStateNotify - or +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 +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. @@ -1808,41 +1808,41 @@ typedef struct _XkbIndicatorNotify { xkb_type - is either +is either XkbIndicatorStateNotify - or +or XkbIndicatorMapNotify, depending on whether the event is a XkbIndicatorStateNotify - event or +event or XkbIndicatorMapNotify, - event. +event. The changed - parameter is a mask that is the bitwise inclusive OR of the indicators that +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 +reports the maps that changed. If the event is of type XkbIndicatorStateNotify, changed - reports the indicators that have changed state. +reports the indicators that have changed state. state - is a mask that specifies the current state of all indicators, whether they +is a mask that specifies the current state of all indicators, whether they have changed or not, for both XkbIndicatorStateNotify - and XkbIndicatorMapNotify events. +and XkbIndicatorMapNotify events. When your client application receives either a XkbIndicatorStateNotify - event or +event or XkbIndicatorMapNotify - event, you can note the changes in a changes structure by calling +event, you can note the changes in a changes structure by calling XkbNoteIndicatorChanges. @@ -1897,16 +1897,16 @@ When your client application receives either a The wanted - parameter is the bitwise inclusive OR of +parameter is the bitwise inclusive OR of XkbIndicatorMapMask - and +and XkbIndicatorStateMask. XkbNoteIndicatorChanges - copies any changes reported in +copies any changes reported in new - and specified in +and specified in wanted - into the changes record specified by +into the changes record specified by old. @@ -1915,7 +1915,7 @@ The To update a local copy of the keyboard description with the actual values, pass the results of one or more calls to XkbNoteIndicatorChanges - to +to XkbGetIndicatorChanges: @@ -1982,41 +1982,41 @@ the results of one or more calls to XkbGetIndicatorChanges - examines the +examines the changes - parameter, pulls over the necessary information from the server, and copies +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 +keyboard description. If any bits are set in the state_changes - field of +field of changes, XkbGetIndicatorChanges - also places the state of those indicators in +also places the state of those indicators in state. If the indicators - field of +field of xkb - is +is NULL, XkbGetIndicatorChanges - allocates and initializes it. To free the +allocates and initializes it. To free the indicators - field, use +field, use XkbFreeIndicatorMaps - (see section 8.6). +(see section 8.6). XkbGetIndicatorChanges - can generate +can generate BadAlloc, BadImplementation, - and +and BadMatch - errors. +errors. @@ -2027,7 +2027,7 @@ If the Most applications do not need to directly allocate the indicators - member of the keyboard description record (the keyboard description record is +member of the keyboard description record (the keyboard description record is described in ). If the need arises, however, use XkbAllocIndicatorMaps. @@ -2059,29 +2059,29 @@ described in ). If the need aris The xkb - parameter must point to a valid keyboard description. If it doesn’t, +parameter must point to a valid keyboard description. If it doesn’t, XkbAllocIndicatorMaps - returns a +returns a BadMatch - error. Otherwise, +error. Otherwise, XkbAllocIndicatorMaps - allocates and initializes the +allocates and initializes the indicators - member of the keyboard description record and returns +member of the keyboard description record and returns Success. If XkbAllocIndicatorMaps - was unable to allocate the indicators record, it reports a +was unable to allocate the indicators record, it reports a BadAlloc - error. +error. To free memory used by the indicators - member of an +member of an XkbDescRec - structure, use +structure, use XkbFreeIndicatorMaps. @@ -2111,7 +2111,7 @@ To free memory used by the If the indicators - member of the keyboard description record +member of the keyboard description record pointed to by xkb is not NULL, XkbFreeIndicatorMaps diff --git a/specs/XKB/ch09.xml b/specs/XKB/ch09.xml index dad70f24..0241880b 100644 --- a/specs/XKB/ch09.xml +++ b/specs/XKB/ch09.xml @@ -16,7 +16,7 @@ document, the audible bell bellaudible - bell is defined to be the system bell, or the default keyboard bell, as +bell is defined to be the system bell, or the default keyboard bell, as opposed to any other audible sound generated elsewhere in the system. @@ -24,7 +24,7 @@ opposed to any other audible sound generated elsewhere in the system. You can ask to receive XkbBellNotify - events (see section 9.4) when any client rings any one of the following: +events (see section 9.4) when any client rings any one of the following: @@ -37,9 +37,9 @@ The default bell Any bell on an input device that can be specified by a bell_class - and +and bell_id - pair +pair @@ -55,7 +55,7 @@ visual feedback, if any, that is associated with the name.) You can also ask to receive XkbBellNotify - events when the server rings the default bell or if any client has requested +events when the server rings the default bell or if any client has requested events only (without the bell sounding) for any of the bell types previously listed. @@ -63,27 +63,27 @@ listed. You can disable audible bells on a global basis (to set the AudibleBell - control, see ). For example, a client that replaces the keyboard +control, see ). For example, a client that replaces the keyboard bell with some other audible cue might want to turn off the AudibleBell - control to prevent the server from also generating a sound and avoid +control to prevent the server from also generating a sound and avoid cacophony. If you disable audible bells and request to receive XkbBellNotify - events, you can generate feedback different from the default bell. +events, you can generate feedback different from the default bell. You can, however, override the AudibleBell - control by calling one of the functions that force the ringing of a bell in +control by calling one of the functions that force the ringing of a bell in spite of the setting of the AudibleBell - control — +control — XkbForceDeviceBell - or +or XkbForceBell - (see section 9.3.3). In this case the server does not generate a bell event. +(see section 9.3.3). In this case the server does not generate a bell event. @@ -92,10 +92,10 @@ Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep codes. The AccessXFeedback - control is used to configure the specific types of operations that generate +control is used to configure the specific types of operations that generate feedback. See section 10.6.3 for a discussion on AccessXFeedback - control. +control. @@ -112,7 +112,7 @@ 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 +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. @@ -122,7 +122,7 @@ 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. +events.
@@ -212,9 +212,9 @@ 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 +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 +event, the audio client could then send a request to an audio server to play a sound. @@ -222,19 +222,19 @@ sound. You can control the audible bells feature by passing the XkbAudibleBellMask - to +to XkbChangeEnabledControls - (see section 10.1.1). If you set +(see section 10.1.1). If you set XkbAudibleBellMask - on, the server rings the system bell when a bell event occurs. This is the +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 +off and a bell event occurs, the server does not ring the system bell unless you call XkbForceDeviceBell - or +or XkbForceBell - (see section 9.3.3). +(see section 9.3.3). @@ -255,25 +255,25 @@ 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 +and bell_id - parameters; set them as follows: Set +parameters; set them as follows: Set bell_class - to +to BellFeedbackClass - or +or KbdFeedbackClass. A device can have more than one feedback of each type; set bell_id - to the particular bell feedback of +to the particular bell feedback of bell_class - type. +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. +to be generated when a bell function is called.
@@ -446,18 +446,18 @@ To ring the bell on an X input extension device or the default keyboard, use Set percent - to be the volume relative to the base volume for the keyboard as described for +to be the volume relative to the base volume for the keyboard as described for XBell. Note that bell_class - and +and bell_id - indicate the bell to physically ring. +indicate the bell to physically ring. name - is simply an arbitrary moniker for the client application’s use. +is simply an arbitrary moniker for the client application’s use. @@ -466,13 +466,13 @@ To determine the current feedback settings of an extension input device, use See the X input extension documentation for more information on XGetFeedbackControl - and related data structures. +and related data structures. If a compatible keyboard extension is not present in the X server, XkbDeviceBell - immediately returns +immediately returns False. Otherwise, XkbDeviceBell @@ -481,13 +481,13 @@ rings the bell as specified for the display and keyboard device and returns If you have disabled the audible bell, the server does not ring the system bell, although it does generate a XkbBellNotify - event. +event. You can call XkbDeviceBell - without first initializing the keyboard extension. +without first initializing the keyboard extension. @@ -556,11 +556,11 @@ default keyboard: If a compatible keyboard extension isn’t present in the X server, XkbBell - calls +calls XBell with the specified display - and +and percent, and returns False. @@ -568,7 +568,7 @@ Otherwise, XkbBell calls XkbDeviceBell - with the specified +with the specified display, window, percent, @@ -576,7 +576,7 @@ and name, a device_spec - of +of XkbUseCoreKbd, a bell_class @@ -586,7 +586,7 @@ and a bell_id of XkbDfltXIId, - and returns +and returns True. @@ -594,13 +594,13 @@ of If you have disabled the audible bell, the server does not ring the system bell, although it does generate a XkbBellNotify - event. +event. You can call XkbBell - without first initializing the keyboard extension. +without first initializing the keyboard extension. @@ -721,17 +721,17 @@ without ringing the corresponding bell, use If a compatible keyboard extension isn’t present in the X server, XkbDeviceBellEvent - immediately returns +immediately returns False. Otherwise, XkbDeviceBellEvent - causes an +causes an XkbBellNotify - event to be sent to all interested clients and returns +event to be sent to all interested clients and returns True. Set percent - to be the volume relative to the base volume for the keyboard as described for +to be the volume relative to the base volume for the keyboard as described for XBell. @@ -739,13 +739,13 @@ Set In addition, XkbDeviceBellEvent - may generate +may generate Atom - protocol errors as well as +protocol errors as well as XkbBellNotify - events. You can call +events. You can call XkbBell - without first initializing the keyboard extension. +without first initializing the keyboard extension. @@ -816,13 +816,13 @@ the keyboard without ringing the bell: If a compatible keyboard extension isn’t present in the X server, XkbBellEvent - immediately returns +immediately returns False. Otherwise, XkbBellEvent calls XkbDeviceBellEvent - with the specified +with the specified display, window, percent, @@ -830,7 +830,7 @@ and name, a device_spec - of +of XkbUseCoreKbd, a bell_class @@ -840,9 +840,9 @@ and a bell_id of XkbDfltXIId, - and returns what +and returns what XkbDeviceBellEvent - returns. +returns. @@ -949,7 +949,7 @@ audible bells, use XkbForceDeviceBell. If a compatible keyboard extension isn’t present in the X server, XkbForceDeviceBell - immediately returns +immediately returns False. Otherwise, XkbForceDeviceBell @@ -957,21 +957,21 @@ rings the bell as specified for the display and keyboard device and returns True. Set percent - to be the volume relative to the base volume for the keyboard as described for +to be the volume relative to the base volume for the keyboard as described for XBell. There is no name - parameter because +parameter because XkbForceDeviceBell does not cause an XkbBellNotify - event. +event. You can call XkbBell - without first initializing the keyboard extension. +without first initializing the keyboard extension. @@ -1017,24 +1017,24 @@ for audible bells, use If a compatible keyboard extension isn’t present in the X server, XkbForceBell - calls +calls XBell with the specified display - and +and percent - and returns +and returns False. Otherwise, XkbForceBell calls XkbForceDeviceBell - with the specified +with the specified display and percent, device_spec - = += XkbUseCoreKbd, bell_class = @@ -1043,26 +1043,26 @@ and = XkbDfltXIId, window - = None, and += None, and name - = += NULL, and returns what XkbForceDeviceBell - returns. +returns. XkbForceBell does not cause an XkbBellNotify - event. +event. You can call XkbBell - without first initializing the keyboard extension. +without first initializing the keyboard extension. @@ -1073,47 +1073,47 @@ You can call Xkb generates XkbBellNotify - events for all bells except for those resulting from calls to +events for all bells except for those resulting from calls to XkbForceDeviceBell - and +and XkbForceBell. To receive XkbBellNotify - events under all possible conditions, pass +events under all possible conditions, pass XkbBellNotifyMask - in both the +in both the bits_to_change and values_for_bits - parameters to +parameters to XkbSelectEvents - (see section 4.3). +(see section 4.3). The XkbBellNotify - event has no event details. It is either selected or it is not. However, you +event has no event details. It is either selected or it is not. However, you can call XkbSelectEventDetails - using +using XkbBellNotify - as the +as the event_type - and specifying +and specifying XkbAllBellEventsMask - in +in bits_to_change - and +and values_for_bits. - This has the same effect as a call to +This has the same effect as a call to XkbSelectEvents. The structure for the XkbBellNotify - event type contains: +event type contains: typedef struct _XkbBellNotify { diff --git a/specs/XKB/ch10.xml b/specs/XKB/ch10.xml index d99c788a..72727f22 100644 --- a/specs/XKB/ch10.xml +++ b/specs/XKB/ch10.xml @@ -40,7 +40,7 @@ remaining controls, known as the controlsnon-boolean are always active. The XkbControlsRec - structure describes the current state of most of the global controls and the +structure describes the current state of most of the global controls and the attributes effecting the behavior of each of these Xkb features. This chapter describes the Xkb controls and how to manipulate them. @@ -52,7 +52,7 @@ describing how the control should work, and a state describing whether the behavior as a whole is enabled or disabled. The attributes and state for most of these controls are held in the XkbControlsRec - structure (see section 10.8). +structure (see section 10.8). @@ -60,13 +60,13 @@ of these controls are held in the You can manipulate the Xkb controls individually, via convenience functions, or as a whole. To treat them as a group, modify an XkbControlsRec - structure to describe all of the changes to be made, and then pass that +structure to describe all of the changes to be made, and then pass that structure and appropriate flags to an Xkb library function, or use a XkbControlsChangesRec - (see section 10.10.1) to reduce network traffic. When using a convenience +(see section 10.10.1) to reduce network traffic. When using a convenience function to manipulate one control individually, you do not use an XkbControlsRec - structure directly. +structure directly. @@ -213,7 +213,7 @@ The Xkb controls are grouped as shown in The individual categories and controls are described first, together with functions for manipulating them. A description of the XkbControlsRec - structure and the general functions for dealing with all of the controls at +structure and the general functions for dealing with all of the controls at once follow at the end of the chapter. @@ -223,9 +223,9 @@ once follow at the end of the chapter. Enable and disable the boolean controls under program control by using the EnabledControls - control; enable and disable them upon program exit by configuring the +control; enable and disable them upon program exit by configuring the AutoReset - control. +control. @@ -235,12 +235,12 @@ Enable and disable the boolean controls under program control by using the The EnabledControls - control is a bit mask where each bit that is turned on means the corresponding +control is a bit mask where each bit that is turned on means the corresponding control is enabled, and when turned off, disabled. It corresponds to the enabled_ctrls - field of an +field of an XkbControlsRec - structure (see section 10.8). The bits describing which controls are turned on +structure (see section 10.8). The bits describing which controls are turned on or off are defined in Table 10.7. @@ -248,9 +248,9 @@ or off are defined in Table 10.7. Use XkbChangeEnabledControls - to manipulate the +to manipulate the EnabledControls - control. +control. XkbChangeEnabledControls @@ -316,14 +316,14 @@ Use The mask - parameter specifies the boolean controls to be enabled or disabled, and the +parameter specifies the boolean controls to be enabled or disabled, and the values - mask specifies the new state for those controls. Valid values for both of +mask specifies the new state for those controls. Valid values for both of these masks are composed of a bitwise inclusive OR of bits taken from the set of mask bits in Table 10.7, using only those masks with ok in the enabled_ctrls - column. +column. @@ -331,9 +331,9 @@ using only those masks with ok in the If the X server does not support a compatible version of Xkb or the Xkb extension has not been properly initialized, XkbChangeEnabledControls - returns +returns False; - otherwise, it sends the request to the X server and returns +otherwise, it sends the request to the X server and returns True. @@ -341,22 +341,22 @@ extension has not been properly initialized, Note that the EnabledControls - control only enables and disables controls; it does not configure them. Some +control only enables and disables controls; it does not configure them. Some controls, such as the AudibleBell - control, have no configuration attributes and are therefore manipulated solely +control, have no configuration attributes and are therefore manipulated solely by enabling and disabling them. Others, however, have additional attributes to configure their behavior. For example, the RepeatControl - control uses +control uses repeat_delay - and +and repeat_interval - fields to describe the timing behavior of keys that repeat. The +fields to describe the timing behavior of keys that repeat. The RepeatControl - behavior is turned on or off depending on the value of the +behavior is turned on or off depending on the value of the XkbRepeatKeysMask - bit, but you must use other means, as described in this chapter, to configure +bit, but you must use other means, as described in this chapter, to configure its behavior in detail. @@ -376,13 +376,13 @@ boolean controls specified in the auto-reset mask maskauto-reset - are set to the corresponding value from the +are set to the corresponding value from the auto-reset values - mask. This makes it possible for clients to "clean up after themselves" +mask. This makes it possible for clients to "clean up after themselves" automatically, even if abnormally terminated. The bits used in the masks correspond to the EnabledControls - control bits. +control bits. @@ -390,12 +390,12 @@ correspond to the For example, a client that replaces the keyboard bell with some other audible cue might want to turn off the AudibleBell - control to prevent the server from also generating a sound and avoid +control to prevent the server from also generating a sound and avoid cacophony. If the client were to exit without resetting the AudibleBell control, the user would be left without any feedback at all. Setting AudibleBell - in both the auto-reset mask and auto-reset values guarantees that the audible +in both the auto-reset mask and auto-reset values guarantees that the audible bell will be turned back on when the client exits. @@ -455,24 +455,24 @@ To get the current values of the auto-reset controls, use XkbGetAutoResetControls - backfills +backfills auto_ctrls - and +and auto_values - with the +with the AutoReset - control attributes for this particular client. It returns +control attributes for this particular client. It returns True - if successful, and +if successful, and False - otherwise. +otherwise. To change the current values of the AutoReset - control attributes, use +control attributes, use XkbSetAutoResetControls. @@ -551,7 +551,7 @@ corresponding bit in auto_values is on, the control is turned on when the client exits; if zero, the control is turned off when the client exits. - For any control selected by +For any control selected by changes, if the corresponding bit is not set in auto_ctrls, @@ -598,14 +598,14 @@ are turned on when the client exits: XkbSetAutoResetControls - backfills +backfills auto_ctrls - and +and auto_values - with the auto-reset controls for this particular client. Note that all of the +with the auto-reset controls for this particular client. Note that all of the bits are valid in the returned values, not just the ones selected in the changes - mask. +mask. @@ -617,7 +617,7 @@ bits are valid in the returned values, not just the ones selected in the The X server’s generation of sounds is controlled by the AudibleBell - control. Configuration of different bell sounds is discussed in . +control. Configuration of different bell sounds is discussed in . @@ -627,12 +627,12 @@ The X server’s generation of sounds is controlled by the The AudibleBell - control is a boolean control that has no attributes. As such, you may enable +control is a boolean control that has no attributes. As such, you may enable and disable it using either the EnabledControls - control or the +control or the AutoReset - control discussed in section 10.1.1. When enabled, protocol requests to +control discussed in section 10.1.1. When enabled, protocol requests to generate a sound result in the X server actually producing a real sound; when disabled, requests to the server to generate a sound are ignored unless the sound is forced. See section 9.2. @@ -650,17 +650,17 @@ sound is forced. See section 9.2. The repeating behavior of keyboard keys is governed by three controls, the PerKeyRepeat - control, which is always active, and the +control, which is always active, and the RepeatKeys - and +and DetectableAutorepeat - controls, which are boolean controls that may be enabled and disabled. +controls, which are boolean controls that may be enabled and disabled. PerKeyRepeat - determines which keys are allowed to repeat. +determines which keys are allowed to repeat. RepeatKeys - governs the behavior of an individual key when it is repeating. +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 +allows a client to detect when a key is repeating as a result of being held down. @@ -671,18 +671,18 @@ down. The PerKeyRepeat - control is a bitmask long enough to contain a bit for each key on the device; +control is a bitmask long enough to contain a bit for each key on the device; it determines which individual keys are allowed to repeat. The Xkb PerKeyRepeat - control provides no functionality different from that available via the core X +control provides no functionality different from that available via the core X protocol. There are no convenience functions in Xkb for manipulating this control. The PerKeyRepeat - control settings are carried in the +control settings are carried in the per_key_repeat - field of an +field of an XkbControlsRec - structure, discussed in section 10.8. +structure, discussed in section 10.8. @@ -694,12 +694,12 @@ control. The The core protocol allows only control over whether or not the entire keyboard or individual keys should auto-repeat when held down. RepeatKeys - is a boolean control that extends this capability by adding control over the +is a boolean control that extends this capability by adding control over the delay until a key begins to repeat and the rate at which it repeats. RepeatKeys - is coupled with the core auto-repeat control: when +is coupled with the core auto-repeat control: when RepeatKeys - is enabled or disabled, the core auto-repeat is enabled or disabled and vice +is enabled or disabled, the core auto-repeat is enabled or disabled and vice versa. @@ -719,7 +719,7 @@ operates does not automatically enable the control as a whole; see To get the current attributes of the RepeatKeys - control for a keyboard device, use +control for a keyboard device, use XkbGetAutoRepeatRate. @@ -782,17 +782,17 @@ To get the current attributes of the XkbGetAutoRepeatRate - queries the server for the current values of the +queries the server for the current values of the RepeatControls - control attributes, backfills +control attributes, backfills timeout_rtrn - and +and interval_rtrn - with them, and returns +with them, and returns True. If a compatible version of the Xkb extension is not available in the server XkbGetAutoRepeatRate - returns +returns False. @@ -862,29 +862,29 @@ To set the attributes of the RepeatKeys control for a keyboard device, use XkbSetAutoRepeatRate - sends a request to the X server to configure the +sends a request to the X server to configure the AutoRepeat - control attributes to the values specified in +control attributes to the values specified in timeout - and +and interval. XkbSetAutoRepeatRate - does not wait for a reply; it normally returns +does not wait for a reply; it normally returns True. Specifying a zero value for either timeout - or +or interval - causes the server to generate a +causes the server to generate a BadValue - protocol error. If a compatible version of the Xkb extension is not available +protocol error. If a compatible version of the Xkb extension is not available in the server, XkbSetAutoRepeatRate - returns +returns False. @@ -898,21 +898,21 @@ Auto-repeat is the generation of multiple key events by a keyboard when the user presses a key and holds it down. Keyboard hardware and device-dependent X server software often implement auto-repeat by generating multiple KeyPress - events with no intervening +events with no intervening KeyRelease - event. The standard behavior of the X server is to generate a +event. The standard behavior of the X server is to generate a KeyRelease - event for every +event for every KeyPress - event. If the keyboard hardware and device-dependent software of the X server +event. If the keyboard hardware and device-dependent software of the X server implement auto-repeat by generating multiple KeyPress - events, the device-independent part of the X server by default synthetically +events, the device-independent part of the X server by default synthetically generates a KeyRelease - event after each +event after each KeyPress - event. This provides predictable behavior for X clients, but does not allow +event. This provides predictable behavior for X clients, but does not allow those clients to detect the fact that a key is auto-repeating. @@ -928,13 +928,13 @@ If a client requests and the server supports DetectableAutorepeat, Xkb generates KeyRelease - events only when the key is physically released. If +events only when the key is physically released. If DetectableAutorepeat - is not supported or has not been requested, the server synthesizes a +is not supported or has not been requested, the server synthesizes a KeyRelease - event for each repeating +event for each repeating KeyPress - event it generates. +event it generates. @@ -942,25 +942,25 @@ Xkb generates DetectableAutorepeat, unlike the other controls in this chapter, is not contained in the XkbControlsRec - structure, nor can it be enabled or disabled via the +structure, nor can it be enabled or disabled via the EnabledControls - control. Instead, query and set +control. Instead, query and set DetectableAutorepeat - using +using XkbGetDetectableAutorepeat - and +and XkbSetDetectableAutorepeat. DetectableAutorepeat - is a condition that applies to all keyboard devices for a client’s +is a condition that applies to all keyboard devices for a client’s connection to a given X server; it cannot be selectively set for some devices and not for others. For this reason, none of the Xkb library functions involving DetectableAutorepeat - involve a device specifier. +involve a device specifier. @@ -1010,29 +1010,29 @@ use XkbGetDetectableAutorepeat - queries the server for the current state of +queries the server for the current state of DetectableAutorepeat - and waits for a reply. If +and waits for a reply. If supported_rtrn - is not +is not NULL, it backfills supported_rtrn with True - if the server supports +if the server supports DetectableAutorepeat, and False - otherwise. +otherwise. XkbGetDetectableAutorepeat - returns the current state of +returns the current state of DetectableAutorepeat - for the requesting client: +for the requesting client: True - if +if DetectableAutorepeat - is set, and +is set, and False - otherwise. +otherwise. @@ -1098,40 +1098,40 @@ they have requested otherwise. XkbSetDetectableAutorepeat - sends a request to the server to set +sends a request to the server to set DetectableAutorepeat - on for the current client if +on for the current client if detectable - is +is True, and off it detectable - is +is False; - it then waits for a reply. If +it then waits for a reply. If supported_rtrn - is not +is not NULL, XkbSetDetectableAutorepeat - backfills +backfills supported_rtrn - with +with True - if the server supports +if the server supports DetectableAutorepeat, and False - if it does not. +if it does not. XkbSetDetectableAutorepeat - returns the current state of +returns the current state of DetectableAutorepeat - for the requesting client: +for the requesting client: True - if +if DetectableAutorepeat - is set, and +is set, and False - otherwise. +otherwise. @@ -1153,25 +1153,25 @@ keyboards. Xkb includes direct support for two keyboard overlays, using the Overlay1 - and +and Overlay2 - controls. When +controls. When Overlay1 - is enabled, all of the keys that are members of the first keyboard overlay +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 +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 +and Overlay2 - are boolean controls. As such, you may enable and disable them using either +are boolean controls. As such, you may enable and disable them using either the EnabledControls - control or the +control or the AutoReset - control discussed in section 10.1.1. +control discussed in section 10.1.1. @@ -1179,9 +1179,9 @@ the 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 +or XkbKB_Overlay2 - key behaviors, as described in section 16.2. +key behaviors, as described in section 16.2. @@ -1195,16 +1195,16 @@ 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, +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 +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 +control or the AutoReset - control discussed in section 10.1.1. The individual keys that simulate +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 . @@ -1216,39 +1216,39 @@ discussed in . The MouseKeys - control allows a user to control all the mouse functions from the keyboard. +control allows a user to control all the mouse functions from the keyboard. When MouseKeys - are enabled, all keys with +are enabled, all keys with MouseKeys - actions bound to them generate core pointer events instead of normal +actions bound to them generate core pointer events instead of normal KeyPress - and +and KeyRelease - events. +events. The MouseKeys - control has a single attribute, +control has a single attribute, mk_dflt_btn - that specifies the core button number to be used by mouse keys actions that do +that specifies the core button number to be used by mouse keys actions that do not explicitly specify a button. There is no convenience function for getting or setting the attribute; instead use XkbGetControls - and +and XkbSetControls - (see section 10.9 and section 10.10). +(see section 10.9 and section 10.10). MouseKeys - can also be turned on and off by pressing the key combination necessary to +can also be turned on and off by pressing the key combination necessary to produce an XK_Pointer_EnableKeys - keysym. The de facto default standard for this is +keysym. The de facto default standard for this is ShiftAltNumLock, but this may vary depending on the keymap. @@ -1259,15 +1259,15 @@ but this may vary depending on the keymap. When the MouseKeysAccel - control is enabled, the effect of a key-activated pointer motion action +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 +is enabled, mouse movement is defined by an initial distance specified in the XkbSA_MovePtr - action and the following fields in the +action and the following fields in the XkbControlsRec - structure (see section 10.8). +structure (see section 10.8).
@@ -1312,20 +1312,20 @@ speed There are no convenience functions to query or change the attributes of the MouseKeysAccel - control; instead use +control; instead use XkbGetControls - and +and XkbSetControls - (see section 10.9 and section 10.10). +(see section 10.9 and section 10.10). The effects of the attributes of the MouseKeysAccel - control depend on whether the +control depend on whether the XkbSA_MovePtr - action (see section 16.1) specifies relative or absolute pointer motion. +action (see section 16.1) specifies relative or absolute pointer motion. @@ -1334,11 +1334,11 @@ The effects of the attributes of the If an XkbSA_MovePtr - action specifies an absolute position for one of the coordinates but still +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 +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. @@ -1351,22 +1351,22 @@ stays at the same X position. If the XkbSA_MovePtr - action specifies relative motion, the initial event always moves the cursor +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 +milliseconds, a second motion event is generated, and another occurs every mk_interval - milliseconds until the user releases the key. +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 +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 +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. @@ -1376,7 +1376,7 @@ the action by For example, if the XkbSA_MovePtr - action specifies a relative motion in the X direction of 5, +action specifies a relative motion in the X direction of 5, mk_delay =160, mk_interval @@ -1398,9 +1398,9 @@ pressed. After 160 milliseconds (mk_delay), - and every 40 milliseconds thereafter +and every 40 milliseconds thereafter (mk_interval), - the pointer moves in the X direction. +the pointer moves in the X direction. @@ -1408,7 +1408,7 @@ After 160 milliseconds The distance in the X direction increases with each interval until 30 intervals ( mk_time_to_max) - have elapsed. +have elapsed. @@ -1416,7 +1416,7 @@ The distance in the X direction increases with each interval until 30 intervals 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 original distance) every interval thereafter, until the key is released. @@ -1424,58 +1424,58 @@ After 30 intervals, the pointer stops accelerating, and moves 150 pixels 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 +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 +is the relative motion specified by the XkbSA_MovePtr - action, +action, mk_max_speed and mk_time_to_max - are parameters to the +are parameters to the MouseKeysAccel - control, and the curveFactor is computed using the +control, and the curveFactor is computed using the MouseKeysAccel mk_curve - parameter as follows: +parameter as follows: - - - + + + With the result that a mk_curve - of zero causes the distance moved to increase linearly from +of zero causes the distance moved to increase linearly from action_delta - to - - - . +to + + +. A negative mk_curve - causes an initial sharp increase in acceleration that tapers off, and a +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. +are between −1000 and 1000. @@ -1526,12 +1526,12 @@ Enabling or disabling the keyboard controls through a graphical user interface may be impossible for people who need to use the controls. For example, a user who needs SlowKeys - (see section 10.6.6) may not even be able to start the graphical application, +(see section 10.6.6) may not even be able to start the graphical application, let alone use it, if SlowKeys - is not enabled. To allow easier access to some of the controls, the +is not enabled. To allow easier access to some of the controls, the AccessXKeys - control provides a set of special key sequences similar to those available in +control provides a set of special key sequences similar to those available in AccessDOS. @@ -1539,7 +1539,7 @@ AccessDOS. When the AccessXKeys - control is enabled, the user can turn controls on or off from the keyboard by +control is enabled, the user can turn controls on or off from the keyboard by entering the following standard key sequences: @@ -1549,24 +1549,24 @@ entering the following standard key sequences: Holding down a Shift key by itself for eight seconds toggles the SlowKeys - control. +control. Pressing and releasing the left or right Shift - key five times in a row, without any intervening key events and with less than +key five times in a row, without any intervening key events and with less than 30 seconds delay between consecutive presses, toggles the state of the StickyKeys - control. +control. Simultaneously operating two or more modifier keys deactivates the StickyKeys - control. +control. @@ -1574,7 +1574,7 @@ Simultaneously operating two or more modifier keys deactivates the When the AccessXKeys - control is disabled, Xkb does not look for the above special key sequences. +control is disabled, Xkb does not look for the above special key sequences. @@ -1582,7 +1582,7 @@ When the Some of these key sequences optionally generate audible feedback of the change in state, as described in section 10.6.3, or XkbControlsNotify - events, described in section 10.11. +events, described in section 10.11. @@ -1592,38 +1592,38 @@ in state, as described in section 10 In environments where computers are shared, features such as SlowKeys - present a problem: if +present a problem: if SlowKeys - is on, the keyboard can appear to be unresponsive because keys are not +is on, the keyboard can appear to be unresponsive because keys are not accepted until they are held for a certain period of time. To help solve this problem, Xkb provides an AccessXTimeout - control to automatically change the enabled/disabled state of any boolean +control to automatically change the enabled/disabled state of any boolean controls and to change the value of the AccessXKeys - and +and AccessXFeedback - control attributes if the keyboard is idle for a specified period of time. +control attributes if the keyboard is idle for a specified period of time. When a timeout as specified by AccessXTimeout - occurs and a control is consequently modified, Xkb generates an +occurs and a control is consequently modified, Xkb generates an XkbControlsNotify - event. For more information on +event. For more information on XkbControlsNotify - events, refer to section 10.11. +events, refer to section 10.11. Use XkbGetAccessXTimeout - to query the current +to query the current AccessXTimeout - options for a keyboard device. +options for a keyboard device. XkbGetAccessXTimeout @@ -1723,26 +1723,26 @@ Use XkbGetAccessXTimeout - sends a request to the X server to obtain the current values for the +sends a request to the X server to obtain the current values for the AccessXTimeout - attributes, waits for a reply, and backfills the values into the appropriate +attributes, waits for a reply, and backfills the values into the appropriate arguments. The parameters opts_mask_rtrn - and +and opts_values_rtrn - are backfilled with the options to modify and the values for +are backfilled with the options to modify and the values for ax_options, which is a field in the XkbControlsRec - structure (see section 10.8). +structure (see section 10.8). XkbGetAccessXTimeout returns True - if successful; if a compatible version of the Xkb extension is not available +if successful; if a compatible version of the Xkb extension is not available in the server, XkbGetAccessXTimeout - returns +returns False. @@ -1750,7 +1750,7 @@ in the server, To configure the AccessXTimeout - options for a keyboard device, use +options for a keyboard device, use XkbSetAccessXTimeout. @@ -1849,40 +1849,40 @@ opts_values timeout - specifies the number of seconds the keyboard must be idle before the controls +specifies the number of seconds the keyboard must be idle before the controls are modified. ctrls_mask - specifies what controls are to be enabled or disabled, and +specifies what controls are to be enabled or disabled, and ctrls_values - specifies whether those controls are to be enabled or disabled. The bit values +specifies whether those controls are to be enabled or disabled. The bit values correspond to those for enabling and disabling boolean controls (see section 10.1.1). The opts_mask - field specifies which attributes of the +field specifies which attributes of the AccessXKeys - and +and AccessXFeedback - controls are to be changed, and +controls are to be changed, and opts_values - specifies the new values for those options. The bit values correspond to those +specifies the new values for those options. The bit values correspond to those for the ax_options - field of an +field of an XkbDescRec - (see section 10.8). +(see section 10.8). XkbSetAccessXTimeout - sends a request to configure the +sends a request to configure the AccessXTimeout - control to the server. +control to the server. It does not wait for a reply, and normally returns True. If a compatible version of the Xkb extension is not available in the server, XkbSetAccessXTimeout - returns +returns False. @@ -1896,22 +1896,22 @@ Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep codes. Use the AccessXFeedback - control to configure the specific types of operations that generate feedback. +control to configure the specific types of operations that generate feedback. There is no convenience function for modifying the AccessXFeedback - control, although the feedback as a whole can be enabled or disabled just as +control, although the feedback as a whole can be enabled or disabled just as other boolean controls are (see section 10.1). Individual beep codes are turned on or off by modifying the following bits in the ax_options - field of an +field of an XkbControlsRec - structure and using +structure and using XkbSetControls - (see section 10.10): +(see section 10.10):
@@ -2015,16 +2015,16 @@ high-pitched beep followed by a low-pitched beep instead of a continuous falling tone. Other implementations can only ring the bell with one fixed pitch. In these cases, use the XkbAX_DumbBellFBMask - bit of +bit of ax_options - to indicate that the bell can only ring with a fixed pitch. +to indicate that the bell can only ring with a fixed pitch. When any of the above feedbacks occur, Xkb may generate a XkbBellNotify - event (see section 9.4). +event (see section 9.4). @@ -2040,9 +2040,9 @@ When any of the above feedbacks occur, Xkb may generate a The server can generate XkbAccessXNotify - events for some of the global keyboard controls. The structure for the +events for some of the global keyboard controls. The structure for the XkbAccessXNotify - event type is as follows: +event type is as follows: typedef struct { @@ -2063,7 +2063,7 @@ typedef struct { The detail - field describes what AccessX event just occurred and can be any of the values +field describes what AccessX event just occurred and can be any of the values in Table 10.4. @@ -2117,20 +2117,20 @@ expired). The keycode - field reports the keycode of the key for which the event occurred. If the +field reports the keycode of the key for which the event occurred. If the action is related to SlowKeys, the slowKeysDelay - field contains the current +field contains the current SlowKeys - acceptance delay. If the action is related to +acceptance delay. If the action is related to BounceKeys, the debounceDelay - field contains the current +field contains the current BounceKeys - debounce delay. +debounce delay. @@ -2139,13 +2139,13 @@ the To receive XkbAccessXNotify - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - (see section 4.3) and pass +(see section 4.3) and pass XkbAccessXNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -2153,17 +2153,17 @@ To receive To receive XkbStateNotify - events only under certain conditions, use +events only under certain conditions, use XkbSelectEventDetails - using +using XkbAccessXNotify - as the +as the event_type - and specifying the desired state changes in +and specifying the desired state changes in bits_to_change - and +and values_for_bits - using mask bits from Table 10.5. +using mask bits from Table 10.5.
@@ -2236,20 +2236,20 @@ The RepeatKeys, and MouseKeys - controls do not generate specific events. Instead, the latching, unlatching, +controls do not generate specific events. Instead, the latching, unlatching, locking, or unlocking of modifiers using StickyKeys - generates +generates XkbStateNotify - events as described in section 5.4. Repeating keys generate normal +events as described in section 5.4. Repeating keys generate normal KeyPress - and +and KeyRelease - events, though the auto-repeat can be detected using +events, though the auto-repeat can be detected using DetectableAutorepeat - (see section 10.3.3). Finally, +(see section 10.3.3). Finally, MouseKeys - generates pointer events identical to those of the core pointer device. +generates pointer events identical to those of the core pointer device. @@ -2262,7 +2262,7 @@ Some users may accidentally bump keys while moving a hand or typing stick toward the key they want. Usually, the keys that are accidentally bumped are just hit for a very short period of time. The SlowKeys - control helps filter these accidental bumps by telling the server to wait a +control helps filter these accidental bumps by telling the server to wait a specified period, called the SlowKeys acceptance delay, before delivering key events. If the key is released before this period @@ -2271,23 +2271,23 @@ their way to the one they want without accidentally getting those characters. Once they have reached the key they want, they can then hold the desired key long enough for the computer to accept it. SlowKeys - is a boolean control with one configurable attribute. +is a boolean control with one configurable attribute. When the SlowKeys - control is active, the server reports the initial key press, subsequent +control is active, the server reports the initial key press, subsequent acceptance or rejection, and release of any key to interested clients by sending an appropriate AccessXNotify - event (see section 10.6.4). +event (see section 10.6.4). To get the SlowKeys - acceptance delay for a keyboard device, use +acceptance delay for a keyboard device, use XkbGetSlowKeysDelay. @@ -2343,18 +2343,18 @@ To get the XkbGetSlowKeysDelay requests the attributes of the SlowKeys - control from the server, waits for a reply and backfills +control from the server, waits for a reply and backfills delay_rtrn with the SlowKeys - delay attribute. +delay attribute. XkbGetSlowKeysDelay returns True - if successful; if a compatible version of the Xkb extension is not available +if successful; if a compatible version of the Xkb extension is not available in the server, XkbGetSlowKeysDelay - returns +returns False. @@ -2362,7 +2362,7 @@ in the server, To set the SlowKeys - acceptance delay for a keyboard device, use +acceptance delay for a keyboard device, use XkbSetSlowKeysDelay. @@ -2417,23 +2417,23 @@ To set the XkbSetSlowKeysDelay - sends a request to configure the +sends a request to configure the SlowKeys - control to the server. +control to the server. It does not wait for a reply, and normally returns True. Specifying a value of 0 - for the +for the delay parameter causes XkbSetSlowKeysDelay - to generate a +to generate a BadValue - protocol error. If a compatible version of the Xkb extension is not available +protocol error. If a compatible version of the Xkb extension is not available in the server XkbSetSlowKeysDelay - returns +returns False. @@ -2446,31 +2446,31 @@ in the server Some users may accidentally bounce on a key when they release it. They press it once, then accidentally press it again after they release it. The BounceKeys - control temporarily disables a key after it has been pressed, effectively +control temporarily disables a key after it has been pressed, effectively debouncing the keyboard. The period of time the key is disabled after it is released is known as the BounceKeys delay. BounceKeys - is a boolean control. +is a boolean control. When the BounceKeys - control is active, the server reports acceptance or rejection of any key to +control is active, the server reports acceptance or rejection of any key to interested clients by sending an appropriate AccessXNotify - event (see section 10.6.4). +event (see section 10.6.4). Use XkbGetBounceKeysDelay - to query the current +to query the current BounceKeys - delay for a keyboard device. +delay for a keyboard device. XkbGetBounceKeysDelay @@ -2525,18 +2525,18 @@ Use XkbGetBounceKeysDelay requests the attributes of the BounceKeys - control from the server, waits for a reply, and backfills +control from the server, waits for a reply, and backfills delay_rtrn with the BounceKeys - delay attribute. +delay attribute. XkbGetBounceKeysDelay returns True - if successful; if a compatible version of the Xkb extension is not available +if successful; if a compatible version of the Xkb extension is not available in the server XkbGetSlowKeysDelay - returns +returns False. @@ -2544,7 +2544,7 @@ in the server To set the BounceKeys - delay for a keyboard device, use +delay for a keyboard device, use XkbSetBounceKeysDelay. @@ -2599,9 +2599,9 @@ To set the XkbSetBounceKeysDelay - sends a request to configure the +sends a request to configure the BounceKeys - control to the server. +control to the server. It does not wait for a reply and normally returns True. Specifying a value of @@ -2610,12 +2610,12 @@ for the delay parameter causes XkbSetBounceKeysDelay - to generate a +to generate a BadValue - protocol error. If a compatible version of the Xkb extension is not available +protocol error. If a compatible version of the Xkb extension is not available in the server, XkbSetBounceKeysDelay - returns +returns False. @@ -2627,29 +2627,29 @@ in the server, Some people find it difficult or even impossible to press two keys at once. For example, a one-fingered typist or someone using a mouth stick cannot press the Shift - and +and 1 - keys at the same time. The +keys at the same time. The StickyKeys - control solves this problem by changing the behavior of the modifier keys. +control solves this problem by changing the behavior of the modifier keys. With StickyKeys, the user can first press a modifier, release it, then press another key. For example, to get an exclamation point on a PC-style keyboard, the user can press the Shift - key, release it, and then press the +key, release it, and then press the 1 - key. +key. StickyKeys - also allows users to lock modifier keys without requiring special locking +also allows users to lock modifier keys without requiring special locking keys. When StickyKeys - is enabled, a modifier is latched when the user presses it just once. The user +is enabled, a modifier is latched when the user presses it just once. The user can press a modifier twice in a row to lock it, and then unlock it by pressing it one more time. @@ -2663,24 +2663,24 @@ nonmodifier key or a pointer button. For instance, to enter the sequence ControlZ - the user could press and release the +the user could press and release the Shift - key to latch it, then press and release the +key to latch it, then press and release the Control - key to latch it, and finally press and release the +key to latch it, and finally press and release the Z key. Because the Control - key is a modifier key, pressing it does not unlatch the +key is a modifier key, pressing it does not unlatch the Shift - key. Thus, after the user presses the +key. Thus, after the user presses the Control - key, both the +key, both the Shift - and +and Control - modifiers are latched. When the user presses the +modifiers are latched. When the user presses the Z - key, the effect is as though the user had pressed +key, the effect is as though the user had pressed Shift Control @@ -2688,11 +2688,11 @@ nonmodifier key or a pointer button. For instance, to enter the sequence . In addition, because the Z - key is not a modifier key, the +key is not a modifier key, the Shift - and +and Control - modifiers are unlatched. +modifiers are unlatched. @@ -2703,9 +2703,9 @@ programmatically. For example, to enter the sequence ("XKB") on a keyboard where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’ is a shifted single quote, the user could press and release the Shift - key twice to lock the +key twice to lock the Shift - modifier. Then, when the user presses the +modifier. Then, when the user presses the 9, ', x, @@ -2714,17 +2714,17 @@ is a shifted single quote, the user could press and release the ', and 0 - keys in sequence, it generates ("XKB"). To unlock the +keys in sequence, it generates ("XKB"). To unlock the Shift - modifier, the user can press and release the +modifier, the user can press and release the Shift - key. +key. StickyKeys - is a boolean control with two separate attributes that may be individually +is a boolean control with two separate attributes that may be individually configured: one to automatically disable it, and one to control the latching behavior of modifier keys. @@ -2735,34 +2735,34 @@ behavior of modifier keys. The StickyKeys - control has two options that can be accessed via the +control has two options that can be accessed via the ax_options - of an +of an XkbControlsRec - structure (see section 10.8). The first option, +structure (see section 10.8). The first option, TwoKeys, specifies whether StickyKeys - should automatically turn off when two keys are pressed at the same time. This +should automatically turn off when two keys are pressed at the same time. This feature is useful for shared computers so people who do not want them do not need to turn StickyKeys - off if a previous user left +off if a previous user left StickyKeys - on. The second option, +on. The second option, LatchToLock, specifies whether or not StickyKeys - locks a modifier when pressed twice in a row. +locks a modifier when pressed twice in a row. Use XkbGetStickyKeysOptions - to query the current +to query the current StickyKeys - attributes for a keyboard device. +attributes for a keyboard device. XkbGetStickyKeysOptions @@ -2817,13 +2817,13 @@ Use XkbGetStickyKeysOptions requests the attributes of the StickyKeys - control from the server, waits for a reply, and backfills +control from the server, waits for a reply, and backfills options_rtrn with a mask indicating whether the individual StickyKeys - options are on or off. Valid bits in +options are on or off. Valid bits in options_rtrn - are: +are: XkbAX_TwoKeysMask @@ -2835,10 +2835,10 @@ with a mask indicating whether the individual XkbGetStickyKeysOptions returns True - if successful; if a compatible version of the Xkb extension is not available +if successful; if a compatible version of the Xkb extension is not available in the server XkbGetStickyKeysOptions - returns +returns False. @@ -2846,7 +2846,7 @@ in the server To set the StickyKeys - attributes for a keyboard device, use +attributes for a keyboard device, use XkbSetStickyKeysOptions. @@ -2911,16 +2911,16 @@ To set the XkbSetStickyKeysOptions - sends a request to configure the +sends a request to configure the StickyKeys - control to the server. +control to the server. It does not wait for a reply and normally returns True. The valid bits to use for both the mask - and +and values - parameters are: +parameters are: XkbAX_TwoKeysMask @@ -2929,9 +2929,9 @@ The valid bits to use for both the - If a compatible version of the Xkb extension is not available in the server, +If a compatible version of the Xkb extension is not available in the server, XkbSetStickyKeysOptions - returns +returns False. @@ -2956,7 +2956,7 @@ and consumed in the server. These are: IgnoreGroupLock - is a boolean control; the rest are always active. +is a boolean control; the rest are always active. @@ -2964,14 +2964,14 @@ and consumed in the server. These are: Without the modifier processing options provided by Xkb, passive grabs set via translations in a client (for example, Alt<KeyPress>space) - do not trigger if any modifiers other than those specified by the translation +do not trigger if any modifiers other than those specified by the translation are set. This results in problems in the user interface when either NumLock - or a secondary keyboard group is active. The +or a secondary keyboard group is active. The IgnoreLockMods - and +and IgnoreGroupLock - controls make it possible to avoid this behavior without exhaustively +controls make it possible to avoid this behavior without exhaustively specifying a grab for every possible modifier combination. @@ -2981,12 +2981,12 @@ specifying a grab for every possible modifier combination. The GroupsWrap - control determines how illegal groups are handled on a global basis. There are +control determines how illegal groups are handled on a global basis. There are a number of valid keyboard sequences that can cause the effective group number to go out of range. When this happens, the group must be normalized back to a valid number. The GroupsWrap - control specifies how this is done. +control specifies how this is done. @@ -2995,7 +2995,7 @@ When dealing with group numbers, all computations are done using the group index, which is the group number minus one. There are three different algorithms; the GroupsWrap - control specifies which one is used: +control specifies which one is used: @@ -3005,7 +3005,7 @@ algorithms; the All invalid group numbers are converted to a valid group number by taking the last four bits of the GroupsWrap - control and using them as the group index. If the result is still out of +control and using them as the group index. If the result is still out of range, Group one is used. @@ -3031,17 +3031,17 @@ modulus applied to the group index. There are no convenience functions for manipulating the GroupsWrap - control. Manipulate the +control. Manipulate the GroupsWrap - control via the +control via the groups_wrap - field in the +field in the XkbControlsRec - structure, then use +structure, then use XkbSetControls - and +and XkbGetControls - (see section 10.9 and section 10.10) to query and change this control. +(see section 10.9 and section 10.10) to query and change this control. See also section 15.3.2 or a discussion of the related field, @@ -3062,12 +3062,12 @@ unanticipated side effects. The IgnoreLockMods - control specifies modifiers that should be excluded from grab calculations. +control specifies modifiers that should be excluded from grab calculations. These modifiers are also not reported in any core events except KeyPress - and +and KeyRelease - events that do not activate a passive grab and that do not occur while a grab +events that do not activate a passive grab and that do not occur while a grab is active. @@ -3075,15 +3075,15 @@ is active. Manipulate the IgnoreLockMods - control via the +control via the ignore_lock - field in the +field in the XkbControlsRec - structure, then use +structure, then use XkbSetControls - and +and XkbGetControls - (see section 10.9 and section 10.10) to query and change this control. Alternatively, +(see section 10.9 and section 10.10) to query and change this control. Alternatively, use XkbSetIgnoreLockMods. @@ -3177,32 +3177,32 @@ virtual_values XkbSetIgnoreLockMods - sends a request to the server to change the server’s +sends a request to the server to change the server’s IgnoreLockMods - control. +control. affect_real - and +and real_values - are masks of real modifier bits indicating which real modifiers are to be +are masks of real modifier bits indicating which real modifiers are to be added and removed from the server’s IgnoreLockMods - control. Modifiers selected by both +control. Modifiers selected by both affect_real - and +and real_values - are added to the server’s +are added to the server’s IgnoreLockMods - control; those selected by +control; those selected by affect_real - but not by +but not by real_values - are removed from the server’s +are removed from the server’s IgnoreLockMods - control. Valid values for +control. Valid values for affect_real - and +and real_values - consist of any combination of the eight core modifier bits: +consist of any combination of the eight core modifier bits: ShiftMask, LockMask, ControlMask, @@ -3210,34 +3210,34 @@ added and removed from the server’s – Mod5Mask. affect_virtual - and +and virtual_values - are masks of virtual modifier bits indicating which virtual modifiers are to +are masks of virtual modifier bits indicating which virtual modifiers are to be added and removed from the server’s IgnoreLockMods - control. Modifiers selected by both +control. Modifiers selected by both affect_virtual - and +and virtual_values - are added to the server’s +are added to the server’s IgnoreLockMods - control; those selected by +control; those selected by affect_virtual - but not by +but not by virtual_values - are removed from the server’s +are removed from the server’s IgnoreLockMods - control. +control. See section 7.1 for a discussion of virtual modifier masks to use in affect_virtual - and +and virtual_values. XkbSetIgnoreLockMods - does not wait for a reply from the server. It returns +does not wait for a reply from the server. It returns True - if the request was sent, and +if the request was sent, and False - otherwise. +otherwise. @@ -3247,7 +3247,7 @@ See section 7.1 for a di The IgnoreGroupLock - control is a boolean control with no attributes. If enabled, it specifies that +control is a boolean control with no attributes. If enabled, it specifies that the locked state of the keyboard group should not be considered when activating passive grabs. @@ -3255,7 +3255,7 @@ passive grabs. Because IgnoreGroupLock - is a boolean control with no attributes, use the general boolean controls +is a boolean control with no attributes, use the general boolean controls functions (see section 10.1) to change its state. @@ -3268,16 +3268,16 @@ functions (see s The core protocol does not provide any means to prevent a modifier from being reported in events sent to clients; Xkb, however makes this possible via the InternalMods - control. It specifies modifiers that should be consumed by the server and not +control. It specifies modifiers that should be consumed by the server and not reported to clients. When a key is pressed and a modifier that has its bit set in the InternalMods - control is reported to the server, the server uses the modifier when +control is reported to the server, the server uses the modifier when determining the actions to apply for the key. The server then clears the bit, so it is not actually reported to the client. In addition, modifiers specified in the InternalMods - control are not used to determine grabs and are not used to calculate core +control are not used to determine grabs and are not used to calculate core protocol compatibility state. @@ -3285,16 +3285,16 @@ protocol compatibility state. Manipulate the InternalMods - control via the +control via the internal - field in the +field in the XkbControlsRec - structure, using +structure, using XkbSetControls - and +and XkbGetControls - (see section 10.9 - and section 10.10). Alternatively, use +(see section 10.9 +and section 10.10). Alternatively, use XkbSetServerInternalMods. @@ -3387,26 +3387,26 @@ virtual_values XkbSetServerInternalMods - sends a request to the server to change the internal modifiers consumed by the +sends a request to the server to change the internal modifiers consumed by the server. affect_real - and +and real_values - are masks of real modifier bits indicating which real modifiers are to be +are masks of real modifier bits indicating which real modifiers are to be added and removed from the server’s internal modifiers control. Modifiers selected by both affect_real - and +and real_values - are added to the server’s internal modifiers control; those selected by +are added to the server’s internal modifiers control; those selected by affect_real - but not by +but not by real_values - are removed from the server’s internal modifiers mask. Valid values for +are removed from the server’s internal modifiers mask. Valid values for affect_real - and +and real_values - consist of any combination of the eight core modifier bits: +consist of any combination of the eight core modifier bits: ShiftMask, LockMask, ControlMask, @@ -3414,29 +3414,29 @@ selected by both – Mod5Mask. affect_virtual - and +and virtual_values - are masks of virtual modifier bits indicating which virtual modifiers are to +are masks of virtual modifier bits indicating which virtual modifiers are to be added and removed from the server’s internal modifiers control. Modifiers selected by both affect_virtual - and +and virtual_values - are added to the server’s internal modifiers control; those selected by +are added to the server’s internal modifiers control; those selected by affect_virtual - but not by +but not by virtual_values - are removed from the server’s internal modifiers control. +are removed from the server’s internal modifiers control. See section 7.1 for a discussion of virtual modifier masks to use in affect_virtual - and +and virtual_values. XkbSetServerInternalMods - does not wait for a reply from the server. It returns +does not wait for a reply from the server. It returns True - if the request was sent and +if the request was sent and False - otherwise. +otherwise. @@ -3453,12 +3453,12 @@ Many of the individual controls described in sections 10.1 through 10.7 may be manipulated via convenience functions discussed in those sections. Some of them, however, have no convenience functions. The XkbControlsRec - structure allows the manipulation of one or more of the controls in a single +structure allows the manipulation of one or more of the controls in a single operation and to track changes to any of them in conjunction with the XkbGetControls - and +and XkbSetControls - functions. This is the only way to manipulate those controls that have no +functions. This is the only way to manipulate those controls that have no convenience functions. @@ -3466,7 +3466,7 @@ convenience functions. The XkbControlsRec - structure is defined as follows: +structure is defined as follows: #define XkbMaxLegalKeyCode 255 @@ -3513,14 +3513,14 @@ typedef struct { The general-purpose functions that work with the XkbControlsRec - structure use a mask to specify which controls are to be manipulated. +structure use a mask to specify which controls are to be manipulated. Table 10.6 lists these controls, the masks used to select them in the general function calls (which - parameter), and the data fields in the +parameter), and the data fields in the XkbControlsRec - structure that comprise each of the individual controls. Also listed are the +structure that comprise each of the individual controls. Also listed are the bit used to turn boolean controls on and off and the section where each control is described in more detail. @@ -3714,9 +3714,9 @@ controls for modification and to enable and disable the control. Note that the same mask bit is used to specify general modifications to the parameters used to configure the control (which), - and to enable and disable the control +and to enable and disable the control (enabled_ctrls). - The anomalies in the table (no ok in column) are for controls that have no +The anomalies in the table (no ok in column) are for controls that have no configurable attributes; and for controls that are not boolean controls and therefore cannot be enabled or disabled. @@ -3871,7 +3871,7 @@ therefore cannot be enabled or disabled. The individual fields of the XkbControlsRec - structure are defined as follows. +structure are defined as follows. @@ -3883,8 +3883,8 @@ The individual fields of the mk_dflt_btn is an attribute of the MouseKeys control - (see section 10.5). It - specifies the mouse button number to use for keyboard simulated mouse button +(see section 10.5). It +specifies the mouse button number to use for keyboard simulated mouse button operations. Its value should be one of the core symbols Button1 – @@ -3898,9 +3898,9 @@ operations. Its value should be one of the core symbols num_groups - is not a part of any control, but is reported in the +is not a part of any control, but is reported in the XkbControlsRec - structure whenever any of its components are fetched from the server. It +structure whenever any of its components are fetched from the server. It reports the number of groups the particular keyboard configuration uses and is computed automatically by the server whenever the keyboard mapping changes. @@ -3912,12 +3912,12 @@ computed automatically by the server whenever the keyboard mapping changes. groups_wrap - is an attribute of the +is an attribute of the GroupsWrap - control (see section 10.7.1). It specifies the handling of illegal groups on a +control (see section 10.7.1). It specifies the handling of illegal groups on a global basis. Valid values for groups_wrap - are shown in Table 10.8. +are shown in Table 10.8.
@@ -3952,7 +3952,7 @@ global basis. Valid values for When groups_wrap - is set to +is set to XkbRedirectIntoRange, its four low-order bits specify the index of the group to use. @@ -3964,9 +3964,9 @@ its four low-order bits specify the index of the group to use. internal - is an attribute of the +is an attribute of the InternalMods - control (see section 10.7.4). It specifies modifiers to be consumed in the +control (see section 10.7.4). It specifies modifiers to be consumed in the server and not passed on to clients when events are reported. Valid values consist of any combination of the eight core modifier bits: ShiftMask, @@ -3984,9 +3984,9 @@ consist of any combination of the eight core modifier bits: ignore_lock - is an attribute of the +is an attribute of the IgnoreLockMods - control (see section 10.7.2). It specifies modifiers to be ignored in grab +control (see section 10.7.2). It specifies modifiers to be ignored in grab calculations. Valid values consist of any combination of the eight core modifier bits: ShiftMask, @@ -4004,15 +4004,15 @@ modifier bits: enabled_ctrls - is an attribute of the +is an attribute of the EnabledControls - control (see section 10.1.1). It contains one bit per boolean control. Each +control (see section 10.1.1). It contains one bit per boolean control. Each bit determines whether the corresponding control is enabled or disabled; a one bit means the control is enabled. The mask bits used to enable these controls are listed in Table 10.7, using only those masks with ok in the enabled_ctrls - column. +column. @@ -4022,15 +4022,15 @@ using only those masks with ok in the repeat_delay - and +and repeat_interval - are attributes of the +are attributes of the RepeatKeys - control (see section 10.3.2). +control (see section 10.3.2). repeat_delay - is the initial delay before a key begins repeating, in milliseconds; +is the initial delay before a key begins repeating, in milliseconds; repeat_interval - is the delay between subsequent key events, in milliseconds. +is the delay between subsequent key events, in milliseconds. @@ -4040,11 +4040,11 @@ using only those masks with ok in the slow_keys_delay - is an attribute of the +is an attribute of the SlowKeys - control (see section 10.6.6). Its value specifies the +control (see section 10.6.6). Its value specifies the SlowKeys - acceptance delay period in milliseconds before a key press is accepted by the +acceptance delay period in milliseconds before a key press is accepted by the server. @@ -4055,11 +4055,11 @@ server. debounce_delay - is an attribute of the +is an attribute of the BounceKeys - control (see section 10.6.7). Its value specifies the +control (see section 10.6.7). Its value specifies the BounceKeys - delay period in milliseconds for which the key is disabled after having been +delay period in milliseconds for which the key is disabled after having been pressed before another press of the same key is accepted by the server. @@ -4075,9 +4075,9 @@ pressed before another press of the same key is accepted by the server. mk_max_speed, and mk_curve - are attributes of the +are attributes of the MouseKeysAccel - control. Refer to section 10.5.2 for a description of these fields and the +control. Refer to section 10.5.2 for a description of these fields and the units involved. @@ -4089,13 +4089,13 @@ units involved. The ax_options - field contains attributes used to configure two different controls, the +field contains attributes used to configure two different controls, the StickyKeys - control (see section 10.6.8) and the +control (see section 10.6.8) and the AccessXFeedback - control (see section 10.6.3). The +control (see section 10.6.3). The ax_options - field is a bitmask and may include any combination of the bits defined in +field is a bitmask and may include any combination of the bits defined in Table 10.9. @@ -4187,20 +4187,20 @@ The The fields pertaining to each control are relevant only when the control is enabled (XkbAccessXFeedbackMask - or +or XkbStickyKeysMask - bit is turned on in the +bit is turned on in the enabled_ctrls - field). +field). Xkb provides a set of convenience macros for working with the ax_options - field of an +field of an XkbControlsRec - structure: +structure: #define XkbAX_NeedOption(c,w) ((c)->ax_options & (w)) @@ -4209,14 +4209,14 @@ Xkb provides a set of convenience macros for working with the The XkbAX_NeedOption - macro is useful for determining whether a particular AccessX option is enabled +macro is useful for determining whether a particular AccessX option is enabled or not. It accepts a pointer to an XkbControlsRec - structure and a valid mask bit from +structure and a valid mask bit from Table 10.9. - If the specified mask bit in the +If the specified mask bit in the ax_options - field of the controls structure is set, the macro returns the mask bit. +field of the controls structure is set, the macro returns the mask bit. Otherwise, it returns zero. Thus, @@ -4226,12 +4226,12 @@ Otherwise, it returns zero. Thus, is nonzero if the latch to lock transition for latching keys is enabled, and zero if it is disabled. Note that XkbAX_NeedOption - only determines whether or not the particular capability is configured to +only determines whether or not the particular capability is configured to operate; the XkbAccessXFeedbackMask - bit must also be turned on in +bit must also be turned on in enabled_ctrls - for the capability to actually be functioning. +for the capability to actually be functioning. @@ -4242,13 +4242,13 @@ operate; the The XkbAX_AnyFeedback - macro accepts a pointer to an +macro accepts a pointer to an XkbControlsRec - structure and tells whether the +structure and tells whether the AccessXFeedback - control is enabled or not. If the +control is enabled or not. If the AccessXFeedback - control is enabled, the macro returns +control is enabled, the macro returns XkbAccessXFeedbackMask. Otherwise, it returns zero. @@ -4261,14 +4261,14 @@ Otherwise, it returns zero. The XkbAX_NeedFeedback - macro is useful for determining if both the +macro is useful for determining if both the AccessXFeedback - control and a particular AccessX feedback option are enabled. The macro +control and a particular AccessX feedback option are enabled. The macro accepts a pointer to an XkbControlsRec - structure and a feedback option from the table above. If both the +structure and a feedback option from the table above. If both the AccessXFeedback - control and the specified feedback option are enabled, the macro returns +control and the specified feedback option are enabled, the macro returns True. Otherwise it returns False. @@ -4287,9 +4287,9 @@ id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values axt_ctrls_mask, and axt_ctrls_values - are attributes of the +are attributes of the AccessXTimeout - control. Refer to section 10.6.2 for a description of these fields and the +control. Refer to section 10.6.2 for a description of these fields and the units involved. @@ -4301,25 +4301,25 @@ units involved. The per_key_repeat - field mirrors the +field mirrors the auto_repeats - field of the core protocol +field of the core protocol XKeyboardState - structure: changing the +structure: changing the auto_repeats - field automatically changes +field automatically changes per_key_repeat - and vice versa. It is provided for convenience and to reduce protocol traffic. +and vice versa. It is provided for convenience and to reduce protocol traffic. For example, to obtain the individual repeat key behavior as well as the repeat delay and rate, use XkbGetControls. If the per_key_repeat - were not in this structure, you would have to call both +were not in this structure, you would have to call both XGetKeyboardControl - and +and XkbGetControls - to get this information. The bits correspond to keycodes. The first seven keys +to get this information. The bits correspond to keycodes. The first seven keys (keycodes 1–7) are indicated in per_key_repeat[0], with bit position 0 (low order) corresponding to the fictitious keycode 0. @@ -4337,7 +4337,7 @@ indicates that the key is a repeating key. Use XkbGetControls - to find the current state of Xkb server controls. +to find the current state of Xkb server controls. XkbGetControls @@ -4387,19 +4387,19 @@ Use XkbGetControls - queries the server for the requested control information, waits for a reply, +queries the server for the requested control information, waits for a reply, and then copies the server’s values for the requested information into the ctrls - structure of the +structure of the xkb - argument. Only those components specified by the +argument. Only those components specified by the which - parameter are copied. Valid values for +parameter are copied. Valid values for which - are any combination of the masks listed in +are any combination of the masks listed in Table 10.7 that have ok in the which - column. +column. @@ -4409,35 +4409,35 @@ If is NULL, XkbGetControls - allocates and initializes it before obtaining the values specified by +allocates and initializes it before obtaining the values specified by which. If xkb->ctrls - is not +is not NULL, XkbGetControls - modifies only those portions of +modifies only those portions of xkb->ctrls - corresponding to the values specified by +corresponding to the values specified by which. XkbGetControls - returns +returns Success - if successful; otherwise, it returns +if successful; otherwise, it returns BadAlloc - if it cannot obtain sufficient storage, +if it cannot obtain sufficient storage, BadMatch - if +if xkb - is +is NULL - or +or which - is empty, or +is empty, or BadImplementation. @@ -4445,18 +4445,18 @@ If To free the ctrls - member of a keyboard description, use +member of a keyboard description, use XkbFreeControls - (see section 10.12) +(see section 10.12) The num_groups - field in the +field in the ctrls - structure is always filled in by +structure is always filled in by XkbGetControls, regardless of which bits are selected by which. @@ -4473,7 +4473,7 @@ keyboard description and call XkbSetControls, or, to reduce network traffic, use an XkbControlsChangesRec - structure and call +structure and call XkbChangeControls. @@ -4481,9 +4481,9 @@ or, to reduce network traffic, use an To change the state of one or more controls, first modify the ctrls - structure in a local copy of the keyboard description and then use +structure in a local copy of the keyboard description and then use XkbSetControls - to copy those changes to the X server. +to copy those changes to the X server. XkbSetControls @@ -4534,28 +4534,28 @@ To change the state of one or more controls, first modify the For each bit that is set in the which - parameter, +parameter, XkbSetControls - sends the corresponding values from the +sends the corresponding values from the xkb->ctrls - field to the server. Valid values for +field to the server. Valid values for which - are any combination of the masks listed in +are any combination of the masks listed in Table 10.7 that have ok in the which - column. +column. If xkb->ctrls - is +is NULL, the server does not support a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbSetControls - returns +returns False. Otherwise, it sends the request to the X server and returns True. @@ -4565,20 +4565,20 @@ Otherwise, it sends the request to the X server and returns Note that changes to attributes of controls in the XkbControlsRec - structure are apparent only when the associated control is enabled, although +structure are apparent only when the associated control is enabled, although the corresponding values are still updated in the X server. For example, the repeat_delay - and +and repeat_interval - fields are ignored unless the +fields are ignored unless the RepeatKeys - control is enabled (that is, the X server’s equivalent of +control is enabled (that is, the X server’s equivalent of xkb->ctrls - has +has XkbRepeatKeysMask - set in +set in enabled_ctrls). - It is permissible to modify the attributes of a control in one call to +It is permissible to modify the attributes of a control in one call to XkbSetControls and enable the control in a subsequent call. See section 10.1.1 for more information on enabling and disabling controls. @@ -4587,15 +4587,15 @@ for more information on enabling and disabling controls. Note that the enabled_ctrls - field is itself a control — the +field is itself a control — the EnabledControls - control. As such, to set a specific configuration of enabled and disabled +control. As such, to set a specific configuration of enabled and disabled boolean controls, you must set enabled_ctrls - to the appropriate bits to enable only the controls you want and disable all +to the appropriate bits to enable only the controls you want and disable all others, then specify the XkbControlsEnabledMask - in a call to +in a call to XkbSetControls. Because this is somewhat awkward if all you want to do is enable and disable controls, and not modify any of their attributes, a convenience function is @@ -4614,17 +4614,17 @@ also provided for this purpose The XkbControlsChangesRec - structure allows applications to track modifications to an +structure allows applications to track modifications to an XkbControlsRec - structure and thereby reduce the amount of traffic sent to the server. The +structure and thereby reduce the amount of traffic sent to the server. The same XkbControlsChangesRec - structure may be used in several successive modifications to the same +structure may be used in several successive modifications to the same XkbControlsRec - structure, then subsequently used to cause all of the changes, and only the +structure, then subsequently used to cause all of the changes, and only the changes, to be propagated to the server. The XkbControlsChangesRec - structure is defined as follows: +structure is defined as follows: typedef struct _XkbControlsChanges { @@ -4640,33 +4640,33 @@ typedef struct _XkbControlsChanges { The changed_ctrls - field is a mask specifying which logical sets of data in the controls +field is a mask specifying which logical sets of data in the controls structure have been modified. In this context, modified means set, that is, if a value is set to the same value it previously contained, it has still been modified, and is noted as changed. Valid values for changed_ctrls - are any combination of the masks listed in +are any combination of the masks listed in Table 10.7 that have ok in the changed_ctrls - column. Setting a bit implies the corresponding data fields from the +column. Setting a bit implies the corresponding data fields from the Relevant XkbControlsRec Data Fields column in Table 10.6 have been modified. The enabled_ctrls_changes - field specifies which bits in the +field specifies which bits in the enabled_ctrls - field have changed. If the number of keyboard groups has changed, the +field have changed. If the number of keyboard groups has changed, the num_groups_changed - field is set to True. +field is set to True. If you have an Xkb description with controls that have been modified and an XkbControlsChangesRec - that describes the changes that have been made, the +that describes the changes that have been made, the XkbChangeControls - function provides a flexible method for updating the controls in a server to +function provides a flexible method for updating the controls in a server to match those in the changed keyboard description. @@ -4718,9 +4718,9 @@ match those in the changed keyboard description. XkbChangeControls - copies any controls fields specified by +copies any controls fields specified by changes - from the keyboard description controls structure, +from the keyboard description controls structure, xkb->ctrls, to the server specified by dpy. @@ -4741,15 +4741,15 @@ to the server specified by Whenever a field in the controls structure changes in the server’s keyboard description, the server sends an XkbControlsNotify - event to all interested clients.To receive +event to all interested clients.To receive XkbControlsNotify - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - (see section 4.3) and pass +(see section 4.3) and pass XkbControlsNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -4757,24 +4757,24 @@ description, the server sends an To receive XkbControlsNotify - events only under certain conditions, use +events only under certain conditions, use XkbSelectEventDetails - using +using XkbControlsNotify - as the +as the event_type - and specifying the desired state changes in +and specifying the desired state changes in bits_to_change - and +and values_for_bits - using mask bits from Table 10.7. +using mask bits from Table 10.7. The structure for the XkbControlsNotify - event is defined as follows: +event is defined as follows: typedef struct { @@ -4802,29 +4802,29 @@ typedef struct { The changed_ctrls - field specifies the controls components that have changed and consists of bits +field specifies the controls components that have changed and consists of bits taken from the masks defined in Table 10.7 with ok in the changed_ctrls - column. +column. The controls currently enabled in the server are reported in the enabled_ctrls - field. If any controls were just enabled or disabled (that is, the contents of +field. If any controls were just enabled or disabled (that is, the contents of the enabled_ctrls - field changed), they are flagged in the +field changed), they are flagged in the enabled_ctrl_changes - field. The valid bits for these fields are the masks listed in +field. The valid bits for these fields are the masks listed in Table 10.7 with ok in the enabled_ctrls - column. The +column. The num_groups - field reports the number of groups bound to the key belonging to the most +field reports the number of groups bound to the key belonging to the most number of groups and is automatically updated when the keyboard mapping changes. @@ -4832,33 +4832,33 @@ number of groups and is automatically updated when the keyboard mapping changes. If the change was caused by a request from a client, the keycode - and +and event_type - fields are set to +fields are set to zero and the req_major - and +and req_minor - fields identify the request. The +fields identify the request. The req_major - value is the same as the major extension opcode. Otherwise, +value is the same as the major extension opcode. Otherwise, event_type - is set to the type of event that caused the change (one of +is set to the type of event that caused the change (one of KeyPress, KeyRelease, DeviceKeyPress, DeviceKeyRelease, ButtonPress - or +or ButtonRelease), - and +and req_major - and +and req_minor - are undefined. If +are undefined. If event_type - is +is KeyPress, KeyRelease, DeviceKeyPress, @@ -4866,21 +4866,21 @@ or DeviceKeyRelease, the keycode - field is set to the key that caused the change. If +field is set to the key that caused the change. If event_type - is +is ButtonPress - or +or ButtonRelease, keycode - contains the button number. +contains the button number. When a client receives an XkbControlsNotify - event, it can note the changes in a changes structure using +event, it can note the changes in a changes structure using XkbNoteControlsChanges. @@ -4935,17 +4935,17 @@ When a client receives an The wanted - parameter is a bitwise inclusive OR of bits taken from the set of masks +parameter is a bitwise inclusive OR of bits taken from the set of masks specified in Table 10.7 with ok in the changed_ctrls - column. +column. XkbNoteControlsChanges - copies any changes reported in +copies any changes reported in new - and specified in +and specified in wanted - into the changes record specified by +into the changes record specified by changes. @@ -4953,7 +4953,7 @@ in the Use XkbGetControlsChanges - to update a local copy of a keyboard description with the changes previously +to update a local copy of a keyboard description with the changes previously noted by one or more calls to XkbNoteControlsChanges. @@ -5009,36 +5009,36 @@ noted by one or more calls to XkbGetControlsChanges - examines the +examines the changes - parameter, queries the server for the necessary information, and copies the +parameter, queries the server for the necessary information, and copies the results into the xkb->ctrls - keyboard description. If the +keyboard description. If the ctrls - field of +field of xkb - is +is NULL, XkbGetControlsChanges - allocates and initializes it. To free the +allocates and initializes it. To free the ctrls - field, use +field, use XkbFreeControls - (see section 10.12). +(see section 10.12). XkbGetControlsChanges - returns +returns Success - if successful and can generate +if successful and can generate BadAlloc, BadImplementation, - and +and BadMatch - errors. +errors. @@ -5049,11 +5049,11 @@ results into the The need to allocate an XkbControlsRec - structure seldom arises; Xkb creates one when an application calls +structure seldom arises; Xkb creates one when an application calls XkbGetControls - or a related function. For those situations where there is not an +or a related function. For those situations where there is not an XkbControlsRec - structure allocated in the +structure allocated in the XkbDescRec, allocate one by calling XkbAllocControls. @@ -5096,40 +5096,40 @@ allocate one by calling XkbAllocControls - allocates the +allocates the ctrls - field of the +field of the xkb - parameter, initializes all fields to zero, and returns +parameter, initializes all fields to zero, and returns Success. If the ctrls - field is not +field is not NULL, XkbAllocControls - simply returns +simply returns Success. If xkb - is +is NULL, XkbAllocControls - reports a +reports a BadMatch - error. If the +error. If the ctrls - field could not be allocated, it reports a +field could not be allocated, it reports a BadAlloc - error. +error. The which - mask specifies the individual fields of the +mask specifies the individual fields of the ctrls - structure to be allocated and can contain any of the valid masks defined in +structure to be allocated and can contain any of the valid masks defined in Table 10.7. Because none of the currently existing controls have any structures associated with them, which is currently of little practical value in this call. @@ -5139,7 +5139,7 @@ associated with them, which is currently of little practical value in this call. To free memory used by the ctrls - member of an +member of an XkbDescRec structure, use XkbFreeControls: @@ -5194,19 +5194,19 @@ structure, use XkbFreeControls - frees the specified components of the +frees the specified components of the ctrls - field in the +field in the xkb - keyboard description and sets the corresponding structure component values to +keyboard description and sets the corresponding structure component values to NULL - or +or zero. The which - mask specifies the fields of +mask specifies the fields of ctrls - to be freed and can contain any of the controls components specified in +to be freed and can contain any of the controls components specified in Table 10.7. @@ -5214,20 +5214,20 @@ The If free_all - is +is True, XkbFreeControls - frees every non- +frees every non- NULL - structure component in the controls, frees the +structure component in the controls, frees the XkbControlsRec - structure referenced by the +structure referenced by the ctrls - member of +member of xkb, and sets ctrls - to +to NULL. @@ -5252,7 +5252,7 @@ for more details. To get the current values of the per-client - controls, use +controls, use XkbGetPerClientControls. @@ -5294,22 +5294,22 @@ To get the current values of the XkbGetPerClientControls - backfills +backfills ctrls - with the +with the per-client control attributes for this particular client. It returns True - if successful, and +if successful, and False - otherwise. +otherwise. To change the current values of the per-client - control attributes, use +control attributes, use XkbSetPerClientControls. @@ -5374,9 +5374,9 @@ by OR-ing the values together. XkbSetPerClientControls backfills value with the control attributes for this particular client. It returns True - if successful, and +if successful, and False - otherwise. +otherwise. diff --git a/specs/XKB/ch11.xml b/specs/XKB/ch11.xml index d1881be7..6463878b 100644 --- a/specs/XKB/ch11.xml +++ b/specs/XKB/ch11.xml @@ -86,13 +86,13 @@ affecting simple string lookups are: If the ForceLatin1Lookup - control is enabled, +control is enabled, XLookupString - only returns strings using the Latin1 character set. If +only returns strings using the Latin1 character set. If ForceLatin1Lookup - is not enabled, +is not enabled, XLookupString - can return characters that are not in the Latin1 set. By default, this control +can return characters that are not in the Latin1 set. By default, this control is disabled, allowing characters outside of the Latin1 set to be returned. @@ -104,7 +104,7 @@ is disabled, allowing characters outside of the Latin1 set to be returned. Simple string lookups in XLookupString - involve two different translation phases. The first phase translates raw +involve two different translation phases. The first phase translates raw device keycodes to individual keysyms. The second phase attempts to map the resulting keysym into a string of one or more characters. In the first phase, some of the modifiers are normally used to determine the appropriate shift @@ -115,59 +115,59 @@ level for a key. The ConsumeLookupMods - control determines whether or not +control determines whether or not XLookupString consumes - the modifiers it uses during the first phase of processing (mapping a keycode +the modifiers it uses during the first phase of processing (mapping a keycode to a keysym). When a modifier is consumed, it is effectively removed from the working copy of the keyboard state information XLookupString - is using and appears to be unset for the remainder of the processing. +is using and appears to be unset for the remainder of the processing. If the ConsumeLookupMods - control is enabled, +control is enabled, XLookupString - does not use the modifiers used to translate the keycode of the event to a +does not use the modifiers used to translate the keycode of the event to a keysym when it is determining the string associated with a keysym. For example, assume the keymap for the ‘A’ key only contains the shift modifier and the ConsumeLookupMods - control is enabled. If a user presses the +control is enabled. If a user presses the Shift - key and the +key and the A - key while the +key while the Num_Lock - key is locked, +key is locked, XLookupString - uses the +uses the Shift - modifier when mapping the keycode for the ‘a’ key to the keysym for +modifier when mapping the keycode for the ‘a’ key to the keysym for ‘A’; subsequently, it only uses the NumLock - modifier when determining the string associated with the keysym ‘A’. +modifier when determining the string associated with the keysym ‘A’. If the ConsumeLookupMods - control is not enabled, +control is not enabled, XLookupString - uses all of the event modifiers to determine the string associated with a +uses all of the event modifiers to determine the string associated with a keysym. This behavior mirrors the behavior of XLookupString - in the core implementation. +in the core implementation. The ConsumeLookupMods - control is unset by default. For more information on modifier consumption, +control is unset by default. For more information on modifier consumption, refer to . @@ -179,16 +179,16 @@ refer to . The AlwaysConsumeShiftAndLock - control, if enabled, forces +control, if enabled, forces XLookupString - to consume the +to consume the Shift - and +and Lock - modifiers when processing all keys, even if the definition for the key type +modifiers when processing all keys, even if the definition for the key type does not specify these modifiers. The AlwaysConsumeShiftAndLock - control is unset by default. See section 15.2 for a discussion of key types. +control is unset by default. See section 15.2 for a discussion of key types. @@ -200,10 +200,10 @@ does not specify these modifiers. The The second type of string lookup performed by XLookupString - involves translating a series of keysyms into a string. Because these lookups +involves translating a series of keysyms into a string. Because these lookups can involve more than one key event, they require XLookupString - to retain some state information between successive calls. The process of +to retain some state information between successive calls. The process of mapping a series of keysyms to a string is known as compose processing. @@ -239,19 +239,19 @@ valid translation to a string. If the subsequent key events do not have a valid translation, some decision must be made about what to do with the key events that were processed while attempting the compose. The ConsumeKeysOnComposeFail - control allows a client to specify what happens with the key events +control allows a client to specify what happens with the key events XLookupString - has been considering when it reaches a dead end in a compose sequence. +has been considering when it reaches a dead end in a compose sequence. If the ConsumeKeysOnComposeFail - control is set, all keys associated with a failed compose sequence should be +control is set, all keys associated with a failed compose sequence should be consumed (discarded). If the ConsumeKeysOnComposeFail - control is not set, the key events associated with a failed compose sequence +control is not set, the key events associated with a failed compose sequence should be processed as a normal sequence of key events. @@ -259,7 +259,7 @@ should be processed as a normal sequence of key events. The ConsumeKeysOnComposeFail - control is disabled by default. +control is disabled by default. @@ -270,15 +270,15 @@ The The ComposeLED - control allows a client to specify whether or not an indicator should be set +control allows a client to specify whether or not an indicator should be set and cleared to provide feedback when compose processing is in progress. The control does not specify which indicator should be used; the mapping for this is up to the individual implementation. If the ComposeLED - control is enabled, it specifies that an indicator should be set when a +control is enabled, it specifies that an indicator should be set when a compose sequence is in progress and cleared when one is not in progress. The ComposeLED - control is disabled by default. +control is disabled by default. @@ -286,7 +286,7 @@ compose sequence is in progress and cleared when one is not in progress. The While the Xkb extension does not specify the type of type of indicator to be used when the ComposeLED - control is implemented, a consistent convention between implementations is to +control is implemented, a consistent convention between implementations is to everyone’s benefit. If a named indicator is used for this purpose, the recommended name is “Compose”. Note that some implementations may use an unnamed, custom hardware LED for @@ -301,18 +301,18 @@ this purpose. The BeepOnComposeFail - control allows a client to specify whether or not a bell should be activated +control allows a client to specify whether or not a bell should be activated to provide feedback when a compose sequence fails. The control does not specify the type of bell that should be used; the mapping for this is up to the individual implementation. If the BeepOnComposeFail - control is enabled, it specifies that a bell should be activated when a +control is enabled, it specifies that a bell should be activated when a compose sequence fails. The BeepOnComposeFail - control is disabled by default. If implemented, the bell should be activated +control is disabled by default. If implemented, the bell should be activated using XkbBell - or +or XkbDeviceBell. @@ -320,7 +320,7 @@ using While the Xkb extension does not specify the type of bell to be used when the BeepOnComposeFail - control is implemented, a consistent convention between implementations is to +control is implemented, a consistent convention between implementations is to everyone’s benefit. If a named bell is used for this purpose, the recommended name is “ComposeFail”. @@ -342,15 +342,15 @@ name is “ComposeFail”. When Xkb is initialized, it implicitly forces requests for NewKeyboardNotify - events. These events may be used by the Xkb library extension internally; they +events. These events may be used by the Xkb library extension internally; they are normally translated into core protocol MappingNotify - events before being passed to the client. While delivering the event to the +events before being passed to the client. While delivering the event to the client is appropriate in most cases, it is not appropriate for some clients that maintain per-key data structures. This is because once the server has sent a NewKeyboardNotify - event, it is free to send the client events for all keys in the new range and +event, it is free to send the client events for all keys in the new range and that range may be outside of the per-key data structures the client is maintaining. @@ -359,11 +359,11 @@ maintaining. The IgnoreNewKeyboards - control, if enabled, prevents Xkb from mapping +control, if enabled, prevents Xkb from mapping NewKeyboardNotify - events to core +events to core MappingNotify - events and passing them to the client. The control is initially disabled. +events and passing them to the client. The control is initially disabled. @@ -461,7 +461,7 @@ implemented, use XkbXlibControlsImplemented. XkbXlibControlsImplemented - returns a bitmask indicating the controls actually implemented in the Xkb +returns a bitmask indicating the controls actually implemented in the Xkb library and is composed of an inclusive OR of bits from Table 11.1. @@ -502,7 +502,7 @@ To determine the current state of the Library Controls, use XkbGetXlibControls - returns the current state of the Library Controls as a bit mask that is an +returns the current state of the Library Controls as a bit mask that is an inclusive OR of the control masks from Table 11.1 for the controls that are enabled. For the optional compose processing controls, the fact that a control @@ -566,20 +566,20 @@ To change the state of the Library Controls, use XkbSetXlibControls - modifies the state of the controls selected by +modifies the state of the controls selected by bits_to_change; - only the controls selected by +only the controls selected by bits_to_change - are modified. If the bit corresponding to a control is on in +are modified. If the bit corresponding to a control is on in bits_to_change - and also on in values_for_bits, the control is enabled. If the bit +and also on in values_for_bits, the control is enabled. If the bit corresponding to a control is on in bits_to_change - but off in +but off in values_for_bits, the control is disabled. bits_to_change - should be an inclusive OR of bits from +should be an inclusive OR of bits from Table 11.1. diff --git a/specs/XKB/ch12.xml b/specs/XKB/ch12.xml index 9086fe78..fcfa8f9f 100644 --- a/specs/XKB/ch12.xml +++ b/specs/XKB/ch12.xml @@ -16,10 +16,10 @@ several core X library functions. When support for Xkb is built into the X library, the XOpenDisplay - function looks for a compatible version of Xkb on the server. If it finds a +function looks for a compatible version of Xkb on the server. If it finds a compatible version, it initializes the extension and enables implicit support - for Xkb in a number of X library functions. This makes it possible for clients +for Xkb in a number of X library functions. This makes it possible for clients to take advantage of nearly all Xkb features without having to be rewritten or even recompiled, if they are built with shared libraries. This implicit support is invisible to most clients, but it can have side effects, so the extension @@ -33,7 +33,7 @@ includes ways to control or disable it. Because XOpenDisplay - initializes Xkb, some events contain an Xkb description of the keyboard state +initializes Xkb, some events contain an Xkb description of the keyboard state instead of that normally used by the core protocol. See section 17.1.1 for more information about the differences between Xkb keyboard state and that reported by the core protocol. @@ -51,46 +51,46 @@ by the core protocol. When Xkb is missing or disabled, the X library tracks changes to the keyboard mapping using MappingNotify - events. Whenever the keyboard mapping is changed, the server sends all clients +events. Whenever the keyboard mapping is changed, the server sends all clients a MappingNotify - event to report the change. When a client receives a +event to report the change. When a client receives a MappingNotify - event, it is supposed to call +event, it is supposed to call XRefreshKeyboardMapping - to update the keyboard description used internally by the X library. +to update the keyboard description used internally by the X library. The X Keyboard Extension uses XkbMapNotify - and +and XkbNewKeyboardNotify - events to track changes to the keyboard mapping. When an Xkb-aware client +events to track changes to the keyboard mapping. When an Xkb-aware client receives either event, it should call XkbRefreshKeyboardMapping - to update the keyboard description used internally by the X library. To avoid +to update the keyboard description used internally by the X library. To avoid duplicate events, the X server does not send core protocol MappingNotify - events to a client that has selected for +events to a client that has selected for XkbMapNotify - events. +events. The implicit support for Xkb selects for XkbMapNotify - events. This means that clients that do not explicitly use Xkb but that are +events. This means that clients that do not explicitly use Xkb but that are using a version of the X library that has implicit support for Xkb do not receive MappingNotify - events over the wire. Clients that were not written with Xkb in mind do not +events over the wire. Clients that were not written with Xkb in mind do not recognize or properly handle the new Xkb events, so the implicit support converts them to MappingNotify - events that report approximately the same information, unless the client has +events that report approximately the same information, unless the client has explicitly selected for the Xkb version of the event. @@ -100,18 +100,18 @@ An Xkb-capable X server does not send events from keys that fall outside the legal range of keycodes expected by that client. Once the server sends a client an XkbNewKeyboardNotify - event, it reports events from all keys because it assumes that any client that +event, it reports events from all keys because it assumes that any client that has received an XkbNewKeyboardNotify - event expects key events from the new range of keycodes. The implicit support +event expects key events from the new range of keycodes. The implicit support for Xkb asks for XkbNewKeyboardNotify - events, so the range of keycodes reported to the client might vary without the +events, so the range of keycodes reported to the client might vary without the client’s knowledge. Most clients don’t really care about the range of legal keycodes, but some clients maintain information about each key and might have problems with events that come from unexpected keys. Such clients can set the XkbLC_IgnoreNewKeyboards - library control (see section 11.3.1) to prevent the implicit support from +library control (see section 11.3.1) to prevent the implicit support from requesting notification of changes to the legal range of keycodes. @@ -147,11 +147,11 @@ clients. The XKeycodeToKeysym XKeycodeToKeysym - function reports the keysym associated with a particular index for a single +function reports the keysym associated with a particular index for a single key. The index specifies a column of symbols in the core keyboard mapping (that is, as reported by the core protocol GetKeyboardMapping - request). The order of the symbols in the core mapping does not necessarily +request). The order of the symbols in the core mapping does not necessarily correspond to the order of the symbols used by Xkb; section 17.1.3 describes the differences. @@ -161,7 +161,7 @@ the differences. The XKeysymToKeycode XKeysymToKeycode - function reports a keycode to which a particular keysym is bound. When Xkb is +function reports a keycode to which a particular keysym is bound. When Xkb is missing or disabled, this function looks in each column of the core keyboard mapping in turn and returns the lowest numbered key that matches in the lowest numbered group. When Xkb is present, this function uses the Xkb ordering for @@ -173,7 +173,7 @@ symbols instead. The XLookupKeysym XLookupKeysym - function reports the symbol in a specific column of the key associated with an +function reports the symbol in a specific column of the key associated with an event. Whether or not Xkb is present, the column specifies an index into the core symbol mapping. @@ -183,20 +183,20 @@ core symbol mapping. The XLookupString XLookupString - function reports the symbol and string associated with a key event, taking +function reports the symbol and string associated with a key event, taking into account the keycode and keyboard state as reported in the event. When Xkb is disabled or missing, XLookupString - uses the rules specified by the core protocol and reports only ISO Latin-1 +uses the rules specified by the core protocol and reports only ISO Latin-1 characters. When Xkb is present, XLookupString - uses the explicit keyboard group, key types, and rules specified by Xkb. When +uses the explicit keyboard group, key types, and rules specified by Xkb. When Xkb is present, XLookupString - is allowed, but not required, to return strings in character sets other than +is allowed, but not required, to return strings in character sets other than ISO Latin-1, depending on the current locale. If any key bindings are defined, XLookupString - does not use any consumed modifiers (see section 11.1.2 and section 15.2) to +does not use any consumed modifiers (see section 11.1.2 and section 15.2) to determine matching bindings. @@ -205,17 +205,17 @@ determine matching bindings. The XRefreshKeyboardMapping XRefreshKeyboardMapping - function updates the X library’s internal representation of the keyboard to +function updates the X library’s internal representation of the keyboard to reflect changes reported via MappingNotify - events. When Xkb is missing or disabled, this function reloads the entire +events. When Xkb is missing or disabled, this function reloads the entire modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support keeps track of the changed components reported by each XkbMapNotify - event and updates only those pieces of the keyboard description that have +event and updates only those pieces of the keyboard description that have changed. If the implicit support has not noted any keyboard mapping changes, XRefreshKeyboardMapping - updates the entire keyboard description. +updates the entire keyboard description. @@ -223,13 +223,13 @@ changed. If the implicit support has not noted any keyboard mapping changes, The XRebindKeysym XRebindKeysym - function associates a string with a keysym and a set of modifiers. Xkb does +function associates a string with a keysym and a set of modifiers. Xkb does not directly change this function, but it does affect the way that the state reported in the event is compared to the state specified to XRebindKeysym. When Xkb is missing or disabled, XLookupString - returns the specified string if the modifiers in the event exactly match the +returns the specified string if the modifiers in the event exactly match the modifiers from this call. When Xkb is present, any modifiers used to determine the keysym are consumed and are not used to look up the string. @@ -304,16 +304,16 @@ level, use XkbKeycodeToKeysym. XkbKeycodeToKeysym - returns the keysym bound to a particular group and shift level for a +returns the keysym bound to a particular group and shift level for a particular key on the core keyboard. If kc - is not a legal keycode for the core keyboard, or if +is not a legal keycode for the core keyboard, or if group - or +or level - are out of range for the specified key, +are out of range for the specified key, XkbKeycodeToKeysym - returns +returns NoSymbol. @@ -363,14 +363,14 @@ use XkbKeysymToModifiers - finds the set of modifiers currently bound to the keysym +finds the set of modifiers currently bound to the keysym ks - on the core keyboard. The value returned is the mask of modifiers bound to the +on the core keyboard. The value returned is the mask of modifiers bound to the keysym ks. If no modifiers are bound to the keysym, XkbKeysymToModifiers - returns zero; otherwise, it returns the inclusive OR of zero or more of the +returns zero; otherwise, it returns the inclusive OR of zero or more of the following: ShiftMask, ControlMask, @@ -379,7 +379,7 @@ following: Mod2Mask, Mod3Mask, Mod4Mask, - and +and Mod5Mask. @@ -387,7 +387,7 @@ following: Use XkbLookupKeySym - to find the symbol associated with a key for a particular state. +to find the symbol associated with a key for a particular state. @@ -465,40 +465,40 @@ Use XkbLookupKeySym - is the equivalent of the core +is the equivalent of the core XLookupKeySym - function. For the core keyboard, given a keycode +function. For the core keyboard, given a keycode key - and an Xkb state +and an Xkb state state, XkbLookupKeySym - returns the symbol associated with the key in +returns the symbol associated with the key in sym_rtrn - and the list of modifiers that should still be applied in +and the list of modifiers that should still be applied in mods_rtrn. The state - parameter is the state from a +parameter is the state from a KeyPress - or +or KeyRelease - event. +event. XkbLookupKeySym - returns +returns True - if it succeeds. +if it succeeds. Use XkbLookupKeyBinding - to find the string bound to a key by +to find the string bound to a key by XRebindKeysym. XkbLookupKeyBinding - is the equivalent of the core +is the equivalent of the core XLookupString - function. +function. @@ -588,24 +588,24 @@ Use XRebindKeysym - binds an ASCII string to a specified keysym, so that the string and keysym are +binds an ASCII string to a specified keysym, so that the string and keysym are returned when the key is pressed and a specified list of modifiers are also being held down. XkbLookupKeyBinding - returns in +returns in buf - the string associated with the keysym +the string associated with the keysym sym - and modifier state +and modifier state state. buf - is +is NULL - terminated unless there’s an overflow. If the string returned is larger than +terminated unless there’s an overflow. If the string returned is larger than nbytes, a count of bytes that does not fit into the buffer is returned in extra_rtrn. XkbTranslateKeySym - returns the number of bytes that it placed into +returns the number of bytes that it placed into buf. @@ -703,22 +703,22 @@ state, use XkbTranslateKeySym - applies the transformations specified in +applies the transformations specified in mods - to the symbol specified by +to the symbol specified by sym_inout. It returns in buf - the string, if any, associated with the keysym for the current locale. If the +the string, if any, associated with the keysym for the current locale. If the transformations in mods - changes the keysym, +changes the keysym, sym_inout - is updated accordingly. If the string returned is larger than +is updated accordingly. If the string returned is larger than nbytes, a count of bytes that does not fit into the buffer is returned in extra_rtrn. XkbTranslateKeySym - returns the number of bytes it placed into +returns the number of bytes it placed into buf. @@ -754,27 +754,27 @@ To update the keyboard description that is internal to the X library, use XkbRefreshKeyboardMapping - is the Xkb equivalent of the core +is the Xkb equivalent of the core XRefreshKeyboardMapping - function. It requests that the X server send the current key mapping +function. It requests that the X server send the current key mapping information to this client. A client usually invokes XkbRefreshKeyboardMapping - after receiving an +after receiving an XkbMapNotify - event. +event. XkbRefreshKeyboardMapping - returns +returns Success - if it succeeds and +if it succeeds and BadMatch - if the event is not an Xkb event. +if the event is not an Xkb event. The XkbMapNotify - event can be generated when some client calls +event can be generated when some client calls XkbSetMap, XkbChangeMap, XkbGetKeyboardByName, @@ -858,9 +858,9 @@ To translate a keycode to a key symbol and modifiers, use mods_rtrn - is backfilled with the modifiers consumed by the translation process. +is backfilled with the modifiers consumed by the translation process. mods - is a bitwise inclusive OR of the legal modifier masks: +is a bitwise inclusive OR of the legal modifier masks: ShiftMask, LockMask, ControlMask, @@ -871,15 +871,15 @@ To translate a keycode to a key symbol and modifiers, use Mod5Mask. The AlwaysConsumeShiftAndLock - library control (see section 11.1.3), if enabled, causes +library control (see section 11.1.3), if enabled, causes XkbTranslateKeyCode - to consume shift and lock. +to consume shift and lock. XkbTranslateKeyCode - returns +returns True - if the translation resulted in a keysym, and +if the translation resulted in a keysym, and False - if it resulted in +if it resulted in NoSymbol. diff --git a/specs/XKB/ch13.xml b/specs/XKB/ch13.xml index aaa29408..654f9dfe 100644 --- a/specs/XKB/ch13.xml +++ b/specs/XKB/ch13.xml @@ -59,7 +59,7 @@ Objects should be drawn in order from highest priority (0) to lowest (255). XkbGeometryRec The keyboard geometry’s top-level description is stored in a XkbGeometryRec - structure. This structure contains three types of information: +structure. This structure contains three types of information: @@ -99,11 +99,11 @@ as follows: The top-level keyboard geometry description includes a list of up to XkbGeomMaxColors - (32) +(32) color names. A color name is a string whose interpretation is not specified by Xkb. The XkbColorRec - structure provides a field for this name as well as a pixel field. The pixel +structure provides a field for this name as well as a pixel field. The pixel field is a convenient place for an application to store a pixel value or color definition, if it needs to. All other geometry data structures refer to colors using their indices in this global list. @@ -135,7 +135,7 @@ a top label. The top-level keyboard geometry description includes a list of key aliases - (see ). Key aliases allow the keyboard layout designer to assign +(see ). Key aliases allow the keyboard layout designer to assign multiple key names to a single key. Key aliases defined in the geometry component of a keyboard mapping @@ -144,14 +144,14 @@ are stored in the XkbNamesRec (xkb->names). - Therefore, consider the key aliases defined by the geometry before +Therefore, consider the key aliases defined by the geometry before considering key aliases supplied by the keycodes. The top-level keyboard geometry description includes a list of shapes; - other keyboard components refer to shapes by their index in this list. A +other keyboard components refer to shapes by their index in this list. A shape consists of an arbitrary name of type Atom and one or more closed-polygon outlines. All points in an outline are specified relative to the origin of its @@ -159,13 +159,13 @@ enclosing shape, that is, whichever shape that contains this outline in its list of outlines. One outline is the primary outline. The primary outline is by default the first outline, or it can be optionally specified by the primary - field in the +field in the XkbShapeRec - structure. A keyboard display application can generate a simpler but still +structure. A keyboard display application can generate a simpler but still accurate keyboard image by displaying only the primary outlines for each shape. Nonrectangular keys must include a rectangular approximation - as one of the outlines associated with the shape. The approximation is not +as one of the outlines associated with the shape. The approximation is not normally displayed but can be used by very simple keyboard display applications to generate a recognizable but degraded image of the keyboard. @@ -175,7 +175,7 @@ to generate a recognizable but degraded image of the keyboard. The XkbGeometryRec - top-level geometry description contains the following information that +top-level geometry description contains the following information that pertains to the keyboard as a whole: @@ -184,16 +184,16 @@ pertains to the keyboard as a whole: A keyboard symbolic name - of type Atom to help users identify the keyboard. +of type Atom to help users identify the keyboard. The width - and +and height - of the keyboard, in mm/10. For nonrectangular keyboards, the width and height +of the keyboard, in mm/10. For nonrectangular keyboards, the width and height describe the smallest bounding box that encloses the outline of the keyboard. @@ -201,7 +201,7 @@ describe the smallest bounding box that encloses the outline of the keyboard. The base color - of the keyboard is the predominant color on the keyboard and is used as the +of the keyboard is the predominant color on the keyboard and is used as the default color for any components whose color is not explicitly specified. @@ -209,14 +209,14 @@ default color for any components whose color is not explicitly specified. The label color - is the color used to draw the labels on most of the keyboard keys. +is the color used to draw the labels on most of the keyboard keys. The label font - is a string that describes the font used to draw labels on most keys; label +is a string that describes the font used to draw labels on most keys; label fonts are arbitrary strings, because Xkb does not specify the format or name space for font names. @@ -226,14 +226,14 @@ space for font names. The keyboard is subdivided into named sections - of related keys and doodads. The sections and doodads on the keyboard are +of related keys and doodads. The sections and doodads on the keyboard are listed in the XkbGeometryRec - top-level keyboard geometry description. A section is composed of keys that +top-level keyboard geometry description. A section is composed of keys that are physically together and logically related. Figure 13.2 shows a keyboard that is divided into four sections. A doodad - describes some visible aspect of the keyboard that is not a key and is not a +describes some visible aspect of the keyboard that is not a key and is not a section. @@ -258,7 +258,7 @@ A shape, used to draw keyboard components and stored in a XkbShapeRec - structure, has: +structure, has: @@ -294,7 +294,7 @@ An outline, stored in a XkbOutlineRec - structure, is a list of one or more points that describes a single +structure, is a list of one or more points that describes a single closed-polygon, as follows: @@ -323,7 +323,7 @@ with the first. A nonzero value for the corner_radius - field specifies that the corners of the polygon should be drawn as circles +field specifies that the corners of the polygon should be drawn as circles with the specified radius. @@ -341,13 +341,13 @@ a simple but still accurate keyboard image by displaying only the primary outlines for each shape. The default primary outline is the first in a shape’s list of outlines. If the primary - field of the +field of the XkbShapeRec - structure is not +structure is not NULL, it points to the primary outline. A rectangular approximation - must be included for nonrectangular keys as one of the outlines associated +must be included for nonrectangular keys as one of the outlines associated with the shape; the approximation is not normally displayed but can be used by very simple keyboard display applications to generate a recognizable but degraded image of the keyboard. @@ -360,7 +360,7 @@ degraded image of the keyboard. As previously noted, a keyboard is subdivided into sections - of related keys. Each section has its own coordinate system — if a section +of related keys. Each section has its own coordinate system — if a section is rotated, the coordinates of any components within the section are interpreted relative to the edges that were on the top and left before rotation. The components that make up a section, stored in a @@ -423,7 +423,7 @@ Rows in a Section An optional list of doodads; - any type of doodad can be enclosed within a section. Position and angle of +any type of doodad can be enclosed within a section. Position and angle of rotation are relative to the origin and angle of rotation of the sections that contain them. Priority for doodads in a section is relative to the other components of the section, not to the keyboard as a whole. @@ -433,7 +433,7 @@ components of the section, not to the keyboard as a whole. An optional overlay - with a name of type Atom and a list of overlay rows (described below). +with a name of type Atom and a list of overlay rows (described below). @@ -450,7 +450,7 @@ containing the entire section. A row description (XkbRowRec) - consists of the coordinates of its origin relative to its enclosing section, +consists of the coordinates of its origin relative to its enclosing section, a flag indicating whether the row is horizontal or vertical, and a list of keys in the row. @@ -459,12 +459,12 @@ in the row. A key description (XkbKeyRec) - consists of a key name, a shape, a key color, and a gap. The key name should +consists of a key name, a shape, a key color, and a gap. The key name should correspond to one of the keys named in the keyboard names description, the shape specifies the appearance of the key, and the key color specifies the color of the key (not the label on the key; the label color is stored in the XkbGeometryRec). - Keys are normally drawn immediately adjacent to one another from left to +Keys are normally drawn immediately adjacent to one another from left to right (or top to bottom) within a row. The gap field specifies the distance between a key and its predecessor. @@ -485,7 +485,7 @@ outline of the entire keyboard. Each doodad’s origin is stored in fields named left - and +and top, which are the coordinates of the doodad’s origin relative to its enclosing object, whether it be a section or the top-level keyboard. The priority for @@ -495,7 +495,7 @@ top-level geometry. The priority for doodads listed in a section are relative to the other components of the section. Each doodad is stored in a structure with a type - field, which specifies the type of doodad. +field, which specifies the type of doodad. @@ -507,10 +507,10 @@ Xkb supports five types of doodads: An indicator doodad - describes one of the physical keyboard indicators. Indicator doodads specify +describes one of the physical keyboard indicators. Indicator doodads specify the shape of the indicator, the indicator color when it is lit (on_color) - and the indicator color when it is dark +and the indicator color when it is dark (off_color). @@ -519,7 +519,7 @@ the shape of the indicator, the indicator color when it is lit An outline doodad - describes some aspect of the keyboard to be drawn as one or more hollow, +describes some aspect of the keyboard to be drawn as one or more hollow, closed polygons. Outline doodads specify the shape, color, and angle of rotation about the doodad origin at which they should be drawn. @@ -528,7 +528,7 @@ rotation about the doodad origin at which they should be drawn. A solid doodad - describes some aspect of the keyboard to be drawn as one or more filled +describes some aspect of the keyboard to be drawn as one or more filled polygons. Solid doodads specify the shape, color, and angle of rotation about the doodad origin at which they should be drawn. @@ -537,7 +537,7 @@ the doodad origin at which they should be drawn. A text doodad - describes a text label somewhere on the keyboard. Text doodads specify the +describes a text label somewhere on the keyboard. Text doodads specify the label string, the font and color to use when drawing the label, and the angle of rotation of the doodad about its origin. @@ -561,7 +561,7 @@ specify the interpretation of logo names. The structures these doodads are stored in and the values of the type - fields are shown in Table 13.1. +fields are shown in Table 13.1.
@@ -647,7 +647,7 @@ An overlay row (XkbOverlayRowRec) - contains a pointer to the row it overlays and a list of +contains a pointer to the row it overlays and a list of overlay keys. @@ -655,7 +655,7 @@ An Each overlay key definition (XkbOverlayKeyRec) - indicates a key that can yield multiple keycodes and consists of a field +indicates a key that can yield multiple keycodes and consists of a field named under, which specifies the primary name of the key and a field named @@ -663,7 +663,7 @@ which specifies the primary name of the key and a field named which specifies the name for the key when the overlay keycode is selected. The key specified in under - must be a member of the section that contains the overlay key definition, +must be a member of the section that contains the overlay key definition, while the key specified in over must not be. @@ -784,13 +784,13 @@ typedef struct _XkbGeometry { /* top-level keyboard geometry structure */ The doodads - array is only for doodads not contained in any of the +array is only for doodads not contained in any of the sections - that has its own +that has its own doodads. The key aliases contained in the key_aliases - array take precedence over any defined in the keycodes component of the +array take precedence over any defined in the keycodes component of the keyboard description. @@ -858,9 +858,9 @@ typedef struct _XkbShape { If approx - and/or +and/or primary - is +is NULL, the default value is used. The default primary outline is the first element in the outlines array, as is the default approximating outline. @@ -892,9 +892,9 @@ typedef struct _XkbRow { /* row in a section */ top - and +and left - are in +are in mm / 10. @@ -923,12 +923,12 @@ typedef struct _XkbOverlayRow { row_under - is an index into the array of +is an index into the array of rows - in the section under this overlay. The section under this overlay row is the +in the section under this overlay. The section under this overlay row is the one pointed to by section_under - in this overlay row’s +in this overlay row’s XkbOverlayRec. @@ -965,18 +965,18 @@ typedef struct _XkbSection { top - and +and left - are the origin of the section, relative to the origin of the keyboard, in +are the origin of the section, relative to the origin of the keyboard, in mm / 10. angle - is in +is in 1 / 10 - degrees. +degrees. @@ -985,9 +985,9 @@ typedef struct _XkbSection { The doodad arrays in the XkbGeometryRec - and the +and the XkbSectionRec - may contain any of the doodad structures and types shown in +may contain any of the doodad structures and types shown in Table 13.1. @@ -1009,26 +1009,26 @@ typedef union _XkbDoodad { The top - and +and left - coordinates of each doodad are the coordinates of the origin of the doodad +coordinates of each doodad are the coordinates of the origin of the doodad relative to the keyboard’s origin if the doodad is in the XkbGeometryRec - doodad array, and with respect to the section’s origin if the doodad is in a +doodad array, and with respect to the section’s origin if the doodad is in a XkbSectionRec - doodad array. The +doodad array. The color_ndx - or +or on_color_ndx - and +and off_color_ndx - fields are color indices into the +fields are color indices into the XkbGeometryRec’s - color array and are the colors to draw the doodads with. Similarly, the +color array and are the colors to draw the doodads with. Similarly, the shape_ndx - fields are indices into the +fields are indices into the XkbGeometryRec’s - shape array. +shape array. @@ -1155,16 +1155,16 @@ To load a keyboard geometry if you already have the keyboard description, use XkbGetGeometry - can return +can return BadValue, BadImplementation, BadName, BadAlloc, - or +or BadLength - errors or +errors or Success - if it succeeds. +if it succeeds. @@ -1224,11 +1224,11 @@ description from this database by name, use XkbGetNamedGeometry - can return +can return BadName - if the +if the name - cannot be found. +cannot be found. @@ -1304,31 +1304,31 @@ To determine the bounding box of the top surface of a shape, use XkbComputeShapeTop - returns a +returns a BoundsRec - that contains two x and y coordinates. These coordinates describe the corners +that contains two x and y coordinates. These coordinates describe the corners of a rectangle that contains the outline that describes the top surface of the shape. The top surface is defined to be the approximating outline if the approx - field of +field of shape - is not +is not NULL. If approx - is +is NULL, the top surface is defined as the last outline in the shape’s - array of outlines. +array of outlines. XkbComputeShapeTop - returns +returns False - if +if shape - is +is NULL - or if there are no outlines for the shape; otherwise, it returns +or if there are no outlines for the shape; otherwise, it returns True. @@ -1336,9 +1336,9 @@ the top surface is defined as the last outline in the A ShapeRec - contains a +contains a BoundsRec - that describes the bounds of the shape. If you add or delete an outline to or +that describes the bounds of the shape. If you add or delete an outline to or from a shape, the bounding box must be updated. To update the bounding box of a shape, use XkbComputeShapeBounds. @@ -1370,27 +1370,27 @@ shape, use XkbComputeShapeBounds. XkbComputeShapeBounds - updates the +updates the BoundsRec - contained in the +contained in the shape - by examining all the outlines of the shape and setting the +by examining all the outlines of the shape and setting the BoundsRec - to the minimum x and minimum y, and maximum x and maximum y values found in +to the minimum x and minimum y, and maximum x and maximum y values found in those outlines. XkbComputeShapeBounds - returns +returns False - if +if shape - is +is NULL - or if there are no outlines for the shape; otherwise, it returns +or if there are no outlines for the shape; otherwise, it returns True. - If you add or delete a key to or from a row, or if you update the shape of one +If you add or delete a key to or from a row, or if you update the shape of one of the keys in that row, you may need to update the bounding box of that row. To update the bounding box of a row, use XkbComputeRowBounds. @@ -1445,20 +1445,20 @@ To update the bounding box of a row, use XkbComputeRowBounds XkbComputeRowBounds - checks the bounds of all keys in the +checks the bounds of all keys in the row and updates the bounding box of the row if necessary. XkbComputeRowBounds - returns +returns False - if any of the arguments is +if any of the arguments is NULL; - otherwise, it returns +otherwise, it returns True. - If you add or delete a row to or from a section, or if you change the geometry +If you add or delete a row to or from a section, or if you change the geometry of any of the rows in that section, you may need to update the bounding box for that section. To update the bounding box of a section, use XkbComputeSectionBounds. @@ -1502,15 +1502,15 @@ that section. To update the bounding box of a section, use XkbComputeSectionBounds - examines all the rows of the +examines all the rows of the section - and updates the bounding box of that section so that it contains all rows. +and updates the bounding box of that section so that it contains all rows. XkbComputeSectionBounds - returns +returns False - if any of the arguments is +if any of the arguments is NULL; - otherwise, it returns +otherwise, it returns True. @@ -1571,7 +1571,7 @@ by using the primary name for a key that is part of an overlay, use XkbFindOverlayForKey - uses the primary name of the key, +uses the primary name of the key, under, to look up the alternate name, which it returns. @@ -1585,10 +1585,10 @@ to look up the alternate name, which it returns. Xkb provides functions to add a single new element to the top-level keyboard geometry. In each case the num_* - fields of the corresponding structure is incremented by 1. These functions do +fields of the corresponding structure is incremented by 1. These functions do not change sz_* - unless there is no more room in the array. Some of these functions fill in the +unless there is no more room in the array. Some of these functions fill in the values of the element’s structure from the arguments. For other functions, you must explicitly write code to fill the structure’s elements. @@ -1659,15 +1659,15 @@ To add one property to an existing keyboard geometry description, use XkbAddGeomProperty - adds one property with the specified +adds one property with the specified name - and +and value - to the keyboard geometry specified by geom. +to the keyboard geometry specified by geom. XkbAddGeomProperty - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the property. To allocate space for an arbitrary number of properties, use the XkbAllocGeomProps function. @@ -1728,12 +1728,12 @@ To add one key alias to an existing keyboard geometry description, use XkbAddGeomKeyAlias - adds one key alias with the value alias to the geometry geom, and associates +adds one key alias with the value alias to the geometry geom, and associates it with the key whose real name is real. XkbAddGeomKeyAlias - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the alias. To allocate space for an arbitrary number of aliases, use the XkbAllocGeomKeyAliases function. @@ -1795,30 +1795,30 @@ To add one color name to an existing keyboard geometry description, use XkbAddGeomColor - adds the specified color +adds the specified color name - and +and pixel - to the specified geometry +to the specified geometry geom. The top-level geometry description includes a list of up to MaxColors - (32) +(32) color names. A color name - is a string whose interpretation is not specified by Xkb and neither is the +is a string whose interpretation is not specified by Xkb and neither is the pixel - value’s interpretation. All other geometry data structures refer to colors +value’s interpretation. All other geometry data structures refer to colors using their indices in this global list or pointers to colors in this list. XkbAddGeomColor - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the color. To allocate space for an arbitrary number of colors to a geometry, use the XkbAllocGeomColors - function. +function. @@ -1865,15 +1865,15 @@ To add one outline to an existing shape, use An outline consists of an arbitrary number of points. XkbAddGeomOutline - adds an outline to the specified +adds an outline to the specified shape - by reserving +by reserving sz_points - points for it. The new outline is allocated and zeroed. +points for it. The new outline is allocated and zeroed. XkbAddGeomOutline - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space. To +if any of the parameters is empty or if it was not able to allocate space. To allocate space for an arbitrary number of outlines to a shape, use XkbAllocGeomOutlines. @@ -1937,17 +1937,17 @@ To add a shape to a keyboard geometry, use A geometry contains an arbitrary number of shapes, each of which is made up of an arbitrary number of outlines. XkbAddGeomShape - adds a shape to a geometry +adds a shape to a geometry geom - by allocating space for +by allocating space for sz_outlines - outlines for it and giving it the name specified by name. If a shape with name +outlines for it and giving it the name specified by name. If a shape with name name - already exists in the geometry, a pointer to the existing shape is returned. +already exists in the geometry, a pointer to the existing shape is returned. XkbAddGeomShape - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space. To +if any of the parameters is empty or if it was not able to allocate space. To allocate space for an arbitrary number of geometry shapes, use XkbAllocGeomShapes. @@ -1986,15 +1986,15 @@ To add one key at the end of an existing row of keys, use Keys are grouped into rows. XkbAddGeomKey - adds one key to the end of the specified +adds one key to the end of the specified row. The key is allocated and zeroed. XkbAddGeomKey - returns +returns NULL - if +if row - is empty or if it was not able to allocate space for the key. To allocate +is empty or if it was not able to allocate space for the key. To allocate space for an arbitrary number of keys to a row, use XkbAllocGeomKeys. @@ -2080,7 +2080,7 @@ To add one section to an existing keyboard geometry, use A keyboard geometry contains an arbitrary number of sections. XkbAddGeomSection - adds one section to an existing keyboard geometry +adds one section to an existing keyboard geometry geom. The new section contains space for the number of rows, doodads, and overlays specified by @@ -2092,12 +2092,12 @@ The new section is allocated and zeroed and given the name specified by name. If a section with name name - already exists in the geometry, a pointer to the existing section is +already exists in the geometry, a pointer to the existing section is returned. XkbAddGeomSection - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the section. To allocate space for an arbitrary number of sections to a geometry, use XkbAllocGeomSections. @@ -2149,15 +2149,15 @@ To add a row to a section, use One of the components of a keyboard geometry section is one or more rows of keys. XkbAddGeomRow - adds one row to the specified +adds one row to the specified section. The newly created row contains space for the number of keys specified in sz_keys. They are allocated and zeroed, but otherwise uninitialized. XkbAddGeomRow - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the row. To allocate space for an arbitrary number of rows to a section, use the XkbAllocGeomRows function. @@ -2221,32 +2221,32 @@ geometry, use A doodad - describes some visible aspect of the keyboard that is not a key and is not a +describes some visible aspect of the keyboard that is not a key and is not a section. XkbAddGeomDoodad - adds a doodad with name specified by name to the geometry +adds a doodad with name specified by name to the geometry geom - if section is +if section is NULL - or to the section of the geometry specified by section if +or to the section of the geometry specified by section if section - is not +is not NULL. XkbAddGeomDoodad - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the doodad. If there is already a doodad with the name name - in the doodad array for the geometry (if +in the doodad array for the geometry (if section - is +is NULL) - or the section (if +or the section (if section - is non- +is non- NULL), - a pointer to that doodad is returned. To allocate space for an arbitrary +a pointer to that doodad is returned. To allocate space for an arbitrary number of doodads to a section, use the XkbAllocGeomSectionDoodads function. To allocate space for an arbitrary number of doodads to a keyboard geometry, use the XkbAllocGeomDoodads function. @@ -2309,17 +2309,17 @@ To add one overlay to a section, use XkbAddGeomOverlay - adds an overlay with the specified name to the specified +adds an overlay with the specified name to the specified section. The new overlay is created with space allocated for sz_rows rows. If an overlay with name name - already exists in the section, a pointer to the existing overlay is +already exists in the section, a pointer to the existing overlay is returned. XkbAddGeomOverlay - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the overlay. To allocate space for an arbitrary number of overlays to a section, use the XkbAllocGeomOverlay function. @@ -2381,21 +2381,21 @@ To add a row to an existing overlay, use XkbAddGeomOverlayRow - adds one row to the +adds one row to the overlay. The new row contains space for sz_keys - keys. If +keys. If row_under - specifies a row that doesn’t exist on the underlying section, +specifies a row that doesn’t exist on the underlying section, XkbAddGeomOverlayRow - returns +returns NULL - and doesn’t change the overlay. +and doesn’t change the overlay. XkbAddGeomOverlayRow - returns +returns NULL - if any of the parameters is empty or if it was not able to allocate space for +if any of the parameters is empty or if it was not able to allocate space for the overlay. @@ -2455,15 +2455,15 @@ To add a key to an existing overlay row, use XkbAddGeomOverlayKey - adds one key to the +adds one key to the row - in the +in the overlay. If there is no key named under - in the row of the underlying section, +in the row of the underlying section, XkbAddGeomOverlayKey - returns +returns NULL. @@ -2479,19 +2479,19 @@ Note that these functions merely allocate space for the new element(s), and it is up to you to fill in the values explicitly in your code. These allocation functions increase sz_* - but never touch +but never touch num_* - (unless there is an allocation failure, in which case they reset both +(unless there is an allocation failure, in which case they reset both sz_* - and +and num_* - to zero). These functions return +to zero). These functions return Success - if they succeed, +if they succeed, BadAlloc - if they are not able to allocate space, or +if they are not able to allocate space, or BadValue - if a parameter is not as expected. +if a parameter is not as expected. @@ -2538,9 +2538,9 @@ XkbAllocGeomOutlines. XkbAllocGeomOutlines - allocates space for +allocates space for num_needed - outlines in the specified +outlines in the specified shape. The outlines are not initialized. @@ -2664,7 +2664,7 @@ XkbAllocGeomKeys. XkbAllocGeomKeys - allocates num_needed keys and adds them to the row. No initialization of the +allocates num_needed keys and adds them to the row. No initialization of the keys is done. @@ -2787,7 +2787,7 @@ To allocate geometry properties, use XkbAllocGeomProps - allocates space for num_needed properties and adds them to the specified +allocates space for num_needed properties and adds them to the specified geometry geom. No initialization of the properties is done. A geometry property associates @@ -2916,7 +2916,7 @@ To allocate geometry key aliases, use XkbAllocGeomKeyAliases - allocates space for num_needed key aliases and adds them to the specified +allocates space for num_needed key aliases and adds them to the specified geometry geom. A key alias is a pair of strings that associates an alternate name for a key @@ -2995,10 +2995,10 @@ If free_all is True, all aliases in the top level of the specified geometry geom - are freed regardless of the value of first or count. Otherwise, count aliases +are freed regardless of the value of first or count. Otherwise, count aliases in geom - are freed beginning with the one specified by first. +are freed beginning with the one specified by first. @@ -3046,7 +3046,7 @@ To allocate geometry colors, use XkbAllocGeomColors - allocates space for num_needed colors and adds them to the specified geometry +allocates space for num_needed colors and adds them to the specified geometry geom. A color name is a string whose interpretation is not specified by Xkb. All other geometry data structures refer to colors using their indices in this @@ -3172,9 +3172,9 @@ To allocate points in an outline, use XkbAllocGeomPoints - allocates space for +allocates space for num_needed - points in the specified +points in the specified outline. The points are not initialized. @@ -3299,9 +3299,9 @@ To allocate space for an arbitrary number of geometry shapes, use XkbAllocGeomShapes - allocates space for +allocates space for num_needed - shapes in the specified geometry +shapes in the specified geometry geom. The shapes are not initialized. @@ -3426,7 +3426,7 @@ To allocate geometry sections, use XkbAllocGeomSections - allocates num_needed sections and adds them to the geometry geom. No +allocates num_needed sections and adds them to the geometry geom. No initialization of the sections is done. @@ -3550,7 +3550,7 @@ To allocate rows in a section, use XkbAllocGeomRows - allocates num_needed rows and adds them to the section. No initialization of +allocates num_needed rows and adds them to the section. No initialization of the rows is done. @@ -3674,7 +3674,7 @@ To allocate overlays in a section, use XkbAllocGeomRows - allocates num_needed overlays and adds them to the section. No initialization +allocates num_needed overlays and adds them to the section. No initialization of the overlays is done. @@ -3798,7 +3798,7 @@ To allocate rows in a overlay, use XkbAllocGeomOverlayRows - allocates num_needed rows and adds them to the overlay. No initialization of +allocates num_needed rows and adds them to the overlay. No initialization of the rows is done. @@ -3922,7 +3922,7 @@ To allocate keys in an overlay row, use XkbAllocGeomOverlayKeys - allocates num_needed keys and adds them to the row. No initialization of the +allocates num_needed keys and adds them to the row. No initialization of the keys is done. @@ -4046,7 +4046,7 @@ To allocate doodads that are global to a keyboard geometry, use XkbAllocGeomDoodads - allocates num_needed doodads and adds them to the specified geometry +allocates num_needed doodads and adds them to the specified geometry geom. No initialization of the doodads is done. @@ -4096,7 +4096,7 @@ To allocate doodads that are specific to a section, use XkbAllocGeomSectionDoodads - allocates num_needed doodads and adds them to the specified +allocates num_needed doodads and adds them to the specified section. No initialization of the doodads is done. @@ -4159,7 +4159,7 @@ To free geometry doodads, use If free_all - is +is True, all doodads in the array are freed, regardless of the value of count. Otherwise, count doodads are freed. @@ -4210,7 +4210,7 @@ To allocate an entire geometry, use XkbAllocGeometry - allocates a keyboard geometry and adds it to the keyboard description +allocates a keyboard geometry and adds it to the keyboard description specified by xkb. The keyboard description should be obtained via the XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the number of elements to be reserved for the subcomponents of the keyboard diff --git a/specs/XKB/ch14.xml b/specs/XKB/ch14.xml index a92ae225..cb30105c 100644 --- a/specs/XKB/ch14.xml +++ b/specs/XKB/ch14.xml @@ -52,9 +52,9 @@ For detailed information on particular components of the keyboard map, refer to The graphic characters or control functions that may be accessed by one key are logically arranged in groups and levels, where group - and +and level - are defined as in the ISO9995 standard: +are defined as in the ISO9995 standard: @@ -96,12 +96,12 @@ Levels are numbered sequentially starting at one. Shift level is derived from the modifier state, but not necessarily in the same way for all keys. For example, the Shift - modifier selects shift level 2 on most keys, but for keypad keys the modifier +modifier selects shift level 2 on most keys, but for keypad keys the modifier bound to Num_Lock - (that is, the +(that is, the NumLock - virtual modifier) also selects shift level 2. +virtual modifier) also selects shift level 2. For example, consider the following key (the gray characters indicate symbols @@ -142,25 +142,25 @@ The standard interpretation rules for the core X keymap only allow clients to access keys such as the one shown in Figure 14.1. That is, clients using the standard interpretation rules can only access one of four keysyms for any given KeyPress - event — two different symbols in two different groups. +event — two different symbols in two different groups. In general, the Shift - modifier, the +modifier, the Lock - modifier, and the modifier bound to the +modifier, and the modifier bound to the Num_Lock - key are used to change between shift level 1 and shift level 2. To switch +key are used to change between shift level 1 and shift level 2. To switch between groups, the core implementation uses the modifier bound to the Mode_switch - key. When the +key. When the Mode_switch - modifier is set, the keyboard is logically in Group 2. When the +modifier is set, the keyboard is logically in Group 2. When the Mode_switch - modifier is not set, the keyboard is logically in Group 1. +modifier is not set, the keyboard is logically in Group 1. @@ -168,9 +168,9 @@ between groups, the core implementation uses the modifier bound to the The core implementation does not clearly specify the behavior of keys. For example, the locking behavior of the CapsLock - and +and Num_Lock - keys depends on the vendor. +keys depends on the vendor. @@ -209,7 +209,7 @@ type and specifies the modifier combinations necessary to access each level. For example, Xkb allows key types where the Control - modifier can be used to access the shift level two of a key. Key types are in +modifier can be used to access the shift level two of a key. Key types are in the client map component and are described in detail in section 15.2. @@ -232,35 +232,35 @@ server. The first function, XkbGetMap, allocates an XkbDescRec - structure, retrieves mapping components from the server, and stores them in +structure, retrieves mapping components from the server, and stores them in the XkbDescRec - structure it just allocated. The second function, +structure it just allocated. The second function, XkbGetUpdatedMap, retrieves mapping components from the server and stores them in an XkbDescRec - structure that has previously been allocated. +structure that has previously been allocated. To allocate an XkbDescRec - structure and populate it with the server’s keyboard client map and server +structure and populate it with the server’s keyboard client map and server map, use XkbGetMap. XkbGetMap is similar to XkbGetKeyboard - (see section 6.2), but is used only for obtaining the address of an +(see section 6.2), but is used only for obtaining the address of an XkbDescRec - structure that is populated with keyboard mapping components. It allows finer +structure that is populated with keyboard mapping components. It allows finer control over which substructures of the keyboard mapping components are to be populated. XkbGetKeyboard - always returns fully populated components, while +always returns fully populated components, while XkbGetMap - can be instructed to return a partially populated component. +can be instructed to return a partially populated component. XkbGetMap @@ -312,51 +312,51 @@ populated. The which - mask is a bitwise inclusive OR of the masks defined in +mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those portions of the keyboard server map and the keyboard client maps that are specified in which - are allocated and populated. +are allocated and populated. In addition to allocating and obtaining the server map and the client map, XkbGetMap - also sets the +also sets the device_spec, the min_key_code, and max_key_code - fields of the keyboard description. +fields of the keyboard description. XkbGetMap - is synchronous; it queries the server for the desired information, waits for a +is synchronous; it queries the server for the desired information, waits for a reply, and then returns. If successful, XkbGetMap - returns a pointer to the +returns a pointer to the XkbDescRec - structure it allocated. If unsuccessful, +structure it allocated. If unsuccessful, XkbGetMap - returns +returns NULL. When unsuccessful, one of the following protocol errors is also generated: BadAlloc - (unable to allocate the +(unable to allocate the XkbDescRec - structure), +structure), BadValue - (some mask bits in +(some mask bits in which - are undefined), +are undefined), or BadImplementation - (a compatible version of the Xkb extension is not available in the server). To +(a compatible version of the Xkb extension is not available in the server). To free the returned data, use XkbFreeClientMap. @@ -561,42 +561,42 @@ description, use XkbGetUpdatedMap. The which - parameter is a bitwise inclusive OR of the masks in +parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed components of the xkb - structure are not already allocated, +structure are not already allocated, XkbGetUpdatedMap - allocates them. +allocates them. XkbGetUpdatedMap - fetches the requested information for the device specified in the +fetches the requested information for the device specified in the XkbDescRec - passed in the +passed in the xkb - parameter. +parameter. XkbGetUpdatedMap - is synchronous; it queries the server for the desired information, waits for a +is synchronous; it queries the server for the desired information, waits for a reply, and then returns. If successful, XkbGetUpdatedMap - returns +returns Success. If unsuccessful, XkbGetUpdatedMap - returns one of the following: +returns one of the following: BadAlloc - (unable to allocate a component in the +(unable to allocate a component in the XkbDescRec - structure), +structure), BadValue - (some mask bits in +(some mask bits in which - are undefined), +are undefined), BadImplementation - (a compatible version of the Xkb extension is not available in the server or +(a compatible version of the Xkb extension is not available in the server or the reply from the server was invalid). @@ -608,10 +608,10 @@ the reply from the server was invalid). There are two ways to make changes to map components: either change a local copy of the keyboard map and call XkbSetMap - to send the modified map to the server, or, to reduce network traffic, use +to send the modified map to the server, or, to reduce network traffic, use an XkbMapChangesRec - structure and call XkbChangeMap. +structure and call XkbChangeMap. XkbSetMap @@ -665,44 +665,44 @@ an Use XkbSetMap - to send a complete new set of values for entire components (for example, all +to send a complete new set of values for entire components (for example, all symbols, all actions, and so on) to the server. The which - parameter specifies the components to be sent to the server, and is a bitwise +parameter specifies the components to be sent to the server, and is a bitwise inclusive OR of the masks listed in Table 14.1. The xkb - parameter is a pointer to an +parameter is a pointer to an XkbDescRec - structure and contains the information to be copied to the server. For each +structure and contains the information to be copied to the server. For each bit set in the which - parameter, +parameter, XkbSetMap - takes the corresponding structure values from the +takes the corresponding structure values from the xkb - parameter and sends it to the server specified by +parameter and sends it to the server specified by dpy. If any components specified by which - are not present in the +are not present in the xkb - parameter, +parameter, XkbSetMap - returns +returns False. Otherwise, it sends the update request to the server and returns True. XkbSetMap - can generate +can generate BadAlloc, BadLength, and BadValue - protocol errors. +protocol errors. @@ -723,7 +723,7 @@ helper functions and provides a pointer to where they are defined. Use the XkbMapChangesRec - structure to identify and track partial modifications to the mapping +structure to identify and track partial modifications to the mapping components and to reduce the amount of traffic between the server and clients. @@ -771,20 +771,20 @@ typedef struct _XkbMapChanges { The changed - field identifies the map components that have changed in an +field identifies the map components that have changed in an XkbDescRec - structure and may contain any of the bits in +structure and may contain any of the bits in Table 14.1, which are also shown in Table 14.2. Every 1 bit in changed - also identifies which other fields in the +also identifies which other fields in the XkbMapChangesRec - structure contain valid values, as indicated in +structure contain valid values, as indicated in Table 14.2. The min_key_code - and +and max_key_code - fields are for reference only; they are ignored on any requests sent to the +fields are for reference only; they are ignored on any requests sent to the server and are always updated by the server whenever it returns the data for an XkbMapChangesRec. @@ -895,9 +895,9 @@ To update only partial components of a keyboard description, modify the appropriate fields in the server and map components of a local copy of the keyboard description, then call XkbChangeMap - with an +with an XkbMapChangesRec - structure indicating which components have changed. +structure indicating which components have changed. XkbChangeMap @@ -950,9 +950,9 @@ keyboard description, then call XkbChangeMap - copies any components specified by the +copies any components specified by the changes - structure from the keyboard description, +structure from the keyboard description, xkb, to the X server specified by dpy. @@ -962,11 +962,11 @@ to the X server specified by If any components specified by changes - are not present in the +are not present in the xkb - parameter, +parameter, XkbChangeMap - returns +returns False. Otherwise, it sends a request to the server and returns True. @@ -975,12 +975,12 @@ Otherwise, it sends a request to the server and returns XkbChangeMap - can generate +can generate BadAlloc, BadLength, and BadValue - protocol errors. +protocol errors. @@ -997,7 +997,7 @@ and The Xkb extension reports XkbMapNotify - events to clients wanting notification whenever a map component of the Xkb +events to clients wanting notification whenever a map component of the Xkb description for a device changes. There are many different types of Xkb keyboard map changes. Xkb uses an event detail mask to identify each type of change. The event detail masks are identical to the masks listed in @@ -1008,13 +1008,13 @@ change. The event detail masks are identical to the masks listed in To receive XkbMapNotify - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - (see section 4.3) and pass +(see section 4.3) and pass XkbMapNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -1022,24 +1022,24 @@ To receive To receive XkbMapNotify - events only under certain conditions, use +events only under certain conditions, use XkbSelectEventDetails - using +using XkbMapNotify - as the +as the event_type - and specifying the desired map changes in +and specifying the desired map changes in bits_to_change - and +and values_for_bits - using mask bits from Table 14.1. +using mask bits from Table 14.1. The structure for XkbMapNotify - events is: +events is: typedef struct { @@ -1075,16 +1075,16 @@ typedef struct { The changed - field specifies the map components that have changed and is the bitwise +field specifies the map components that have changed and is the bitwise inclusive OR of the mask bits defined in Table 14.1. The other fields in this event are interpreted as the like-named fields in an XkbMapChangesRec - (see section 14.3.1). The +(see section 14.3.1). The XkbMapNotifyEvent - structure also has an additional +structure also has an additional resized - field that is reserved for future use. +field that is reserved for future use. @@ -1095,7 +1095,7 @@ event are interpreted as the like-named fields in an Calling XkbGetMap - (see section 14.2) should be sufficient for most applications to get client +(see section 14.2) should be sufficient for most applications to get client and server maps. As a result, most applications do not need to directly allocate client and server maps. @@ -1106,11 +1106,11 @@ If you change the number of key types or construct map components without loading the necessary components from the X server, do not allocate any map components directly using malloc - or +or Xmalloc. Instead, use the Xkb allocators, XkbAllocClientMap, - and +and XkbAllocServerMap. @@ -1118,11 +1118,11 @@ Instead, use the Xkb allocators, Similarly, use the Xkb destructors, XkbFreeClientMap, - and +and XkbFreeServerMap - instead of +instead of free - or +or Xfree. @@ -1183,13 +1183,13 @@ To allocate and initialize an empty client map description record, use XkbAllocClientMap - allocates and initializes an empty client map in the +allocates and initializes an empty client map in the map - field of the keyboard description specified by +field of the keyboard description specified by xkb. The which - parameter specifies the particular components of the client map structure to +parameter specifies the particular components of the client map structure to allocate and is a mask composed by a bitwise inclusive OR of one or more of the masks shown in Table 14.3. @@ -1214,11 +1214,11 @@ The type_count field specifies the number of entries to preallocate for the types - field of the client map. If the +field of the client map. If the type_count field is less than XkbNumRequiredTypes - (see section 15.2.1), returns +(see section 15.2.1), returns BadValue. @@ -1227,20 +1227,20 @@ field is less than The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter are used to allocate the +parameter are used to allocate the syms - and +and key_sym_map - fields of the client map. The fields are allocated to contain the maximum +fields of the client map. The fields are allocated to contain the maximum number of entries necessary for max_key_code - − +− min_key_code - + 1 keys. ++ 1 keys. @@ -1248,18 +1248,18 @@ number of entries necessary for The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter are used to allocate the +parameter are used to allocate the modmap - field of the client map. The field is allocated to contain the maximum number +field of the client map. The field is allocated to contain the maximum number of entries necessary for max_key_code - − +− min_key_code - + 1 keys. ++ 1 keys. @@ -1268,19 +1268,19 @@ of entries necessary for The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter must be legal values if the +parameter must be legal values if the XkbKeySymsMask - or +or XkbModifierMapMask - masks are set in the +masks are set in the which - parameter. If they are not valid, +parameter. If they are not valid, XkbAllocClientMap - returns +returns BadValue. @@ -1289,34 +1289,34 @@ If the client map of the keyboard description is not NULL, and any fields are already allocated in the client map, XkbAllocClientMap - does not overwrite the existing values; it simply ignores that part of the +does not overwrite the existing values; it simply ignores that part of the request. The only exception is the types - array. If +array. If type_count - is greater than the current +is greater than the current num_types - field of the client map, +field of the client map, XkbAllocClientMap - resizes the +resizes the types - array and resets the +array and resets the num_types - field accordingly. +field accordingly. If XkbAllocClientMap - is successful, it returns +is successful, it returns Success. Otherwise, it can return either BadMatch, BadAlloc, or BadValue - errors. +errors. @@ -1327,7 +1327,7 @@ or To free memory used by the client map member of an XkbDescRec - structure, use +structure, use XkbFreeClientMap. @@ -1380,17 +1380,17 @@ To free memory used by the client map member of an XkbFreeClientMap - frees the components of client map specified by +frees the components of client map specified by which - in the +in the XkbDescRec - structure specified by the +structure specified by the xkb - parameter and sets the corresponding structure component values to +parameter and sets the corresponding structure component values to NULL. The which - parameter specifies a combination of the client map masks shown in +parameter specifies a combination of the client map masks shown in Table 14.3. @@ -1398,22 +1398,22 @@ The If free_all - is +is True, which - is ignored; +is ignored; XkbFreeClientMap - frees every non- +frees every non- NULL - structure component in the client map, frees the +structure component in the client map, frees the XkbClientMapRec - structure referenced by the +structure referenced by the map - member of the +member of the xkb - parameter, and sets the +parameter, and sets the map - member to +member to NULL. @@ -1475,13 +1475,13 @@ To allocate and initialize an empty server map description record, use XkbAllocServerMap - allocates and initializes an empty server map in the +allocates and initializes an empty server map in the server - field of the keyboard description specified by +field of the keyboard description specified by xkb. The which - parameter specifies the particular components of the server map structure to +parameter specifies the particular components of the server map structure to allocate, as specified in Table 14.4. @@ -1503,11 +1503,11 @@ allocate, as specified in Table 14.4. The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter are used to allocate the +parameter are used to allocate the explicit field of the server map. @@ -1517,17 +1517,17 @@ field of the server map. The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter are used to allocate the +parameter are used to allocate the key_acts field of the server map. The count_acts - parameter is used to allocate the +parameter is used to allocate the acts - field of the server map. +field of the server map. @@ -1535,11 +1535,11 @@ field of the server map. The The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter are used to allocate the +parameter are used to allocate the behaviors field of the server map. @@ -1549,9 +1549,9 @@ field of the server map. The min_key_code - and +and max_key_code - fields of the +fields of the xkb parameter are used to allocate the vmodmap @@ -1564,22 +1564,22 @@ field of the server map. The min_key_code - and +and max_key_code - fields of the +fields of the xkb - parameter must be legal values. If they are not valid, +parameter must be legal values. If they are not valid, XkbAllocServerMap - returns +returns BadValue. If the server map of the keyboard description is not NULL - and any fields are already allocated in the server map, +and any fields are already allocated in the server map, XkbAllocServerMap - does not overwrite the existing values. The only exception is with the +does not overwrite the existing values. The only exception is with the acts array. If the count_acts @@ -1587,7 +1587,7 @@ parameter is greater than the current num_acts field of the server map, XkbAllocServerMap - resizes the +resizes the acts array and resets the num_acts @@ -1598,13 +1598,13 @@ field accordingly. If XkbAllocServerMap - is successful, it returns +is successful, it returns Success. Otherwise, it can return either BadMatch - or +or BadAlloc - errors. +errors. @@ -1615,7 +1615,7 @@ Otherwise, it can return either To free memory used by the server member of an XkbDescRec - structure, use +structure, use XkbFreeServerMap. @@ -1669,34 +1669,34 @@ To free memory used by the server member of an The XkbFreeServerMap - function frees the specified components of server map in the +function frees the specified components of server map in the XkbDescRec - structure specified by the +structure specified by the xkb - parameter and sets the corresponding structure component values to +parameter and sets the corresponding structure component values to NULL. The which - parameter specifies a combination of the server map masks and is a bitwise +parameter specifies a combination of the server map masks and is a bitwise inclusive OR of the masks listed in Table 14.4. If free_all - is +is True, which - is ignored and +is ignored and XkbFreeServerMap - frees every non- +frees every non- NULL - structure component in the server map, frees the +structure component in the server map, frees the XkbServerMapRec - structure referenced by the +structure referenced by the server - member of the +member of the xkb - parameter, and sets the +parameter, and sets the server - member to +member to NULL. diff --git a/specs/XKB/ch15.xml b/specs/XKB/ch15.xml index 2956a2b8..a6f3f7c6 100644 --- a/specs/XKB/ch15.xml +++ b/specs/XKB/ch15.xml @@ -63,7 +63,7 @@ typedef struct { /* Client Map */ The following sections describe each of the elements of the XkbClientMapRec - structure in more detail. +structure in more detail. @@ -80,7 +80,7 @@ Key types are used to determine the shift level of a key given the current state of the keyboard. The set of all possible key types for the Xkb keyboard description are held in the types - field of the client map, whose total size is stored in +field of the client map, whose total size is stored in size_types, and whose total number of valid entries is stored in num_types. @@ -115,125 +115,125 @@ typedef struct { /* Modifiers for a key type */ The mods - field of a key type is an +field of a key type is an XkbModsRec - (see section 7.2) specifying the modifiers the key type uses when calculating +(see section 7.2) specifying the modifiers the key type uses when calculating the shift level, and can be composed of both the core modifiers and virtual modifiers. To set the modifiers associated with a key type, modify the real_mods - and +and vmods - fields of the +fields of the mods XkbModsRec - accordingly. The +accordingly. The mask - field of the +field of the XkbModsRec - is reserved for use by Xkb and is calculated from the +is reserved for use by Xkb and is calculated from the real_mods - and +and vmods - fields. +fields. The num_levels - field holds the total number of shift levels for the key type. Xkb uses +field holds the total number of shift levels for the key type. Xkb uses num_levels - to ensure the array of symbols bound to a key is large enough. Do not modify +to ensure the array of symbols bound to a key is large enough. Do not modify num_levels - directly to change the number if shift levels for a key type. Instead, use +directly to change the number if shift levels for a key type. Instead, use XkbResizeKeyType - (see section 15.2.3). +(see section 15.2.3). The map - field is a vector of +field is a vector of XkbKTMapEntryRec - structures, with +structures, with map_count - entries, that specify the modifier combinations for each possible shift level. +entries, that specify the modifier combinations for each possible shift level. Each map entry contains an active - field, a +field, a mods - field, and a +field, and a level - field. The +field. The active - field determines whether the modifier combination listed in the +field determines whether the modifier combination listed in the mods - field should be considered when determining shift level. If +field should be considered when determining shift level. If active - is +is False, this map - entry is ignored. If +entry is ignored. If active - is +is True, the level - field of the +field of the map entry specifies the shift level to use when the current modifier combination matches the combination specified in the mods - field of the +field of the map - entry. +entry. Any combination of modifiers not explicitly listed somewhere in the map - yields shift level one. In addition, +yields shift level one. In addition, map - entries specifying unbound virtual modifiers are not considered. +entries specifying unbound virtual modifiers are not considered. Any modifiers specified in mods - are normally +are normally consumed - by +by XkbTranslateKeyCode - (see section 12.1.3). For those rare occasions a modifier +(see section 12.1.3). For those rare occasions a modifier should - be considered despite having been used to look up a symbol, key types include +be considered despite having been used to look up a symbol, key types include an optional preserve - field. If a +field. If a preserve - member of a key type is not +member of a key type is not NULL, it represents a list of modifiers where each entry corresponds directly to one of the key type’s map. Each entry lists the modifiers that should not - be consumed if the matching map entry is used to determine shift level. +be consumed if the matching map entry is used to determine shift level. Each shift level has a name and these names are held in the level_names - array, whose length is +array, whose length is num_levels. The type itself also has a name, which is held in the name - field. +field. @@ -328,7 +328,7 @@ although this format is one possible example): The name - of the example key type is "ALPHATHREE," and the modifiers it pays attention +of the example key type is "ALPHATHREE," and the modifiers it pays attention to are Shift, Lock, @@ -342,60 +342,60 @@ of shift level two is "Caps," and the name of shift level three is "Level3." Given the combination of the map - and +and preserve - specifications, there are five +specifications, there are five map - entries. The first map entry specifies that shift level one is to be used if +entries. The first map entry specifies that shift level one is to be used if no modifiers are set. The second entry specifies the Lock - modifier alone also yields shift level one. The third entry specifies the +modifier alone also yields shift level one. The third entry specifies the Shift - modifier alone yields shift level two. The fourth and fifth entries specify +modifier alone yields shift level two. The fourth and fifth entries specify that the virtual LevelThree - modifier alone, or in combination with the +modifier alone, or in combination with the Shift - modifier, yields shift level three. +modifier, yields shift level three. Shift level three can be reached only if the virtual modifier LevelThree - is bound to a real modifier (see section 16.4). If +is bound to a real modifier (see section 16.4). If LevelThree - is not bound to a real modifier, the +is not bound to a real modifier, the map - entries associated with it are ignored. +entries associated with it are ignored. Because the Lock - modifier is to be preserved for further event processing, the +modifier is to be preserved for further event processing, the preserve - list is not +list is not NULL - and parallels the +and parallels the map - list. All +list. All preserve - entries, except for the one corresponding to the +entries, except for the one corresponding to the map - entry that specifies the +entry that specifies the Lock modifier, do not list any modifiers. For the map - entry that specifies the +entry that specifies the Lock - modifier, the corresponding +modifier, the corresponding preserve - list entry lists the +list entry lists the Lock - modifier, meaning do not consume the +modifier, meaning do not consume the Lock - modifier. In this particular case, the preserved modifier is passed to Xlib +modifier. In this particular case, the preserved modifier is passed to Xlib translation functions and causes them to notice that the Lock - modifier is set; consequently, the Xlib functions apply the appropriate +modifier is set; consequently, the Xlib functions apply the appropriate capitalization rules to the symbol. Because this preserve entry is set only for a modifier that yields shift level one, the capitalization occurs only for level-one symbols. @@ -408,16 +408,16 @@ level-one symbols. Xkb allows up to XkbMaxKeyTypes - (255) key types to be defined, but requires at least +(255) key types to be defined, but requires at least XkbNumRequiredTypes - (4) predefined types to be in a key map. These predefined key types are +(4) predefined types to be in a key map. These predefined key types are referred to as the canonical key types and describe the types of keys available on most keyboards. The definitions for the canonical key types are held in the first XkbNumRequiredTypes - entries of the +entries of the types - field of the client map and are indexed using the following constants: +field of the client map and are indexed using the following constants: XkbOneLevelIndex @@ -463,9 +463,9 @@ The TWO_LEVEL key type describes groups that consist of two symbols but are neither alphabetic nor numeric keypad keys. The default TWO_LEVEL type uses only the Shift - modifier. It returns shift level two if +modifier. It returns shift level two if Shift - is set, and level one if it is not. A symbolic representation of this key type +is set, and level one if it is not. A symbolic representation of this key type could look like the following: @@ -497,9 +497,9 @@ lowercase form of a symbol followed by the uppercase form of the same symbol. The default ALPHABETIC type implements locale-sensitive Shift cancels CapsLock behavior using both the Shift - and +and Lock - modifiers as follows: +modifiers as follows: @@ -507,25 +507,25 @@ CapsLock behavior using both the If Shift - and +and Lock - are both set, the default ALPHABETIC type yields level one. +are both set, the default ALPHABETIC type yields level one. If Shift - alone is set, it yields level two. +alone is set, it yields level two. If Lock - alone is set, it yields level one, but preserves the +alone is set, it yields level one, but preserves the Lock - modifier so Xlib notices and applies the appropriate capitalization rules. The +modifier so Xlib notices and applies the appropriate capitalization rules. The Xlib functions are locale-sensitive and apply different capitalization rules for different locales. @@ -534,9 +534,9 @@ for different locales. If neither Shift - nor +nor Lock - is set, it yields level one. +is set, it yields level one. @@ -576,7 +576,7 @@ reside at level two. The default KEYPAD key type implements and the real modifier bound to the virtual modifier named NumLock, known as the NumLock - modifier, as follows: +modifier, as follows: @@ -584,32 +584,32 @@ and the real modifier bound to the virtual modifier named If Shift - and +and NumLock - are both set, the default KEYPAD type yields level one. +are both set, the default KEYPAD type yields level one. If Shift - alone is set, it yields level two. +alone is set, it yields level two. If NumLock - alone is set, it yields level two. +alone is set, it yields level two. If neither Shift - nor +nor NumLock - is set, it yields level one. +is set, it yields level one. @@ -697,13 +697,13 @@ default values, use XkbInitCanonicalKeyTypes - initializes the first +initializes the first XkbNumRequiredTypes - key types of the keyboard specified by the +key types of the keyboard specified by the xkb - parameter to their default values. The +parameter to their default values. The which - parameter specifies what canonical key types to initialize and is a bitwise +parameter specifies what canonical key types to initialize and is a bitwise inclusive OR of the following masks: XkbOneLevelMask, XkbTwoLevelMask, @@ -712,37 +712,37 @@ and XkbKeypadMask. Only those canonical types specified by the which - mask are initialized. +mask are initialized. If XkbKeypadMask - is set in the +is set in the which - parameter, +parameter, XkbInitCanonicalKeyTypes - looks up the +looks up the NumLock - named virtual modifier to determine which virtual modifier to use when +named virtual modifier to determine which virtual modifier to use when initializing the KEYPAD key type. If the NumLock - virtual modifier does not exist, +virtual modifier does not exist, XkbInitCanonicalKeyTypes - creates it. +creates it. XkbInitCanonicalKeyTypes - normally returns Success. It returns +normally returns Success. It returns BadAccess - if the Xkb extension has not been properly initialized, and +if the Xkb extension has not been properly initialized, and BadAccess - if the +if the xkb - parameter is not valid. +parameter is not valid. @@ -819,15 +819,15 @@ use XkbGetKeyTypes - is used to obtain descriptions of the key types themselves, not the key types +is used to obtain descriptions of the key types themselves, not the key types bound to individual keys. To obtain the key types bound to an individual key, refer to the key_sym_map - field of the client map (see section 15.3.1). +field of the client map (see section 15.3.1). XkbGetKeyTypes - queries the server for the desired types, waits for a reply, and returns the +queries the server for the desired types, waits for a reply, and returns the desired types in the xkb->map->types. If successful, it returns Success. @@ -836,15 +836,15 @@ If successful, it returns Success. XkbGetKeyTypes - returns +returns BadAccess - if the Xkb extension has not been properly initialized and +if the Xkb extension has not been properly initialized and BadValue - if the combination of +if the combination of first - and +and num - results in numbers out of valid range. +results in numbers out of valid range. @@ -932,20 +932,20 @@ To change the number of levels in a key type, use XkbResizeKeyType - changes the type specified by +changes the type specified by xkb->map->types [ type_ndx ], and reallocates the symbols and actions bound to all keys that use the type, if necessary. XkbResizeKeyType - updates only the local copy of the types in +updates only the local copy of the types in xkb; - to update the server’s copy for the physical device, use +to update the server’s copy for the physical device, use XkbSetMap - or +or XkbChangeMap - after calling +after calling XkbResizeKeyType. @@ -953,16 +953,16 @@ if necessary. The map_count - parameter specifies the total number of map entries needed for the type, and +parameter specifies the total number of map entries needed for the type, and can be zero or greater. If map_count - is zero, +is zero, XkbResizeKeyType - frees the existing +frees the existing map - and +and preserve - entries for the type if they exist and sets them to +entries for the type if they exist and sets them to NULL. @@ -970,23 +970,23 @@ can be zero or greater. If The want_preserve - parameter specifies whether a +parameter specifies whether a preserve - list for the key should be created. If +list for the key should be created. If want_preserve - is +is True, the preserve - list with +list with map_count - entries is allocated or reallocated if it already exists. Otherwise, if +entries is allocated or reallocated if it already exists. Otherwise, if want_preserve - is +is False, the preserve - field is freed if necessary and set to +field is freed if necessary and set to NULL. @@ -994,7 +994,7 @@ the The new_num_lvls - parameter specifies the new maximum number of shift levels for the type and is +parameter specifies the new maximum number of shift levels for the type and is used to calculate and resize the symbols and actions bound to all keys that use the type. @@ -1003,17 +1003,17 @@ the type. If type_ndx - does not specify a legal type, +does not specify a legal type, new_num_lvls - is less than 1, or the +is less than 1, or the map_count - is less than zero, +is less than zero, XkbResizeKeyType - returns +returns BadValue. If XkbResizeKeyType - encounters any problems with allocation, it returns +encounters any problems with allocation, it returns BadAlloc. Otherwise, it returns Success. @@ -1027,11 +1027,11 @@ Otherwise, it returns Use XkbCopyKeyType - and +and XkbCopyKeyTypes - to copy one or more +to copy one or more XkbKeyTypeRec - structures. +structures. XkbCopyKeyType @@ -1072,39 +1072,39 @@ Use XkbCopyKeyType - copies the key type specified by +copies the key type specified by from - to the key type specified by +to the key type specified by into. Both must point to legal XkbKeyTypeRec - structures. Xkb assumes +structures. Xkb assumes from - and +and into - point to different places. As a result, overlaps can be fatal. +point to different places. As a result, overlaps can be fatal. XkbCopyKeyType - frees any existing +frees any existing map, preserve, and level_names - in +in into - prior to copying. If any allocation errors occur while copying +prior to copying. If any allocation errors occur while copying from - to +to into, XkbCopyKeyType - returns +returns BadAlloc. Otherwise, XkbCopyKeyType - copies +copies from - to +to into - and returns +and returns Success. @@ -1159,41 +1159,41 @@ Otherwise, XkbCopyKeyTypes - copies +copies num_types XkbKeyTypeRec - structures from the array specified by +structures from the array specified by from - into the array specified by +into the array specified by into. It is intended for copying between, rather than within, keyboard descriptions, so it doesn’t check for overlaps. The same rules that apply to the from - and +and into - parameters in +parameters in XkbCopyKeyType - apply to each entry of the +apply to each entry of the from - and +and into - arrays of +arrays of XkbCopyKeyTypes. If any allocation errors occur while copying from - to +to into, XkbCopyKeyTypes - returns +returns BadAlloc. Otherwise, XkbCopyKeyTypes - copies +copies from - to +to into - and returns +and returns Success. @@ -1208,14 +1208,14 @@ Otherwise, The entire list of key symbols for the keyboard mapping is held in the syms - field of the client map. Whereas the core keyboard mapping is a +field of the client map. Whereas the core keyboard mapping is a two-dimensional array of KeySyms - whose rows are indexed by keycode, the +whose rows are indexed by keycode, the syms - field of Xkb is a linear list of +field of Xkb is a linear list of KeySyms - that needs to be indexed uniquely for each key. This section describes the key +that needs to be indexed uniquely for each key. This section describes the key symbol map and the methods for determining the symbols bound to a key. @@ -1223,45 +1223,45 @@ symbol map and the methods for determining the symbols bound to a key. The reason the syms - field is a linear list of +field is a linear list of KeySyms - is to reduce the memory consumption associated with a keymap; because Xkb +is to reduce the memory consumption associated with a keymap; because Xkb allows individual keys to have multiple shift levels and a different number of groups per key, a single two-dimensional array of KeySyms - would potentially be very large and sparse. Instead, Xkb provides a small +would potentially be very large and sparse. Instead, Xkb provides a small two-dimensional array of KeySyms - for each key. To store all of these individual arrays, Xkb concatenates each +for each key. To store all of these individual arrays, Xkb concatenates each array together in the syms - field of the client map. +field of the client map. In order to determine which KeySyms - in the +in the syms - field are associated with each keycode, the client map contains an array of +field are associated with each keycode, the client map contains an array of key symbol mappings, held in the key_sym_map - field. The +field. The key_sym_map - field is an array of +field is an array of XkbSymMapRec - structures indexed by keycode. The +structures indexed by keycode. The key_sym_map - array has +array has min_key_code - unused entries at the start to allow direct indexing using a keycode. All +unused entries at the start to allow direct indexing using a keycode. All keycodes falling between the minimum and maximum legal keycodes, inclusive, have key_sym_map - arrays, whether or not any key actually yields that code. The +arrays, whether or not any key actually yields that code. The KeySymMapRec - structure is defined as follows: +structure is defined as follows: #define XkbNumKbdGroups 4 @@ -1289,9 +1289,9 @@ These fields are described in detail in the following sections. The kt_index - array of the +array of the XkbSymMapRec - structure contains the indices of the key types (see section 15.2) for each +structure contains the indices of the key types (see section 15.2) for each possible group of symbols associated with the key. To obtain the index of a key type or the pointer to a key type, Xkb provides the following macros, to access the key types: @@ -1302,7 +1302,7 @@ hold key types for the maximum legal number of groups (XkbNumKbdGroups, currently four); if a key has fewer than XkbNumKbdGroups - groups, the extra key types are reported but ignored. +groups, the extra key types are reported but ignored. XkbKeyTypeIndex @@ -1352,15 +1352,15 @@ currently four); if a key has fewer than XkbKeyTypeIndex - computes an index into the +computes an index into the types - vector of the client map in +vector of the client map in xkb - from the given +from the given keycode - and +and group - index. +index. @@ -1412,15 +1412,15 @@ currently four); if a key has fewer than XkbKeyType - returns a pointer to the key type in the +returns a pointer to the key type in the types - vector of the client map in +vector of the client map in xkb - corresponding to the given +corresponding to the given keycode - and +and group - index. +index. @@ -1431,9 +1431,9 @@ currently four); if a key has fewer than The group_info - field of an +field of an XkbSymMapRec - is an encoded value containing the number of groups of symbols bound to the +is an encoded value containing the number of groups of symbols bound to the key as well as the specification of the treatment of out-of-range groups. It is legal for a key to have zero groups, in which case it also has zero symbols and all events from that key yield @@ -1442,10 +1442,10 @@ To obtain the number of groups of symbols bound to the key, use XkbKeyNumGroups. To change the number of groups bound to a key, use XkbChangeTypesOfKey - (see section 15.3.6). To obtain a mask that determines the treatment of +(see section 15.3.6). To obtain a mask that determines the treatment of out-of-range groups, use XkbKeyGroupInfo - and +and XkbOutOfRangeGroupInfo. @@ -1453,26 +1453,26 @@ out-of-range groups, use The keyboard controls (see ) contain a groups_wrap - field specifying the handling of illegal groups on a global basis. That is, +field specifying the handling of illegal groups on a global basis. That is, when the user performs an action causing the effective group to go out of the legal range, the groups_wrap - field specifies how to normalize the effective keyboard group to a group that +field specifies how to normalize the effective keyboard group to a group that is legal for the keyboard as a whole, but there is no guarantee that the normalized group will be within the range of legal groups for any individual key. The per-key group_info - field specifies how a key treats a legal effective group if the key does not +field specifies how a key treats a legal effective group if the key does not have a type specified for the group of concern. For example, the Enter - key usually has just one group defined. If the user performs an action causing +key usually has just one group defined. If the user performs an action causing the global keyboard group to change to Group2, the group_info - field for the +field for the Enter - key describes how to handle this situation. +key describes how to handle this situation. @@ -1481,9 +1481,9 @@ Out-of-range groups for individual keys are mapped to a legal group using the same options as are used for the overall keyboard group. The particular type of mapping used is controlled by the bits set in the group_info - flag, as shown in Table 15.2. - See section 10.7.1 - for more details on the normalization methods in this table. +flag, as shown in Table 15.2. +See section 10.7.1 +for more details on the normalization methods in this table.
@@ -1556,7 +1556,7 @@ Xkb provides the following macros to access group information: XkbKeyNumGroups - returns the number of groups of symbols bound to the key corresponding to +returns the number of groups of symbols bound to the key corresponding to keycode. @@ -1598,11 +1598,11 @@ Xkb provides the following macros to access group information: XkbKeyGroupInfo - returns the +returns the group_info - field from the +field from the XkbSymMapRec - structure associated with the key corresponding to +structure associated with the key corresponding to keycode. @@ -1633,11 +1633,11 @@ Xkb provides the following macros to access group information: XkbOutOfRangeGroupInfo - returns only the out-of-range processing information from the +returns only the out-of-range processing information from the group_info - field of an +field of an XkbSymMapRec - structure. +structure. @@ -1667,11 +1667,11 @@ Xkb provides the following macros to access group information: XkbOutOfRangeGroupNumber - returns the out-of-range group number, represented as a group index, from the +returns the out-of-range group number, represented as a group index, from the group_info - field of an +field of an XkbSymMapRec - structure. +structure. @@ -1683,9 +1683,9 @@ Xkb provides the following macros to access group information: The maximum number of shift levels for a type is also referred to as the width of a key type. The width - field of the +field of the key_sym_map - entry for a key contains the width of the widest type associated with the key. +entry for a key contains the width of the widest type associated with the key. The width field cannot be explicitly changed; it is updated automatically whenever the @@ -1701,11 +1701,11 @@ symbols or set of types bound to a key are changed. The key width and number of groups associated with a key are used to form a small two-dimensional array of KeySyms - for a key. This array may be different sizes for different keys. The array for +for a key. This array may be different sizes for different keys. The array for a single key is stored as a linear list, in row-major order. The arrays for all of the keys are stored in the syms - field of the client map. There is one row for each group associated with a key +field of the client map. There is one row for each group associated with a key and one column for each level. The index corresponding to a given group and shift level is computed as: @@ -1717,18 +1717,18 @@ shift level is computed as: The offset - field of the +field of the key_sym_map - entry for a key is used to access the beginning of the array. +entry for a key is used to access the beginning of the array. Xkb provides the following macros for accessing the width - and +and offset - for individual keys, as well as macros for accessing the two-dimensional array +for individual keys, as well as macros for accessing the two-dimensional array of symbols bound to the key: @@ -1769,7 +1769,7 @@ of symbols bound to the key: XkbKeyGroupsWidth - computes the maximum width associated with the key corresponding to +computes the maximum width associated with the key corresponding to keycode. @@ -1822,9 +1822,9 @@ of symbols bound to the key: XkbKeyGroupWidth - computes the width of the type associated with the group +computes the width of the type associated with the group grp - for the key corresponding to +for the key corresponding to keycode. @@ -1866,7 +1866,7 @@ of symbols bound to the key: XkbKeySymsOffset - returns the offset of the two-dimensional array of keysyms for the key +returns the offset of the two-dimensional array of keysyms for the key corresponding to keycode. @@ -1909,7 +1909,7 @@ corresponding to XkbKeyNumSyms - returns the total number of keysyms for the key corresponding to +returns the total number of keysyms for the key corresponding to keycode. @@ -1951,7 +1951,7 @@ corresponding to XkbKeySymsPtr - returns the pointer to the two-dimensional array of keysyms for the key +returns the pointer to the two-dimensional array of keysyms for the key corresponding to keycode. @@ -2016,13 +2016,13 @@ corresponding to XkbKeySymEntry - returns the +returns the KeySym - corresponding to shift level +corresponding to shift level shift - and group +and group grp - from the two-dimensional array of keysyms for the key corresponding to +from the two-dimensional array of keysyms for the key corresponding to keycode @@ -2099,32 +2099,32 @@ To obtain the symbols for a subset of the keys in a keyboard description, use XkbGetKeySyms - sends a request to the server to obtain the set of keysyms bound to +sends a request to the server to obtain the set of keysyms bound to num - keys starting with the key whose keycode is +keys starting with the key whose keycode is first. It waits for a reply and returns the keysyms in the map.syms - field of +field of xkb. If successful, XkbGetKeySyms - returns +returns Success. The xkb - parameter must be a pointer to a valid Xkb keyboard description. +parameter must be a pointer to a valid Xkb keyboard description. If the client map - in the +in the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeySyms - allocates and initializes it before obtaining the symbols. +allocates and initializes it before obtaining the symbols. @@ -2132,18 +2132,18 @@ If the client If a compatible version of Xkb is not available in the server or the Xkb extension has not been properly initialized, XkbGetKeySyms - returns +returns BadAccess. If num - is less than 1 or greater than +is less than 1 or greater than XkbMaxKeyCount, XkbGetKeySyms - returns +returns BadValue. If any allocation errors occur, XkbGetKeySyms - returns +returns BadAlloc. @@ -2244,35 +2244,35 @@ To change the number of groups and the types bound to a key, use XkbChangeTypesOfKey - reallocates the symbols and actions bound to the key, if necessary, and +reallocates the symbols and actions bound to the key, if necessary, and initializes any new symbols or actions to NoSymbol - or +or NoAction, as appropriate. If the p_changes - parameter is not +parameter is not NULL, XkbChangeTypesOfKey - adds the +adds the XkbKeySymsMask - to the +to the changes - field of +field of p_changes - and modifies the +and modifies the first_key_sym - and +and num_key_syms - fields of +fields of p_changes - to include the +to include the key - that was changed. See section 14.3.1 for more information on the +that was changed. See section 14.3.1 for more information on the XkbMapChangesPtr - structure. If successful, +structure. If successful, XkbChangeTypesOfKey - returns +returns Success. @@ -2280,9 +2280,9 @@ as appropriate. If the The n_groups - parameter specifies the new number of groups for the key. The +parameter specifies the new number of groups for the key. The groups - parameter is a mask specifying the groups for which new types are supplied and +parameter is a mask specifying the groups for which new types are supplied and is a bitwise inclusive OR of the following masks: XkbGroup1Mask, XkbGroup2Mask, @@ -2295,24 +2295,24 @@ and The new_types_in - parameter is an integer array of length +parameter is an integer array of length n_groups. Each entry represents the type to use for the associated group and is an index into xkb->map->types. The new_types_in - array is indexed by group index; if +array is indexed by group index; if n_groups - is four and +is four and groups - only has +only has XkbGroup1Mask - and +and XkbGroup3Mask - set, +set, new_types_in - looks like this: +looks like this: @@ -2363,32 +2363,32 @@ groups: If the Xkb extension has not been properly initialized, XkbChangeTypesOfKey - returns +returns BadAccess. If the xkb - parameter it not valid (that is, it is +parameter it not valid (that is, it is NULL - or it does not contain a valid client map), +or it does not contain a valid client map), XkbChangeTypesOfKey - returns +returns BadMatch. If the key - is not a valid keycode, +is not a valid keycode, n_groups - is greater than +is greater than XkbNumKbdGroups, or the groups - mask does not contain any of the valid group mask bits, +mask does not contain any of the valid group mask bits, XkbChangeTypesOfKey - returns +returns BadValue. If it is necessary to resize the key symbols or key actions arrays and any allocation errors occur, XkbChangeTypesOfKey - returns +returns BadAlloc. @@ -2452,34 +2452,34 @@ To change the number of symbols bound to a key, use XkbResizeKeySyms - reserves the space needed for +reserves the space needed for needed - keysyms and returns a pointer to the beginning of the new array that holds the +keysyms and returns a pointer to the beginning of the new array that holds the keysyms. It adjusts the offset - field of the +field of the key_sym_map - entry for the key if necessary and can also change the +entry for the key if necessary and can also change the syms, num_syms, and size_syms - fields of +fields of xkb->map - if it is necessary to reallocate the +if it is necessary to reallocate the syms - array. +array. XkbResizeKeySyms - does not modify either the width or number of groups associated with the key. +does not modify either the width or number of groups associated with the key. If needed - is greater than the current number of keysyms for the key, +is greater than the current number of keysyms for the key, XkbResizeKeySyms - initializes all new keysyms in the array to +initializes all new keysyms in the array to NoSymbol. @@ -2488,17 +2488,17 @@ If Because the number of symbols needed by a key is normally computed as width * number of groups, and XkbResizeKeySyms - does not modify either the width or number of groups for the key, a +does not modify either the width or number of groups for the key, a discrepancy exists upon return from XkbResizeKeySyms - between the space allocated for the keysyms and the number required. The +between the space allocated for the keysyms and the number required. The unused entries in the list of symbols returned by XkbResizeKeySyms - are not preserved across future calls to any of the map editing functions, so +are not preserved across future calls to any of the map editing functions, so you must update the key symbol mapping (which updates the width and number of groups for the key) before calling another allocator function. A call to XkbChangeTypesOfKey - will update the mapping. +will update the mapping. @@ -2506,7 +2506,7 @@ groups for the key) before calling another allocator function. A call to If any allocation errors occur while resizing the number of symbols bound to the key, XkbResizeKeySyms - returns +returns NULL. @@ -2524,7 +2524,7 @@ a key. The modmap - entry of the client map is an array, indexed by keycode, specifying the real +entry of the client map is an array, indexed by keycode, specifying the real modifiers bound to a key. Each entry is a mask composed of a bitwise inclusive OR of the legal real modifiers: ShiftMask, @@ -2538,7 +2538,7 @@ and Mod5Mask. If a bit is set in a modmap - entry, the corresponding key is bound to that modifier. +entry, the corresponding key is bound to that modifier. @@ -2621,14 +2621,14 @@ description, use XkbGetKeyModifierMap - sends a request to the server for the modifier mappings for +sends a request to the server for the modifier mappings for num - keys starting with the key whose keycode is +keys starting with the key whose keycode is first. It waits for a reply and places the results in the xkb->map->modmap array. If successful, XkbGetKeyModifierMap - returns +returns Success. @@ -2636,9 +2636,9 @@ It waits for a reply and places the results in the If the map component of the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeyModifierMap - allocates and initializes it. +allocates and initializes it. @@ -2646,11 +2646,11 @@ If the map component of the If a compatible version of Xkb is not available in the server or the Xkb extension has not been properly initialized, XkbGetKeySyms - returns +returns BadAccess. If any allocation errors occur while obtaining the modifier map, XkbGetKeyModifierMap - returns +returns BadAlloc. diff --git a/specs/XKB/ch16.xml b/specs/XKB/ch16.xml index 554580de..3f5e42f0 100644 --- a/specs/XKB/ch16.xml +++ b/specs/XKB/ch16.xml @@ -12,7 +12,7 @@ The server - field of the complete Xkb keyboard description (see section 6.1) is a pointer +field of the complete Xkb keyboard description (see section 6.1) is a pointer to the Xkb server map. @@ -68,16 +68,16 @@ The acts, and key_acts - fields specify the key actions, defined in section 16.1. The +fields specify the key actions, defined in section 16.1. The behaviors - field describes the behavior for each key and is defined in section 16.2. The +field describes the behavior for each key and is defined in section 16.2. The explicit - field describes the explicit components for a key and is defined in +field describes the explicit components for a key and is defined in section 16.3. The vmods - and the +and the vmodmap - fields describe the virtual modifiers and the per-key virtual modifier mapping +fields describe the virtual modifiers and the per-key virtual modifier mapping and are defined in section 16.4. @@ -89,9 +89,9 @@ A key action defines the effect key presses and releases have on the internal state of the server. For example, the expected key action associated with pressing the Shift - key is to set the +key is to set the Shift - modifier. There is zero or one key action associated with each keysym bound to +modifier. There is zero or one key action associated with each keysym bound to each key. @@ -99,12 +99,12 @@ each key. Just as the entire list of key symbols for the keyboard mapping is held in the syms - field of the client map, the entire list of key actions for the keyboard +field of the client map, the entire list of key actions for the keyboard mapping is held in the acts - array of the server map. The total size of +array of the server map. The total size of acts - is specified by +is specified by size_acts, and the number of entries is specified by num_acts. @@ -114,44 +114,44 @@ and the number of entries is specified by The key_acts - array, indexed by keycode, describes the actions associated with a key. The +array, indexed by keycode, describes the actions associated with a key. The key_acts - array has +array has min_key_code - unused entries at the start to allow direct indexing using a keycode. If a +unused entries at the start to allow direct indexing using a keycode. If a key_acts - entry is +entry is zero, it means the key does not have any actions associated with it. If an entry is not zero, the entry represents an index into the acts - field of the server map, much as the +field of the server map, much as the offset - field of a +field of a KeySymMapRec - structure is an index into the +structure is an index into the syms - field of the client map. +field of the client map. The reason the acts - field is a linear list of +field is a linear list of XkbActions - is to reduce the memory consumption associated with a keymap. Because Xkb +is to reduce the memory consumption associated with a keymap. Because Xkb allows individual keys to have multiple shift levels and a different number of groups per key, a single two-dimensional array of KeySyms - would potentially be very large and sparse. Instead, Xkb provides a small +would potentially be very large and sparse. Instead, Xkb provides a small two-dimensional array of XkbActions - for each key. To store all of these individual arrays, Xkb concatenates each +for each key. To store all of these individual arrays, Xkb concatenates each array together in the acts - field of the server map. +field of the server map. @@ -206,11 +206,11 @@ to key actions: XkbKeyHasActions - returns +returns True - if the key corresponding to +if the key corresponding to keycode - has any actions associated with it; otherwise, it returns +has any actions associated with it; otherwise, it returns False. @@ -252,11 +252,11 @@ to key actions: XkbKeyNumActions - computes the number of actions associated with the key corresponding to +computes the number of actions associated with the key corresponding to keycode. This should be the same value as the result of XkbKeyNumSyms - (see section 15.3.3). +(see section 15.3.3). @@ -297,12 +297,12 @@ This should be the same value as the result of XkbKeyActionsPtr - returns a pointer to the two-dimensional array of key actions associated with +returns a pointer to the two-dimensional array of key actions associated with the key corresponding to keycode. Use XkbKeyActionsPtr - only if the key actually has some actions associated with it, that is, +only if the key actually has some actions associated with it, that is, XkbKeyNumActions (xkb, keycode) returns something greater than zero. @@ -356,13 +356,13 @@ Use XkbKeyAction - returns the key action indexed by +returns the key action indexed by idx - in the two-dimensional array of key actions associated with the key +in the two-dimensional array of key actions associated with the key corresponding to keycode. idx - may be computed from the group and shift level of interest as follows: +may be computed from the group and shift level of interest as follows: @@ -428,11 +428,11 @@ corresponding to XkbKeyActionEntry - returns the key action corresponding to group +returns the key action corresponding to group grp - and shift level +and shift level shift - from the two-dimensional table of key actions associated with the key +from the two-dimensional table of key actions associated with the key corresponding to keycode. @@ -446,7 +446,7 @@ corresponding to The description for an action is held in an XkbAction - structure, which is a union of all possible Xkb action types: +structure, which is a union of all possible Xkb action types: typedef union _XkbAction { @@ -470,7 +470,7 @@ typedef union _XkbAction { The type - field is provided for convenience and is the same as the type field in the +field is provided for convenience and is the same as the type field in the individual structures. The following sections describe the individual structures for each action in detail. @@ -485,7 +485,7 @@ structures for each action in detail. The XkbAnyAction - structure is a convenience structure that refers to any of the actions: +structure is a convenience structure that refers to any of the actions: #define XkbAnyActionDataSize 7 @@ -499,12 +499,12 @@ typedef struct _XkbAnyAction { The data - field represents a structure for an action, and its interpretation depends on +field represents a structure for an action, and its interpretation depends on the type - field. The valid values for the +field. The valid values for the type - field, and the data structures associated with them are shown in +field, and the data structures associated with them are shown in Table 16.1: @@ -529,7 +529,7 @@ the XkbSA_NoAction XkbSA_NoAction - means the server does not perform an action for the key; this action does not +means the server does not perform an action for the key; this action does not have an associated data structure. any @@ -636,7 +636,7 @@ have an associated data structure. Actions associated with the XkbModAction - structure change the state of the modifiers when keys are pressed and released +structure change the state of the modifiers when keys are pressed and released (see for a discussion of modifiers): @@ -662,15 +662,15 @@ In the following description, the term action modifiers modifiersaction - means the real modifier bits associated with this action. Depending on the +means the real modifier bits associated with this action. Depending on the value of flags - (see Table 16.3), - these are designated either in the +(see Table 16.3), +these are designated either in the mask - field of the +field of the XkbModAction - structure itself or the real modifiers bound to the key for which the action +structure itself or the real modifiers bound to the key for which the action is being used. In the latter case, this is the client map->modmap [ @@ -682,7 +682,7 @@ is being used. In the latter case, this is the client The type - field can have any of the values shown in +field can have any of the values shown in Table 16.2. @@ -718,9 +718,9 @@ provided no other key affecting the same modifiers is logically down. If no other keys are physically depressed when this key is released, and XkbSA_ClearLocks - is set in the +is set in the flags - field, the key release unlocks any action modifiers. +field, the key release unlocks any action modifiers. @@ -734,7 +734,7 @@ If no other keys are physically depressed when this key is released, and Key press and key release events have the same effect as for XkbSA_SetMods; - if no keys are physically depressed when this key is released, key release +if no keys are physically depressed when this key is released, key release events have the following additional effects: @@ -742,16 +742,16 @@ events have the following additional effects: Modifiers unlocked due to XkbSA_ClearLocks - have no further effect. +have no further effect. If XkbSA_LatchToLock - is set in the +is set in the flags - field, a key release locks and then unlatches any remaining action modifiers +field, a key release locks and then unlatches any remaining action modifiers that are already latched. @@ -759,9 +759,9 @@ that are already latched. A key release latches any action modifiers not used by the XkbSA_ClearLocks - and +and XkbSA_LatchToLock - flags. +flags. @@ -775,9 +775,9 @@ A key release latches any action modifiers not used by the A key press sets the base state of any action modifiers. If XkbSA_LockNoLock - is set in the +is set in the flags - field, a key press also sets the locked state of any action modifiers. +field, a key press also sets the locked state of any action modifiers. @@ -785,9 +785,9 @@ A key press sets the base state of any action modifiers. If A key release clears any action modifiers in the keyboard’s base modifiers, provided no other key that affects the same modifiers is down. If XkbSA_LockNoUnlock - is not set in the +is not set in the flags - field, and any of the action modifiers were locked before the corresponding +field, and any of the action modifiers were locked before the corresponding key press occurred, a key release unlocks them. @@ -801,9 +801,9 @@ key press occurred, a key release unlocks them. The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.3. - A general meaning is given in the table, but the exact meaning depends on +A general meaning is given in the table, but the exact meaning depends on the action type. @@ -831,7 +831,7 @@ modifiers specified by the vmods1, and vmods2 - fields. +fields. @@ -872,9 +872,9 @@ the server only locks the action modifiers. If XkbSA_UseModMapMods - is not set in the +is not set in the flags - field, the +field, the mask, real_mods, vmods1, @@ -896,22 +896,22 @@ The vmods1, and vmods2 - fields represent the components of an Xkb modifier description +fields represent the components of an Xkb modifier description (see section 7.2). While the mask - and +and real_mods - fields correspond directly to the +fields correspond directly to the mask - and +and real_mods - fields of an Xkb modifier description, the +fields of an Xkb modifier description, the vmods1 - and +and vmods2 - fields are combined to correspond to the +fields are combined to correspond to the vmods - field of an Xkb modifier description. Xkb provides the following macros, to +field of an Xkb modifier description. Xkb provides the following macros, to convert between the two formats: @@ -941,15 +941,15 @@ convert between the two formats: XkbModActionVMods - returns the +returns the vmods1 - and +and vmods2 - fields of +fields of act - converted to the +converted to the vmods - format of an Xkb modifier description. +format of an Xkb modifier description. @@ -990,21 +990,21 @@ convert between the two formats: XkbSetModActionVMods - sets the +sets the vmods1 - and +and vmods2 - fields of +fields of act - using the +using the vmods - format of an Xkb modifier description. +format of an Xkb modifier description. Despite the fact that the first parameter of these two macros is of type XkbAction, these macros may be used only with Actions of type XkbModAction - and +and XkbISOAction. @@ -1018,7 +1018,7 @@ type XkbAction, these macros may be used only with Actions of type Actions associated with the XkbGroupAction - structure change the current group state when keys are pressed and released +structure change the current group state when keys are pressed and released (see for a description of groups and keyboard state): @@ -1032,7 +1032,7 @@ typedef struct _XkbGroupAction { The type - field can have any of the following values: +field can have any of the following values:
@@ -1056,25 +1056,25 @@ The If the XkbSA_GroupAbsolute - bit is set in the +bit is set in the flags - field, key press events change the base keyboard group to the group specified +field, key press events change the base keyboard group to the group specified by the group_XXX - field. Otherwise, key press events change the base keyboard group by adding +field. Otherwise, key press events change the base keyboard group by adding the group_XXX - field to the base keyboard group. In either case, the resulting effective +field to the base keyboard group. In either case, the resulting effective keyboard group is brought back into range depending on the value of the groups_wrap - field of the controls structure (see section 10.7.1). +field of the controls structure (see section 10.7.1). If a key with an XkbSA_ISOLock - action (see section 16.1.8) is pressed while this key is down, the key release +action (see section 16.1.8) is pressed while this key is down, the key release of this key has no effect. Otherwise, the key release cancels the effects of the key press. @@ -1083,7 +1083,7 @@ the key press. If the XkbSA_ClearLocks - bit is set in the flags field, and no keys are physically depressed when this +bit is set in the flags field, and no keys are physically depressed when this key is released, the key release also sets the locked keyboard group to Group1. @@ -1099,7 +1099,7 @@ key is released, the key release also sets the locked keyboard group to Key press and key release events have the same effect as for XkbSA_SetGroup; - if no keys are physically depressed when this key is released, key release +if no keys are physically depressed when this key is released, key release events have the following additional effects. @@ -1107,14 +1107,14 @@ events have the following additional effects. If the XkbSA_LatchToLock - bit is set in the +bit is set in the flags - field and the latched keyboard group index is nonzero, the key release adds +field and the latched keyboard group index is nonzero, the key release adds the delta applied by the corresponding key press to the locked keyboard group and subtracts it from the latched keyboard group. The locked and effective keyboard group are brought back into range according to the value of the groups_wrap - field of the controls structure. +field of the controls structure. @@ -1133,18 +1133,18 @@ Otherwise, the key press adds the key press delta to the latched keyboard group. If the XkbSA_GroupAbsolute - is set in the +is set in the flags - field, key press events set the locked keyboard group to the group specified +field, key press events set the locked keyboard group to the group specified by the group_XXX - field. Otherwise, key press events add the group specified by the +field. Otherwise, key press events add the group specified by the group_XXX - field to the locked keyboard group. In either case, the resulting locked and +field to the locked keyboard group. In either case, the resulting locked and effective keyboard groups are brought back into range depending on the value of the groups_wrap - field of the controls structure. +field of the controls structure. @@ -1162,9 +1162,9 @@ A key release has no effect. The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.5. - A general meaning is given in the table, but the exact meaning depends on +A general meaning is given in the table, but the exact meaning depends on the action type. @@ -1188,7 +1188,7 @@ the action If set and no keys are physically depressed when this key transition occurs, the server sets the locked keyboard group to Group1 - on a key release. +on a key release. @@ -1204,7 +1204,7 @@ the server locks the action group if it is already latched. If set, the group_XXX - field represents an absolute group number. Otherwise, it represents a group +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. @@ -1215,7 +1215,7 @@ delta to be added to the current group to determine the new group number. The group_XXX - field represents a signed character. Xkb provides the following macros to +field represents a signed character. Xkb provides the following macros to convert between a signed integer value and a signed character: @@ -1245,11 +1245,11 @@ convert between a signed integer value and a signed character: XkbSAGroup - returns the +returns the group_XXX - field of +field of act - converted to a signed int. +converted to a signed int. @@ -1290,18 +1290,18 @@ convert between a signed integer value and a signed character: XkbSASetGroup - sets the +sets the group_XXX - field of +field of act - from the group index +from the group index grp. Despite the fact that the first parameter of these two macros is of type XkbAction, these macros may only be used with Actions of type XkbGroupAction - and +and XkbISOAction. @@ -1315,7 +1315,7 @@ type XkbAction, these macros may only be used with Actions of type Actions associated with the XkbPtrAction - structure move the pointer when keys are pressed and released: +structure move the pointer when keys are pressed and released: typedef struct _XkbPtrAction { @@ -1331,38 +1331,38 @@ typedef struct _XkbPtrAction { If the MouseKeys - control is not enabled (see section 10.5.1), +control is not enabled (see section 10.5.1), KeyPress - and +and KeyRelease - events are treated as though the action is +events are treated as though the action is XkbSA_NoAction. If the MouseKeys - control is enabled, a server action of type +control is enabled, a server action of type XkbSA_MovePtr - instructs the server to generate core pointer +instructs the server to generate core pointer MotionNotify - events rather than the usual +events rather than the usual KeyPress - event, and the corresponding +event, and the corresponding KeyRelease - event disables any mouse keys timers that were created as a result of handling +event disables any mouse keys timers that were created as a result of handling the XkbSA_MovePtr - action. +action. The type - field of the +field of the XkbPtrAction - structure is always +structure is always XkbSA_MovePtr. @@ -1370,7 +1370,7 @@ The The flags - field is a bitwise inclusive OR of the masks shown in +field is a bitwise inclusive OR of the masks shown in Table 16.6. @@ -1392,9 +1392,9 @@ The If not set, and the MouseKeysAccel - control is enabled (see section 10.5.2), the +control is enabled (see section 10.5.2), the KeyPress - initiates a mouse keys timer for this key; every time the timer expires, the +initiates a mouse keys timer for this key; every time the timer expires, the cursor moves. @@ -1420,15 +1420,15 @@ to the current pointer Y coordinate to determine the new pointer Y coordinate. Each of the X and Y coordinates of the XkbPtrAction - structure is composed of two signed 16-bit values, that is, the X coordinate +structure is composed of two signed 16-bit values, that is, the X coordinate is composed of high_XXX - and +and low_XXX, and similarly for the Y coordinate. Xkb provides the following macros, to convert between a signed integer and two signed 16-bit values in XkbPtrAction - structures: +structures: XkbPtrActionX @@ -1457,13 +1457,13 @@ convert between a signed integer and two signed 16-bit values in XkbPtrActionX - returns the +returns the high_XXX - and +and low_XXX - fields of +fields of act - converted to a signed int. +converted to a signed int. @@ -1493,13 +1493,13 @@ convert between a signed integer and two signed 16-bit values in XkbPtrActionY - returns the +returns the high_YYY - and +and low_YYY - fields of +fields of act - converted to a signed int. +converted to a signed int. @@ -1541,13 +1541,13 @@ convert between a signed integer and two signed 16-bit values in XkbSetPtrActionX - sets the +sets the high_XXX - and +and low_XXX - fields of +fields of act - from the signed integer value +from the signed integer value x. @@ -1589,13 +1589,13 @@ convert between a signed integer and two signed 16-bit values in XkbSetPtrActionX - sets the +sets the high_YYY - and +and low_YYY - fields of +fields of act - from the signed integer value +from the signed integer value y. @@ -1609,7 +1609,7 @@ convert between a signed integer and two signed 16-bit values in Actions associated with the XkbPtrBtnAction - structure simulate the press and release of pointer buttons when keys are +structure simulate the press and release of pointer buttons when keys are pressed and released: @@ -1626,11 +1626,11 @@ typedef struct _XkbPtrBtnAction { If the MouseKeys - (see section 10.5.1) control is not enabled, +(see section 10.5.1) control is not enabled, KeyPress - and +and KeyRelease - events are treated as though the action is +events are treated as though the action is XkbSA_NoAction. @@ -1638,7 +1638,7 @@ If the The type - field can have any one of the values shown in +field can have any one of the values shown in Table 16.7. @@ -1663,16 +1663,16 @@ The If XkbSA_UseDfltButton - is set in the +is set in the flags - field, the event is generated for the pointer button specified by the +field, the event is generated for the pointer button specified by the mk_dflt_btn - attribute of the +attribute of the MouseKeys - control (see section 10.5.1). Otherwise, the event is generated for the button +control (see section 10.5.1). Otherwise, the event is generated for the button specified by the button - field. +field. @@ -1681,42 +1681,42 @@ If the mouse button specified for this action is logically down, the key press and corresponding key release are ignored and have no effect. Otherwise, a key press causes one or more core pointer button events instead of the usual KeyPress - event. If +event. If count - is +is zero, a key press generates a single ButtonPress - event; if +event; if count - is greater than +is greater than zero, a key press generates count - pairs of +pairs of ButtonPress - and +and ButtonRelease - events. +events. If count - is +is zero, a key release generates a core pointer ButtonRelease - that matches the event generated by the corresponding +that matches the event generated by the corresponding KeyPress; - if +if count - is nonzero, a key release does not cause a +is nonzero, a key release does not cause a ButtonRelease - event. A key release never generates a key +event. A key release never generates a key KeyRelease - event. +event. @@ -1730,31 +1730,31 @@ a key release generates a core pointer If the button specified by the MouseKeys - default button +default button or button - is not locked, a key press causes a +is not locked, a key press causes a ButtonPress - event instead of a +event instead of a KeyPress - event and locks the button. If the button is already locked or if +event and locks the button. If the button is already locked or if XkbSA_LockNoUnlock - is set in the +is set in the flags - field, a key press is ignored and has no effect. +field, a key press is ignored and has no effect. If the corresponding key press was ignored, and if XkbSA_LockNoLock - is not set in the +is not set in the flags - field, a key release generates a +field, a key release generates a ButtonRelease - event instead of a +event instead of a KeyRelease - event and unlocks the specified button. If the corresponding key press locked +event and unlocks the specified button. If the corresponding key press locked a button, the key release is ignored and has no effect. @@ -1768,9 +1768,9 @@ a button, the key release is ignored and has no effect. The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.8. - A general meaning is given in the table, but the exact meaning depends on +A general meaning is given in the table, but the exact meaning depends on the action type: @@ -1793,9 +1793,9 @@ the action If set, the action uses the pointer button specified by the mk_dflt_btn - attribute of the +attribute of the MouseKeys - control (see section 10.5.1). Otherwise, the action uses the pointer button +control (see section 10.5.1). Otherwise, the action uses the pointer button specified by the button field. @@ -1830,11 +1830,11 @@ the server only locks the pointer button. Actions associated with the XkbPtrDfltAction - structure change the +structure change the mk_dflt_btn - attribute of the +attribute of the MouseKeys - control (see section 10.5.1): +control (see section 10.5.1): typedef struct _XkbPtrDfltAction { @@ -1848,26 +1848,26 @@ typedef struct _XkbPtrDfltAction { If the MouseKeys - control is not enabled, +control is not enabled, KeyPress - and +and KeyRelease - events are treated as though the action is +events are treated as though the action is XkbSA_NoAction. Otherwise, this action changes the mk_dflt_btn - attribute of the +attribute of the MouseKeys - control. +control. The type - field of the +field of the XkbPtrDfltAction - structure should always be +structure should always be XkbSA_SetPtrDflt. @@ -1875,9 +1875,9 @@ The The flags - field is composed of the bitwise inclusive OR of the values shown in +field is composed of the bitwise inclusive OR of the values shown in Table 16.9 - (currently there is only one value defined). +(currently there is only one value defined).
@@ -1898,9 +1898,9 @@ The If set, the value - field represents an absolute pointer button. Otherwise, the +field represents an absolute pointer button. Otherwise, the value - field represents the amount to be added to the current default button. +field represents the amount to be added to the current default button. @@ -1910,32 +1910,32 @@ If set, the The affect - field specifies what changes as a result of this action. The only valid value +field specifies what changes as a result of this action. The only valid value for the affect - field is XkbSA_AffectDfltBtn. +field is XkbSA_AffectDfltBtn. The valueXXX - field is a signed character that represents the new button value for the +field is a signed character that represents the new button value for the mk_dflt_btn - attribute of the +attribute of the MouseKeys - control (see section 10.5.1). If +control (see section 10.5.1). If XkbSA_DfltBtnAbsolute - is set in +is set in flags, valueXXX - specifies the button to be used; otherwise, +specifies the button to be used; otherwise, valueXXX - specifies the amount to be added to the current default button. In either +specifies the amount to be added to the current default button. In either case, illegal button choices are wrapped back around into range. Xkb provides the following macros, to convert between the integer and signed character values in XkbPtrDfltAction - structures: +structures: XkbSAPtrDfltValue @@ -1964,11 +1964,11 @@ values in XkbSAPtrDfltValue - returns the +returns the valueXXX - field of +field of act - converted to a signed int. +converted to a signed int. @@ -2009,11 +2009,11 @@ values in XkbSASetPtrDfltValue - sets the +sets the valueXXX - field of +field of act - from +from val. @@ -2027,23 +2027,23 @@ values in Actions associated with the XkbISOAction - structure lock modifiers and the group according to the ISO9995 specification. +structure lock modifiers and the group according to the ISO9995 specification. Operated by itself, the XkbISOAction - is just a caps lock. Operated simultaneously with another modifier key, it +is just a caps lock. Operated simultaneously with another modifier key, it transforms the other key into a locking key. For example, press ISO_Lock, press and release Control_L, release ISO_Lock - ends up locking the +ends up locking the Control - modifier. +modifier. @@ -2061,11 +2061,11 @@ The default behavior is to convert: The affects - field allows you to turn those effects on or off individually. Set +field allows you to turn those effects on or off individually. Set XkbSA_ISONoAffectMods - to disable the first, +to disable the first, XkbSA_ISONoAffectGroup - to disable the second, and so forth. +to disable the second, and so forth. @@ -2090,9 +2090,9 @@ typedef struct _XkbISOAction { The type - field of the +field of the XkbISOAction - structure should always be +structure should always be XkbSA_ISOLock. @@ -2100,23 +2100,23 @@ The The interpretation of the flags - field depends on whether the +field depends on whether the XkbSA_ISODfltIsGroup - is set in the +is set in the flags - field or not. +field or not. If the XkbSA_ISODfltIsGroup - is set in the +is set in the flags - field, the action is used to change the group state. The remaining valid bits +field, the action is used to change the group state. The remaining valid bits of the flags - field are composed of a bitwise inclusive OR using the masks shown in +field are composed of a bitwise inclusive OR using the masks shown in Table 16.10. @@ -2143,13 +2143,13 @@ remaining bits in this table to carry their interpretations. A key press sets the base group as specified by the group_XXX - field and the +field and the XkbSA_GroupAbsolute - bit of the +bit of the flags - field (see section Note). If no other actions are transformed by the +field (see section Note). If no other actions are transformed by the XkbSA_ISOLock - action, a key release locks the group. Otherwise, a key release clears group +action, a key release locks the group. Otherwise, a key release clears group set by the key press. @@ -2159,7 +2159,7 @@ set by the key press. If set, the group_XXX - field represents an absolute group number. Otherwise, it represents a group +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. @@ -2168,13 +2168,13 @@ delta to be added to the current group to determine the new group number. If not set, any XkbSA_SetMods - or +or XkbSA_LatchMods - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockMods - actions instead. +actions instead. @@ -2182,13 +2182,13 @@ If not set, any If not set, any XkbSA_SetGroup - or +or XkbSA_LatchGroup - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockGroup - actions instead. +actions instead. @@ -2196,11 +2196,11 @@ If not set, any If not set, any XkbSA_PtrBtn - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockPtrBtn - actions instead. +actions instead. @@ -2208,11 +2208,11 @@ If not set, any If not set, any XkbSA_SetControls - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockControls - actions instead. +actions instead. @@ -2222,12 +2222,12 @@ If not set, any If the XkbSA_ISODfltIsGroup - is not set in the +is not set in the flags - field, the action is used to change the modifier state and the remaining valid +field, the action is used to change the modifier state and the remaining valid bits of the flags - field are composed of a bitwise inclusive OR using the masks shown in +field are composed of a bitwise inclusive OR using the masks shown in Table 16.11. @@ -2261,7 +2261,7 @@ and vmods2 fields (see section 16.1.3). If no other actions are transformed by the XkbSA_ISOLock - action, a key release locks the action modifiers. Otherwise, a key release +action, a key release locks the action modifiers. Otherwise, a key release clears the base modifiers set by the key press. @@ -2277,7 +2277,7 @@ modifiers specified by the vmods1, and vmods2 - fields. +fields. @@ -2293,13 +2293,13 @@ and If not set, any XkbSA_SetMods - or +or XkbSA_LatchMods - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockMods - actions instead. +actions instead. @@ -2307,13 +2307,13 @@ If not set, any If not set, any XkbSA_SetGroup - or +or XkbSA_LatchGroup - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockGroup - actions instead. +actions instead. @@ -2321,11 +2321,11 @@ If not set, any If not set, any XkbSA_PtrBtn - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockPtrBtn - actions instead. +actions instead. @@ -2333,11 +2333,11 @@ If not set, any If not set, any XkbSA_SetControls - actions that occur simultaneously with the +actions that occur simultaneously with the XkbSA_ISOLock - action are treated as +action are treated as XkbSA_LockControls - actions instead. +actions instead. @@ -2347,7 +2347,7 @@ If not set, any The group_XXX - field represents a signed character. Xkb provides macros to convert between a +field represents a signed character. Xkb provides macros to convert between a signed integer value and a signed character as shown in section Note. @@ -2359,22 +2359,22 @@ The vmods1, and vmods2 - fields represent the components of an Xkb modifier description - (see section 7.2). While the +fields represent the components of an Xkb modifier description +(see section 7.2). While the mask - and +and real_mods - fields correspond directly to the +fields correspond directly to the mask - and +and real_mods - fields of an Xkb modifier description, the +fields of an Xkb modifier description, the vmods1 - and +and vmods2 - fields are combined to correspond to the +fields are combined to correspond to the vmods - field of an Xkb modifier description. Xkb provides macros to convert between +field of an Xkb modifier description. Xkb provides macros to convert between the two formats as shown in section 16.1.3. @@ -2382,7 +2382,7 @@ the two formats as shown in The affect - field is composed of a bitwise inclusive OR using the masks shown in +field is composed of a bitwise inclusive OR using the masks shown in Table 16.11. @@ -2404,15 +2404,15 @@ The If XkbSA_ISONoAffectMods - is not set, any +is not set, any SA_SetMods - or +or SA_LatchMods - actions occurring simultaneously with the +actions occurring simultaneously with the XkbISOAction - are treated as +are treated as SA_LockMods - instead. +instead. @@ -2420,15 +2420,15 @@ If If XkbSA_ISONoAffectGroup - is not set, any +is not set, any SA_SetGroup - or +or SA_LatchGroup - actions occurring simultaneously with the +actions occurring simultaneously with the XkbISOAction - are treated as +are treated as SA_LockGroup - instead. +instead. @@ -2436,13 +2436,13 @@ If If XkbSA_ISONoAffectPtr - is not set, any +is not set, any SA_PtrBtn - actions occurring simultaneously with the +actions occurring simultaneously with the XkbISOAction - are treated as +are treated as SA_LockPtrBtn - instead. +instead. @@ -2450,13 +2450,13 @@ If If XkbSA_ISONoAffectCtrls - is not set, any +is not set, any SA_SetControls - actions occurring simultaneously with the +actions occurring simultaneously with the XkbISOAction - are treated as +are treated as SA_LockControls - instead. +instead. @@ -2472,7 +2472,7 @@ If Actions associated with the XkbSwitchScreenAction - action structure change the active screen on a multiscreen display: +action structure change the active screen on a multiscreen display: This action is optional. Servers are free to ignore the action or @@ -2493,9 +2493,9 @@ typedef struct _XkbSwitchScreenAction { The type - field of the +field of the XkbSwitchScreenAction - structure should always be +structure should always be XkbSA_SwitchScreen. @@ -2503,7 +2503,7 @@ The The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.13. @@ -2525,7 +2525,7 @@ The If set, the screenXXX - field represents the index of the new screen. Otherwise, it represents an +field represents the index of the new screen. Otherwise, it represents an offset from the current screen to the new screen. @@ -2544,15 +2544,15 @@ shares the same physical display. The screenXXX - field is a signed character value that represents either the relative or +field is a signed character value that represents either the relative or absolute screen index, depending on the state of the XkbSA_SwitchAbsolute - bit in the +bit in the flags - field. Xkb provides the following macros to convert between the integer and +field. Xkb provides the following macros to convert between the integer and signed character value for screen numbers in XkbSwitchScreenAction - structures: +structures: XkbSAScreen @@ -2581,11 +2581,11 @@ signed character value for screen numbers in XkbSAScreen - returns the +returns the screenXXX - field of +field of act - converted to a signed int. +converted to a signed int. @@ -2626,11 +2626,11 @@ signed character value for screen numbers in XkbSASetScreen - sets the +sets the screenXXX - field of +field of act - from +from s. @@ -2644,7 +2644,7 @@ signed character value for screen numbers in Actions associated with the XkbCtrlsAction - structure change the state of the boolean controls (see section 10.1): +structure change the state of the boolean controls (see section 10.1): typedef struct _XkbCtrlsAction { @@ -2666,7 +2666,7 @@ typedef struct _XkbCtrlsAction { The type - field can have any one of the values shown in +field can have any one of the values shown in Table 16.14. @@ -2691,7 +2691,7 @@ The A key press enables any boolean controls specified in the ctrls - fields that were not already enabled at the time of the key press. +fields that were not already enabled at the time of the key press. @@ -2703,7 +2703,7 @@ A key release disables any controls enabled by the key press. This action can cause XkbControlsNotify - events (see section 10.1). +events (see section 10.1). @@ -2717,29 +2717,29 @@ This action can cause If the XkbSA_LockNoLock - bit is not set in the +bit is not set in the flags - field, a key press enables any controls specified in the +field, a key press enables any controls specified in the ctrls - fields that were not already enabled at the time of the key press. +fields that were not already enabled at the time of the key press. If the XkbSA_LockNoUnlock - bit is not set in the +bit is not set in the flags - field, a key release disables any controls specified in the +field, a key release disables any controls specified in the ctrls - fields that were not already disabled at the time of the key press. +fields that were not already disabled at the time of the key press. This action can cause XkbControlsNotify - events (see section 10.1). +events (see section 10.1). @@ -2752,7 +2752,7 @@ This action can cause The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.15. @@ -2792,15 +2792,15 @@ the server only enables controls. The XkbSA_SetControls - action implements a key that enables a boolean control when pressed and +action implements a key that enables a boolean control when pressed and disables it when released. The XkbSA_LockControls - action is used to implement a key that toggles the state of a boolean control +action is used to implement a key that toggles the state of a boolean control each time it is pressed and released. The XkbSA_LockNoLock - and +and XkbSA_LockNoUnlock - flags allow modifying the toggling behavior to only unlock or only lock the +flags allow modifying the toggling behavior to only unlock or only lock the boolean control. @@ -2812,9 +2812,9 @@ The ctrls2, and ctrls3 - fields represent the boolean controls in the +fields represent the boolean controls in the enabled_ctrls - field of the controls structure (see section 10.1). Xkb provides the following +field of the controls structure (see section 10.1). Xkb provides the following macros, to convert between the two formats: @@ -2844,11 +2844,11 @@ macros, to convert between the two formats: XkbActionCtrls - returns the +returns the ctrls - fields of +fields of act - converted to an unsigned int. +converted to an unsigned int. @@ -2889,13 +2889,13 @@ macros, to convert between the two formats: XkbSAActionSetCtrls - sets the +sets the ctrls0 - through +through ctrls3 - fields of +fields of act - from +from ctrls. @@ -2909,9 +2909,9 @@ macros, to convert between the two formats: Actions associated with the XkbMessageAction - structure generate +structure generate XkbActionMessage - events: +events: #define XkbActionMessageLength 6 @@ -2927,9 +2927,9 @@ typedef struct _XkbMessageAction { The type - field of the +field of the XkbMessageAction - structure should always be +structure should always be XkbSA_ActionMessage. @@ -2937,7 +2937,7 @@ The The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.16. @@ -2959,9 +2959,9 @@ The If set, key press events generate an XkbActionMessage - event that reports the keycode, event type, and contents of the +event that reports the keycode, event type, and contents of the message - field. +field. @@ -2969,9 +2969,9 @@ If set, key press events generate an If set, key release events generate an XkbActionMessage - event that reports the keycode, event type, and contents of the +event that reports the keycode, event type, and contents of the message - field. +field. @@ -2979,11 +2979,11 @@ If set, key release events generate an If set, key press and key release events generate KeyPress - and +and KeyRelease - events, regardless of whether they generate +events, regardless of whether they generate XkbActionMessage - events. +events. @@ -2993,9 +2993,9 @@ If set, key press and key release events generate The message - field is an array of +field is an array of XkbActionMessageLength - unsigned characters and may be set to anything the keymap designer wishes. +unsigned characters and may be set to anything the keymap designer wishes. @@ -3008,24 +3008,24 @@ The To receive XkbActionMessage - events by calling either +events by calling either XkbSelectEvents - or +or XkbSelectEventDetails - (see section 4.3). +(see section 4.3). To receive XkbActionMessage - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - and pass +and pass XkbActionMessageMask - in both +in both bits_to_change - and +and values_for_bits. @@ -3033,19 +3033,19 @@ To receive The XkbActionMessage - event has no event details. However, you can call +event has no event details. However, you can call XkbSelectEventDetails - using +using XkbActionMessage - as the +as the event_type - and specifying +and specifying XkbAllActionMessagesMask - in +in bits_to_change - and +and values_for_bits. - This has the same effect as a call to +This has the same effect as a call to XkbSelectEvents. @@ -3053,7 +3053,7 @@ The The structure for the XkbActionMessage - event is defined as follows: +event is defined as follows: typedef struct _XkbActionMessage { @@ -3076,9 +3076,9 @@ typedef struct _XkbActionMessage { The keycode - is the keycode of the key that was pressed or released. The +is the keycode of the key that was pressed or released. The press - field specifies whether the event was the result of a key press or key +field specifies whether the event was the result of a key press or key release. @@ -3086,47 +3086,47 @@ release. The key_event_follows - specifies whether a +specifies whether a KeyPress - (if +(if press - is +is True) - or +or KeyRelease - (if +(if press - is +is False) - event is also sent to the client. As with all other Xkb events, +event is also sent to the client. As with all other Xkb events, XkbActionMessageEvents - are delivered to all clients requesting them, regardless of the current +are delivered to all clients requesting them, regardless of the current keyboard focus. However, the KeyPress - or +or KeyRelease - event that conditionally follows an +event that conditionally follows an XkbActionMessageEvent - is sent only to the client selected by the current keyboard focus. +is sent only to the client selected by the current keyboard focus. key_event_follows - is +is True - only for the client that is actually sent the following +only for the client that is actually sent the following KeyPress - or +or KeyRelease - event. +event. The message - field is set to the message specified in the action and is guaranteed to be +field is set to the message specified in the action and is guaranteed to be NULL -terminated; the Xkb extension forces a NULL - into +into message [ XkbActionMessageLength @@ -3144,11 +3144,11 @@ The Actions associated with the XkbRedirectKeyAction - structure generate +structure generate KeyPress - and +and KeyRelease - events containing a keycode different from the key that was pressed or +events containing a keycode different from the key that was pressed or released: @@ -3171,9 +3171,9 @@ typedef struct _XkbRedirectKeyAction { The type - field for the +field for the XkbRedirectKeyAction - structure should always be +structure should always be XkbSA_RedirectKey. @@ -3181,23 +3181,23 @@ The Key presses cause a KeyPress - event for the key specified by the +event for the key specified by the new_key - field instead of the actual key. The state reported in this event reports the +field instead of the actual key. The state reported in this event reports the current effective modifiers changed as follows: any real modifiers selected by the mods_mask - field are set to corresponding values from the +field are set to corresponding values from the mods - field. Any real modifiers bound to the virtual modifiers specified by the +field. Any real modifiers bound to the virtual modifiers specified by the vmods_mask0 - and +and vmods_mask1 - fields are either set or cleared, depending on the corresponding values in the +fields are either set or cleared, depending on the corresponding values in the vmods0 - and +and vmods1 - fields. If the real and virtual modifier definitions specify conflicting +fields. If the real and virtual modifier definitions specify conflicting values for a single modifier, the real modifier definition has priority. @@ -3205,9 +3205,9 @@ values for a single modifier, the real modifier definition has priority. Key releases cause a KeyRelease - event for the key specified by the +event for the key specified by the new_key - field instead of the actual key. The state for this event consists of the +field instead of the actual key. The state for this event consists of the effective keyboard modifiers at the time of the release, changed as described previously. @@ -3216,7 +3216,7 @@ previously. The XkbSA_RedirectKey - action normally redirects to another key on the same device as the key that +action normally redirects to another key on the same device as the key that caused the event, unless that device does not belong to the input extension KeyClass, in which case this action causes an event on the core keyboard device. (The @@ -3229,11 +3229,11 @@ input extension.) The vmods_mask0 - and +and vmods_mask1 - fields actually represent one +fields actually represent one vmods_mask - value, as described in . Xkb provides the following macros, to +value, as described in . Xkb provides the following macros, to convert between the two formats: @@ -3263,13 +3263,13 @@ convert between the two formats: XkbSARedirectVModsMask - returns the +returns the vmods_mask0 - and +and vmods_mask1 - fields of +fields of act - converted to an unsigned int. +converted to an unsigned int. @@ -3310,13 +3310,13 @@ convert between the two formats: XkbSARedirectSetVModsMask - sets the +sets the vmods_mask0 - and +and vmods_mask1 - fields of +fields of act - from +from vm. @@ -3324,9 +3324,9 @@ convert between the two formats: Similarly, the vmods0 - and +and vmods1 - fields actually represent one +fields actually represent one vmods value, as described in . To convert between the two formats, Xkb provides the following convenience macros: @@ -3411,15 +3411,15 @@ provides the following convenience macros: Actions associated with XkbDeviceBtnAction - structures generate +structures generate DeviceButtonPress - and +and DeviceButtonRelease - events instead of normal +events instead of normal KeyPress - and +and KeyRelease - events: +events: typedef struct _XkbDeviceBtnAction { @@ -3435,7 +3435,7 @@ typedef struct _XkbDeviceBtnAction { The type - field can have any one of the values shown in +field can have any one of the values shown in Table 16.17. @@ -3469,30 +3469,30 @@ specified by this action are illegal, this action behaves like Otherwise, key presses cause one or more input extension device events instead of the usual key press event. If the count - field is zero, a key press generates a single +field is zero, a key press generates a single DeviceButtonPress - event. If count is greater than zero, a key press event generates +event. If count is greater than zero, a key press event generates count - pairs of +pairs of DeviceButtonPress - and +and DeviceButtonRelease - events. +events. If count - is zero, a key release generates an input extension +is zero, a key release generates an input extension DeviceButtonRelease - event that matches the event generated by the corresponding key press. If +event that matches the event generated by the corresponding key press. If count - is nonzero, a key release does not cause a +is nonzero, a key release does not cause a DeviceButtonRelease - event. Key releases never cause +event. Key releases never cause KeyRelease - events. +events. @@ -3512,30 +3512,30 @@ behaves like XkbSA_NoAction. Otherwise, if the specified button is not locked and the XkbSA_LockNoLock - bit is not set in the +bit is not set in the flags - field, a key press generates an input extension +field, a key press generates an input extension DeviceButtonPress - event instead of a +event instead of a KeyPress - event and locks the button. If the button is already locked or if +event and locks the button. If the button is already locked or if XkbSA_LockNoLock - bit is set in the +bit is set in the flags - field, the key press is ignored and has no effect. +field, the key press is ignored and has no effect. If the corresponding key press was ignored, and if the XkbSA_LockNoUnlock - bit is not set in the +bit is not set in the flags - field, a key release generates an input extension +field, a key release generates an input extension DeviceButtonRelease - event instead of a +event instead of a KeyRelease - event and unlocks the button. If the corresponding key press locked a button, +event and unlocks the button. If the corresponding key press locked a button, the key release is ignored and has no effect. @@ -3549,7 +3549,7 @@ the key release is ignored and has no effect. The flags - field is composed of the bitwise inclusive OR of the masks shown in +field is composed of the bitwise inclusive OR of the masks shown in Table 16.18. @@ -3597,10 +3597,10 @@ A valuator valuator - manipulates a range of values for some entity, like a mouse axis, a slider or +manipulates a range of values for some entity, like a mouse axis, a slider or a dial. Actions associated with XkbDeviceValuatorAction - structures are used to simulate events from one or two input extension device +structures are used to simulate events from one or two input extension device valuators. @@ -3622,11 +3622,11 @@ typedef struct _XkbDeviceValuatorAction { If device - is illegal or if neither +is illegal or if neither v1_ndx - nor +nor v2_ndx - specifies a legal valuator, this action behaves like +specifies a legal valuator, this action behaves like XkbSA_NoAction. @@ -3634,23 +3634,23 @@ If The low four bits of v1_what - and +and v2_what - specify the corresponding scale value (denoted +specify the corresponding scale value (denoted val<n>Scale - in Table 16.17), if needed. - The high four bits of +in Table 16.17), if needed. +The high four bits of v1_what - and +and v2_what - specify the operation to perform to set the values. The high four bits of +specify the operation to perform to set the values. The high four bits of v1_what - and +and v2_what - can have the values shown in Table 16.17; - the use of +can have the values shown in Table 16.17; +the use of val<n>Scale - is shown in that table also. +is shown in that table also.
@@ -3700,7 +3700,7 @@ The low four bits of XkbSA_SetValAbsolute v<n>_value - is set to (2 val<n>Scale). +is set to (2 val<n>Scale). @@ -3710,12 +3710,12 @@ The low four bits of Illegal values for XkbSA_SetValRelative - or +or XkbSA_SetValAbsolute - are clamped into range. Note that all of these possibilities are legal for +are clamped into range. Note that all of these possibilities are legal for absolute valuators. For relative valuators, only XkbSA_SetValRelative - is permitted. Part of the input extension description of a device is the range +is permitted. Part of the input extension description of a device is the range of legal values for all absolute valuators, whence the maximum and minimum legal values shown in Table 16.17. @@ -3725,7 +3725,7 @@ legal values shown in Table 16.17. The following two masks are provided as a convenience to select either portion of v1_what - or +or v2_what: @@ -3736,9 +3736,9 @@ of v1_ndx - and +and v2_ndx - specify valuators that actually exists. For example, most mice have two +specify valuators that actually exists. For example, most mice have two valuators (x and y axes) so the only legal values for a mouse would be 0 and 1. For a dial box with eight dials, any value in the range 0..7 would be correct. @@ -3751,7 +3751,7 @@ For a dial box with eight dials, any value in the range 0..7 would be correct. To update the actions (the key_acts - array) for a subset of the keys in a keyboard description, use +array) for a subset of the keys in a keyboard description, use XkbGetKeyActions. @@ -3817,32 +3817,32 @@ To update the actions (the XkbGetKeyActions - sends a request to the server to obtain the actions for +sends a request to the server to obtain the actions for num - keys on the keyboard starting with key +keys on the keyboard starting with key first. It waits for a reply and returns the actions in the server->key_acts - field of +field of xkb. If successful, XkbGetKeyActions - returns +returns Success. The xkb - parameter must be a pointer to a valid Xkb keyboard description. +parameter must be a pointer to a valid Xkb keyboard description. If the server - map in the +map in the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeyActions - allocates and initializes it before obtaining the actions. +allocates and initializes it before obtaining the actions. @@ -3850,18 +3850,18 @@ If the If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbGetKeyActions - returns +returns BadAccess. If num - is less than 1 or greater than +is less than 1 or greater than XkbMaxKeyCount, XkbGetKeyActions - returns +returns BadValue. If any allocation errors occur, XkbGetKeyActions - returns +returns BadAlloc. @@ -3926,27 +3926,27 @@ To change the number of actions bound to a key, use The xkb - parameter points to the keyboard description containing the +parameter points to the keyboard description containing the key - whose number of actions is to be changed. The +whose number of actions is to be changed. The key - parameter is the keycode of the key to change, and +parameter is the keycode of the key to change, and needed - specifies the new number of actions required for the key. +specifies the new number of actions required for the key. XkbResizeKeyActions - reserves the space needed for the actions and returns a pointer to the +reserves the space needed for the actions and returns a pointer to the beginning of the new array that holds the actions. It can change the acts, num_acts, and size_acts - fields of +fields of xkb->server - if it is necessary to reallocate the +if it is necessary to reallocate the acts array. @@ -3955,9 +3955,9 @@ array. If needed - is greater than the current number of keysyms for the key, +is greater than the current number of keysyms for the key, XkbResizeKeyActions - initializes all new actions in the array to +initializes all new actions in the array to NoAction. @@ -3966,17 +3966,17 @@ If Because the number of actions needed by a key is normally computed as width * number of groups, and XkbResizeKeyActions - does not modify either the width or number of groups for the key, a +does not modify either the width or number of groups for the key, a discrepancy exists on return from XkbResizeKeyActions - between the space allocated for the actions and the number required. The +between the space allocated for the actions and the number required. The unused entries in the list of actions returned by XkbResizeKeyActions - are not preserved across future calls to any of the map editing functions, so +are not preserved across future calls to any of the map editing functions, so you must update the key actions (which updates the width and number of groups for the key) before calling another allocator function. A call to XkbChangeTypesOfKey - updates these. +updates these. @@ -3984,7 +3984,7 @@ for the key) before calling another allocator function. A call to If any allocation errors occur while resizing the number of actions bound to the key, XkbResizeKeyActions - returns +returns NULL. @@ -4003,7 +4003,7 @@ a key. Key behavior refers to the demeanor of a key. For example, the expected behavior of the CapsLock - key is that it logically locks when pressed, and then logically unlocks when +key is that it logically locks when pressed, and then logically unlocks when pressed again. @@ -4014,36 +4014,36 @@ pressed again. Keys that belong to the same radio group have the XkbKB_RadioGroup - type in the +type in the type - field and the radio group index specified in the +field and the radio group index specified in the data - field in the +field in the XkbBehavior - structure. If the radio group has a name in the +structure. If the radio group has a name in the XkbNamesRec - structure, the radio group index is the index into the +structure, the radio group index is the index into the radio_group - array in the +array in the XkbNamesRec - structure. A radio group key when pressed stays logically down until another +structure. A radio group key when pressed stays logically down until another key in the radio group is pressed, when the first key becomes logically up and the new key becomes logically down. Setting the XkbKB_RGAllowNone - bit in the behavior for all of the keys of the radio group means that pressing +bit in the behavior for all of the keys of the radio group means that pressing the logically down member of the radio group causes it to logically release, in which case none of the keys of the radio group would be logically down. If XkbKB_RGAllowNone - is not set, there is no way to release the logically down member of the group. +is not set, there is no way to release the logically down member of the group. The low five bits of the data - field of the +field of the XkbBehavior - structure are the group number, the high three bits are flags. The only flag +structure are the group number, the high three bits are flags. The only flag currently defined is: @@ -4059,11 +4059,11 @@ currently defined is: The behaviors - field of the server map is an array of +field of the server map is an array of XkbBehavior - structures, indexed by keycode, and contains the behavior for each key. The +structures, indexed by keycode, and contains the behavior for each key. The XkbBehavior - structure is defined as follows: +structure is defined as follows: typedef struct _XkbBehavior { @@ -4076,9 +4076,9 @@ typedef struct _XkbBehavior { The type - field specifies the Xkb behavior, and the value of the +field specifies the Xkb behavior, and the value of the data - field depends on the +field depends on the type. Xkb supports the key behaviors shown in Table 16.20. @@ -4102,7 +4102,7 @@ Xkb supports the key behaviors shown in Press and release events are processed normally. The data - field is unused. +field is unused. @@ -4114,7 +4114,7 @@ corresponding release is ignored. If the key is logically down when pressed, the key press is ignored but the corresponding release is processed normally. The data - field is unused. +field is unused. @@ -4124,7 +4124,7 @@ The If another member of the radio group is logically down (all members of the radio group have the same index, specified in data) - when a key is pressed, the server synthesizes a key release for the member +when a key is pressed, the server synthesizes a key release for the member that is logically down and then processes the new key press event normally. @@ -4132,7 +4132,7 @@ If the key itself is logically down when pressed, the key press event is ignored, but the processing of the corresponding key release depends on the value of the XkbKB_RGAllowNone - bit in +bit in flags. If it is set, the key release is processed normally; otherwise, the key release is also ignored. @@ -4147,12 +4147,12 @@ All other key release events are ignored. If the Overlay1 - control is enabled (see section 10.4), +control is enabled (see section 10.4), data - is interpreted as a keycode, and events from this key are reported as if they +is interpreted as a keycode, and events from this key are reported as if they came from data’s - keycode. Otherwise, press and release events are processed normally. +keycode. Otherwise, press and release events are processed normally. @@ -4160,12 +4160,12 @@ came from If the Overlay2 - control is enabled (see section 10.4), +control is enabled (see section 10.4), data - is interpreted as a keycode, and events from this key are reported as if they +is interpreted as a keycode, and events from this key are reported as if they came from data’s - keycode. Otherwise, press and release events are processed normally. +keycode. Otherwise, press and release events are processed normally. @@ -4175,13 +4175,13 @@ came from Xkb also provides the mask, XkbKB_Permanent - to specify whether the key behavior type should be simulated by Xkb or whether +to specify whether the key behavior type should be simulated by Xkb or whether the key behavior describes an unalterable physical, electrical, or software aspect of the keyboard. If the XkbKB_Permanent - bit is not set in the +bit is not set in the type - field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the +field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the keyboard to implement the behavior. @@ -4193,7 +4193,7 @@ keyboard to implement the behavior. To obtain the behaviors (the behaviors - array) for a subset of the keys in a keyboard description from the server, use +array) for a subset of the keys in a keyboard description from the server, use XkbGetKeyBehaviors: @@ -4260,17 +4260,17 @@ To obtain the behaviors (the XkbGetKeyBehaviors - sends a request to the server to obtain the behaviors for +sends a request to the server to obtain the behaviors for num - keys on the keyboard starting with the key whose keycode is +keys on the keyboard starting with the key whose keycode is first. It waits for a reply and returns the behaviors in the server->behaviors - field of +field of xkb. If successful, XkbGetKeyBehaviors - returns +returns Success. @@ -4278,11 +4278,11 @@ If successful, If the server - map in the +map in the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeyBehaviors - allocates and initializes it before obtaining the actions. +allocates and initializes it before obtaining the actions. @@ -4290,18 +4290,18 @@ If the If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbGetKeyBehaviors - returns +returns BadAccess. If num - is less than 1 or greater than +is less than 1 or greater than XkbMaxKeyCount, XkbGetKeyBehaviors - returns +returns BadValue. If any allocation errors occur, XkbGetKeyBehaviors - returns +returns BadAlloc. @@ -4331,7 +4331,7 @@ mapping. The explicit components masks are held in the explicit - field of the server map, which is an array indexed by keycode. Each entry in +field of the server map, which is an array indexed by keycode. Each entry in this array is a mask that is a bitwise inclusive OR of the values shown in Table 16.21. @@ -4403,9 +4403,9 @@ specified in a symbol interpretation. Automatic assignment of the XkbKB_Lock - behavior to the key, if the +behavior to the key, if the XkbSI_LockingKey - flag is set in a symbol interpretation. +flag is set in a symbol interpretation. @@ -4427,7 +4427,7 @@ match the key. To obtain the explicit components (the explicit - array) for a subset of the keys in a keyboard description, use +array) for a subset of the keys in a keyboard description, use XkbGetKeyExplicitComponents. @@ -4493,32 +4493,32 @@ To obtain the explicit components (the XkbGetKeyExplicitComponents - sends a request to the server to obtain the explicit components for +sends a request to the server to obtain the explicit components for num - keys on the keyboard starting with key +keys on the keyboard starting with key first. It waits for a reply and returns the explicit components in the server->explicit - array of +array of xkb. If successful, XkbGetKeyExplicitComponents - returns +returns Success. The xkb - parameter must be a pointer to a valid Xkb keyboard description. +parameter must be a pointer to a valid Xkb keyboard description. If the server - map in the +map in the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeyExplicitComponents - allocates and initializes it before obtaining the actions. +allocates and initializes it before obtaining the actions. @@ -4526,18 +4526,18 @@ If the If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbGetKeyExplicitComponents - returns +returns BadMatch. If num - is less than 1 or greater than +is less than 1 or greater than XkbMaxKeyCount, XkbGetKeyExplicitComponents - returns +returns BadValue. If any allocation errors occur, XkbGetKeyExplicitComponents - returns +returns BadAlloc. @@ -4550,12 +4550,12 @@ If any allocation errors occur, The vmods - member of the server map is a fixed-length array containing +member of the server map is a fixed-length array containing XkbNumVirtualMods - entries. Each entry corresponds to a virtual modifier and provides the binding +entries. Each entry corresponds to a virtual modifier and provides the binding of the virtual modifier to the real modifier bits. Each entry in the vmods - array is a bitwise inclusive OR of the legal modifier masks: +array is a bitwise inclusive OR of the legal modifier masks: @@ -4572,12 +4572,12 @@ of the virtual modifier to the real modifier bits. Each entry in the The vmodmap - member of the server map is similar to the +member of the server map is similar to the modmap - array of the client map (see section 15.4), but is used to define the virtual +array of the client map (see section 15.4), but is used to define the virtual modifier mapping for each key. Like the modmap - member, it is indexed by keycode, and each entry is a mask representing the +member, it is indexed by keycode, and each entry is a mask representing the virtual modifiers bound to the corresponding key: @@ -4586,23 +4586,23 @@ virtual modifiers bound to the corresponding key: Each of the bits in a vmodmap - entry represents an index into the +entry represents an index into the vmods - member. That is, bit 0 of a +member. That is, bit 0 of a vmodmap - entry refers to index 0 of the +entry refers to index 0 of the vmods - array, bit 1 refers to index 1, and so on. +array, bit 1 refers to index 1, and so on. If a bit is set in the vmodmap - entry for a key, that key is bound to the corresponding virtual modifier in +entry for a key, that key is bound to the corresponding virtual modifier in the vmods - array. +array. @@ -4610,9 +4610,9 @@ the The vmodmap - and +and vmods - members of the server map are the master virtual modifier definitions. Xkb +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. @@ -4644,7 +4644,7 @@ Virtual Modifier Relationships To obtain a subset of the virtual modifier bindings (the vmods - array) in a keyboard description, use +array) in a keyboard description, use XkbGetVirtualMods: @@ -4699,24 +4699,24 @@ To obtain a subset of the virtual modifier bindings (the XkbGetVirtualMods - sends a request to the server to obtain the +sends a request to the server to obtain the vmods - entries for the virtual modifiers specified in the mask, +entries for the virtual modifiers specified in the mask, which, and waits for a reply. See section 7.1 for a description of how to determine the virtual modifier mask. For each bit set in which, XkbGetVirtualMods - updates the corresponding virtual modifier definition in the +updates the corresponding virtual modifier definition in the server->vmods - array of +array of xkb. The xkb - parameter must be a pointer to a valid Xkb keyboard description. If +parameter must be a pointer to a valid Xkb keyboard description. If successful, XkbGetVirtualMods - returns +returns Success. @@ -4724,11 +4724,11 @@ successful, If the server - map has not been allocated in the +map has not been allocated in the xkb - parameter, +parameter, XkbGetVirtualMods - allocates and initializes it before obtaining the virtual modifier bindings. +allocates and initializes it before obtaining the virtual modifier bindings. @@ -4736,7 +4736,7 @@ If the If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbGetVirtualMods - returns +returns BadMatch. Any errors in allocation cause XkbGetVirtualMods @@ -4752,7 +4752,7 @@ to return To obtain the virtual modifier map (the vmodmap - array) for a subset of the keys in a keyboard description, use +array) for a subset of the keys in a keyboard description, use XkbGetKeyVirtualModMap: @@ -4821,30 +4821,30 @@ To obtain the virtual modifier map (the XkbGetKeyVirtualModmap sends a request to the server to obtain the virtual modifier mappings for num - keys on the keyboard starting with key +keys on the keyboard starting with key first. It waits for a reply and returns the virtual modifier mappings in the server->vmodmap - array of +array of xkb. If successful, XkbGetKeyVirtualModMap - returns +returns Success. The xkb - parameter must be a pointer to a valid Xkb keyboard description +parameter must be a pointer to a valid Xkb keyboard description If the server - map in the +map in the xkb - parameter has not been allocated, +parameter has not been allocated, XkbGetKeyVirtualModMap - allocates and initializes it before obtaining the virtual modifier mappings. +allocates and initializes it before obtaining the virtual modifier mappings. @@ -4852,18 +4852,18 @@ If the If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbGetKeyVirtualModMap - returns +returns BadMatch. If num - is less than 1 or greater than +is less than 1 or greater than XkbMaxKeyCount, XkbGetKeyVirtualModMap - returns +returns BadValue. If any allocation errors occur, XkbGetKeyVirtualModMap - returns +returns BadAlloc. diff --git a/specs/XKB/ch17.xml b/specs/XKB/ch17.xml index 6f9fa548..dcc2b214 100644 --- a/specs/XKB/ch17.xml +++ b/specs/XKB/ch17.xml @@ -46,12 +46,12 @@ maintains a core keyboard mapping that approximates the Xkb keyboard mapping. The core keyboard mapping may be updated piecemeal, on a per-key basis. When the server receives a core protocol ChangeKeyboardMapping - or +or SetModifierMapping - request, it updates its core keyboard mapping, then uses the compatibility map +request, it updates its core keyboard mapping, then uses the compatibility map to update its Xkb keyboard mapping. When the server receives an XkbSetMap - request, it updates those portions of its Xkb keyboard mapping specified by +request, it updates those portions of its Xkb keyboard mapping specified by the request, then uses its compatibility map to update the corresponding parts of its core keyboard map. Consequently, the server’s Xkb keyboard map and also its core keyboard map may contain components that were set directly and @@ -90,9 +90,9 @@ In addition, whenever the Xkb state is retrieved, the compat_grab_mods, and compat_lookup_mods - fields of the +fields of the XkbStateRec - returned indicate the result of applying the compatibility map to the current +returned indicate the result of applying the compatibility map to the current Xkb state in the server. @@ -102,9 +102,9 @@ Xkb state in the server. After core protocol requests received by the server to change the keyboard mapping (ChangeKeyboardMapping - and +and SetModifierMapping) - have been applied to the server’s core keyboard map, the results must be +have been applied to the server’s core keyboard map, the results must be transformed to achieve an equivalent change of the Xkb keyboard mapping maintained by the server. @@ -115,7 +115,7 @@ maintained by the server. After Xkb protocol requests received by the server to change the keyboard mapping (XkbSetMap) - have been applied to the server’s Xkb keyboard map, the results are +have been applied to the server’s Xkb keyboard map, the results are transformed to achieve an approximately equivalent change to the core keyboard mapping maintained by the server. @@ -138,7 +138,7 @@ All configurable aspects of mapping Xkb state and configuration to and from core protocol state and configuration are defined by a compatibility map, contained in an XkbCompatMapRec - structure; plus a set of explicit override controls used to prevent particular +structure; plus a set of explicit override controls used to prevent particular components of type 2 (core-to-Xkb keyboard mapping) transformations from automatically occurring. These explicit override controls are maintained in a separate data structure discussed in section 16.3. @@ -148,11 +148,11 @@ separate data structure discussed in Figure 17.3, there are four group compatibility map mapgroup compatibility - (contained in +(contained in groups - [0..3]) in the +[0..3]) in the XkbCompatMapRec - structure, one per possible Xkb group. Each group compatibility map is a +structure, one per possible Xkb group. Each group compatibility map is a modifier definition (see section 7.2 for a description of modifier definitions). The mask - component of the definition specifies which real modifiers should be set in +component of the definition specifies which real modifiers should be set in the core protocol state field when the corresponding group is active. Because only one group is active at any one time, only one of the four possible transformations is ever applied at any one point in time. If the device described by the XkbDescRec - does not support four groups, the extra groups fields are present, but +does not support four groups, the extra groups fields are present, but undefined. Normally, the Xkb-aware server reports keyboard state in the state - member of events such as a +member of events such as a KeyPress - event and +event and ButtonPress - event, encoded as follows: +event, encoded as follows: @@ -306,7 +306,7 @@ For each changed key, determine the number of symbols in each of the groups found in step 1a. There is one explicit override control associated with each of the four possible groups for each Xkb key, ExplicitKeyType1 - through +through ExplicitKeyType4. If no explicit override control is set for a group, the number of symbols used for that group from the core map is two. If the explicit override control @@ -324,7 +324,7 @@ group on the key. If the total number of symbols required by the Xkb map for a particular key needs more symbols than the core protocol map contains, the additional symbols are taken to be NoSymbol - keysyms appended to the end of the core set. If the core map contains more +keysyms appended to the end of the core set. If the core map contains more symbols than are needed by the Xkb map, trailing symbols in the core map are discarded. In the absence of an explicit override for group one or two, symbols are assigned in order by group; the first symbols in the core map are assigned @@ -380,7 +380,7 @@ the corresponding key definitions in the Xkb map. Apply symbol interpretations to modify key operation. This phase is completely skipped if the ExplicitInterpret - override control bit is set in the explicit controls mask for the Xkb key (see +override control bit is set in the explicit controls mask for the Xkb key (see section 16.3). @@ -406,11 +406,11 @@ apply a default interpretation. The symbol interpretations used in step 2 are configurable and may be specified using XkbSymInterpretRec - structures referenced by the +structures referenced by the sym_interpret - field of an +field of an XkbCompatMapRec - (see Figure 17.3). +(see Figure 17.3). @@ -423,7 +423,7 @@ Symbol interpretations are used to guide the X server when it modifies the Xkb keymap in step 2. An initial set of symbol interpretations is loaded by the server when it starts. A client may add new ones using XkbSetCompatMap - (see section 17.4). +(see section 17.4). @@ -459,21 +459,21 @@ typedef struct { If sym - is not +is not NULL, it limits the symbol interpretation to keys on which that particular keysym is selected by the modifiers matching the criteria specified by mods - and +and match. If sym - is +is NULL, the interpretation may be applied to any symbol selected on a key when the modifiers match the criteria specified by mods - and +and match. @@ -506,7 +506,7 @@ are to be interpreted. (0) None of the bits that are on in mods - can be set, but other bits can be. +can be set, but other bits can be. @@ -515,7 +515,7 @@ None of the bits that are on in mods Zero or more of the bits that are on in mods - can be set, as well as others. +can be set, as well as others. @@ -524,7 +524,7 @@ Zero or more of the bits that are on in One or more of the bits that are on in mods - can be set, as well as any others. +can be set, as well as any others. @@ -533,7 +533,7 @@ One or more of the bits that are on in All of the bits that are on in mods - must be set, but others may be set as well. +must be set, but others may be set as well. @@ -542,7 +542,7 @@ All of the bits that are on in All of the bits that are on in mods - must be set, and no other bits may be set. +must be set, and no other bits may be set. @@ -552,19 +552,19 @@ All of the bits that are on in In addition to the above bits, match - may contain the +may contain the XkbSI_LevelOneOnly - bit, in which case the modifier match criteria specified by +bit, in which case the modifier match criteria specified by mods - and +and match - applies only if +applies only if sym - is in level one of its group; otherwise, +is in level one of its group; otherwise, mods - and +and match - are ignored and the symbol matches a condition where no modifiers are set. +are ignored and the symbol matches a condition where no modifiers are set. @@ -620,7 +620,7 @@ is applied to modify the Xkb map as follows. The act - field specifies a single action to be bound to the symbol position; any key +field specifies a single action to be bound to the symbol position; any key event that selects the symbol causes the action to be taken. Valid actions are defined in section 16.1. @@ -629,23 +629,23 @@ defined in section 16.1. If the Xkb keyboard map for the key does not have its ExplicitVModMap - control set, the +control set, the XkbSI_LevelOneOnly - bit and symbol position are examined. If the +bit and symbol position are examined. If the XkbSI_LevelOneOnly - bit is not set in +bit is not set in match - or the symbol is in position G1L1, the +or the symbol is in position G1L1, the virtual_mod - field is examined. If +field is examined. If virtual_mod - is not +is not XkbNoModifier, virtual_mod - specifies a single virtual modifier to be added to the virtual modifier map +specifies a single virtual modifier to be added to the virtual modifier map for the key. virtual_mod - is specified as an index in the range [0..15]. +is specified as an index in the range [0..15]. @@ -663,11 +663,11 @@ field potentially specify additional behavior modifications: If the Xkb keyboard map for the key does not have its ExplicitAutoRepeat - control set, its auto repeat behavior is set based on the value of the +control set, its auto repeat behavior is set based on the value of the XkbSI_AutoRepeat - bit. If the +bit. If the XkbSI_AutoRepeat - bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is +bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is turned off. @@ -675,13 +675,13 @@ turned off. If the Xkb keyboard map for the key does not have its ExplicitBehavior - control set, its locking behavior is set based on the value of the +control set, its locking behavior is set based on the value of the XkbSI_LockingKey - bit. If +bit. If XkbSI_LockingKey - is set, the key behavior is set to +is set, the key behavior is set to KB_Lock; - otherwise, it is turned off (see section 16.3). +otherwise, it is turned off (see section 16.3). @@ -736,13 +736,13 @@ all of the real modifiers associated with any of the virtual modifiers bound to the key. In addition, if any of the actions associated with the key affect any component of the keyboard group, all of the modifiers in the mask - field of all of the group compatibility maps are added to the modifier mapping +field of all of the group compatibility maps are added to the modifier mapping as well. While an XkbSA_ISOLock - action can theoretically affect any modifier, if the Xkb mapping for a key +action can theoretically affect any modifier, if the Xkb mapping for a key specifies an XkbSA_ISOLock - action, only the modifiers or group that are set by default are added to the +action, only the modifiers or group that are set by default are added to the modifier mapping. @@ -755,13 +755,13 @@ modifier mapping. Use XkbGetCompatMap - to fetch any combination of the current compatibility map components from the +to fetch any combination of the current compatibility map components from the server. When another client modifies the compatibility map, you are notified if you have selected for XkbCompatMapNotify - events (see section 17.5). +events (see section 17.5). XkbGetCompatMap - is particularly useful when you receive an event of this type, as it allows +is particularly useful when you receive an event of this type, as it allows you to update your program’s version of the compatibility map to match the modified version now in the server. If your program is dealing with multiple servers and needs to configure them all in a similar manner, the updated @@ -819,17 +819,17 @@ explicit override components of the server state. XkbGetCompatMap - fetches the components of the compatibility map specified in +fetches the components of the compatibility map specified in which - from the server specified by +from the server specified by display - and places them in the +and places them in the compat - structure of the keyboard description +structure of the keyboard description xkb. Valid values for which - are an inclusive OR of the values shown in +are an inclusive OR of the values shown in Table 17.2. @@ -870,40 +870,40 @@ Valid values for If no compatibility map structure is allocated in xkb - upon entry, +upon entry, XkbGetCompatMap - allocates one. If one already exists, its contents are overwritten with the +allocates one. If one already exists, its contents are overwritten with the returned results. XkbGetCompatMap - fetches compatibility map information for the device specified by the +fetches compatibility map information for the device specified by the device_spec - field of +field of xkb. Unless you have specifically modified this field, it is the default keyboard device. XkbGetCompatMap - returns +returns Success - if successful, +if successful, BadAlloc - if it is unable to obtain necessary storage for either the return values or +if it is unable to obtain necessary storage for either the return values or work space, BadMatch - if the +if the dpy - field of the +field of the xkb - argument is non- +argument is non- NULL - and does not match the +and does not match the display - argument, and +argument, and BadLength - under certain conditions caused by server or Xkb implementation errors. +under certain conditions caused by server or Xkb implementation errors. @@ -1012,44 +1012,44 @@ format mapping by calling the function XkbUpdateMapFromCore - interprets input argument information representing a keyboard map in core +interprets input argument information representing a keyboard map in core format to update the Xkb keyboard description passed in xkb. Only a portion of the Xkb map is updated — the portion corresponding to keys with keycodes in the range first_key - through +through first_key - + ++ num_keys - - 1. If +- 1. If XkbUpdateMapFromCore - is being called in response to a +is being called in response to a MappingNotify event, first_key - and +and num_keys - are reported in the +are reported in the MappingNotify - event. +event. core_keysyms - contains the keysyms corresponding to the keycode range being updated, in core +contains the keysyms corresponding to the keycode range being updated, in core keyboard description order. map_width - is the number of keysyms per key in +is the number of keysyms per key in core_keysyms. Thus, the first map_width - entries in +entries in core_keysyms - are for the key with keycode +are for the key with keycode first_key, the next map_width - entries are for key +entries are for key first_key - + 1, and so on. ++ 1, and so on. @@ -1057,11 +1057,11 @@ the next In addition to modifying the Xkb keyboard mapping in xkb, XkbUpdateMapFromCore - backfills the changes structure whose address is passed in +backfills the changes structure whose address is passed in changes - to indicate the modifications that were made. You may then use +to indicate the modifications that were made. You may then use changes - in subsequent calls such as +in subsequent calls such as XkbSetMap, to propagate the local modifications to a server. @@ -1072,7 +1072,7 @@ When dealing with core keyboard mappings or descriptions, it is sometimes necessary to determine the Xkb key types appropriate for the symbols bound to a key in a core keyboard mapping. Use XkbKeyTypesForCoreSymbols - for this purpose: +for this purpose: @@ -1160,11 +1160,11 @@ key in a core keyboard mapping. Use XkbKeyTypesForCoreSymbols - expands the symbols in +expands the symbols in core_syms - and types in +and types in types_inout - according to the rules specified in section 12 of the core protocol, then +according to the rules specified in section 12 of the core protocol, then chooses canonical key types (canonical key types are defined in section 15.2.1) for groups 1 and 2 using the rules specified by the Xkb protocol and places them in @@ -1177,36 +1177,36 @@ which will be non- A core keymap is a two-dimensional array of keysyms. It has map_width - columns and +columns and max_key_code - rows. +rows. XkbKeyTypesForCoreSymbols - takes a single row from a core keymap, determines the number of groups +takes a single row from a core keymap, determines the number of groups associated with it, the type of each group, and the symbols bound to each group. The return value is the number of groups, types_inout - has the types for each group, and +has the types for each group, and xkb_syms_rtrn - has the symbols in Xkb order (that is, groups are contiguous, regardless of +has the symbols in Xkb order (that is, groups are contiguous, regardless of size). protected - contains the explicitly protected key types. There is one explicit override +contains the explicitly protected key types. There is one explicit override control associated with each of the four possible groups for each Xkb key, ExplicitKeyType1 - through +through ExplicitKeyType4; protected is an inclusive OR of these controls. map_width - is the width of the core keymap and is not dependent on any Xkb definitions. +is the width of the core keymap and is not dependent on any Xkb definitions. types_inout - is an array of four type indices. On input, +is an array of four type indices. On input, types_inout - contains the indices of any types already assigned to the key, in case they +contains the indices of any types already assigned to the key, in case they are explicitly protected from change. @@ -1214,11 +1214,11 @@ are explicitly protected from change. Upon return, types_inout - contains any automatically selected (that is, canonical) types plus any +contains any automatically selected (that is, canonical) types plus any protected types. Canonical types are assigned to all four groups if there are enough symbols to do so. The four entries in types_inout - correspond to the four groups for the key in question. +correspond to the four groups for the key in question. @@ -1281,7 +1281,7 @@ semantics updated, use XkbApplyCompatMapToKey - essentially performs the operation described in section 17.1.2 to a specific +essentially performs the operation described in section 17.1.2 to a specific key. This updates the behavior, actions, repeat status, and virtual modifier bindings of the key. @@ -1297,17 +1297,17 @@ Xkb compatibility map, then call XkbSetCompatMap. You may allocate a new compatibility map for this purpose using XkbAllocCompatMap - (see section 17.6). You may also use a compatibility map from another server, +(see section 17.6). You may also use a compatibility map from another server, although you need to adjust the device_spec - field in the +field in the XkbDescRec - accordingly. Note that symbol interpretations in a compatibility map +accordingly. Note that symbol interpretations in a compatibility map ( sym_interpret, the vector of XkbSymInterpretRec - structures) are also allocated using this same function. +structures) are also allocated using this same function. XkbSetCompatMap @@ -1369,18 +1369,18 @@ the vector of XkbSetCompatMap - copies compatibility map information from the keyboard description in +copies compatibility map information from the keyboard description in xkb - to the server specified in +to the server specified in display’s - compatibility map for the device specified by the +compatibility map for the device specified by the device_spec - field of +field of xkb. Unless you have specifically modified this field, it is the default keyboard device. which - specifies the compatibility map components to be set, and is an inclusive OR +specifies the compatibility map components to be set, and is an inclusive OR of the bits shown in Table 17.2. @@ -1388,13 +1388,13 @@ of the bits shown in Table 17.2. After updating its compatibility map for the specified device, if update_actions - is +is True, - the server applies the new compatibility map to its entire keyboard for the +the server applies the new compatibility map to its entire keyboard for the device to generate a new set of key semantics, compatibility state, and a new core keyboard map. If update_actions - is +is False, the new compatibility map is not used to generate any modifications to the current device semantics, state, or core keyboard map. One reason for not @@ -1402,22 +1402,22 @@ applying the compatibility map immediately would be if one server was being configured to match another on a piecemeal basis; the map should not be applied until everything is updated. To force an update at a later time, use XkbSetCompatMap - specifying +specifying which - as zero and +as zero and update_actions - as +as True. XkbSetCompatMap - returns +returns True - if successful and +if successful and False - if unsuccessful. The server may report problems it encounters when processing +if unsuccessful. The server may report problems it encounters when processing the request subsequently via protocol errors. @@ -1489,27 +1489,27 @@ use XkbAddSymInterpret - adds +adds si - to the list of symbol interpretations in +to the list of symbol interpretations in xkb. If updateMap - is +is True, it (re)applies the compatibility map to all of the keys on the keyboard. If changes - is non- +is non- NULL, it reports the parts of the keyboard that were affected (unless updateMap - is +is True, not much changes). XkbAddSymInterpret - returns a pointer to the actual new symbol interpretation in the list or +returns a pointer to the actual new symbol interpretation in the list or NULL - if it failed. +if it failed. @@ -1524,31 +1524,31 @@ not much changes). The server automatically generates MappingNotify - events when the keyboard mapping changes. If you wish to be notified of +events when the keyboard mapping changes. If you wish to be notified of changes to the compatibility map, you should select for XkbCompatMapNotify - events. If you select for +events. If you select for XkbMapNotify - events, you no longer receive the automatically generated +events, you no longer receive the automatically generated MappingNotify - events. If you subsequently deselect +events. If you subsequently deselect XkbMapNotifyEvent - delivery, you again receive +delivery, you again receive MappingNotify - events. +events. To receive XkbCompatMapNotify - events under all possible conditions, use +events under all possible conditions, use XkbSelectEvents - (see section 4.3) and pass +(see section 4.3) and pass XkbCompatMapNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -1556,17 +1556,17 @@ To receive To receive XkbCompatMapNotify - events only under certain conditions, use +events only under certain conditions, use XkbSelectEventDetails - using +using XkbCompatMapNotify - as the +as the event_type - and specifying the desired map changes in +and specifying the desired map changes in bits_to_change - and +and values_for_bits - using mask bits from Table 17.2. +using mask bits from Table 17.2. @@ -1579,7 +1579,7 @@ made by other clients. The structure for the XkbCompatMapNotifyEvent - is: +is: typedef struct { @@ -1604,28 +1604,28 @@ typedef struct { changed_groups - is the number of group compatibility maps that have changed. If you are +is the number of group compatibility maps that have changed. If you are maintaining a corresponding copy of the compatibility map, or get a fresh copy from the server using XkbGetCompatMap, changed_groups - references +references groups [0.. changed_groups -1] in the XkbCompatMapRec - structure. +structure. first_si - is the index of the first changed symbol interpretation, +is the index of the first changed symbol interpretation, num_si - is the number of changed symbol interpretations, and +is the number of changed symbol interpretations, and num_total_si - is the total number of valid symbol interpretations. If you are maintaining a +is the total number of valid symbol interpretations. If you are maintaining a corresponding copy of the compatibility map, or get a fresh copy from the server using XkbGetCompatMap, @@ -1633,9 +1633,9 @@ server using num_si, and num_total_si - are appropriate for use with the +are appropriate for use with the compat.sym_interpret - vector in this structure. +vector in this structure. @@ -1697,27 +1697,27 @@ compatibility map if you do not already have one available. To do so, use xkb - specifies the keyboard description for which compatibility maps are to be +specifies the keyboard description for which compatibility maps are to be allocated. The compatibility map is the compat - field in this structure. +field in this structure. which - specifies the compatibility map components to be allocated (see +specifies the compatibility map components to be allocated (see XkbGetCompatMap, in section 17.2). which - is an inclusive OR of the bits shown in +is an inclusive OR of the bits shown in Table 17.2. num_si - specifies the total number of entries to allocate in the symbol interpretation +specifies the total number of entries to allocate in the symbol interpretation vector (xkb.compat.sym_interpret). @@ -1727,34 +1727,34 @@ vector Note that symbol interpretations in a compatibility map (the sym_interpret - vector of +vector of XkbSymInterpretRec - structures) are also allocated using this same function. To ensure that there +structures) are also allocated using this same function. To ensure that there is sufficient space in the symbol interpretation vector for entries to be added, use XkbAllocCompatMap - specifying +specifying which - as +as XkbSymInterpretMask - and the number of free symbol interpretations needed in +and the number of free symbol interpretations needed in num_si. XkbAllocCompatMap - returns +returns Success - if successful, +if successful, BadMatch - if +if xkb - is +is NULL, or BadAlloc - if errors are encountered when attempting to allocate storage. +if errors are encountered when attempting to allocate storage. @@ -1813,33 +1813,33 @@ To free an entire compatibility map or selected portions of one, use which - specifies the compatibility map components to be freed (see +specifies the compatibility map components to be freed (see XkbGetCompatMap, in section 17.2). which - is an inclusive OR of the bits shown in +is an inclusive OR of the bits shown in Table 17.2 free_map - indicates whether the +indicates whether the XkbCompatMapRec - structure itself should be freed. If +structure itself should be freed. If free_map - is +is True, which - is ignored, all non- +is ignored, all non- NULL - compatibility map components are freed, and the +compatibility map components are freed, and the compat - field in the +field in the XkbDescRec - referenced by +referenced by xkb - is set to +is set to NULL. diff --git a/specs/XKB/ch18.xml b/specs/XKB/ch18.xml index 55e63015..0f283ecf 100644 --- a/specs/XKB/ch18.xml +++ b/specs/XKB/ch18.xml @@ -13,9 +13,9 @@ the type of keyboard connected to the server and then examine keysyms and modifier mappings to determine the effects of most modifiers (the Shift, Lock - and +and Control - modifiers are defined by the core protocol but no semantics are implied for +modifiers are defined by the core protocol but no semantics are implied for any other modifiers). @@ -25,7 +25,7 @@ To make it easier for applications to present a keyboard to the user, Xkb supports symbolic names for most components of the keyboard extension. Most of these symbolic names are grouped into the names - component of the keyboard description. +component of the keyboard description. @@ -89,10 +89,10 @@ typedef struct _XkbNamesRec { The keycodes - name identifies the range and meaning of the keycodes returned by the keyboard +name identifies the range and meaning of the keycodes returned by the keyboard in question. The geometry - name, on the other hand, identifies the physical location, size and shape of +name, on the other hand, identifies the physical location, size and shape of the various keys on the keyboard. As an example to distinguish between these two names, consider function keys on PC-compatible keyboards. Function keys are sometimes above the main keyboard and sometimes to the left of the main @@ -107,33 +107,33 @@ keyboards with differing numbers of keys provided all keys have the same semantics when present. For example, 101 and 102 key PC keyboards might use the same name. In these cases, applications can use the keyboard geometry - name to determine which subset of the named keycodes is in use. +name to determine which subset of the named keycodes is in use. The symbols - name identifies the symbols logically bound to the keys. The symbols name is a +name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or usage of the keyboard with these symbols. The phys_symbols - name, on the other hand, identifies the symbols actually engraved on the +name, on the other hand, identifies the symbols actually engraved on the keyboard. Given this, the symbols - name and +name and phys_symbols - names might be different. For example, the description for a keyboard that has +names might be different. For example, the description for a keyboard that has English US engravings, but that is using Swiss German symbols might have a phys_symbols - name of "en_US" and a +name of "en_US" and a symbols - name of "de_CH." +name of "de_CH." The types - name provides some information about the set of key types (see section 15.2) +name provides some information about the set of key types (see section 15.2) that can be associated with the keyboard. In addition, each key type can have a name, and each shift level of a type can have a name. Although these names are stored in the map description with each of the types, they are accessed using @@ -144,7 +144,7 @@ the same methods as the other symbolic names. The compat - name provides some information about the rules used to bind actions to keys +name provides some information about the rules used to bind actions to keys that are changed using core protocol requests. @@ -157,7 +157,7 @@ in the indicators, and groups - fixed-length arrays. +fixed-length arrays. @@ -165,13 +165,13 @@ and Each key has a four-byte symbolic name. All of the symbolic key names are held in the keys - array, and +array, and num_keys - reports the number of entries that are in the keys array. For each key, the +reports the number of entries that are in the keys array. For each key, the key name links keys with similar functions or in similar positions on keyboards that report different keycodes. For example, the F1 - key may emit keycode 23 on one keyboard and keycode 86 on another. By naming +key may emit keycode 23 on one keyboard and keycode 86 on another. By naming this key "FK01" on both keyboards, the keyboard layout designer can reuse parts of keyboard descriptions for different keyboards. @@ -186,20 +186,20 @@ designer may wish to refer to the left arrow key on a PC keyboard using the ISO9995-5 positional specification of A31 or using the functional specification of LEFT. The key_aliases - field holds a variable-length array of real and alias key name pairs, and the +field holds a variable-length array of real and alias key name pairs, and the total number of entries in the key_aliases - array is held in +array is held in num_key_aliases. For each real and alias key name pair, the real - field refers to the a name in the keys array, and the +field refers to the a name in the keys array, and the alias - field refers to the alias for that key. Using the previous example, the +field refers to the alias for that key. Using the previous example, the keyboard designer may use the name A31 in the keys array, but also define the name LEFT as an alias for A31 in the key_aliases - array. +array. Key aliases defined in the geometry component of a keyboard mapping @@ -208,7 +208,7 @@ database, which are stored in the XkbNamesRec (xkb->names). - Therefore, consider the key aliases defined by the geometry before +Therefore, consider the key aliases defined by the geometry before considering key aliases supplied by the XkbNamesRec. @@ -228,9 +228,9 @@ held in the variable-length array radio_groups, and num_rg - tells how many elements are in the +tells how many elements are in the radio_groups - array. +array. @@ -426,12 +426,12 @@ To obtain symbolic names from the server, use XkbGetNames - retrieves symbolic names for the components of the keyboard extension from the +retrieves symbolic names for the components of the keyboard extension from the X server. The which - parameter specifies the name components to be updated in the +parameter specifies the name components to be updated in the xkb - parameter, and is the bitwise inclusive OR of the valid names mask bits +parameter, and is the bitwise inclusive OR of the valid names mask bits defined in Table 18.1. @@ -439,25 +439,25 @@ defined in Table 18.1. If the names - field of the keyboard description +field of the keyboard description xkb - is +is NULL, XkbGetNames - allocates and initializes the +allocates and initializes the names - component of the keyboard description before obtaining the values specified by +component of the keyboard description before obtaining the values specified by which. If the names - field of +field of xkb - is not +is not NULL, XkbGetNames - obtains the values specified by +obtains the values specified by which - and copies them into the keyboard description +and copies them into the keyboard description xkb. @@ -465,23 +465,23 @@ If the If the map - component of the +component of the xkb - parameter is +parameter is NULL, XkbGetNames - does not retrieve type or shift level names, even if +does not retrieve type or shift level names, even if XkbKeyTypeNamesMask - or +or XkbKTLevelNamesMask - are set in +are set in which. XkbGetNames - can return +can return Success, or BadAlloc, @@ -489,14 +489,14 @@ or BadMatch, and BadImplementation - errors. +errors. To free symbolic names, use XkbFreeNames - (see section 18.6) +(see section 18.6) @@ -508,22 +508,22 @@ To free symbolic names, use To change the symbolic names in the server, first modify a local copy of the keyboard description and then use either XkbSetNames, - or, to save network traffic, use a +or, to save network traffic, use a XkbNameChangesRec structure and call XkbChangeNames - to download the changes to the server. +to download the changes to the server. XkbSetNames - and +and XkbChangeNames - can generate +can generate BadAlloc, BadAtom, BadLength, BadMatch, - and +and BadImplementation - errors. +errors. XkbSetNames @@ -597,42 +597,42 @@ structure and call Use XkbSetNames - to change many names at the same time. For each bit set in +to change many names at the same time. For each bit set in which, XkbSetNames - takes the corresponding value (or values in the case of arrays) from the +takes the corresponding value (or values in the case of arrays) from the keyboard description xkb - and sends it to the server. +and sends it to the server. The first_type - and +and num_types - arguments are used only if +arguments are used only if XkbKeyTypeNamesMask - or +or XkbKTLevelNamesMask - is set in +is set in which - and specify a subset of the types for which the corresponding names are to be +and specify a subset of the types for which the corresponding names are to be changed. If either or both of these mask bits are set but the specified types are illegal, XkbSetNames - returns +returns False - and does not update any of the names specified in +and does not update any of the names specified in which. The specified types are illegal if xkb - does not include a map component or if +does not include a map component or if first_type - and +and num_types - specify types that are not defined in the keyboard description. +specify types that are not defined in the keyboard description. @@ -647,7 +647,7 @@ The specified types are illegal if The XkbNameChangesRec - allows applications to identify small modifications to the symbolic names and +allows applications to identify small modifications to the symbolic names and effectively reduces the amount of traffic sent to the server: @@ -678,7 +678,7 @@ typedef struct _XkbNameChanges { The changed - field specifies the name components that have changed and is the bitwise +field specifies the name components that have changed and is the bitwise inclusive OR of the valid names mask bits defined in Table 18.1. The rest of the fields in the structure specify the ranges that have changed for the @@ -766,11 +766,11 @@ various kinds of symbolic names, as shown in XkbChangeNames - provides a more flexible method for changing symbolic names than +provides a more flexible method for changing symbolic names than XkbSetNames - and requires the use of an +and requires the use of an XkbNameChangesRec - structure. +structure. XkbChangeNames @@ -821,16 +821,16 @@ various kinds of symbolic names, as shown in XkbChangeNames - copies any names specified by +copies any names specified by changes - from the keyboard description, +from the keyboard description, xkb, to the X server specified by dpy. XkbChangeNames - aborts and returns +aborts and returns False - if any illegal type names or type shift level names are specified by +if any illegal type names or type shift level names are specified by changes. @@ -848,15 +848,15 @@ to the X server specified by Whenever a symbolic name changes in the server’s keyboard description, the server sends a XkbNamesNotify - event to all interested clients. To receive name notify events, use +event to all interested clients. To receive name notify events, use XkbSelectEvents - (see section 4.3) with +(see section 4.3) with XkbNamesNotifyMask - in both the +in both the bits_to_change - and +and values_for_bits - parameters. +parameters. @@ -865,13 +865,13 @@ To receive events for only specific names, use XkbSelectEventDetails. Set the event_type - parameter to +parameter to XkbNamesNotify, and set both the bits_to_change and values_for_bits - detail parameter to a mask composed of a bitwise OR of masks in +detail parameter to a mask composed of a bitwise OR of masks in Table 18.1. @@ -879,7 +879,7 @@ and The structure for the XkbNamesNotify - event is defined as follows: +event is defined as follows: typedef struct { @@ -915,7 +915,7 @@ typedef struct { The changed - field specifies the name components that have changed and is the bitwise +field specifies the name components that have changed and is the bitwise inclusive OR of the valid names mask bits defined in Table 18.1. The other fields in this event are interpreted as the like-named fields in an @@ -926,7 +926,7 @@ fields in this event are interpreted as the like-named fields in an When your application receives a XkbNamesNotify - event, you can note the changed names in a changes structure using +event, you can note the changed names in a changes structure using XkbNoteNameChanges. @@ -981,14 +981,14 @@ When your application receives a The wanted - parameter is the bitwise inclusive OR of the valid names mask bits shown in +parameter is the bitwise inclusive OR of the valid names mask bits shown in Table 18.1. XkbNoteNameChanges - copies any changes that are reported in +copies any changes that are reported in new - and specified in +and specified in wanted - into the changes record specified by +into the changes record specified by old. @@ -997,7 +997,7 @@ The To update the local copy of the keyboard description with the actual values, pass to XkbGetNameChanges - the results of one or more calls to +the results of one or more calls to XkbNoteNameChanges. @@ -1052,23 +1052,23 @@ pass to XkbGetNameChanges - examines the +examines the changes - parameter, retrieves the necessary information from the server, and places the +parameter, retrieves the necessary information from the server, and places the results into the xkb - keyboard description. +keyboard description. XkbGetNameChanges - can generate +can generate BadAlloc, BadImplementation, - and +and BadMatch - errors. +errors. @@ -1080,9 +1080,9 @@ results into the Most applications do not need to directly allocate symbolic names structures. Do not allocate a names structure directly using malloc - or +or Xmalloc - if your application changes the number of key aliases or radio groups or +if your application changes the number of key aliases or radio groups or constructs a symbolic names structure without loading the necessary components from the X server. Instead use XkbAllocNames. @@ -1146,15 +1146,15 @@ from the X server. Instead use XkbAllocNames - can return +can return BadAlloc, BadMatch, - and +and BadValue - errors. +errors. The which - parameter is the bitwise inclusive OR of the valid names mask bits defined in +parameter is the bitwise inclusive OR of the valid names mask bits defined in Table 18.1. @@ -1162,11 +1162,11 @@ The Do not free symbolic names structures directly using free - or +or XFree. Use XkbFreeNames - instead. +instead. @@ -1219,7 +1219,7 @@ Use The which - parameter is the bitwise inclusive OR of the valid names mask bits defined in +parameter is the bitwise inclusive OR of the valid names mask bits defined in Table 18.1. diff --git a/specs/XKB/ch19.xml b/specs/XKB/ch19.xml index 756c83a9..faa62a27 100644 --- a/specs/XKB/ch19.xml +++ b/specs/XKB/ch19.xml @@ -24,9 +24,9 @@ input extension keyboard device as the X keyboard, in which case the old X keyboard device becomes inaccessible except via the input device extension. In this case, core protocol MappingNotify - and input extension +and input extension XChangeDeviceNotify - events are generated to notify all clients that a new keyboard with a new +events are generated to notify all clients that a new keyboard with a new keymap has been designated. @@ -43,14 +43,14 @@ for the client. Xkb provides an XkbNewKeyboardNotify - event that reports a change in keyboard geometry and/or the range of supported +event that reports a change in keyboard geometry and/or the range of supported keycodes. The server can generate an XkbNewKeyboardNotify - event when it detects a new keyboard or in response to an +event when it detects a new keyboard or in response to an XkbGetKeyboardByName - request that loads a new keyboard description. Selecting for +request that loads a new keyboard description. Selecting for XkbNewKeyboardNotify - events allows Xkb-aware clients to be notified whenever a keyboard change +events allows Xkb-aware clients to be notified whenever a keyboard change occurs that may affect the keymap. @@ -58,11 +58,11 @@ occurs that may affect the keymap. When a client requests XkbNewKeyboardNotify - events, the server compares the range of keycodes for the current keyboard to +events, the server compares the range of keycodes for the current keyboard to the range of keycodes that are valid for the client. If they are not the same, the server immediately sends the client an XkbNewKeyboardNotify - event. Even if the new keyboard is not new to the server, +event. Even if the new keyboard is not new to the server, it is new to this particular client. @@ -70,14 +70,14 @@ it is new to this particular client. When the server sends an XkbNewKeyboardNotify - event to a client to inform it of a new keycode range, it resets the stored +event to a client to inform it of a new keycode range, it resets the stored range of legal keycodes for the client to the keycode range reported in the event; it does not reset this range for the client if it does not sent an XkbNewKeyboardNotify - event to a client. Because Xkb-unaware clients and Xkb-aware clients that do +event to a client. Because Xkb-unaware clients and Xkb-aware clients that do not request XkbNewKeyboardNotify - events are never sent these events, the server’s notion of the legal keycode +events are never sent these events, the server’s notion of the legal keycode range never changes, and these clients never receive events from keys that fall outside of their notion of the legal keycode range. @@ -86,9 +86,9 @@ outside of their notion of the legal keycode range. Clients that have not selected to receive XkbNewKeyboardNotify - events do, however, receive the +events do, however, receive the XkbNewKeyboardNotify - event when a keyboard change occurs. Clients that have not selected to receive +event when a keyboard change occurs. Clients that have not selected to receive this event also receive numerous other events detailing the individual changes that occur when a keyboard change occurs. @@ -97,19 +97,19 @@ that occur when a keyboard change occurs. Clients wishing to track changes in min_key_code - and +and max_key_code - must watch for both +must watch for both XkbNewKeyboardNotify - and +and XkbMapNotify - events, because a simple mapping change causes an +events, because a simple mapping change causes an XkbMapNotify - event and may change the range of valid keycodes, but does not cause an +event and may change the range of valid keycodes, but does not cause an XkbNewKeyboardNotify - event. If a client does not select for +event. If a client does not select for XkbNewKeyboardNotify - events, the server restricts the range of keycodes reported to the client. +events, the server restricts the range of keycodes reported to the client. @@ -122,7 +122,7 @@ In addition to filtering out-of-range key events, Xkb: Adjusts core protocol MappingNotify - events to refer only to keys that match the stored legal range. +events to refer only to keys that match the stored legal range. @@ -130,7 +130,7 @@ Adjusts core protocol Reports keyboard mappings for keys that match the stored legal range to clients that issue a core protocol GetKeyboardMapping - request. +request. @@ -138,16 +138,16 @@ that issue a core protocol Reports modifier mappings only for keys that match the stored legal range to clients that issue a core protocol GetModifierMapping - request. +request. Restricts the core protocol ChangeKeyboardMapping - and +and SetModifierMapping - requests to keys that fall inside the stored legal range. +requests to keys that fall inside the stored legal range. @@ -168,7 +168,7 @@ Xkb events are discarded, and no Xkb requests have their keycode range clamped. The structure for the XkbNewKeyboardNotify - event is defined as follows: +event is defined as follows: typedef struct _XkbNewKeyboardNotify { @@ -193,23 +193,23 @@ typedef struct _XkbNewKeyboardNotify { To receive name notify events, use XkbSelectEvents - (see section 4.3) with +(see section 4.3) with XkbNewKeyboardNotifyMask - in both the +in both the bits_to_change - and +and values_for_bits - parameters. To receive events for only specific names, use +parameters. To receive events for only specific names, use XkbSelectEventDetails. Set the event_type - parameter to +parameter to XkbNewKeyboardNotify, and set both the bits_to_change and values_for_bits - detail parameter to a mask composed of a bitwise OR of masks in +detail parameter to a mask composed of a bitwise OR of masks in Table 19.1. @@ -255,33 +255,33 @@ and The req_major - and +and req_minor - fields indicate what type of keyboard change has occurred. +fields indicate what type of keyboard change has occurred. If req_major - and +and req_minor - are zero, the device change was not caused by a software request to the server +are zero, the device change was not caused by a software request to the server — a spontaneous change has occurred, such as hot-plugging a new device. In this case, device - is the device identifier for the new, current X keyboard device, but no +is the device identifier for the new, current X keyboard device, but no implementation-independent guarantee can be made about old_device. old_device - may be identical to +may be identical to device - (an implementor is permitted to reuse the device specifier when the device +(an implementor is permitted to reuse the device specifier when the device changes); or it may be different. Note that req_major - and +and req_minor - being zero do not necessarily mean that the physical keyboard device has +being zero do not necessarily mean that the physical keyboard device has changed; rather, they only imply a spontaneous change outside of software control (some systems have keyboards that can change personality at the press of a key). @@ -291,40 +291,40 @@ of a key). If the keyboard change is the result of an X Input Extension ChangeKeyboardDevice - request, +request, req_major - contains the input extension major opcode, and +contains the input extension major opcode, and req_minor - contains the input extension request number for +contains the input extension request number for X_ChangeKeyboardDevice. In this case, device - and +and old_device - are different, with +are different, with device - being the identifier for the new, current X keyboard device, and +being the identifier for the new, current X keyboard device, and old_device - being the identifier for the former device. +being the identifier for the former device. If the keyboard change is the result of an XkbGetKeyboardByName - function call, which generates an +function call, which generates an X_kbGetKbdByName - request, +request, req_major - contains the Xkb extension base event code (see section 2.4), and +contains the Xkb extension base event code (see section 2.4), and req_minor - contains the event code for the Xkb extension request +contains the event code for the Xkb extension request X_kbGetKbdByName. device - contains the device identifier for the new device, but nothing definitive can +contains the device identifier for the new device, but nothing definitive can be said for old_device; - it may be identical to +it may be identical to device, or it may be different, depending on the implementation. diff --git a/specs/XKB/ch20.xml b/specs/XKB/ch20.xml index 1f5c8f15..33501fb7 100644 --- a/specs/XKB/ch20.xml +++ b/specs/XKB/ch20.xml @@ -99,7 +99,7 @@ used to refer to either individual components or a keymap. There may be multiple entries for each of the component types. An entry may be either complete - or +or partial. Partial entries describe only a piece of the corresponding keyboard component and are designed to be combined with other entries of the same type to form a @@ -113,7 +113,7 @@ useful on its own because it does not include those symbols that are the same on both the ASCII and national layouts (such as function keys). On the other hand, this partial map can be used to configure any - ASCII keyboard to use a national layout. +ASCII keyboard to use a national layout. @@ -128,15 +128,15 @@ later definitions override earlier ones. Component names have the form “class(member)” where class - describes a subset of the available components for a particular type and the +describes a subset of the available components for a particular type and the optional member - identifies a specific component from that subset. For example, the name +identifies a specific component from that subset. For example, the name "atlantis(acme)" for a symbols component might specify the symbols used for the atlantis national keyboard layout by the vendor "acme." Each class has an optional default - member — references that specify a class but not a member refer to the +member — references that specify a class but not a member refer to the default member of the class, if one exists. Xkb places no constraints on the interpretation of the class and member names used in component names. @@ -144,9 +144,9 @@ interpretation of the class and member names used in component names. The class - and +and member - names are both specified using characters from the Latin-1 character set. Xkb +names are both specified using characters from the Latin-1 character set. Xkb implementations must accept all alphanumeric characters, minus (‘-’) and underscore (‘_’) in class or member names, and must not accept parentheses, plus, vertical bar, percent sign, asterisk, question mark, or white space. The @@ -227,15 +227,15 @@ To obtain this list, use XkbListComponents - queries the server for a list of component names matching the patterns +queries the server for a list of component names matching the patterns specified in ptrns. It waits for a reply and returns the matching component names in an XkbComponentListRec - structure. When you are done using the structure, you should free it using +structure. When you are done using the structure, you should free it using XkbFreeComponentList. device_spec - indicates a particular device in which the caller is interested. A server is +indicates a particular device in which the caller is interested. A server is allowed (but not required) to restrict its reply to portions of the database that are relevant for that particular device. @@ -243,14 +243,14 @@ that are relevant for that particular device. ptrns - is a pointer to an +is a pointer to an XkbComponentNamesRec, described below. Each of the fields in ptrns - contains a pattern naming the components of interest. Each of the patterns is +contains a pattern naming the components of interest. Each of the patterns is composed of characters from the ISO Latin1 - encoding, but can contain only parentheses, the wildcard characters +encoding, but can contain only parentheses, the wildcard characters ‘?’ and ‘*’, and characters permitted in a component class or member name (see section 20.1). A pattern may be @@ -277,12 +277,12 @@ from the pattern. max_inout - is used to throttle the amount of data passed to and from the server. On +is used to throttle the amount of data passed to and from the server. On input, it specifies the maximum number of names to be returned (the total number of names in all component categories). Upon return from XkbListComponents, max_inout - contains the number of names that matched the request but were not returned +contains the number of names that matched the request but were not returned because of the limit. @@ -292,15 +292,15 @@ because of the limit. XkbComponentNamesRec The component name patterns used to describe the request are passed to XkbListComponents - using an +using an XkbComponentNamesRec - structure. This structure has no special allocation constraints or +structure. This structure has no special allocation constraints or interrelationships with other structures; allocate and free this structure using standard malloc - and +and free - calls or their equivalent: +calls or their equivalent: typedef struct _XkbComponentNames { @@ -319,7 +319,7 @@ typedef struct _XkbComponentNames { XkbComponentNameRec XkbListComponents - returns a pointer to an +returns a pointer to an XkbComponentListRec: @@ -349,7 +349,7 @@ Note that the structure used to specify patterns on input is an XkbComponentNamesRec, and that used to hold the individual component names upon return is an XkbComponentNameRec - (no trailing ‘s’ in Name). +(no trailing ‘s’ in Name). @@ -393,9 +393,9 @@ A set of flags is associated with each component; these flags provide additional hints about the component’s use. These hints are designated by bit masks in the flags field of the XkbComponentNameRec - structures contained in the +structures contained in the XkbComponentListRec - returned from +returned from XkbListComponents. The least significant byte of the flags field has the same meaning for all types of keyboard components; the interpretation of the most significant byte @@ -405,7 +405,7 @@ The symbols hints in Table 20.2 apply only to partial symbols components (those with XkbLC_Partial - also set); full symbols components are assumed to specify all of the pieces. +also set); full symbols components are assumed to specify all of the pieces. @@ -416,10 +416,10 @@ an exhaustive list of the kinds of keys that are affected. For example, national keyboard layouts affect primarily alphanumeric keys, but many affect a few modifier keys as well; such mappings should set only the XkbLC_AlphanumericKeys - hint. In general, symbols components should set only one of the four flags +hint. In general, symbols components should set only one of the four flags ( XkbLC_AlternateGroup - may be combined with any of the other flags). +may be combined with any of the other flags).
@@ -632,12 +632,12 @@ one, use names - contains a set of expressions describing the keyboard components the server +contains a set of expressions describing the keyboard components the server should use to build the new keyboard description. want - and +and need - are bit fields describing the parts of the resulting keyboard description that +are bit fields describing the parts of the resulting keyboard description that should be present in the returned XkbDescRec. @@ -646,9 +646,9 @@ should be present in the returned The individual fields in names - are +are component expressions - composed of keyboard component names (no wildcarding as may be used in +composed of keyboard component names (no wildcarding as may be used in XkbListComponents), the special component name symbol ‘%’, and the special operator characters @@ -662,7 +662,7 @@ A component expression is parsed left to right, as follows: The special component name “computed” may be used in keycodes - component expressions and refers to a component consisting of a set of +component expressions and refers to a component consisting of a set of keycodes computed automatically by the server as needed. @@ -670,7 +670,7 @@ keycodes computed automatically by the server as needed. The special component name “canonical” may be used in types - component expressions and refers to a partial component defining the four +component expressions and refers to a partial component defining the four standard key types: ALPHABETIC, ONE_LEVEL, @@ -684,7 +684,7 @@ and The special component name ‘%’ refers to the keyboard description for the device specified in device_spec - or the keymap names component. If a keymap names component is specified that +or the keymap names component. If a keymap names component is specified that does not begin with ‘+’ or ‘|’ and does not contain ‘%’, then ‘%’ @@ -696,18 +696,18 @@ Otherwise, it refers to the keyboard description for The ‘+’ - operator specifies that the following component should +operator specifies that the following component should override - the currently assembled description; any definitions that are present in both +the currently assembled description; any definitions that are present in both components are taken from the second. The ‘|’ - operator specifies that the next specified component should +operator specifies that the next specified component should augment - the currently assembled description; any definitions that are present in both +the currently assembled description; any definitions that are present in both components are taken from the first. @@ -728,7 +728,7 @@ entire expression is invalid and is ignored. For example, if names->symbols - contained the expression "+de", it specifies that the default member of the +contained the expression "+de", it specifies that the default member of the "de" class of symbols should be applied to the current keyboard mapping, overriding any existing definitions (it could also be written "+de(default)"). @@ -740,12 +740,12 @@ Here is a slightly more involved example: the expression ASCII keyboard supplied by the "acme" vendor. The new definition begins with the symbols for the ASCII keyboard for Acme (acme(ascii)), - overrides them with definitions for the basic German keyboard +overrides them with definitions for the basic German keyboard (de(basic)), - and then applies the definitions from the default iso9995-3 keyboard +and then applies the definitions from the default iso9995-3 keyboard ( iso9995-3) - to any undefined keys or groups of keys (part three of the iso9995 standard +to any undefined keys or groups of keys (part three of the iso9995 standard defines a common set of bindings for the secondary group, but allows national layouts to override those definitions where necessary). @@ -757,9 +757,9 @@ ordering are. Note that the presence of a keymap names - component that does not contain +component that does not contain ‘%’ - (either explicit or implied by virtue of an expression starting with an +(either explicit or implied by virtue of an expression starting with an operator) indicates a description that is independent of the keyboard description for the device specified in device_spec. @@ -774,40 +774,40 @@ independent of any actual device. The server parses all non- NULL - fields in +fields in names - and uses them to build a keyboard description. However, before parsing the +and uses them to build a keyboard description. However, before parsing the expressions in names, the server ORs the bits in want - and +and need - together and examines the result in relationship to the expressions in +together and examines the result in relationship to the expressions in names. Table 20.3 identifies the components that are required for each of the possible bits in want - or +or need. If a required component has not been specified in the names - structure (the corresponding field is +structure (the corresponding field is NULL), - the server substitutes the expression +the server substitutes the expression “%”, - resulting in the component values being taken from +resulting in the component values being taken from device_spec. In addition, if load - is +is True, the server modifies names - if necessary (again using a +if necessary (again using a “%” - entry) to ensure all of the following fields are non- +entry) to ensure all of the following fields are non- NULL: types, @@ -888,28 +888,28 @@ and need - specifies a set of keyboard components that the server must be able to resolve +specifies a set of keyboard components that the server must be able to resolve in order for XkbGetKeyboardByName - to succeed; if any of the components specified in +to succeed; if any of the components specified in need - cannot be successfully resolved, +cannot be successfully resolved, XkbGetKeyboardByName - fails. +fails. want - specifies a set of keyboard components that the server should attempt to +specifies a set of keyboard components that the server should attempt to resolve, but that are not mandatory. If the server is unable to resolve any of these components, XkbGetKeyboardByName - still succeeds. Bits specified in +still succeeds. Bits specified in want - that are also specified in +that are also specified in need - have no effect in the context of +have no effect in the context of want. @@ -917,33 +917,33 @@ these components, If load - is +is True, the server updates its keyboard description for device_spec - to match the result of the keyboard description just built. If load is +to match the result of the keyboard description just built. If load is False, the server’s description for device device_spec - is not updated. In all cases, the parts specified by +is not updated. In all cases, the parts specified by want - and +and need - from the just-built keyboard description are returned. +from the just-built keyboard description are returned. The names - structure in an +structure in an XkbDescRec - keyboard description record (see ) contains one field for each of +keyboard description record (see ) contains one field for each of the five component types used to build a keyboard description. When a keyboard description is built from a set of database components, the corresponding fields in this names - structure are set to match the expressions used to build the component. +structure are set to match the expressions used to build the component. @@ -964,12 +964,12 @@ database of components and returning all or part of it is diagrammed in Figure The information returned to the client in the XkbDescRec - is essentially the result of a series of calls to extract information from a +is essentially the result of a series of calls to extract information from a fictitious device whose description matches the one just built. The calls corresponding to each of the mask bits are summarized in Table 20.4, together with the XkbDescRec - components that are filled in. +components that are filled in.
@@ -1055,23 +1055,23 @@ XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb) There is no way to determine which components specified in want - (but not in +(but not in need) - were actually fetched, other than breaking the call into successive calls to +were actually fetched, other than breaking the call into successive calls to XkbGetKeyboardByName - and specifying individual components. +and specifying individual components. XkbGetKeyboardByName - always sets +always sets min_key_code - and +and max_key_code - in the returned +in the returned XkbDescRec - structure. +structure. @@ -1092,7 +1092,7 @@ If you simply want to obtain information about the current keyboard device, rather than generating a new keyboard description from elements in the server database, use XkbGetKeyboard - (see section 6.2). +(see section 6.2). XkbGetKeyboard @@ -1145,10 +1145,10 @@ database, use XkbGetKeyboard - is used to read the current description for one or more components of a +is used to read the current description for one or more components of a keyboard device. It calls XkbGetKeyboardByName - as follows: +as follows: diff --git a/specs/XKB/ch21.xml b/specs/XKB/ch21.xml index ce9c889f..7d122d92 100644 --- a/specs/XKB/ch21.xml +++ b/specs/XKB/ch21.xml @@ -14,7 +14,7 @@ include, but are not limited to: mice, tablets, touchscreens, barcode readers, button boxes, trackballs, identifier devices, data gloves, and eye trackers. Xkb provides additional control over all X input extension devices, whether they are KeyClass - devices or not, as well as the core keyboard and pointer. +devices or not, as well as the core keyboard and pointer. @@ -63,14 +63,14 @@ the following additional access is provided: If allowed, Xkb functionality for additional KeyClass - devices supported by the input extension is accessed via those same functions. +devices supported by the input extension is accessed via those same functions. If allowed, Xkb functionality for non- KeyClass - devices supported by the input extension is also accessed via the +devices supported by the input extension is also accessed via the XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter. @@ -81,9 +81,9 @@ Each device has an X Input Extension device ID. Each device may have several classes of feedback. For example, there are two types of feedbacks that can generate bells: bell feedback and keyboard feedback (BellFeedbackClass - and +and KbdFeedbackClass). - A device can have more than one feedback of each type; the feedback ID +A device can have more than one feedback of each type; the feedback ID identifies the particular feedback within its class. @@ -128,17 +128,17 @@ input extension and Xkb, then the core keyboard, the core keyboard indicators, and the core keyboard bells may each be addressed using an appropriate device spec, class, and ID. The constant XkbDfltXIId - may be used as the device ID to specify the core keyboard indicators for the +may be used as the device ID to specify the core keyboard indicators for the core indicator feedback. The particular device ID corresponding to the core keyboard feedback and the core indicator feedback may be obtained by calling XkbGetDeviceInfo - and specifying +and specifying XkbUseCoreKbd - as the +as the device_spec; - the values will be returned in +the values will be returned in dflt_kbd_fb - and +and dflt_led_fb. @@ -146,11 +146,11 @@ keyboard feedback and the core indicator feedback may be obtained by calling If the server does not allow Xkb access to input extension KeyClass - devices, attempts to use Xkb requests with those devices fail with a +devices, attempts to use Xkb requests with those devices fail with a BadKeyboard - error. Attempts to access non- +error. Attempts to access non- KeyClass - input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail +input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail silently if Xkb access to those devices is not supported by the X server. @@ -165,7 +165,7 @@ silently if Xkb access to those devices is not supported by the X server. Information about X Input Extension devices is transferred between a client program and the Xkb extension in an XkbDeviceInfoRec - structure: +structure: typedef struct { @@ -202,26 +202,26 @@ typedef struct { The type - field is a registered symbolic name for a class of devices (for example, +field is a registered symbolic name for a class of devices (for example, "TABLET"). If a device is a keyboard (that is, is a member of KeyClass), - it has its own state, and +it has its own state, and has_own_state - is +is True. If has_own_state - is +is False, the state of the core keyboard is used. The supported - and +and unsupported - fields are masks where each bit indicates a capability. The meaning of the +fields are masks where each bit indicates a capability. The meaning of the mask bits is listed in Table 21.1, together with the fields in the XkbDeviceInfoRec - structure that are associated with the capability represented by each bit. The +structure that are associated with the capability represented by each bit. The same bits are used to indicate the specific information desired in many of the functions described subsequently in this section. @@ -273,7 +273,7 @@ input extension devices. Clients can assign names to indicators on non- KeyClass - input extension devices. +input extension devices. @@ -283,7 +283,7 @@ Clients can assign names to indicators on non- Clients can assign indicator maps to indicators on non- KeyClass - input extension devices. +input extension devices. @@ -293,7 +293,7 @@ Clients can assign indicator maps to indicators on non- Clients can request the status of indicators on non- KeyClass - input extension devices. +input extension devices. @@ -355,7 +355,7 @@ The supported, and unsupported - fields are always filled in when a valid reply is returned from the server +fields are always filled in when a valid reply is returned from the server involving an XkbDeviceInfoRec. All of the other fields are modified only if the particular function asks for @@ -371,7 +371,7 @@ To determine whether the X server allows Xkb access to particular capabilities of input devices other than the core X keyboard, or to determine the status of indicator maps, indicator names or button actions on a non- KeyClass - extension device, use XkbGetDeviceInfo. +extension device, use XkbGetDeviceInfo. XkbGetDeviceInfo @@ -444,13 +444,13 @@ which, device_spec, ind_class, ind_id) --> XkbGetDeviceInfo - returns information about the input device specified by +returns information about the input device specified by device_spec. Unlike the device_spec - parameter of most Xkb functions, +parameter of most Xkb functions, device_spec - does not need to be a keyboard device. It must, however, indicate either the +does not need to be a keyboard device. It must, however, indicate either the core keyboard or a valid X Input Extension device. @@ -463,18 +463,18 @@ is a mask specifying optional information to be returned. It is an inclusive OR of one or more of the values from Table 21.1 and causes the returned XkbDeviceInfoRec - to contain values for the corresponding fields specified in the table. +to contain values for the corresponding fields specified in the table. The XkbDeviceInfoRec - returned by +returned by XkbGetDeviceInfo - always has values for +always has values for name - (may be a null string, ""), +(may be a null string, ""), type, supported, unsupported, @@ -490,7 +490,7 @@ Other fields are filled in as specified by Upon return, the supported - field will be set to the inclusive OR of zero or more bits from +field will be set to the inclusive OR of zero or more bits from Table 21.1; each bit set indicates an optional Xkb extension device feature supported by the server implementation, and a client may modify the associated behavior. @@ -500,20 +500,20 @@ the server implementation, and a client may modify the associated behavior. If the XkbXI_ButtonActionsMask - bit is set in +bit is set in which, the XkbDeviceInfoRec - returned will have the button actions +returned will have the button actions (btn_acts - field) filled in for all buttons. +field) filled in for all buttons. If which - includes one of the bits in XkbXI_IndicatorsMask, +includes one of the bits in XkbXI_IndicatorsMask, the feedback class of the indicators must be specified in ind_class, and the feedback ID of the indicators must be specified in ind_id. If the request does not include any of @@ -527,65 +527,65 @@ XListInputDevices request. If any of the XkbXI_IndicatorsMask - bits are set in +bits are set in which, the XkbDeviceInfoRec - returned will have filled in the portions of the +returned will have filled in the portions of the leds - structure corresponding to the indicator feedback identified by +structure corresponding to the indicator feedback identified by ind_class - and +and ind_id. The leds - vector of the +vector of the XkbDeviceInfoRec - is allocated if necessary and +is allocated if necessary and sz_leds - and +and num_leds - filled in. The +filled in. The led_class, led_id - and +and phys_indicators - fields of the +fields of the leds - entry corresponding to +entry corresponding to ind_class - and +and ind_id - are always filled in. If +are always filled in. If which - contains +contains XkbXI_IndicatorNamesMask, the names_present - and +and names - fields of the +fields of the leds - structure corresponding to +structure corresponding to ind_class - and +and ind_id - are returned. +are returned. If which - contains +contains XkbXI_IndicatorStateMask, the corresponding state - field is updated. If +field is updated. If which - contains +contains XkbXI_IndicatorMapsMask, the maps_present - and +and maps - fields are updated. +fields are updated. @@ -596,10 +596,10 @@ available via These convenience functions mirror some of the mask bits. The functions all take an XkbDeviceInfoPtr - as an input argument and operate on the X Input Extension device specified by +as an input argument and operate on the X Input Extension device specified by the device_spec - field of the structure. Only the parts of the structure indicated in the +field of the structure. Only the parts of the structure indicated in the function description are updated. The XkbDeviceInfoRec structure used in the function call can be obtained by calling @@ -689,24 +689,24 @@ XkbGetDeviceButtonActions. XkbGetDeviceButtonActions - queries the server for the desired button information for the device indicated +queries the server for the desired button information for the device indicated by the device_spec - field of +field of device_info - and waits for a reply. If successful, +and waits for a reply. If successful, XkbGetDeviceButtonActions - backfills the button actions +backfills the button actions (btn_acts - field of +field of device_info) - for only the requested buttons, updates the +for only the requested buttons, updates the name, type, supported, and unsupported - fields, and returns +fields, and returns Success. @@ -714,20 +714,20 @@ and all_buttons, first_button - and +and num_buttons - specify the device buttons for which actions should be returned. Setting +specify the device buttons for which actions should be returned. Setting all_buttons - to +to True - requests actions for all device buttons; if +requests actions for all device buttons; if all_buttons - is +is False, first_button - and +and num_buttons - specify a range of buttons for which actions are requested. +specify a range of buttons for which actions are requested. @@ -737,19 +737,19 @@ extension has not been properly initialized, XkbGetDeviceButtonActions returns BadAccess. If allocation errors occur, a BadAlloc - status is returned. If the specified device +status is returned. If the specified device (device_info->device_spec) - is invalid, a +is invalid, a BadKeyboard - status is returned. If the device has no buttons, a +status is returned. If the device has no buttons, a BadMatch - status is returned. If +status is returned. If first_button - and +and num_buttons - specify illegal buttons, a +specify illegal buttons, a BadValue - status is returned. +status is returned. @@ -829,24 +829,24 @@ nfo, led_class, led_id, which) --> XkbGetDeviceLedInfo - queries the server for the desired LED information for the feedback specified +queries the server for the desired LED information for the feedback specified by led_class - and +and led_id - for the X input extension device indicated by +for the X input extension device indicated by device_spec->device_info - and waits for a reply. If successful, +and waits for a reply. If successful, XkbGetDeviceLedInfo - backfills the relevant fields of +backfills the relevant fields of device_info - as determined by +as determined by which - with the results and returns +with the results and returns Success. Valid values for which - are the inclusive OR of any of +are the inclusive OR of any of XkbXI_IndicatorNamesMask, XkbXI_IndicatorMapsMask, and @@ -857,7 +857,7 @@ and The fields of device_info - that are filled in when this request succeeds are +that are filled in when this request succeeds are name, type, supported, @@ -865,63 +865,63 @@ and unsupported, and portions of the leds - structure corresponding to +structure corresponding to led_class - and +and led_id - as indicated by the bits set in +as indicated by the bits set in which. The device_info->leds - vector is allocated if necessary and +vector is allocated if necessary and sz_leds - and +and num_leds - filled in. The +filled in. The led_class, led_id - and +and phys_indicators - fields of the +fields of the device_info->leds - entry corresponding to +entry corresponding to led_class - and +and led_id - are always filled in. +are always filled in. If which - contains +contains XkbXI_IndicatorNamesMask, the names_present - and +and names - fields of the +fields of the device_info->leds - structure corresponding to +structure corresponding to led_class - and +and led_id - are updated, if +are updated, if which - contains +contains XkbXI_IndicatorStateMask, the corresponding state - field is updated, and if +field is updated, and if which - contains +contains XkbXI_IndicatorMapsMask, the maps_present - and +and maps - fields are updated. +fields are updated. @@ -929,7 +929,7 @@ the If a compatible version of Xkb is not available in the server or the Xkb extension has not been properly initialized, XkbGetDeviceLedInfo - returns +returns BadAccess. If allocation errors occur, a BadAlloc @@ -937,14 +937,14 @@ status is returned. If the device has no indicators, a BadMatch error is returned. If ledClass - or +or ledID - have illegal values, a +have illegal values, a BadValue - error is returned. If they have legal values but do not specify a feedback +error is returned. If they have legal values but do not specify a feedback that contains LEDs and is associated with the specified device, a BadMatch - error is returned. +error is returned. @@ -956,7 +956,7 @@ Structure To obtain an XkbDeviceInfoRec - structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. +structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. XkbAllocDeviceInfo @@ -1005,25 +1005,25 @@ To obtain an XkbAllocDeviceInfo - allocates space for an +allocates space for an XkbDeviceInfoRec - structure and initializes that structure’s +structure and initializes that structure’s device_spec - field with the device ID specified by device_spec. If +field with the device ID specified by device_spec. If n_buttons - is nonzero, +is nonzero, n_buttons XkbActions - are linked into the +are linked into the XkbDeviceInfoRec - structure and initialized to zero. If sz_leds is nonzero, +structure and initialized to zero. If sz_leds is nonzero, sz_leds XkbDeviceLedInfoRec - structures are also allocated and linked into the +structures are also allocated and linked into the XkbDeviceInfoRec - structure. If you request +structure. If you request XkbDeviceLedInfoRec - structures be allocated using this request, you must initialize them +structures be allocated using this request, you must initialize them explicitly. @@ -1031,7 +1031,7 @@ explicitly. To obtain an XkbDeviceLedInfoRec - structure, use XkbAllocDeviceLedInfo. +structure, use XkbAllocDeviceLedInfo. @@ -1070,18 +1070,18 @@ To obtain an XkbAllocDeviceLedInfo - allocates space for an +allocates space for an XkbDeviceLedInfoRec - and places it in +and places it in device_info. If num_needed is nonzero, num_needed XkbIndicatorMapRec - structures are also allocated and linked into the +structures are also allocated and linked into the XkbDeviceLedInfoRec - structure. If you request +structure. If you request XkbIndicatorMapRec - structures be allocated using this request, you must initialize them +structures be allocated using this request, you must initialize them explicitly. All other fields are initialized to zero. @@ -1089,7 +1089,7 @@ explicitly. All other fields are initialized to zero. To initialize an XkbDeviceLedInfoRec - structure, use XkbAddDeviceLedInfo. +structure, use XkbAddDeviceLedInfo. @@ -1139,22 +1139,22 @@ To initialize an XkbAddDeviceLedInfo - first checks to see whether an entry matching +first checks to see whether an entry matching led_class - and +and led_id - already exists in the +already exists in the device_info->leds - array. If it finds a matching entry, it returns a pointer to that entry. +array. If it finds a matching entry, it returns a pointer to that entry. Otherwise, it checks to be sure there is at least one empty entry in device_info->leds - and extends it if there is not enough room. It then increments +and extends it if there is not enough room. It then increments device_info->num_leds - and fills in the next available entry in +and fills in the next available entry in device_info->leds - with +with led_class - and +and led_id. @@ -1162,20 +1162,20 @@ Otherwise, it checks to be sure there is at least one empty entry in If successful, XkbAddDeviceLedInfo - returns a pointer to the +returns a pointer to the XkbDeviceLedInfoRec - structure that was initialized. If unable to allocate sufficient storage, or +structure that was initialized. If unable to allocate sufficient storage, or if device_info - points to an invalid +points to an invalid XkbDeviceInfoRec - structure, or if +structure, or if led_class - or +or led_id - are inappropriate, +are inappropriate, XkbAddDeviceLedInfo - returns +returns NULL. @@ -1183,7 +1183,7 @@ if To allocate additional space for button actions in an XkbDeviceInfoRec - structure, use XkbResizeDeviceButtonActions. +structure, use XkbResizeDeviceButtonActions. @@ -1222,30 +1222,30 @@ To allocate additional space for button actions in an XkbResizeDeviceButtonActions - reallocates space, if necessary, to make sure there is room for a total of +reallocates space, if necessary, to make sure there is room for a total of new_total - button actions in the +button actions in the device_info - structure. Any new entries allocated are zeroed. If successful, +structure. Any new entries allocated are zeroed. If successful, XkbResizeDeviceButtonActions - returns Success. If new_total is zero, all button actions are deleted, +returns Success. If new_total is zero, all button actions are deleted, device_info->num_btns - is set to zero, and +is set to zero, and device_info->btn_acts - is set to +is set to NULL. If device_info is invalid or new_total is greater than 255, BadValue - is returned. If a memory allocation failure occurs, a +is returned. If a memory allocation failure occurs, a BadAlloc - is returned. +is returned. To free an XkbDeviceInfoRec - structure, use XkbFreeDeviceInfo. +structure, use XkbFreeDeviceInfo. @@ -1298,44 +1298,44 @@ If free_all is True, the XkbFreeDeviceInfo - frees all components of +frees all components of device_info - and the +and the XkbDeviceInfoRec - structure pointed to by +structure pointed to by device_info - itself. If free_all is +itself. If free_all is False, the value of which determines which subcomponents are freed. which is an inclusive OR of one or more of the values from Table 21.1. If which contains XkbXI_ButtonActionsMask, - all button actions associated with +all button actions associated with device_info - are freed, +are freed, device_info->btn_acts - is set to +is set to NULL, and device_info->num_btns - is set to zero. If which contains all bits in +is set to zero. If which contains all bits in XkbXI_IndicatorsMask, all XkbDeviceLedInfoRec - structures associated with +structures associated with device_info - are freed, +are freed, device_info->leds - is set to +is set to NULL, and device_info->sz_leds - and +and device_info->num_leds - are set to zero. If which contains XkbXI_IndicatorMapsMask, - all indicator maps associated with +are set to zero. If which contains XkbXI_IndicatorMapsMask, +all indicator maps associated with device_info - are cleared, but the number of LEDs and the leds structures themselves are +are cleared, but the number of LEDs and the leds structures themselves are preserved. If which contains XkbXI_IndicatorNamesMask, all indicator names associated with device_info are cleared, but the number of LEDs and the leds @@ -1343,7 +1343,7 @@ structures themselves are preserved. If which contains XkbXI_IndicatorStateMask, the indicator state associated with the device_info - leds are set to zeros but the number of LEDs and the leds structures +leds are set to zeros but the number of LEDs and the leds structures themselves are preserved. @@ -1373,11 +1373,11 @@ core pointer device, but support for actions on extension devices is optional. Implementations that do not support button actions for extension devices must not set the XkbXI_ButtonActionsMask - bit in the +bit in the supported - field of an +field of an XkbDeviceInfoRec - structure. +structure. @@ -1387,7 +1387,7 @@ implementation that does not support modification of those characteristics, no protocol error is generated. Instead, the server reports a failure for the request; it also sends an XkbExtensionDeviceNotify - event to the client that issued the request if the client has selected to +event to the client that issued the request if the client has selected to receive these events. @@ -1396,11 +1396,11 @@ receive these events. To change characteristics of an X Input Extension device in the server, first modify a local copy of the device structure and then use either XkbSetDeviceInfo, - or, to save network traffic, use an +or, to save network traffic, use an XkbDeviceChangesRec - structure (see section 21.6) and call +structure (see section 21.6) and call XkbChangeDeviceInfo - to download the changes to the server. +to download the changes to the server. @@ -1457,19 +1457,19 @@ which, device_info) --> XkbSetDeviceInfo - sends a request to the server to modify the characteristics of the device +sends a request to the server to modify the characteristics of the device specified in the device_info - structure. The particular characteristics modified are identified by the bits +structure. The particular characteristics modified are identified by the bits set in which - and take their values from the relevant fields in +and take their values from the relevant fields in device_info - (see Table 21.1). +(see Table 21.1). XkbSetDeviceInfo - returns +returns True - if the request was successfully sent to the server. If the X server +if the request was successfully sent to the server. If the X server implementation does not allow interaction between the X input extension and the Xkb Extension, the function does nothing and returns False. @@ -1479,14 +1479,14 @@ Xkb Extension, the function does nothing and returns The which - parameter specifies which aspects of the device should be changed and is a +parameter specifies which aspects of the device should be changed and is a bitmask composed of an inclusive OR or one or more of the following bits: XkbXI_ButtonActionsMask, XkbXI_IndicatorNamesMask, XkbXI_IndicatorMapsMask. If the features requested to be manipulated in which - are valid for the device, but the server does not support assignment of one or +are valid for the device, but the server does not support assignment of one or more of them, that particular portion of the request is ignored. @@ -1494,43 +1494,43 @@ more of them, that particular portion of the request is ignored. If the device specified in device_info->device_spec - does not contain buttons and a request affecting buttons is made, or the +does not contain buttons and a request affecting buttons is made, or the device does not contain indicators and a request affecting indicators is made, a BadMatch - protocol error results. +protocol error results. If the XkbXI_ButtonActionsMask - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign key actions to buttons on input extension devices other than the core keyboard device. If the XkbXI_ButtonActionsMask - is set in +is set in which, the actions for all buttons specified in device_info are set to the XkbActions - specified in +specified in device_info->btn_acts. If the number of buttons requested to be updated is not valid for the device, XkbSetDeviceInfo - returns +returns False - and a +and a BadValue - protocol error results. +protocol error results. If the XkbXI_IndicatorMapsMask - and / or +and / or XkbXI_IndicatorNamesMask - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign maps and / or names to the indicators of nonkeyboard extension devices. If supported, maps and / or names can be assigned to all extension device indicators, whether they are part of a @@ -1541,36 +1541,36 @@ keyboard feedback or part of an indicator feedback. If the XkbXI_IndicatorMapsMask - and / or +and / or XkbXI_IndicatorNamesMask - flag is set in +flag is set in which, the indicator maps and / or names for all device_info->num_leds - indicator devices specified in +indicator devices specified in device_info->leds - are set to the maps and / or names specified in +are set to the maps and / or names specified in device_info->leds. device_info->leds->led_class - and +and led_id - specify the input extension class and device ID for each indicator device to +specify the input extension class and device ID for each indicator device to modify; if they have invalid values, a BadValue - protocol error results and +protocol error results and XkbSetDeviceInfo - returns +returns False. If they have legal values but do not specify a keyboard or indicator class feedback for the device in question, a BadMatch - error results. If any of the values in +error results. If any of the values in device_info->leds->names - are not a valid Atom or +are not a valid Atom or None, a BadAtom - protocol error results. +protocol error results. @@ -1648,13 +1648,13 @@ device, first_button, num_buttons, actions) --> XkbSetDeviceButtonActions - assigns actions to the buttons of the device specified in +assigns actions to the buttons of the device specified in device_info->device_spec. Actions are assigned to num_buttons - buttons beginning with +buttons beginning with first_button - and are taken from the actions specified in +and are taken from the actions specified in device_info->btn_acts. @@ -1663,19 +1663,19 @@ Actions are assigned to If the server does not support assignment of Xkb actions to extension device buttons, XkbSetDeviceButtonActions - has no effect and returns +has no effect and returns False. If the device has no buttons or if first_button - or +or num_buttons - specify buttons outside of the valid range as determined by +specify buttons outside of the valid range as determined by device_info->num_btns, the function has no effect and returns False. Otherwise, XkbSetDeviceButtonActions - sends a request to the server to change the actions for the specified buttons +sends a request to the server to change the actions for the specified buttons and returns True. @@ -1684,14 +1684,14 @@ and returns If the actual request sent to the server involved illegal button numbers, a BadValue - protocol error is generated. If an invalid device identifier is specified in +protocol error is generated. If an invalid device identifier is specified in device_info->device_spec, a BadKeyboard - protocol error results. If the actual device specified in +protocol error results. If the actual device specified in device_info->device_spec - does not contain buttons and a request affecting buttons is made, a +does not contain buttons and a request affecting buttons is made, a BadMatch - protocol error is generated. +protocol error is generated. @@ -1706,7 +1706,7 @@ a BadKeyboard The Xkb extension generates XkbExtensionDeviceNotify - events when the status of an input extension device changes or when an attempt +events when the status of an input extension device changes or when an attempt is made to use an Xkb feature that is not supported by a particular device. @@ -1717,24 +1717,24 @@ delivered only to the client requesting the event. To track changes to the status of input extension devices or attempts to use unsupported features of a device, select to receive XkbExtensionDeviceNotify - events by calling either +events by calling either XkbSelectEvents - or +or XkbSelectEventDetails - (see section 4.3). +(see section 4.3). To receive XkbExtensionDeviceNotify - events under all possible conditions, call +events under all possible conditions, call XkbSelectEvents - and pass +and pass XkbExtensionDeviceNotifyMask - in both +in both bits_to_change - and +and values_for_bits. @@ -1742,19 +1742,19 @@ To receive The XkbExtensionDeviceNotify - event has no event details. However, you can call +event has no event details. However, you can call XkbSelectEventDetails - using +using XkbExtensionDeviceNotify - as the +as the event_type - and specifying +and specifying XkbAllExtensionDeviceEventsMask - in +in bits_to_change - and +and values_for_bits. - This has the same effect as a call to +This has the same effect as a call to XkbSelectEvents. @@ -1762,7 +1762,7 @@ The The structure for XkbExtensionDeviceNotify - events is: +events is: typedef struct { @@ -1789,7 +1789,7 @@ typedef struct { The XkbExtensionDeviceNotify - event has fields enabling it to report changes in the state (on/off) of all of +event has fields enabling it to report changes in the state (on/off) of all of the buttons for a device, but only for one LED feedback associated with a device. You will get multiple events when more than one LED feedback changes state or configuration. @@ -1807,9 +1807,9 @@ state or configuration. Changes to an Xkb extension device may be tracked by listening to XkbExtensionDeviceNotify - events and accumulating the changes in an +events and accumulating the changes in an XkbDeviceChangesRec - structure. The changes noted in the structure may then be used in subsequent +structure. The changes noted in the structure may then be used in subsequent operations to update either a server configuration or a local copy of an Xkb extension device configuration. The changes structure is defined as follows: @@ -1836,7 +1836,7 @@ typedef struct _XkbDeviceLedChanges { A local description of the configuration and state of a device may be kept in an XkbDeviceInfoRec - structure. The actual state or configuration of the device may change because +structure. The actual state or configuration of the device may change because of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user interaction with the device. The X server sends an XkbExtensionDeviceNotify event to all interested clients when the state of any buttons or indicators or @@ -1854,7 +1854,7 @@ server. To note device changes reported in an XkbExtensionDeviceNotify - event, use XkbNoteDeviceChanges. +event, use XkbNoteDeviceChanges. XkbNoteDeviceChanges @@ -1910,17 +1910,17 @@ and is composed of the bitwise inclusive OR of one or more of the masks from Table 21.1. The reason - field of the event in +field of the event in new - indicates the types of changes the event is reporting. +indicates the types of changes the event is reporting. XkbNoteDeviceChanges - updates the +updates the XkbDeviceChangesRec - specified by +specified by old - with the changes that are both specified in +with the changes that are both specified in wanted - and contained in +and contained in new->reason. @@ -1929,7 +1929,7 @@ The To update a local copy of the state and configuration of an X input extension device with the changes previously noted in an XkbDeviceChangesRec - structure, use XkbGetDeviceInfoChanges. +structure, use XkbGetDeviceInfoChanges. @@ -1991,15 +1991,15 @@ changes) --> The changes->changed field indicates which attributes of the device specified in changes->device - have changed. The parameters describing the changes are contained in the other +have changed. The parameters describing the changes are contained in the other fields of changes. XkbGetDeviceInfoChanges - uses that information to call XkbGetDeviceInfo to obtain the current status of +uses that information to call XkbGetDeviceInfo to obtain the current status of those attributes that have changed. It then updates the local description of the device in device_info - with the new information. +with the new information. @@ -2057,11 +2057,11 @@ XkbDeviceChangesRec, use XkbChangeDeviceInfo. XkbChangeDeviceInfo - updates the server’s description of the device specified in +updates the server’s description of the device specified in device_info->device_spec - with the changes specified in +with the changes specified in changes - and contained in +and contained in device_info. The update is made by an XkbSetDeviceInfo request. diff --git a/specs/XKB/ch22.xml b/specs/XKB/ch22.xml index 5fe31531..4a3981af 100644 --- a/specs/XKB/ch22.xml +++ b/specs/XKB/ch22.xml @@ -125,64 +125,64 @@ To change the values of any of the debug controls, use XkbSetDebuggingFlags - modifies the debug output flags as specified by +modifies the debug output flags as specified by mask - and +and flags, modifies the debug controls flags as specified by ctrls_mask - and +and ctrls, prints the message msg, and backfills ret_flags - and +and ret_ctrls - with the resulting debug output and debug controls flags. +with the resulting debug output and debug controls flags. When bits are set in the debug output masks, mask - and +and flags, Xkb prints debug information corresponding to each bit at appropriate points during its processing. The device to which the output is written is implementation-dependent, but is normally the same device to which X server error messages are directed; thus the bits that can be set in mask - and +and flags - is implementation-specific. To turn on a debug output selection, set the bit +is implementation-specific. To turn on a debug output selection, set the bit for the output in the mask - parameter and set the corresponding bit in the +parameter and set the corresponding bit in the flags - parameter. To turn off event selection for an event, set the bit for the +parameter. To turn off event selection for an event, set the bit for the output in the mask - parameter and do not set the corresponding bit in the +parameter and do not set the corresponding bit in the flags - parameter. +parameter. When bits are set in the debug controls masks, ctrls_mask - and +and ctrls, Xkb modifies its behavior according to each controls bit. ctrls_mask - and +and ctrls - are related in the same way that +are related in the same way that mask - and +and flags - are. The valid controls bits are defined in +are. The valid controls bits are defined in Table 22.1. @@ -212,11 +212,11 @@ Xkb modifies its behavior according to each controls bit. XkbSetDebuggingFlags - returns +returns True - if successful and +if successful and False - otherwise. The only protocol error it may generate is +otherwise. The only protocol error it may generate is BadAlloc, if for some reason it is unable to allocate storage. @@ -224,17 +224,17 @@ if for some reason it is unable to allocate storage. XkbSetDebuggingFlags - is intended for developer use and may be disabled in production X servers. If +is intended for developer use and may be disabled in production X servers. If it is disabled, XkbSetDebuggingFlags - has no effect and does not generate any protocol errors. +has no effect and does not generate any protocol errors. The message in msg - is written immediately. The device to which it is written is implementation +is written immediately. The device to which it is written is implementation dependent but is normally the same device where X server error messages are directed. diff --git a/specs/XKB/glossary.xml b/specs/XKB/glossary.xml index 37fdfba2..1eb600c9 100644 --- a/specs/XKB/glossary.xml +++ b/specs/XKB/glossary.xml @@ -89,9 +89,9 @@ The canonical key types are predefined key types that describe the types of keys available on most keyboards. The definitions for the canonical key types are held in the first XkbNumRequiredTypes - entries of the +entries of the types - field of the client map and are indexed using the following constants: +field of the client map and are indexed using the following constants: @@ -132,7 +132,7 @@ The key mapping information needed to convert arbitrary keycodes to symbols. The compat - name is a string that provides some information about the rules used to bind +name is a string that provides some information about the rules used to bind actions to keys that are changed using core protocol requests. @@ -191,10 +191,10 @@ Xkb normally consumes modifiers in determining the appropriate symbol for an event, that is, the modifiers are not considered during any of the later stages of event processing. For those rare occasions when a modifier should - be considered despite having been used to look up a symbol, key types include +be considered despite having been used to look up a symbol, key types include an optional preserve - field. +field. @@ -213,14 +213,14 @@ An event created from the core X server. Detectable auto-repeat allows a client to detect an auto-repeating key. If a client requests and the server supports detectable auto-repeat, Xkb generates KeyRelease - events only when the key is physically released. Thus the client receives a +events only when the key is physically released. Thus the client receives a number of KeyPress - events for that key without intervening +events for that key without intervening KeyRelease - events until the key is finally released, when a +events until the key is finally released, when a KeyRelease - event is received. +event is received. @@ -232,12 +232,12 @@ The effective group is the arithmetic sum of the locked, latched, and base groups. The effective keyboard group is always brought back into range depending on the value of the GroupsWrap - control for the keyboard. If an event occurs with an effective group that is +control for the keyboard. If an event occurs with an effective group that is legal for the keyboard as a whole, but not for the key in question, the group for that event only - is normalized using the algorithm specified by the +is normalized using the algorithm specified by the group_info - member of the key symbol map +member of the key symbol map (XkbSymMapRec). @@ -427,9 +427,9 @@ explicitly set its state and whether it tracks the keyboard state. The indicator map is the collection of these attributes for each indicator and is held in the maps - array, which is an array of +array, which is an array of XkbIndicatorRec - structures. +structures. @@ -512,7 +512,7 @@ symbolic names section. The behaviors - field of the server map is an array of +field of the server map is an array of XkbBehavior, indexed by keycode, and contains the behavior for each key. The X server uses key behavior to determine whether to process or filter out any given key event; @@ -546,7 +546,7 @@ exactly one behavior. A key symbol map describes the symbols bound to a key and the rules to be used to interpret those symbols. It is an array of XkbSymMapRec - structures indexed by keycode. +structures indexed by keycode. @@ -558,13 +558,13 @@ Key types are used to determine the shift level of a key given the current state of the keyboard. There is one key type for each group for a key. Key types are defined using the XkbKeyTypeRec - and +and XkbKTMapEntryRec - structures. Xkb allows up to +structures. Xkb allows up to XkbMaxKeyTypes - (255) key types to be defined, but requires at least +(255) key types to be defined, but requires at least XkbNumRequiredTypes - (4) predefined types to be in a key map. +(4) predefined types to be in a key map. @@ -590,7 +590,7 @@ components. They correspond to the compat, and types - symbolic names associated with a keyboard. +symbolic names associated with a keyboard. @@ -629,7 +629,7 @@ Keyboard geometry describes the physical appearance of the keyboard, including the shape, location, and color of all keyboard keys or other visible keyboard components such as indicators and is stored in a XkbGeometryRec - structure. The information contained in a keyboard geometry is sufficient to +structure. The information contained in a keyboard geometry is sufficient to allow a client program to draw an accurate two-dimensional image of the keyboard. @@ -642,7 +642,7 @@ keyboard. The keyboard geometry name describes the physical location, size, and shape of the various keys on the keyboard and is part of the XkbNamesRec - structure. +structure. @@ -673,7 +673,7 @@ the device. The keycode name describes the range and meaning of the keycodes returned by the keyboard and is part of the XkbNamesRec - structure. +structure. @@ -752,11 +752,11 @@ protocol eight modifiers Control, and Mod1 - through +through Mod5), - called the +called the real - modifiers. In addition, Xkb extends modifier flexibility by providing a set of +modifiers. In addition, Xkb extends modifier flexibility by providing a set of sixteen named virtual modifiers, each of which can be bound to any set of the eight real modifiers. @@ -811,7 +811,7 @@ polygon, used in the geometry specification for a keyboard. The physical indicator mask is a field in the XkbIndicatorRec - that indicates which indicators are bound to physical LEDs on the keyboard; if +that indicates which indicators are bound to physical LEDs on the keyboard; if a bit is set in phys_indicators, then the associated indicator has a physical LED associated with it. This @@ -826,11 +826,11 @@ LEDs on the keyboard. The symbols - keyboard name identifies the symbols logically bound to the keys. The symbols +keyboard name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or usage of the keyboard with these symbols. The phys_symbols - keyboard name, on the other hand, identifies the symbols actually engraved on +keyboard name, on the other hand, identifies the symbols actually engraved on the keyboard. @@ -843,12 +843,12 @@ Xkb normally consumes modifiers in determining the appropriate symbol for an event, that is, the modifiers are not considered during any of the later stages of event processing. For those rare occasions when a modifier should - be considered despite having been used to look up a symbol, key types include +be considered despite having been used to look up a symbol, key types include an optional preserve - field. If a modifier is present in the +field. If a modifier is present in the preserve - list, it is a preserved modifier. +list, it is a preserved modifier. @@ -874,11 +874,11 @@ Xkb supports the eight core protocol modifiers Control, and Mod1 - through +through Mod5); - these are called the +these are called the real - modifiers, as opposed to the set of sixteen named virtual modifiers that can +modifiers, as opposed to the set of sixteen named virtual modifiers that can be bound to any set of the eight real modifiers. @@ -907,11 +907,11 @@ produced when a key is actuated. The symbols - keyboard name identifies the symbols logically bound to the keys. The symbols +keyboard name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or usage of the keyboard with these symbols. The phys_symbols - keyboard name, on the other hand, identifies the symbols actually engraved on +keyboard name, on the other hand, identifies the symbols actually engraved on the keyboard. @@ -923,7 +923,7 @@ the keyboard. Xkb supports symbolic names for most components of the keyboard extension. Most of these symbolic names are grouped into the names - component of the keyboard description. +component of the keyboard description. @@ -942,7 +942,7 @@ group, and button state information pertaining to the event. The types - name provides some information about the set of key types that can be +name provides some information about the set of key types that can be associated with the keyboard. In addition, each key type can have a name, and each shift level of a type can have a name. @@ -967,7 +967,7 @@ of the real modifiers (Shift, Lock, Control, - and +and Mod1 – Mod5). -- cgit v1.2.1