xenocara/lib/libXi/man/XGetDeviceProperty.man

'\" t
.\"     Title: xgetdeviceproperty
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/05/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "XGETDEVICEPROPERTY" "libmansuffix" "09/05/2024" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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"
XGetDeviceProperty, XChangeDeviceProperty, XDeleteDeviceProperty \- Get, change or delete a device\*(Aqs property\&.
.SH "SYNOPSIS"
.sp
.nf
#include <X11/extensions/XInput\&.h>
.fi
.sp
.nf
int XGetDeviceProperty( Display *display,
                        XDevice *device,
                        Atom property,
                        long offset,
                        long length,
                        Bool delete,
                        Atom req_type,
                        Atom *actual_type_return,
                        int *actual_format_return,
                        unsigned long *nitems_return,
                        unsigned long *bytes_after_return,
                        unsigned char **prop_return)
.fi
.sp
.nf
void XChangeDeviceProperty( Display *display,
                            XDevice *device,
                            Atom property,
                            Atom type,
                            int format,
                            int mode,
                            const unsigned char *data,
                            int nelements)
.fi
.sp
.nf
void XDeleteDeviceProperty( Display *display,
                            XDevice *device,
                            Atom property)
.fi
.sp
.nf
actual_type_return
       Returns an atom identifier that defines the actual type
       of the property\&.
.fi
.sp
.nf
actual_format_return
       Returns the actual format of the property\&.
.fi
.sp
.nf
bytes_after_return
       Returns the number of bytes remaining to be read in the
       property if a partial read was performed\&.
.fi
.sp
.nf
data
       Specifies the property data\&.
.fi
.sp
.nf
delete
       Specifies a Boolean value that determines whether the
       property is deleted\&.
.fi
.sp
.nf
display
       Specifies the connection to the X server\&.
.fi
.sp
.nf
device
       The device to grab\&.
.fi
.sp
.nf
format
       Specifies whether the data should be viewed as a list of
       8\-bit, 16\-bit, or 32\-bit quantities\&. Possible values are
       8, 16, and 32\&. This information allows the X server to
       correctly perform byte\-swap operations as necessary\&. If
       the format is 16\-bit or 32\-bit, you must explicitly cast
       the data pointer to an (unsigned char*) in the call to
       XChangeDeviceProperty\&.
.fi
.sp
.nf
length
       Specifies the length in 32\-bit multiplies of the data to
       be retrieved\&.
.fi
.sp
.nf
mode
       Specifies the mode of operation\&. You can pass
       PropModeReplace, PropModePrepend, or PropModeAppend\&.
.fi
.sp
.nf
nelements
       Specifies the number of elements in data\&.
.fi
.sp
.nf
nitems_return
       Returns the actual number of 8\-bit, 16\-bit, or 32\-bit
       items stored in the prop_return array\&.
.fi
.sp
.nf
num_values
       Specifies the number of elements in the values list\&.
.fi
.sp
.nf
offset
       Specifies the offset in the specified property (in
       32\-bit quantities) where the data is to be retrieved\&.
.fi
.sp
.nf
property
       Specifies the property to modify or query\&.
.fi
.sp
.nf
prop_return
       Returns the data in the specified format\&. If the
       returned format is 8, the returned data is represented
       as a char array\&. If the returned format is 16, the
       returned data is represented as an array of short int
       type and should be cast to that type to obtain the
       elements\&. If the returned format is 32, the property
       data will be stored as an array of longs (which in a
       64\-bit application will be 64\-bit values that are padded
       in the upper 4 bytes)\&.
.fi
.sp
.nf
req_type
       Specifies the atom identifier associated with the
       property type or AnyPropertyType\&.
.fi
.SH "DESCRIPTION"
.sp
The XGetDeviceProperty function returns the actual type of the property; the actual format of the property; the number of 8\-bit, 16\-bit, or 32\-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned\&. For a detailed description of this function, see the man page to XGetWindowProperty\&.
.sp
The XChangeDeviceProperty function alters the property for the specified device and causes the server to generate a XPropertyNotifyEvent event on that device\&. For a detailed description of this function, see the man page to XChangeProperty\&.
.sp
The XDeleteDeviceProperty function deletes the specified device property\&. Note that a client cannot delete a property created by a driver or the server\&. Attempting to do so will result in a BadAtom error\&.
.sp
XGetDeviceProperty can generate a BadAtom, BadDevice error\&.
.sp
XChangeDeviceProperty can generate a BadDevice, a BadMatch, a BadAtom, and a BadValue error\&.
.sp
XDeleteDeviceProperty can generate a BadDevice, and a BadAtom error\&.
.SH "DIAGNOSIS"
.sp
.if n \{\
.RS 4
.\}
.nf
BadAtom
       A value does not describe a valid named identifier or
       the client attempted to remove a driver\-allocated
       property\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
BadDevice
       An invalid device was specified\&. The device does not
       exist\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
.if n \{\
.RS 4
.\}
.nf
XListDeviceProperties(libmansuffix)
.fi
.if n \{\
.RE
.\}