1XICHANGEPROPERTY(3) XICHANGEPROPERTY(3)
2
6 XIChangeProperty, XIGetProperty, XIDeleteProperty - change, retrieve or
7 delete a device's property.
8
10 #include <X11/extensions/XInput2.h>
11 void XIChangeProperty( Display* dpy,
13 int deviceid,
14 Atom property,
15 Atom type,
16 int format,
17 int mode,
18 unsigned char *data,
19 int num_items)
20 void XIDeleteProperty( Display *dpy,
22 int deviceid,
23 Atom property)
24 Status XIGetProperty( Display *dpy,
26 int deviceid,
27 Atom property,
28 long offset,
29 long length,
30 Bool delete_property,
31 Atom type,
32 Atom *type_return,
33 int *format_return,
34 unsigned long *num_items_return,
35 unsigned long *bytes_after_return,
36 unsigned char **data)
37 bytes_after_return
39 Returns the number of bytes remaining to be read in the property
40 if a partial read was performed.
41 data
43 Specifies the property data.
44 display
46 Specifies the connection to the X server.
47 delete_property
49 Specifies a Boolean value that determines whether the property
50 is to be deleted.
51 deviceid
53 The device to list the properties for.
54 format
56 Specifies whether the data should be viewed as a list of
57 8-bit, 16-bit, or 32-bit quantities. Possible values are 8,
58 16, and 32. This information allows the X server to correctly
59 perform byte-swap operations as necessary. If the
60 format is 16-bit or 32-bit, you must explicitly cast your
61 data pointer to an (unsigned char *) in the call to
62 XIChangeProperty.
63 format_return
65 Returns the actual format of the property.
66 length
68 Specifies the length in 32-bit multiples of the data to be
69 retrieved.
70 offset
72 Specifies the offset in the specified property (in 32-bit
73 quantities) where the data is to be retrieved.
74 mode
76 One of XIPropModeAppend, XIPropModePrepend or XIPropModeReplace.
77 num_items
79 Number of items in data in the format specified.
80 nitems_return
82 Returns the actual number of 8-bit, 16-bit, or 32-bit items
83 stored in data.
84 property
86 Specifies the property name.
87 type
89 Specifies the type of the property. The X server does not
90 interpret the type but simply passes it back to an application
91 that later calls XIGetProperty.
92 type_return
94 Returns the atom identifier that defines the actual type of
95 the property.
96
98 The XIGetProperty function returns the actual type of the property; the
99 actual format of the property; the number of 8-bit, 16-bit, or 32-bit
100 items transferred; the number of bytes remaining to be read in the
101 property; and a pointer to the data actually returned. XIGetProperty
102 sets the return arguments as follows:
103 • If the specified property does not exist for the specified device,
105 XIGetProperty returns None to actual_type_return and the value zero
106 to actual_format_return and bytes_after_return. The nitems_return
107 argument is empty. In this case, the delete argument is ignored.
108 • If the specified property exists but its type does not match the
110 specified type, XIGetProperty returns the actual property type to
111 actual_type_return, the actual property format (never zero) to
112 actual_format_return, and the property length in bytes (even if the
113 actual_format_return is 16 or 32) to bytes_after_return. It also
114 ignores the delete argument. The nitems_return argument is empty.
115 • If the specified property exists and either you assign
117 XIAnyPropertyType to the req_type argument or the specified type
118 matches the actual property type, XIGetProperty returns the actual
119 property type to actual_type_return and the actual property format
120 (never zero) to actual_format_return. It also returns a value to
121 bytes_after_return and nitems_return, by defining the following
122 values:
123 N = length of the stored property in bytes
125 I = 4 * offset
126 T = N - I
127 L = MINIMUM(T, 4 * length)
128 A = N - (I + L)
129 The returned value starts at byte index I in the property (indexing
131 from zero), and its length in bytes is L. If the value for long_offset
132 causes L to be negative, a BadValue error results. The value of
133 bytes_after_return is A, giving the number of trailing unread bytes in
134 the stored property.
135 If the returned format is 8, the returned data is represented as a char
137 array. If the returned format is 16, the returned data is represented
138 as a uint16_t array and should be cast to that type to obtain the
139 elements. If the returned format is 32, the returned data is
140 represented as a uint32_t array and should be cast to that type to
141 obtain the elements.
142 XIGetProperty always allocates one extra byte in prop_return (even if
144 the property is zero length) and sets it to zero so that simple
145 properties consisting of characters do not have to be copied into yet
146 another string before use.
147 If delete is True and bytes_after_return is zero, XIGetProperty deletes
149 the property from the window and generates an XIPropertyNotify event on
150 the window.
151 The function returns Success if it executes successfully. To free the
153 resulting data, use XFree.
154 XIGetProperty can generate BadAtom, BadValue, and BadWindow errors.
156 The XIChangeProperty function alters the property for the specified
158 device and causes the X server to generate a XIPropertyNotify event for
159 that device. XIChangeProperty performs the following:
160 • If mode is XIPropModeReplace, XIChangeProperty discards the
162 previous property value and stores the new data.
163 • If mode is XIPropModePrepend or XIPropModeAppend, XIChangeProperty
165 inserts the specified data before the beginning of the existing
166 data or onto the end of the existing data, respectively. The type
167 and format must match the existing property value, or a BadMatch
168 error results. If the property is undefined, it is treated as
169 defined with the correct type and format with zero-length data.
170 If the specified format is 8, the property data must be a char array.
172 If the specified format is 16, the property data must be a uint16_t
173 array. If the specified format is 32, the property data must be a
174 uint32_t array.
175 The lifetime of a property is not tied to the storing client.
177 Properties remain until explicitly deleted, until the device is
178 removed, or until the server resets. The maximum size of a property is
179 server dependent and can vary dynamically depending on the amount of
180 memory the server has available. (If there is insufficient space, a
181 BadAlloc error results.)
182 XIChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue,
184 and BadDevice errors.
185 The XIDeleteProperty function deletes the specified property only if
187 the property was defined on the specified device and causes the X
188 server to generate a XIPropertyNotify event for the device unless the
189 property does not exist.
190 XIDeleteProperty can generate BadAtom and BadDevice errors.
192
194 BadAlloc The server failed to allocate the requested resource or server
195 memory.
196 BadAtom A value for an Atom argument does not name a defined Atom.
198 BadValue Some numeric value falls outside the range of values accepted
200 by the request. Unless a specific range is specified for an argument,
201 the full range defined by the argument’s type is accepted. Any argument
202 defined as a set of alternatives can generate this error.
203 BadDevice An invalid device was specified. The device does not exist.
205 BadAtom An invalid property was specified. The property does not exist.
207
209 The protocol headers for XI 2.0 did not provide
210 XIAnyPropertyType, XIPropModeReplace, XIPropModePrepend or
211 XIPropModeAppend. Use AnyPropertyType, PropModeReplace,
212 PropModePrepend and PropModeAppend instead, respectively.
213
215 XIListProperties(3)
216 05/04/2023 XICHANGEPROPERTY(3)