# Indicators

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 the logical state of the CapsLock key.

Furthermore, the core X implementation does not provide clients with the ability to determine what bits in the led_mask field of the XKeyboardState 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 Scroll Lock LED or whether the keyboard even has a Scroll Lock LED.

Xkb provides indicator names and programmable indicators to help solve these problems. Using Xkb, clients can determine the names of the various indicators, determine and control the way that the individual indicators should be updated to reflect keyboard changes, and determine which of the 32 keyboard indicators reported by the protocol are actually present on the keyboard. Clients may also request immediate notification of changes to the state of any subset of the keyboard indicators, which makes it straightforward to provide an on-screen virtual LED panel. This chapter describes Xkb indicators and the functions used for manipulating them.

## Indicator Names

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

## Indicator Data Structures

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

### XkbIndicatorRec

The description for all the Xkb indicators is held in the indicators field of the complete keyboard description (see ), which is defined as follows:

    #define      XkbNumIndicators      32

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

This structure contains the phys_indicators 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.

The phys_indicators 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 field is necessary because some indicators may not have corresponding physical LEDs on the keyboard. For example, most keyboards have an LED for indicating the state of CapsLock, 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 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.

XkbIndicatorRec

### XkbIndicatorMapRec

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 XkbIndicatorRec structures:

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

This indicator map specifies for each indicator:

- The conditions under which the keyboard modifier state affects the indicator

- The conditions under which the keyboard group state affects the indicator

- The conditions under which the state of the boolean controls affects the indicator

- The effect (if any) of attempts to explicitly change the state of the indicator using the functions `XkbSetControls` or `XChangeKeyboardControl`

For more information on the effects of explicit changes to indicators and the relationship to the indicator map, see section 8.4.1.

#### XkbIndicatorMapRec flags field

The flags field specifies the conditions under which the indicator can be changed and the effects of changing the indicator. The valid values for flags and their effects are shown in Table 8.1.

XkbIndicatorMapRec flags Field

Value |  | Effect
--- | --- | ---
XkbIM_NoExplicit | (1L<<7) | Client applications cannot change the state of the indicator.
XkbIM_NoAutomatic | (1L<<6) | Xkb does not automatically change the value of the indicator based upon a change in the keyboard state, regardless of the values for the other fields of the indicator map.
XkbIM_LEDDrivesKB | (1L<<5) | A client application changing the state of the indicator causes the state of the keyboard to change.

Note that if XkbIM_NoAutomatic is not set, by default the indicator follows the keyboard state.

If XkbIM_LEDDrivesKB is set and XkbIM_NoExplicit is not, and if you call a function which updates the server’s image of the indicator map (such as `XkbSetIndicatorMap` or `XkbSetNamedDeviceIndicator`), 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 XkbIM_NoExplicit 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 Scroll Lock LED to be controlled by client applications. To do so, the keyboard designer could set the XkbIM_NoExplicit flag for the CapsLock LED, but not set it for the Scroll Lock 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 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 XkbIM_NoExplicit flag, but would instead set the XkbIM_LEDDrivesKB 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 indicator on. If the conditions do not match, Xkb turns the indicator off.

#### XkbIndicatorMapRec which_groups and groups fields

The which_groups and the groups fields of an indicator map determine how the keyboard group state affects the corresponding indicator. The which_groups field controls the interpretation of groups and may contain any one of the following values:

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

The groups field specifies what keyboard groups an indicator watches and is the bitwise inclusive OR of the following valid values:

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

If XkbIM_NoAutomatic is not set (the keyboard drives the indicator), the effect of which_groups and groups is shown in Table 8.2.

XkbIndicatorMapRec which_groups and groups, Keyboard Drives Indicator

which_groups | Effect
--- | ---
XkbIM_UseNone | The groups field and the current keyboard group state are ignored.
XkbIM_UseBase | If groups 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.
XkbIM_UseLatched | If groups 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.
XkbIM_UseLocked | The groups 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.
XkbIM_UseEffective | The groups 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.

