1XGetWindowProperty(3X11) XLIB FUNCTIONS XGetWindowProperty(3X11)
2
6 XGetWindowProperty, XListProperties, XChangeProperty, XRotateWindow‐
7 Properties, XDeleteProperty - obtain and change window properties
8
10 int XGetWindowProperty(Display *display, Window w, Atom property, long
11 long_offset, long long_length, Bool delete, Atom req_type, Atom
12 *actual_type_return, int *actual_format_return, unsigned long
13 *nitems_return, unsigned long *bytes_after_return, unsigned char
14 **prop_return);
15 Atom *XListProperties(Display *display, Window w, int
17 *num_prop_return);
18 int XChangeProperty(Display *display, Window w, Atom property, Atom
20 type, int format, int mode, unsigned char *data, int nelements);
21 int XRotateWindowProperties(Display *display, Window w, Atom proper‐
23 ties[], int num_prop, int npositions);
24 int XDeleteProperty(Display *display, Window w, Atom property);
26
28 actual_format_return
29 Returns the actual format of the property.
30 actual_type_return
32 Returns the atom identifier that defines the actual type of
33 the property.
34 bytes_after_return
36 Returns the number of bytes remaining to be read in the prop‐
37 erty if a partial read was performed.
38 data Specifies the property data.
40 delete Specifies a Boolean value that determines whether the prop‐
42 erty is deleted.
43 display Specifies the connection to the X server.
45 format Specifies whether the data should be viewed as a list of
47 8-bit, 16-bit, or 32-bit quantities. Possible values are 8,
48 16, and 32. This information allows the X server to cor‐
49 rectly perform byte-swap operations as necessary. If the
50 format is 16-bit or 32-bit, you must explicitly cast your
51 data pointer to an (unsigned char *) in the call to XChange‐
52 Property.
53 long_length
55 Specifies the length in 32-bit multiples of the data to be
56 retrieved.
57 long_offset
59 Specifies the offset in the specified property (in 32-bit
60 quantities) where the data is to be retrieved.
61 mode Specifies the mode of the operation. You can pass PropMod‐
63 eReplace, PropModePrepend, or PropModeAppend.
64 nelements Specifies the number of elements of the specified data for‐
66 mat.
67 nitems_return
69 Returns the actual number of 8-bit, 16-bit, or 32-bit items
70 stored in the prop_return data.
71 num_prop Specifies the length of the properties array.
73 num_prop_return
75 Returns the length of the properties array.
76 npositions
78 Specifies the rotation amount.
79 prop_return
81 Returns the data in the specified format.
82 property Specifies the property name.
84 properties
86 Specifies the array of properties that are to be rotated.
87 req_type Specifies the atom identifier associated with the property
89 type or AnyPropertyType.
90 type Specifies the type of the property. The X server does not
92 interpret the type but simply passes it back to an applica‐
93 tion that later calls XGetWindowProperty.
94 w Specifies the window whose property you want to obtain,
96 change, rotate or delete.
97
99 The XGetWindowProperty function returns the actual type of the prop‐
100 erty; the actual format of the property; the number of 8-bit, 16-bit,
101 or 32-bit items transferred; the number of bytes remaining to be read
102 in the property; and a pointer to the data actually returned. XGetWin‐
103 dowProperty sets the return arguments as follows:
104 · If the specified property does not exist for the specified window,
106 XGetWindowProperty returns None to actual_type_return and the
107 value zero to actual_format_return and bytes_after_return. The
108 nitems_return argument is empty. In this case, the delete argu‐
109 ment is ignored.
110 · If the specified property exists but its type does not match the
112 specified type, XGetWindowProperty returns the actual property
113 type to actual_type_return, the actual property format (never
114 zero) to actual_format_return, and the property length in bytes
115 (even if the actual_format_return is 16 or 32) to
116 bytes_after_return. It also ignores the delete argument. The
117 nitems_return argument is empty.
118 · If the specified property exists and either you assign AnyProper‐
120 tyType to the req_type argument or the specified type matches the
121 actual property type, XGetWindowProperty returns the actual prop‐
122 erty type to actual_type_return and the actual property format
123 (never zero) to actual_format_return. It also returns a value to
124 bytes_after_return and nitems_return, by defining the following
125 values:
126 N = actual length of the stored property in bytes
128 (even if the format is 16 or 32)
129 I = 4 * long_offset
130 T = N - I
131 L = MINIMUM(T, 4 * long_length)
132 A = N - (I + L)
133 The returned value starts at byte index I in the property (index‐
135 ing from zero), and its length in bytes is L. If the value for
136 long_offset causes L to be negative, a BadValue error results.
137 The value of bytes_after_return is A, giving the number of trail‐
138 ing unread bytes in the stored property.
139 If the returned format is 8, the returned data is represented as a char
141 array. If the returned format is 16, the returned data is represented
142 as a short array and should be cast to that type to obtain the ele‐
143 ments. If the returned format is 32, the returned data is represented
144 as a long array and should be cast to that type to obtain the elements.
145 XGetWindowProperty always allocates one extra byte in prop_return (even
147 if the property is zero length) and sets it to zero so that simple
148 properties consisting of characters do not have to be copied into yet
149 another string before use.
150 If delete is True and bytes_after_return is zero, XGetWindowProperty
152 deletes the property from the window and generates a PropertyNotify
153 event on the window.
154 The function returns Success if it executes successfully. To free the
156 resulting data, use XFree.
157 XGetWindowProperty can generate BadAtom, BadValue, and BadWindow
159 errors.
160 The XListProperties function returns a pointer to an array of atom
162 properties that are defined for the specified window or returns NULL if
163 no properties were found. To free the memory allocated by this func‐
164 tion, use XFree.
165 XListProperties can generate a BadWindow error.
167 The XChangeProperty function alters the property for the specified win‐
169 dow and causes the X server to generate a PropertyNotify event on that
170 window. XChangeProperty performs the following:
171 · If mode is PropModeReplace, XChangeProperty discards the previous
173 property value and stores the new data.
174 · If mode is PropModePrepend or PropModeAppend, XChangeProperty
176 inserts the specified data before the beginning of the existing
177 data or onto the end of the existing data, respectively. The type
178 and format must match the existing property value, or a BadMatch
179 error results. If the property is undefined, it is treated as
180 defined with the correct type and format with zero-length data.
181 If the specified format is 8, the property data must be a char array.
183 If the specified format is 16, the property data must be a short array.
184 If the specified format is 32, the property data must be a long array.
185 The lifetime of a property is not tied to the storing client. Proper‐
187 ties remain until explicitly deleted, until the window is destroyed, or
188 until the server resets. For a discussion of what happens when the
189 connection to the X server is closed, see section 2.6. The maximum
190 size of a property is server dependent and can vary dynamically depend‐
191 ing on the amount of memory the server has available. (If there is
192 insufficient space, a BadAlloc error results.)
193 XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and
195 BadWindow errors.
196 The XRotateWindowProperties function allows you to rotate properties on
198 a window and causes the X server to generate PropertyNotify events. If
199 the property names in the properties array are viewed as being numbered
200 starting from zero and if there are num_prop property names in the
201 list, then the value associated with property name I becomes the value
202 associated with property name (I + npositions) mod N for all I from
203 zero to N - 1. The effect is to rotate the states by npositions places
204 around the virtual ring of property names (right for positive nposi‐
205 tions, left for negative npositions). If npositions mod N is nonzero,
206 the X server generates a PropertyNotify event for each property in the
207 order that they are listed in the array. If an atom occurs more than
208 once in the list or no property with that name is defined for the win‐
209 dow, a BadMatch error results. If a BadAtom or BadMatch error results,
210 no properties are changed.
211 XRotateWindowProperties can generate BadAtom, BadMatch, and BadWindow
213 errors.
214 The XDeleteProperty function deletes the specified property only if the
216 property was defined on the specified window and causes the X server to
217 generate a PropertyNotify event on the window unless the property does
218 not exist.
219 XDeleteProperty can generate BadAtom and BadWindow errors.
221
223 BadAlloc The server failed to allocate the requested resource or
224 server memory.
225 BadAtom A value for an Atom argument does not name a defined Atom.
227 BadValue Some numeric value falls outside the range of values accepted
229 by the request. Unless a specific range is specified for an
230 argument, the full range defined by the argument's type is
231 accepted. Any argument defined as a set of alternatives can
232 generate this error.
233 BadWindow A value for a Window argument does not name a defined Window.
235
237 XFree(3X11), XInternAtom(3X11)
238 Xlib - C Language X Interface
239X Version 11 libX11 1.0.3 XGetWindowProperty(3X11)