Next: , Previous: , Up: Atoms   [Contents][Index]


12.2 Properties

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:

Function: change-property window property data type format &key (:mode :replace) (:start 0) :end :transform
window

A window.

property

A property name xatom.

data

A sequence of property data elements.

type

The property type xatom.

format

One of 8, 16, or 32.

:mode

One of :replace, :append, or :prepend.

:start
:end

Specify the subsequence of previous data replaced when :mode is :replace.

:transform

A function that transforms each data element into a data value to store.

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.

Function: delete-property window property
window

A window.

property

A property name xatom.

Deletes the window property. If the property already exists, a :property-notify event is generated for the window.

Function: get-property window property &key :type (:start 0) :end :delete-p (:result-type 'list) :transform
window

A window.

property

A property name xatom.

:type

The requested type xatom or nil.

:start
:end

Specify the subsequence of property data returned.

:transform

A function that transforms each data element into a data value to return.

:delete-p

If true, the existing property can be deleted.

:result-type

The type of data sequence to return. Default is ’list.

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.

data

Type sequence.

type

Type xatom.

format

Type (member 8 16 32).

bytes-after

Type card32.

Function: list-properties window &key (:result-type 'list)
window

A window.

:result-type

The type of sequence to return. Default is ’list.

Returns a sequence containing the names of all window properties.

properties

Type sequence of keyword.

Function: rotate-properties window properties &optional (delta 1)
window

A window.

properties

A sequence of xatom values.

delta

The index interval between source and destination elements of properties.

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.


Next: , Previous: , Up: Atoms   [Contents][Index]