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

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.

XChangeProperty

Syntax

Arguments

Description

Diagnostics

See also