The effect of which_groups and groups when you change an indicator for which XkbIM_LEDDrivesKB 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.

XkbIndicatorMapRec which_groups and groups, Indicator Drives Keyboard

which_groups | New State | Effect on Keyboard Group State
--- | --- | ---
XkbIM_UseNone | On or Off | No effect
XkbIM_UseBase | On or Off | No effect
XkbIM_UseLatched | On | The groups field is treated as a group mask. The keyboard group latch is changed to the lowest numbered group specified in groups; if groups is empty, the keyboard group latch is changed to zero.
XkbIM_UseLatched | Off | The groups 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 groups is zero, the keyboard group latch is set to the index of the highest legal keyboard group.
XkbIM_UseLocked or XkbIM_UseEffective | On | If the groups mask is empty, group is not changed; otherwise, the locked keyboard group is changed to the lowest numbered group specified in groups.
XkbIM_UseLocked or XkbIM_UseEffective | Off | Locked keyboard group is changed to the lowest numbered group that is not specified in the groups mask, or to Group1 if the groups mask contains all keyboard groups.

#### XkbIndicatorMapRec which_mods and mods fields

The mods field specifies what modifiers an indicator watches. The mods 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 mods 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 mods.vmods. You can disregard the mods.mask 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 XkbDescRec contains the virtual modifier definitions.

which_mods 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 XkbIM_NoAutomatic is not set (the keyboard drives the indicator), the indicator is lit whenever any of the modifiers specified in the mask field of the mods 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 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 OR of the following values to compose a value for which_mods:

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

If XkbIM_NoAutomatic is not set (the keyboard drives the indicator), the effect of which_mods and mods is shown in Table 8.4

XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator

which_mods | Effect on Keyboard Modifiers
--- | ---
XkbIM_UseNone | The mods field and the current keyboard modifier state are ignored.
XkbIM_UseBase | The indicator is lit when any of the modifiers specified in the mask field of mods are on in the keyboard base state. If both mods.real_mods and mods.vmods are zero, the indicator is lit when the base keyboard state contains no modifiers.
XkbIM_UseLatched | The indicator is lit when any of the modifiers specified in the mask field of mods are latched. If both mods.real_mods and mods.vmods are zero, the indicator is lit when none of the modifier keys are latched.
XkbIM_UseLocked | The indicator is lit when any of the modifiers specified in the mask field of mods are locked. If both mods.real_mods and mods.vmods are zero, the indicator is lit when none of the modifier keys are locked.
XkbIM_UseEffective | The indicator is lit when any of the modifiers specified in the mask field of mods are in the effective keyboard state. If both mods.real_mods and mods.vmods are zero, the indicator is lit when the effective keyboard state contains no modifiers.
XkbIM_UseCompat | The indicator is lit when any of the modifiers specified in the mask field of mods are in the keyboard compatibility state. If both mods.real_mods and mods.vmods are zero, the indicator is lit when the keyboard compatibility state contains no modifiers.

The effect on the keyboard modifiers of which_mods and mods when you change an indicator for which XkbIM_LEDDrivesKB 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.

XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard

which_mods | New State | Effect on Keyboard Modifiers
--- | --- | ---
XkbIM_UseNone or XkbIM_UseBase | On or Off | No Effect
XkbIM_UseLatched | On | Any modifiers specified in the mask field of mods are added to the latched modifiers.
XkbIM_UseLatched | Off | Any modifiers specified in the mask field of mods are removed from the latched modifiers.
XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective | On | Any modifiers specified in the mask field of mods are added to the locked modifiers.
XkbIM_UseLocked | Off | Any modifiers specified in the mask field of mods are removed from the locked modifiers.
XkbIM_UseCompat or XkbIM_UseEffective | Off | Any modifiers specified in the mask field of mods are removed from both the locked and latched modifiers.

#### XkbIndicatorMapRec ctrls field

The ctrls field specifies what controls (see ) the indicator watches and is composed using the bitwise inclusive OR of the following values:

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

