X Properties

The X window system associates properties with windows (these are totally separate to the properties that sawfish associates with window objects, see Window Property Lists). Most inter-client communication is performed through manipulation of these properties.

All functions defined below, that operate on X properties, accept their window parameter as either a window object (denoting the associated client window), the numeric xid of a window, or the symbol root denoting the root window.

Sawfish represents X atoms (both the names and data types of X properties) as symbols. There is an exact correspondence between the names of atoms and the name of the symbol representing them. For example, the X atom STRING is represented by the lisp symbol STRING.

list-x-properties window

Function

Return a list of symbols defining the X properties set on window.

delete-x-property window property

Function

Deletes the X property named property (a symbol) associated with window.

get-x-property window property

Function

Returns a list (type format data) representing the X property property of window. If no such property exists, return nil. type is the atom defining the type of the property. format is an integer, either 8, 16 or 32, defining the number of bits in each of the data items. data is an array, either a string for an 8-bit format property, or a vector of integers otherwise. If type is ATOM and format is 32, then data will be a vector of symbols, representing the atoms read.

set-x-property window property data type format

Function

Set the X property property of window to the array data, either a string or a vector of integers. type is a symbol representing the atom defining the type of the property; format is either 8, 16 or 32 defining the number of bits in the data values. If type is ATOM and format is 32, then any symbols in data will be converted to their numeric X atoms.

The standard X property formats don't allow for an array of strings to be stored, so these are often encoded as the strings concatenated, separated by zero characters. These are usually called text properties. Sawfish has two functions for manipulating them:

get-x-text-property window property

Function

Similar to get-x-property, but returns either nil or a vector of strings.

set-x-text-property window property data

Function

Sets the X text property property of window to the array of strings data.

It's also possible to detect when the value of any property associated with a managed window changes, using the property-notify-hook. See Standard Hooks. The following convenience function takes advantage of this hook:

call-after-property-changed prop fun

Function

Arrange for function fun to be called with arguments (window property state) when the X11 property named prop (a symbol) changes. Prop may also be a list of property names to monitor.