XGetWindowProperty() XGetWindowProperty()
Name
XGetWindowProperty - obtain the atom type and property format for a window.
Synopsis
int XGetWindowProperty(display, w, property, long_offset, long_length,
delete, req_type, actual_type_return, actual_format_return, nitems_return, bytes_after_return, prop_return)
Display *display;
Window w;
Atom property;
long 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;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay().
w Specifies the ID of the window whose atom type and property format you want to obtain.
property Specifies the atom of the desired property.
long_offset
Specifies the offset in 32-bit quantities where data will be retrieved.
long_length
Specifies the length in 32-bit multiples of the data to be retrieved.
delete Specifies a boolean value of True or False. If you pass True and a property is returned, the property is deleted from the window
after being read and a PropertyNotify event is generated on the window.
req_type Specifies an atom describing the desired format of the data. If AnyPropertyType is specified, returns the property from the
specified window regardless of its type. If a type is specified, the function returns the property only if its type equals the
specified type.
actual_type_return
Returns the actual type of the property.
actual_format_return
Returns the actual data type of the returned data.
nitems_return
Returns the actual number of 8-, 16-, or 32-bit items returned in prop_return.
bytes_after_return
Returns the number of bytes remaining to be read in the property if a partial read was performed.
prop_return
Returns a pointer to the data actually returned, in the specified format. XGetWindowProperty() always allocates one extra byte
after the data and sets it to NULL. This byte is not counted in nitems_return.
Returns
Success on success. The failure return value is undefined.
Description
XGetWindowProperty() gets the value of a property if it is the desired type. XGetWindowProperty() sets the return arguments acccording to
the following rules:
o If the specified property does not exist for the specified window, then: actual_type_return is None; actual_format_return = 0; and
bytes_after_return = 0. delete is ignored in this case, and nitems_return is empty.
o If the specified property exists, but its type does not match req_type, then: actual_type_return is the actual property type;
actual_format_return is the actual property format (never zero); and bytes_after_return is the property length in bytes (even if
actual_format_return is 16 or 32). delete is ignored in this case, and nitems_return is empty.
o If the specified property exists, and either req_type is AnyPropertyType or the specified type matches the actual property type, then:
actual_type_return is the actual property type; and actual_format_return is the actual property format (never zero). bytes_after_return
and nitems_return are defined by combining the following values:
N = actual length of stored property in bytes (even if actual_format_return is 16 or 32)
I = 4 * long_offset (convert offset from longs into bytes)
L = MINIMUM((N - I), 4 * long_length) (BadValue if L < 0)
bytes_after = N - (I + L) (number of trailing unread bytes in stored property)
The returned data (in prop_return) starts at byte index I in the property (indexing from 0). The actual length of the returned data in
bytes is L. L is converted into the number of 8-, 16-, or 32-bit items returned by dividing by 1, 2, or 4 respectively and this value
is returned in nitems_return. The number of trailing unread bytes is returned in bytes_after_return.
If delete == True and bytes_after_return == 0 the function deletes the property from the window and generates a PropertyNotify event on the
window.
When XGetWindowProperty() executes successfully, it returns Success. The Success return value and the undocumented value returned on fail-
ure are the opposite of all other routines that return int or Status. The value of Success is undocumented, but is zero (0) in the current
sample implementation from MIT. The failure value, also undocumented, is currently one (1). Therefore, comparing either value to True or
False, or using the syntax "if (!XGetWindowProperty(...))" is incorrect.
To free the resulting data, use XFree().
For more information, see Volume One, Chapter 12, Interclient Communication.
Errors
BadAtom
BadValue Value of long_offset caused L to be negative above.
BadWindow
See Also
XChangeProperty(), XGetAtomName(), XGetFontProperty(), XListProperties(), XRotateWindowProperties(), XSetStandardProperties().
Xlib - Properties XGetWindowProperty()