path: root/lib/libXi/man/XGetFeedbackControl.man

'\" t
.\"     Title: xgetfeedbackcontrol
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/04/2023
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "XGETFEEDBACKCONTROL" "libmansuffix" "05/04/2023" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
XGetFeedbackControl, XChangeFeedbackControl \- query and change input device feedbacks
.SH "SYNOPSIS"
.sp
.nf
#include <X11/extensions/XInput\&.h>
.fi
.sp
.nf
XFeedbackState *XGetFeedbackControl( Display *display,
                                     XDevice *device,
                                     int *num_feedbacks);
.fi
.sp
.nf
int XChangeFeedbackControl( Display *display,
                            XDevice *device,
                            Mask mask,
                            XFeedbackControl *control);
.fi
.sp
.nf
display
       Specifies the connection to the X server\&.
.fi
.sp
.nf
device
       Specifies the device whose feedbacks are to be queried
       or modified\&.
.fi
.sp
.nf
num_feedbacks
       Specifies an address into which the number of feedbacks
       supported by the device is to be returned\&.
.fi
.sp
.nf
mask
       Specifies a mask specific to each type of feedback that
       describes how the feedback is to be modified\&.
.fi
.sp
.nf
control
       Specifies the address of an XFeedbackControl structure
       that contains the new values for the feedback\&.
.fi
.SH "DESCRIPTION"
.sp
.if n \{\
.RS 4
.\}
.nf
These requests are provided to manipulate those input devices
that support feedbacks\&. A BadMatch error will be generated if
the requested device does not support feedbacks\&. Whether or not
a given device supports feedbacks can be determined by
examining the information returned by the XOpenDevice request\&.
For those devices that support feedbacks, XOpenDevice will
return an XInputClassInfo structure with the input_class field
equal to the constant FeedbackClass (defined in the file XI\&.h)\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XGetFeedbackControl request returns a pointer to a list of
XFeedbackState structures\&. Each item in this list describes one
of the feedbacks supported by the device\&. The items are
variable length, so each contains its length to allow traversal
to the next item in the list\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The feedback classes that are currently defined are:
KbdFeedbackClass, PtrFeedbackClass, StringFeedbackClass,
IntegerFeedbackClass, LedFeedbackClass, and BellFeedbackClass\&.
These constants are defined in the file XI\&.h\&. An input device
may support zero or more classes of feedback, and may support
multiple feedbacks of the same class\&. Each feedback contains a
class identifier and an id that is unique within that class for
that input device\&. The id is used to identify the feedback when
making an XChangeFeedbackControl request\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
XGetFeedbackControl can generate a BadDevice or BadMatch error\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XChangeFeedbackControl request modifies the values of one
feedback on the specified device\&. The feedback is identified by
the id field of the XFeedbackControl structure that is passed
with the request\&. The fields of the feedback that are to be
modified are identified by the bits of the mask that is passed
with the request\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
XChangeFeedbackControl can generate a BadDevice, BadMatch, or
BadValue error\&.
.fi
.if n \{\
.RE
.\}
.SS "Structures"
.sp
.if n \{\
.RS 4
.\}
.nf
Each class of feedback is described by a structure specific to
that class\&. These structures are defined in the file XInput\&.h\&.
XFeedbackState and XFeedbackControl are generic structures that
contain three fields that are at the beginning of each class of
feedback:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
} XFeedbackState, XFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XKbdFeedbackState structure defines the attributes that are
returned for feedbacks equivalent to those on the X keyboard\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int click;
    int percent;
    int pitch;
    int duration;
    int led_mask;
    int global_auto_repeat;
    char auto_repeats[32];
} XKbdFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XPtrFeedbackState structure defines the attributes that are
returned for feedbacks equivalent to those on the the X
pointer\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int accelNum;
    int accelDenom;
    int threshold;
} XPtrFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XIntegerFeedbackState structure defines attributes that are
returned for integer feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int resolution;
    int minVal;
    int maxVal;
} XIntegerFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XStringFeedbackState structure defines the attributes that
are returned for string feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int max_symbols;
    int num_syms_supported;
    KeySym *syms_supported;
} XStringFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XBellFeedbackState structure defines the attributes that
are returned for bell feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int percent;
    int pitch;
    int duration;
} XBellFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XLedFeedbackState structure defines the attributes that are
returned for LED feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int led_values;
} XLedFeedbackState;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XPrtFeedbackControl structure defines the attributes that
can be controlled for pointer feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int accelNum;
    int accelDenom;
    int threshold;
} XPtrFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XKbdFeedbackControl structure defines the attributes that
can be controlled for keyboard feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int click;
    int percent;
    int pitch;
    int duration;
    int led_mask;
    int led_value;
    int key;
    int auto_repeat_mode;
} XKbdFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XStringFeedbackControl structure defines the attributes
that can be controlled for string feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int num_keysyms;
    KeySym  *syms_to_display;
} XStringFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XIntegerFeedbackControl structure defines the attributes
that can be controlled for integer feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID class;
    int length;
    XID id;
    int int_to_display;
} XIntegerFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XBellFeedbackControl structure defines the attributes that
can be controlled for bell feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     percent;
    int     pitch;
    int     duration;
} XBellFeedbackControl;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The XLedFeedbackControl structure defines the attributes that
can be controlled for LED feedbacks\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     led_mask;
    int     led_values;
} XLedFeedbackControl;
.fi
.if n \{\
.RE
.\}
.SH "DIAGNOSTICS"
.sp
.if n \{\
.RS 4
.\}
.nf
BadDevice
       An invalid device was specified\&. The specified device
       does not exist or has not been opened by this client via
       XOpenInputDevice\&. This error may also occur if some
       other client has caused the specified device to become
       the X keyboard or X pointer device via the
       XChangeKeyboardDevice or XChangePointerDevice requests\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
BadMatch
       This error may occur if an XGetFeedbackControl request
       was made specifying a device that has no feedbacks, or
       an XChangeFeedbackControl request was made with an
       XFeedbackControl structure that contains an invalid
       feedback type\&. It may also occur if an invalid
       combination of mask bits is specified ( DvKey but no
       DvAutoRepeatMode for keyboard feedbacks), or if an
       invalid KeySym is specified for a string feedback\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
BadValue
       Some numeric value falls outside the range of values
       accepted by the XChangeFeedbackControl request\&. Unless a
       specific range is specified for an argument, the full
       range defined by the argument\*(Aqs type is accepted\&. Any
       argument defined as a set of alternatives can generate
       this error\&.
.fi
.if n \{\
.RE
.\}