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.
|
See also
XDeleteProperty(),
XGetWindowProperty(),
XListProperties(),
XRotateWindowProperties(),
"
Obtaining and Changing Window Properties"
Christophe Tronche, [email protected]
