GetWinProp(3X) — DeltaWindows 1.3.3 Release 4 Version 4.3

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

displaySpecifies a connection to an X server; returned from XOpenDisplay().

wSpecifies the ID of the window whose atom type and property format you want to obtain.

propertySpecifies 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.

deleteSpecifies 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_typeSpecifies 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:

•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 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 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 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 10, Interclient Communication.

ERRORS

BadAtom

BadValueValue of long_offset caused L to be negative above.

BadWindow