Xkb lights the indicator whenever any of the boolean controls specified in ctrls is enabled.

XkbIndicatorMapRec

## Getting Information About Indicators

Xkb allows applications to obtain information about indicators using two different methods. The first method, which is similar to the core X implementation, uses a mask to specify the indicators. The second method, which is more suitable for applications concerned with interoperability, uses indicator names. The correspondence between the indicator name and the bit position in masks is as follows: one of the parameters returned from `XkbGetNamedDeviceIndicator` 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.

### Getting Indicator State

Because the state of the indicators is relatively volatile, the keyboard description does not hold the current state of the indicators. To obtain the current state of the keyboard indicators, use `XkbGetIndicatorState`.

Status `XkbGetIndicatorState` Display *display unsigned int device_spec unsigned int *state_return

display

  connection to the X server

device_spec

  device ID, or XkbUseCoreKbd

state_return

  backfilled with a mask of the indicator state

`XkbGetIndicatorState` queries the display 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 BadMatch error. Otherwise, it sends the request to the X server, places the state of the indicators into state_return, and returns Success. Thus the value reported by `XkbGetIndicatorState` is identical to the value reported by the core protocol.

XkbGetIndicatorState

### Getting Indicator Information by Index

To get the map for one or more indicators, using a mask to specify the indicators, use `XkbGetIndicatorMap`.

Status `XkbGetIndicatorMap` Display *dpy unsigned int which XkbDescPtr desc

dpy

  connection to the X server

which

  mask of indicators for which maps should be returned

desc

  keyboard description to be updated

`XkbGetIndicatorMap` 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 desc. If the indicators field of the desc parameter is NULL, `XkbGetIndicatorMap` allocates and initializes it.

`XkbGetIndicatorMap` can generate BadAlloc, BadLength, BadMatch, and BadImplementation errors.

To free the indicator maps, use `XkbFreeIndicatorMaps` (see section 8.6).

XkbGetIndicatorMap

### Getting Indicator Information by Name

Xkb also allows applications to refer to indicators by name. Use `XkbGetNames` 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 XLED_SCROLL_LOCK on Sun workstations, you can instead use `XkbGetNamedDeviceIndicator` or `XkbGetNamedIndicator` to look up information on the indicator named Scroll Lock.

Use `XkbGetNamedDeviceIndicator` to look up the indicator map and other information for an indicator by name on a specific device.

Bool `XkbGetNamedDeviceIndicator` Display *dpy unsigned int device_spec unsigned int led_class unsigned int led_id Atom name int *ndx_rtrn Bool *state_rtrn XkbIndicatorMapPtr map_rtrn Bool *real_rtrn

dpy

  connection to the X server

device_spec

  keyboard device ID, or XkbUseCoreKbd

led_class

  feedback class, or XkbDfltXIClass

led_id

  feedback ID, or XkbDfltXIId

name

  name of the indicator to be retrieved

ndx_rtrn

  backfilled with the index of the retrieved indicator

state_rtrn

  backfilled with the current state of the retrieved indicator

map_rtrn

  backfilled with the mapping for the retrieved indicator

real_rtrn

  backfilled with True if the named indicator is real (physical)

If the device specified by device_spec with feedback specified by led_class and led_id has an indicator named name, `XkbGetNamedDeviceIndicator` returns True and populates the rest of the parameters with information about the indicator. Otherwise, `XkbGetNamedDeviceIndicator` returns False.

The ndx_rtrn 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. state_rtrn returns the current state of the named indicator (True = on, False = off). map_rtrn 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 True.

Each of the "_rtrn" arguments is optional; you can pass NULL for any unneeded "_rtrn" arguments.

`XkbGetNamedDeviceIndicator` can generate BadAtom and BadImplementation errors.

As a convenience function, Xkb provides a function to get information about indicators with the default class and identifier on the default device: `XkbGetNamedIndicator`.

Bool `XkbGetNamedIndicator` Display *dpy Atom name int *ndx_rtrn Bool *state_rtrn XkbIndicatorMapPtr map_rtrn Bool *real_rtrn

