table of contents
XICHANGEPROPERTY(3) | XICHANGEPROPERTY(3) |
NAME¶
XIChangeProperty, XIGetProperty, XIDeleteProperty - change, retrieve or delete a device's property.SYNOPSIS¶
#include <X11/extensions/XInput2.h>
void XIChangeProperty( Display* dpy, int deviceid, Atom property, Atom type, int format, int mode, unsigned char *data, int num_items)
void XIDeleteProperty( Display *dpy, int deviceid, Atom property)
Status XIGetProperty( Display *dpy, int deviceid, Atom property, long offset, long length, Bool delete_property, Atom type, Atom *type_return, int *format_return, unsigned long *num_items_return, unsigned long *bytes_after_return, unsigned char **data)
bytes_after_return Returns the number of bytes remaining to be read in the prop- erty if a partial read was performed.
data Specifies the property data.
display Specifies the connection to the X server.
delete_property Specifies a Boolean value that determines whether the property is to be deleted.
deviceid The device to list the properties for.
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 your data pointer to an (unsigned char *) in the call to XIChangeProperty.
format_return Returns the actual format of the property.
length Specifies the length in 32-bit multiples of the data to be retrieved.
offset Specifies the offset in the specified property (in 32-bit quantities) where the data is to be retrieved.
mode One of XIPropModeAppend, XIPropModePrepend or XIPropModeReplace.
num_items Number of items in data in the format specified.
nitems_return Returns the actual number of 8-bit, 16-bit, or 32-bit items stored in data.
property Specifies the property name.
type Specifies the type of the property. The X server does not interpret the type but simply passes it back to an application that later calls XIGetProperty.
type_return Returns the atom identifier that defines the actual type of the property.
DESCRIPTION¶
The XIGetProperty 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. XIGetProperty sets the return arguments as follows:•If the specified property does not
exist for the specified device, XIGetProperty returns None to
actual_type_return and the value zero to actual_format_return and
bytes_after_return. The nitems_return argument is empty. In this case, the
delete argument is ignored.
•If the specified property exists but
its type does not match the specified type, XIGetProperty returns the actual
property type to actual_type_return, the actual property format (never zero)
to actual_format_return, and the property length in bytes (even if the
actual_format_return is 16 or 32) to bytes_after_return. It also ignores the
delete argument. The nitems_return argument is empty.
•If the specified property exists and
either you assign XIAnyPropertyType to the req_type argument or the specified
type matches the actual property type, XIGetProperty returns the actual
property type to actual_type_return and the actual property format (never
zero) to actual_format_return. It also returns a value to bytes_after_return
and nitems_return, by defining the following values:
N = length of the stored property in bytes I = 4 * offset T = N - I L = MINIMUM(T, 4 * length) A = N - (I + L)
•If mode is XIPropModeReplace,
XIChangeProperty discards the previous property value and stores the new
data.
•If mode is XIPropModePrepend or
XIPropModeAppend, XIChangeProperty inserts the specified data before the
beginning of the existing data or onto the end of the existing data,
respectively. The type and format must match the existing property value, or a
BadMatch error results. If the property is undefined, it is treated as defined
with the correct type and format with zero-length data.
DIAGNOSTICS¶
BadAlloc The server failed to allocate the requested resource or server memory.BUGS¶
The protocol headers for XI 2.0 did not provide XIAnyPropertyType, XIPropModeReplace, XIPropModePrepend or XIPropModeAppend. Use AnyPropertyType, PropModeReplace, PropModePrepend and PropModeAppend instead, respectively.
SEE ALSO¶
XIListProperties(3)05/15/2013 |