4.3 Properties and Atoms

A property is a collection of named, typed data. The window system has a set of predefined properties (for example, the name of a window, size hints, and so on), and users can define any other arbitrary information and associate it with windows. Each property has a name, which is an ISO Latin-1 string. For each named property, a unique identifier (atom) is associated with it. A property also has a type, for example, string or integer. These types are also indicated using atoms, so arbitrary new types can be defined. Data of only one type may be associated with a single property name. Clients can store and retrieve properties associated with windows. For efficiency reasons, an atom is used rather than a character string. XInternAtom() can be used to obtain the atom for property names.

A property is also stored in one of several possible formats. The X server can store the information as 8-bit quantities, 16-bit quantities, or 32-bit quantities. This permits the X server to present the data in the byte order that the client expects.

Note

If you define further properties of complex type, you must encode and decode them yourself. These functions must be carefully written if they are to be portable. For further information about how to write a library extension, see "Extensions".
The type of a property is defined by an atom, which allows for arbitrary extension in this type scheme.

Certain property names are predefined in the server for commonly used functions. The atoms for these properties are defined in X11/Xatom.h. To avoid name clashes with user symbols, the #define name for each atom has the XA_ prefix. For definitions of these properties, see below. For an explanation of the functions that let you get and set much of the information stored in these predefined properties, see "Inter-Client Communication Functions".

The core protocol imposes no semantics on these property names, but semantics are specified in other X Consortium standards, such as the Inter-Client Communication Conventions Manual and the X Logical Font Description Conventions.

You can use properties to communicate other information between applications. The functions described in this section let you define new properties and get the unique atom IDs in your applications.

Although any particular atom can have some client interpretation within each of the name spaces, atoms occur in five distinct name spaces within the protocol:

The built-in selection property names are:

PRIMARY
SECONDARY

The built-in property names are:
CUT_BUFFER0 RESOURCE_MANAGER
CUT_BUFFER1 WM_CLASS
CUT_BUFFER2 WM_CLIENT_MACHINE
CUT_BUFFER3 WM_COLORMAP_WINDOWS
CUT_BUFFER4 WM_COMMAND
CUT_BUFFER5 WM_HINTS
CUT_BUFFER6 WM_ICON_NAME
CUT_BUFFER7 WM_ICON_SIZE
RGB_BEST_MAP WM_NAME
RGB_BLUE_MAP WM_NORMAL_HINTS
RGB_DEFAULT_MAP WM_PROTOCOLS
RGB_GRAY_MAP WM_STATE
RGB_GREEN_MAP WM_TRANSIENT_FOR
RGB_RED_MAP WM_ZOOM_HINTS

The built-in property types are:

ARC POINT
ATOM RGB_COLOR_MAP
BITMAP RECTANGLE
CARDINAL STRING
COLORMAP VISUALID
CURSOR WINDOW
DRAWABLE WM_HINTS
FONT WM_SIZE_HINTS
INTEGER
PIXMAP

The built-in font property names are:
MIN_SPACE STRIKEOUT_DESCENT
NORM_SPACE STRIKEOUT_ASCENT
MAX_SPACE ITALIC_ANGLE
END_SPACE X_HEIGHT
SUPERSCRIPT_X QUAD_WIDTH
SUPERSCRIPT_Y WEIGHT
SUBSCRIPT_X POINT_SIZE
SUBSCRIPT_Y RESOLUTION
UNDERLINE_POSITION COPYRIGHT
UNDERLINE_THICKNESS NOTICE
FONT_NAME FAMILY_NAME
FULL_NAME CAP_HEIGHT

For further information about font properties, see "Font Metrics".

To return an atom for a given name, use XInternAtom(). To return atoms for an array of names, use XInternAtoms().

To return a name for a given atom identifier, use XGetAtomName().

To return the names for an array of atom identifiers, use XGetAtomNames().

Next: Obtaining and Changing Window Properties

Christophe Tronche, ch@tronche.com