dpy

  connection to the X server

name

  name of the indicator to be retrieved

ndx_rtrn

  backfilled with the index of the retrieved indicator

state_rtrn

  backfilled with the current state of the retrieved indicator

map_rtrn

  backfilled with the mapping for the retrieved indicator

real_rtrn

  backfilled with True if the named indicator is real (physical)

`XkbGetNamedIndicator` calls `XkbGetNamedDeviceIndicator` with the specified parameters, a device_spec of XkbUseCoreKbd, a led_class of XkbDfltXIClass, and a led_id of XkbDfltXIId, and returns the value which was returned by `XkbGetNamedDeviceIndicator`.

XkbGetNamedDeviceIndicator
XkbGetNamedIndicator

## Changing Indicator Maps and State

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

You cannot change the phys_indicators field of the indicators structure. The only way to change the phys_indicators 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 `XkbSetNamedDeviceIndicator`, or, to reduce network traffic, use an XkbIndicatorChangesRec structure and use `XkbChangeIndicators`.

### Effects of Explicit Changes on Indicators

This section discusses the effects of explicitly changing indicators depending upon different settings in the indicator map. See Table 8.3 and Table 8.5 for information on the effects of the indicator map fields when explicit changes are made.

If XkbIM_LEDDrivesKB is set and XkbIM_NoExplicit is not, and if you call a function that updates the server’s image of the indicator map (such as `XkbSetIndicatorMap` or `XkbSetNamedDeviceIndicator`), 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 XkbIM_NoExplicit is present, keyboard state or controls are unaffected.

If neither XkbIM_NoAutomatic nor XkbIM_NoExplicit 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.

The effects of changing an indicator that drives the keyboard are cumulative; it is possible for a single change to affect keyboard group, modifiers, and controls simultaneously.

If you change an indicator for which both the XkbIM_LEDDrivesKB and XkbIM_NoAutomatic 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.

If the XkbIM_NoAutomatic flag is not set and XkbIM_LEDDrivesKB 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 XkbIM_UseBase and mods of Shift if, at the time Xkb processes the request to extinguish the indicator, one of the Shift 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 ctrls field of its indicator map. Explicitly extinguishing such an indicator causes Xkb to disable all of the boolean controls specified in ctrls.

### Changing Indicator Maps by Index

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:

Bool `XkbSetIndicatorMap` Display *dpy unsigned int which XkbDescPtr desc

dpy

  connection to the X server

which

  mask of indicators to change

desc

  keyboard description from which the maps are taken

For each bit set in the which parameter, `XkbSetIndicatorMap` sends the corresponding indicator map from the desc parameter to the server.

XkbSetIndicatorMap

### Changing Indicator Maps by Name

`XkbSetNamedDeviceIndicator` and `XkbSetNamedIndicator` can do several related things:

- Name an indicator if it is not already named

- Toggle the state of the indicator

- Set the indicator to a specified state

- Set the indicator map for the indicator

Bool`XkbSetNamedDeviceIndicator` Display *dpy unsigned int device_spec unsigned int led_class unsigned int led_id Atom name Bool change_state Bool state Bool create_new XkbIndicatorMapPtr map

dpy

  connection to the X server

device_spec

  device ID, or XkbUseCoreKbd

led_class

  feedback class, or XkbDfltXIClass

led_id

  feedback ID, or XkbDfltXIId

name

  name of the indicator to change

change_state

  whether to change the indicator state or not

state

  desired new state for the indicator

create_new

  whether a new indicator with the specified name should be created when necessary

map

  new map for the indicator

If a compatible version of the Xkb extension is not available in the server, `XkbSetNamedDeviceIndicator` returns False. Otherwise, it sends a request to the X server to change the indicator specified by name and returns True.

If change_state is True, `XkbSetNamedDeviceIndicator` tells the server to change the state of the named indicator to the value specified by state. If change_state is False, state is not used.

