XGetWindowProperty

Syntax

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 the connection to the X server.
w Specifies the window whose property you want to obtain.
property Specifies the property name.
long_offset Specifies the offset in the specified property (in 32-bit quantities) where the data is to be retrieved.
long_length Specifies the length in 32-bit multiples of the data to be retrieved.
delete Specifies a Boolean value that determines whether the property is deleted.
req_type Specifies the atom identifier associated with the property type or AnyPropertyType.
actual_type_return Returns the atom identifier that defines the actual type of the property.
actual_format_return Returns the actual format of the property.
nitems_return Returns the actual number of 8-bit, 16-bit, or 32-bit items stored in the prop_return data.
bytes_after_return Returns the number of bytes remaining to be read in the property if a partial read was performed.
prop_return Returns the data in the specified format.

Description

The XGetWindowProperty() function returns the actual type of the property; the actual format of the property; the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned. XGetWindowProperty() sets the return arguments as follows: If the returned format is 8, the returned data is represented as a char array. If the returned format is 16, the returned data is represented as a short array and should be cast to that type to obtain the elements. If the returned format is 32, the returned data is represented as a long array and should be cast to that type to obtain the elements.

XGetWindowProperty() always allocates one extra byte in prop_return (even if the property is zero length) and sets it to zero so that simple properties consisting of characters do not have to be copied into yet another string before use.

If delete is True and bytes_after_return is zero, XGetWindowProperty() deletes the property from the window and generates a PropertyNotify event on the window.

The function returns Success if it executes successfully. To free the resulting data, use XFree().

XGetWindowProperty() can generate BadAtom, BadValue , and BadWindow errors.

Diagnostics

BadAtom A value for an Atom argument does not name a defined Atom.
BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
BadWindow A value for a Window argument does not name a defined Window.

See also

XChangeProperty(), XDeleteProperty(), XListProperties(), XRotateWindowProperties(), "Obtaining and Changing Window Properties"
Christophe Tronche, [email protected]