NAME

XChangeProperty − change a property associated with a window. 

Synopsis

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

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

wSpecifies the ID of the window whose property you want to change. 

propertySpecifies the property atom. 

typeSpecifies the type of the property.  X does not interpret the type, but simply passes it back to an application that later calls XGetWindow­Prop­erty. 

formatSpecifies 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 pointer to a (char *) in the call to XChangeProperty().  Possible values are 8, 16, and 32. 

modeSpecifies the mode of the operation.  Possible values are Prop­Mode­Replace, PropModePrepend, PropModeAppend. 

dataSpecifies the property data. 

nelementsSpecifies the number of elements in the property. 

Description

XChangeProperty() changes a property and generates PropertyNotify events if they have been selected.  XChangeProperty() does the following according to the mode argument:

•  PropModeReplace
Discards the previous property value and stores the new data.

•  PropModePrepend
Inserts the data before the beginning of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data. type and format arguments must match the existing property value; otherwise a BadMatch error occurs. 

•  PropModeAppend
Appends the data onto the end of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data. type and format arguments must match the existing property value; otherwise a BadMatch error occurs.  The property may remain defined even after the client which defined it exits.  The prop­erty becomes undefined only if the application calls XDeleteProperty(), destroys the specified window, or closes the last connection to the X server.  The maximum size of a property is server-dependent and can vary dynamically if the server has insufficient memory.  For more information, see Volume One, Chapter 10, Interclient Communication. 

Errors

BadAlloc
BadAtom
BadMatch
BadValue
BadWindow

See Also

XDeleteProperty(), XGetFontProperty(), XGetWindowProperty(), XInternAtom(), XListProperties(), XRotateWindowProperties(), XSetStandardProperties(). 

Copyright O’Reilly & Assoc.  —