If an indicator with the name specified by name does not already exist, the create_new parameter tells the server whether it should create a new named indicator. If create_new is True, the server finds the first indicator that doesn’t have a name and gives it the name specified by name.

If the optional parameter, map, is not NULL, `XkbSetNamedDeviceIndicator` tells the server to change the indicator’s map to the values specified in map.

`XkbSetNamedDeviceIndicator` can generate BadAtom and BadImplementation errors. In addition, it can also generate XkbIndicatorStateNotify (see section 8.5), XkbIndicatorMapNotify, and XkbNamesNotify events (see section 18.5).

As a convenience function, Xkb provides a function to set information about indicators with the default class and identifier on the default device: `XkbSetNamedIndicator`.

Bool`XkbSetNamedIndicator` Display *dpy Atom name Bool change_state Bool state Bool create_new XkbIndicatorMapPtr map

dpy

  connection to the X server

name

  name of the indicator to change

change_state

  whether to change the indicator state or not

state

  desired new state for the indicator

create_new

  whether a new indicator with the specified name should be created when necessary

map

  new map for the indicator

`XkbSetNamedIndicator` calls `XkbSetNamedDeviceIndicator` with the specified parameters, a device_spec of XkbUseCoreKbd, a led_class of XkbDfltXIClass, and a led_id of XkbDfltXIId, and returns the value which was returned by `XkbSetNamedDeviceIndicator`.

XkbSetNamedDeviceIndicator
XkbSetNamedIndicator

### The XkbIndicatorChangesRec Structure

The XkbIndicatorChangesRec identifies small modifications to the indicator map. Use it with the function `XkbChangeIndicators` to reduce the amount of traffic sent to the server.

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

The state_changes 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.

To change indicator maps or state without passing the entire keyboard description, use `XkbChangeIndicators`.

Bool `XkbChangeIndicators` Display *dpy XkbDescPtr xkb XkbIndicatorChangesPtr changes unsigned int state

dpy

  connection to the X server

xkb

  keyboard description from which names are to be taken.

changes

  indicators to be updated on the server

state

  new state of indicators listed in changes->state_changes

`XkbChangeIndicators` copies any maps specified by changes from the keyboard description, xkb, to the server specified by dpy. If any bits are set in the state_changes field of changes, `XkbChangeIndicators` also sets the state of those indicators to the values specified in the state mask. A 1 bit in state turns the corresponding indicator on, a 0 bit turns it off.

`XkbChangeIndicators` can generate BadAtom and BadImplementation errors. In addition, it can also generate XkbIndicatorStateNotify and XkbIndicatorMapNotify events (see section 8.5).

XkbIndicatorChangesRec
XkbChangeIndicators

## Tracking Changes to Indicator State or Map

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

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

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

Both types of indicator events use the same structure:

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

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

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

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

void `XkbNoteIndicatorChanges` XkbIndicatorChangesPtr old XkbIndicatorNotifyEvent *new unsigned int wanted

old

  XkbIndicatorChanges structure to be updated

new

  event from which changes are to be copied

wanted

  which changes are to be noted

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

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

Status `XkbGetIndicatorChanges` Display *dpy XkbDescPtr xkb XkbIndicatorChangesPtr changes unsigned int *state

dpy

  connection to the X server

xkb

  keyboard description to hold the new values

changes

  indicator maps/state to be obtained from the server

state

  backfilled with the state of the indicators

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

`XkbGetIndicatorChanges` can generate BadAlloc, BadImplementation, and BadMatch errors.

events XkbIndicatorStateNotify
XkbIndicatorStateNotifyEvent
events XkbIndicatorMapNotify
XkbIndicatorMapNotifyEvent
XkbNoteIndicatorChanges
XkbGetIndicatorChanges

## Allocating and Freeing Indicator Maps

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

Status `XkbAllocIndicatorMaps` XkbDescPtr xkb

xkb

  keyboard description structure

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

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

void `XkbFreeIndicatorMaps` XkbDescPtr xkb

xkb

  keyboard description structure

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

XkbAllocIndicatorMaps
XkbFreeIndicatorMaps
indicators