Miscellaneous Functions

Changing the Mode of an Input Device

To change the mode of a device, use XSetDeviceMode.

int XSetDeviceMode(display, device, mode)
        Display *display;
        XDevice *device;
        int      mode;

The XSetDeviceMode function changes the mode of an input device that is capable of reporting either absolute positional information or relative motion information. Not all input devices are capable of reporting motion data, and not all are capable of changing modes from Absolute to Relative.

XSetDeviceMode can generate a BadDevice or BadMode error.

Checking the State of an Extension Input Device

To query the state of the keys, buttons, and valuators of an extension input device, use XQueryDeviceState.

XDeviceState *XQueryDeviceState(display, device)
        Display *display;
        XDevice *device;

The XQueryDeviceState function queries the state of an input device. The current state of keys and buttons (up or down), and valuators (current value) on the device is reported by this request. Each key or button is represented by a bit in the XKeyState or XButtonState structure that is returned. Valuators on the device report 0 if they are reporting relative information, or the current value if they are reporting absolute information.

XQueryDeviceState can generate a BadDevice error.

The XDeviceState structure contains:

typedef struct {
        XID          device_id;
        int          num_classes;
        XInputClass *data;
} XDeviceState;

The XValuatorState structure contains:

typedef struct {
        unsigned char class;
        unsigned char length;
        unsigned char num_valuators;
        unsigned char mode;
        int          *valuators;
} XValuatorState;

The XKeyState structure contains:

typedef struct {
        unsigned char class;
        unsigned char length;
        unsigned char num_keys;
        char          keys[32];
} XKeyState;

The XButtonState structure contains:

typedef struct {
        unsigned char class;
        unsigned char length;
        unsigned char num_buttons;
        char          buttons[32];
} XButtonState;

Finding the Extension Version

To find the version of the input extension, use XGetExtensionVersion.

XExtensionVersion *XGetExtensionVersion(display, name)
        Display *display;
        char    *name;

The XGetExtensionVersion function queries the version of the input extension, and returns an XExtensionVersion structure. You should use XFree to free the XExtensionVersion structure.

This function returns an XExtensionVersion structure.

typedef struct {
        int     present;
        short   major_version;
        short   minor_version;
} XExtensionVersion;

Ringing a Bell on an Extension Input Device

To ring a bell on a extension input device, use XDeviceBell.

void XDeviceBell (display, device, feedbackclass, feedbackid,
percent)
        Display *display;
        XDevice *device;
        XID      feedbackclass, feedbackid;
        int      percent;

This function is analogous to the core XBell function. It rings the specified bell on the specified input device feedback using the specified volume.

The specified volume is relative to the base volume for the feedback. If the value for the percent argument is not in the range -100 to 100 inclusive, a BadValue error results.

The volume at which the bell rings when the percent argument is nonnegative is:

base - (( base * percent) / 100) + percent

The volume at which the bell rings when the percent argument is negative is:

base + ( ( base * percent )/100 )

To change the base volume of the bell, use ChangeFeedbackControl.

XDeviceBell can generate BadDevice and BadValue errors.

Initializing Valuators on an Input Device

Some devices that report absolute positional data can be initialized to a starting value. Devices that are capable of reporting relative motion or absolute positional data may require that their valuators be initialized to a starting value after the mode of the device is changed to Absolute. To initialize the valuators on such a device, use the SetDeviceValuators function.

Status XSetDeviceValuators (display, device, valuators,
first_valuator, num_valuators)
        Display *display;
        XDevice *device;
        int     *valuators, first_valuator, num_valuators;

This function initializes the specified valuators on the specified extension input device. Valuators are numbered beginning with zero. Only the valuators in the range specified by first_valuator and num_valuators are set. If the number of valuators supported by the device is less than the expression first_valuator + num_valuators, a BadValue error will result.

If the request succeeds, Success is returned. If the specified device is grabbed by some other client, the request will fail and a status of AlreadyGrabbed will be returned.

XSetDeviceValuators can generate BadLength, BadDevice, BadMatch, and BadValue errors.

