XGetDeviceProperty.txt revision c27c18e8 
1XGETDEVICEPROPERTY(libmansuffix)
2================================
3
4NAME
5----
6
7   XGetDeviceProperty, XChangeDeviceProperty,
8   XDeleteDeviceProperty - Get, change or delete a device's
9   property.
10
11SYNOPSIS
12--------
13
14   #include <X11/extensions/XInput.h>
15 
16   int XGetDeviceProperty( Display *display,
17                           XDevice *device,
18                           Atom property,
19                           long offset,
20                           long length,
21                           Bool delete,
22                           Bool pending,
23                           Atom req_type,
24                           Atom *actual_type_return,
25                           int *actual_format_return,
26                           unsigned long *nitems_return,
27                           unsigned long *bytes_after_return,
28                           unsigned char **prop_return)
29
30   void XChangeDeviceProperty( Display *display,
31                               XDevice *device,
32                               Atom property,
33                               Atom type,
34                               int format,
35                               int mode,
36                               const char *data,
37                               int nelements)
38
39   void XDeleteDeviceProperty( Display *display,
40                               XDevice *device,
41                               Atom property)
42
43
44   actual_type_return
45          Returns an atom identifier that defines the actual type
46          of the property.
47
48   actual_format_return
49          Returns the actual format of the property.
50
51   bytes_after_return
52          Returns the number of bytes remaining to be read in the
53          property if a partial read was performed.
54
55   data
56          Specifies the property data.
57
58   delete
59          Specifies a Boolean value that determines whether the
60          property is deleted.
61
62   display
63          Specifies the connection to the X server.
64
65   device
66          The device to grab.
67
68   format
69          Specifies whether the data should be viewed as a list of
70          8-bit, 16-bit, or 32-bit quantities. Possible values are
71          8, 16, and 32. This information allows the X server to
72          correctly perform byte-swap operations as necessary. If
73          the format is 16-bit or 32-bit, you must explicitly cast
74          the data pointer to an (unsigned char*) in the call to
75          XChangeDeviceProperty.
76
77   length
78          Specifies the length in 32-bit multiplies of the data to
79          be retrieved.
80
81   mode
82          Specifies the mode of operation. You can pass
83          PropModeReplace, PropModePrepend, or PropModeAppend.
84
85   nelements
86          Specifies the number of elements in data.
87
88   nitems_return
89          Returns the actual number of 8-bit, 16-bit, or 32-bit
90          items stored in the prop_return array.
91
92   num_values
93          Specifies the number of elements in the values list.
94
95   offset
96          Specifies the offset in the specified property (in
97          32-bit quantities) where the data is to be retrieved.
98
99   pending
100          Specifies whether to retrieve the pending state of the
101          property or the current state.
102
103   property
104          Specifies the property to modify or query.
105
106   prop_return
107          Returns the data in the specified format. If the
108          returned format is 8, the returned data is represented
109          as a char array. If the returned format is 16, the
110          returned data is represented as an array of short int
111          type and should be cast to that type to obtain the
112          elements. If the returned format is 32, the property
113          data will be stored as an array of longs (which in a
114          64-bit application will be 64-bit values that are padded
115          in the upper 4 bytes).
116
117   req_type
118          Specifies the atom identifier associated with the
119          property type or AnyPropertyType.
120
121DESCRIPTION
122-----------
123
124The XGetDeviceProperty function returns the actual type of the
125property; the actual format of the property; the number of
1268-bit, 16-bit, or 32-bit items transferred; the number of bytes
127remaining to be read in the property; and a pointer to the data
128actually returned. For a detailed description of this function,
129see the man page to XGetWindowProperty.
130
131The XChangeDeviceProperty function alters the property for the
132specified device and causes the server to generate a
133XPropertyNotifyEvent event on that device. For a detailed
134description of this function, see the man page to
135XChangeProperty.
136
137The XDeleteDeviceProperty function deletes the specified device
138property. Note that a client cannot delete a property created
139by a driver or the server. Attempting to do so will result in a
140BadAtom error.
141
142XGetDeviceProperty can generate a BadAtom, BadDevice error.
143
144XChangeDeviceProperty can generate a BadDevice, a BadMatch, a
145BadAtom, and a BadValue error.
146
147XDeleteDeviceProperty can generate a BadDevice, and a BadAtom
148error.
149
150DIAGNOSIS
151---------
152
153   BadAtom
154          A value does not describe a valid named identifier or
155          the client attempted to remove a driver-allocated
156          property.
157
158   BadDevice
159          An invalid device was specified. The device does not
160          exist.
161
162SEE ALSO
163--------
164
165   XListDeviceProperties(libmansuffix)
166