For each window, an X server can record a set of properties. Properties are a general mechanism for clients to associate arbitrary data with a window, and for clients to communicate window data to each other via the server. No interpretation is placed on property data by the server itself.
A property consists of a name, a type, a data format, and data. The name of a property is given by an atom. The property type is another atom used to denote the intended interpretation of the property data. The property formats specifies whether the property data should be treated as a set of 8-, 16-, or 32-bit elements. The property format must be specified so that the X server can communicate property data with the correct byte order.
CLX provides functions to:
| change-property | window property data type format &key (:mode :replace) (:start 0) :end :transform | Function |
Creates a new window property or changes an existing property. A :property-notify event is generated for the window. If the :mode is :replace, the new data, type, and format replace any previous values. The subsequence of previous data elements that are replaced is defined by the :start and :end indexes. If the :mode is :prepend or :append, no previous data is changed, but the new data is added at the beginning or the end, respectively. For these modes, if the property already exists, the new type and format must match the previous values. The :transform, if given, is a function used to compute the actual property data stored. The :transform, which must accept a single data element and return a single transformed data element, is called for each data element. If the data is a string, the default :transform function transforms each character into its ASCII code; otherwise, the default is to store the data unchanged. |
| delete-property | window property | Function |
|
Deletes the window property. If the property already exists, a :property-notify event is generated for the window. |
| get-property | window property &key :type (:start 0) :end :delete-p (:result-type 'list) :transform | Function |
Returns a subsequence of the data for the window property. The :start and :end indexes specify the property data elements returned. The :transform function is called for elements of the specified subsequence to compute the data sequence returned. The property type and format are also returned. The final return value gives the actual number of data bytes (not elements) following the last data element returned. If the property does not exist, the returned data and type are nil and the returned format and bytes-after are zero. If the given :type is non-nil but does not match the actual property type, then the data returned is nil, the type and format returned give the actual property values, and the bytes-after returned gives the total number of bytes (not elements) in the property data. If the given :type is nil or if it matches the actual property type, then:
In this case, the :delete-p argument is also examined. If :delete-p is true and bytes-after is zero, the property is deleted and a :property-notify event is generated for the window. |
| list-properties | window &key (:result-type 'list) | Function |
Returns a sequence containing the names of all window properties.
|
| rotate-properties | window properties &optional (delta 1) | Function |
Rotates the values of the given window properties. The value of property i in the given sequence is changed to the value of the property at index (mod (+ i delta) (length properties)). This function operates much like the rotatef macro in Common Lisp. If (mod delta (length properties)) is non-zero, a :property-notify event is generated on the window for each property, in the same order as they appear in the properties sequence. |