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()