Getting Input Device Controls

Some input devices support various configuration controls that can be queried or changed by clients. The set of supported controls will vary from one input device to another. Requests to manipulate these controls will fail if either the target X server or the target input device does not support the requested device control.

Each device control has a unique identifier. Information passed with each device control varies in length and is mapped by data structures unique to that device control.

To query a device control, use the XGetDeviceControl function.

XDeviceControl *XGetDeviceControl (display, device, control)
        Display *display;
        XDevice *device;
        int      control;

This request returns the current state of the specified device control. If the target X server does not support that device control, a BadValue error is returned. If the specified device does not support that device control, a BadMatch error is returned.

If the request is successful, a pointer to a generic XDeviceState structure is returned. The information returned varies according to the specified control and is mapped by a structure appropriate for that control. The first two fields are common to all device controls:

typedef struct {
      XID     control;
      int     length;
} XDeviceState;

The control may be compared to constants defined in the file XI.h. Currently defined device controls include DEVICE_RESOLUTION.

The information returned for the DEVICE_RESOLUTION control is defined in the following XDeviceResolutionState structure:

typedef struct {
      XID     control;
      int     length;
      int     num_valuators;
      int     *resolutions;
      int     *min_resolutions;
      int     *max_resolutions;
} XDeviceResolutionState;

This device control returns a list of valuators and the range of valid resolutions allowed for each. Valuators are numbered beginning with 0. Resolutions for all valuators on the device are returned. For each valuator i on the device, resolutions[i] returns the current setting of the resolution, min_resolutions[i] returns the minimum valid setting, and max_resolutions[i] returns the maximum valid setting.

When this control is specified for a device that has no valuators, XGetDeviceControl will fail with a BadMatch error.

XGetDeviceControl can generate BadMatch and BadValue errors.

Changing Input Device Controls

Some input devices support various configuration controls that can be changed by clients. Typically, this is done to initialize the device to a known state or configuration. The set of supported controls varies from one input device to another. Requests to manipulate these controls fail if either the target X server or the target input device does not support the requested device control. Setting the device control also fails if the target input device is grabbed by another client, or has been opened by another client and has been set to a conflicting state.

Each device control has a unique identifier. Information passed with each device control varies in length and is mapped by data structures unique to that device control.

To change a device control use XChangeDeviceControl.

Status XChangeDeviceControl (display, device, control, value)
        Display        *display;
        XDevice        *device;
        XID             control;
        XDeviceControl *value;

This request changes the current state of the specified device control. If the target X server does not support that device control, a BadValue error is returned. If the specified device does not support that device control, a BadMatch error is returned. If another client has the target device grabbed, a status of AlreadyGrabbed will be returned. If another client has the device open and has set it to a conflicting state, a status of DeviceBusy is returned.

If the request fails for any reason, the device control will not be changed.

If the request is successful, the device control will be changed and a status of Success will be returned. The information passed varies according to the specified control and is mapped by a structure appropriate for that control. The first two fields are common to all device controls:

typedef struct {
      XID     control;
      int     length;
} XDeviceControl;

The control may be set using constants defined in the file XI.h. Currently defined device controls include DEVICE_RESOLUTION.

The information that can be changed by the DEVICE_RESOLUTION control is defined in the following XDeviceResolutionControl structure:

typedef struct {
      XID     control;
      int     length;
      int     first_valuator;
      int     num_valuators;
      int     *resolutions;
} XDeviceResolutionControl;

This device control changes the resolution of the specified valuators on the specified extension input device. Valuators are numbered beginning with zero. Only the valuators in the range specified by first_valuator and num_valuators are set. A value of -1 in the resolutions list indicates that the resolution for this valuator is not to be changed. The num_valuators field specifies the number of valuators in the resolutions list.

When this control is specified, XChangeDeviceControl fails with a BadMatch error if the specified device has no valuators. If a resolution is specified that is not within the range of valid values (as returned by XGetDeviceControl) the request will fail with a BadValue error. If the number of valuators supported by the device is less than the expression first_valuator + num_valuators, a BadValue error will result.