XGetWindowProperty()XGetWindowProperty()NameXGetWindowProperty – 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 gener‐
ated 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 prop‐
erty if a partial read was performed.
prop_return
Returns a pointer to the data actually returned, in the spec‐
ified 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.
DescriptionXGetWindowProperty() gets the value of a property if it is the desired
type. XGetWindowProperty() sets the return arguments acccording to the
following rules:
· 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.
· 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.
· If the specified property exists, and either req_type is AnyProper‐
tyType or the specified type matches the actual property type, then:
actual_type_return is the actual property type; and actual_for‐
mat_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 failure
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 cur‐
rently 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 Communi‐
cation.
Errors
BadAtom
BadValue Value of long_offset caused L to be negative above.
BadWindow
See AlsoXChangeProperty(), XGetAtomName(), XGetFontProperty(), XListProper‐
ties(), XRotateWindowProperties(), XSetStandardProperties().
Xlib - Properties XGetWindowProperty()
