XChangeProperty

Syntax

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;

Arguments

display Specifies the connection to the X server.
w Specifies the window whose property you want to change.
property Specifies the property name.
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 XGetWindowProperty().
format Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. 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 pointer to an (unsigned char *) in the call to XChangeProperty().
mode Specifies the mode of the operation. You can pass PropModeReplace, PropModePrepend, or PropModeAppend.
data Specifies the property data.
nelements Specifies the number of elements of the specified data format.

Description

The XChangeProperty() function alters the property for the specified window and causes the X server to generate a PropertyNotify event on that window. XChangeProperty() performs the following: If the specified format is 8, the property data must be a char array. If the specified format is 16, the property data must be a short array. If the specified format is 32, the property data must be a long array.

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 "X Server Connection Close Operations". 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.)

XChangeProperty() can generate BadAlloc , BadAtom , BadMatch , BadValue , and BadWindow errors.

Diagnostics

BadAlloc The server failed to allocate the requested source 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.
BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
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

XDeleteProperty(), XGetWindowProperty(), XListProperties(), XRotateWindowProperties(), "Obtaining and Changing Window Properties"
Christophe Tronche, ch@tronche.com