XGetWindowProperty(3X) XGetWindowProperty(3X)NAME XGetWindowProperty, XListProperties, XChangeProperty, XRotateWindowProperties, XDeleteProperty - get and change window properties 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; Atom *XListProperties (display, w, num-prop-return) Display *display; Window w; int *num-prop-return; XChangeProperty (display, w, property, type, format, mode, data, nelements) Display *display; Window w; Atom property,type; int format; int mode; unsigned char *data; int nelements; November, 1990 1
XGetWindowProperty(3X) XGetWindowProperty(3X)XRotateWindowProperties (display, w, properties, num-prop, npositions) Display *display; Window w; Atom properties[]; int num-prop; int npositions; XDeleteProperty (display, w, property) Display *display; Window w; Atom property; 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 re- turn arguments as follows: If the specified property does not exist for the speci- fied window, XGetWindowProperty returns None in actual-type-return and 0 in actual-format-return and bytes-after-return. The nitems-return argument is emp- ty. In this case, the delete argument is ignored. If the specified property exists but its type does not match the specified type, XGetWindowProperty returns the actual property type in actual-type-return, the ac- tual property format (never 0) in actual-format-return, and the property length in bytes (even if actual- format-return is 16 or 32) in bytes-after-return. The delete argument is also ignored. The nitems-return ar- gument is empty. If the specified property exists and either you assign AnyPropertyType to the req-type argument or the speci- fied type matches the actual property type, XGetWin- dowProperty returns the actual property type in actual-type-return and the actual property format (nev- er 0) in actual-format-return. It also returns a value in bytes-after-return and nitems-return, by defining the following values: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 * long-offset T = N - I L = MINIMUM(T, 4 * long-length) A = N - (I + L) 2 November, 1990
XGetWindowProperty(3X) XGetWindowProperty(3X)The returned value starts at byte index I in the pro- perty (indexing from zero), and its length in bytes is L. If the value for long-offset causes L to be nega- tive, a BadValue error results. The value of bytes- after-return is A, giving the number of trailing unread bytes in the stored property. XGetWindowProperty always allocates one extra byte in prop- return (even if the property is zero length) and sets it to ASCII null so that simple properties consisting of charac- ters do not have to be copied into yet another string before use. If delete is TRUE and bytes-after-return is 0, XGetWindowProperty deletes the property from the window and generates a PropertyNotify event on the window. The XGetWindowProperty function returns Success if it exe- cutes successfully. To free the resulting data, use XFree. The XListProperties function returns a pointer to an array of atom properties that are defined for the specified window or returns null if no properties were found. To free the memory allocated by this function, use XFree. The XChangeProperty function alters the property for the specified window and causes the X server to generate a PropertyNotify event for that window. The XChangeProperty function performs the following: If mode is PropModeReplace, XChangeProperty discards the previous property value and stores the new data. If mode is PropModePrepend or PropModeAppend, XChangeProperty inserts the specified data before the beginning of the existing data or onto the end of the existing data, respectively. The type and format must match the existing property value, or a BadMatch error results. If the property is undefined, it is treated as defined with the correct type and format with zero- length data. The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the window is destroyed, or until the server resets. For a discussion of what happens when the connection to the X server is closed, see Section 2.5 of Xlib - C Language Interface. The maximum size of a property is server-dependent and can vary dynamically depending on the amount of memory the server has available. (If there is insufficient space, a BadAlloc error results.) November, 1990 3
XGetWindowProperty(3X) XGetWindowProperty(3X)The XRotateWindowProperties function allows you to rotate properties in the properties array, and causes the X server to generate a PropertyNotify event. If the property names in the properties array are viewed as being numbered start- ing from zero and if there are num-prop property names in the list, the value associated with property name I becomes the value associated with property name (I + npositions) mod N for all I from zero to N - 1. The effect is to rotate the states by npositions places around the virtual ring of pro- perty names (right for positive npositions, left for nega- tive npositions). If npositions mod N is nonzero, the X server generates a PropertyNotify event for each property in the order that they are listed in the array. If an atom oc- curs more than once in the list or no property with that name is defined for the window, a BadMatch error results. If a BadAtom or BadMatch error results, no properties are changed. The XDeleteProperty function deletes the specified property only if the property was defined on the specified window. XDeleteProperty causes the X server to generate a PropertyNotify event for the window, unless the property does not exist. Arguments These functions accept the following arguments: actual-format-return Returns the actual format of the property. actual-type-return Returns the atom identifier that defines the actual type of the property. bytes-after-return Returns the number of bytes remaining. This is the number of bytes remaining to be read in the property if a partial read was performed. data Specifies the property data. delete Specifies a Boolean value that determines whether the property is deleted from the window. You can pass one of these constants: TRUE or FALSE. display Specifies the connection to the X server. format Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. This information allows the X server to correctly perform byte-swap operations as necessary. If the format is 16-bit or 32-bit, you must explicitly cast your data 4 November, 1990
XGetWindowProperty(3X) XGetWindowProperty(3X)pointer to a (char *) in the call to XChangeProper- ty. Possible values are 8, 16, and 32. long-length Specifies the length in 32-bit multiples of the data to be retrieved. long-offset Specifies the offset in the specified property (in 32-bit quantities) where data will be retrieved. mode Specifies the mode of the operation. One of the following constants can be passed: PropModeReplace, PropModePrepend, or PropModeAppend. nelements Specifies the number of elements of the specified data format (8-bit, 16-bit, or 32-bit). nitems-return Returns the actual number of 8-bit, 16-bit, or 32- bit items stored in the prop-return data. num-prop Specifies the length of the properties array. num-prop-return Returns the length of the properties array. npositions Specifies the rotation amount. prop-return Returns a pointer to the data in the specified for- mat. property Specifies the property atom. properties Specifies the array of properties that are to be ro- tated. req-type Specifies the atom identifier associated with the property type. You can also pass AnyPropertyType. type Specifies the type of the property. The X server does not interpret the type but simply passes it back to an application that later calls XGetWin- dowProperty. November, 1990 5
XGetWindowProperty(3X) XGetWindowProperty(3X)w Specifies the window ID. ERRORS BadAlloc The server failed to allocate the requested resource or server memory. BadAtom A value for an Atom argument does not name a defined atom. BadMatch An InputOnly window is used as a drawable; or, an argument or pair of arguments has the correct type and range but fails to match in some other required way. BadValue A numeric value falls outside the range of values accepted by the request. Unless a range is speci- fied 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 de- fined window. The XGetWindowProperty function can generate BadAtom, Bad- Value, and BadWindow errors. The XListProperties function can generate a BadWindow error. The XChangeProperty function can generate BadAlloc, BadAtom, BadMatch, BadValue, and BadWindow errors. The XRotateWindowProperties function can generate BadAtom, BadMatch, and BadWindow errors. The XDeleteProperty function can generate BadAtom and BadWindow errors. SEE ALSO XFree(3X), XInternAtom(3X) Xlib - C Language Interface 6 November, 1990