Frame Part Definitions

Each frame part is defined as an association list (or alist), a list of cons cells, the car of each cell defines the attribute, the cdr defines the value given to that attribute. So, for example, the alist ((foo . 1) (bar . 2)) specifies two attributes: foo with value 1, and bar with value 2. See Association Lists.

The attributes that may be defined are as follows:

(class . class)

Specifies the frame part class of the part.

(background . data)

(background . (normal focused highlighted clicked))

Specifies the background of the part. May be a color, an image, or a string naming a color. If a single element, then it is used for all states of the part, otherwise if a list, then each of the four elements defines the background for that particular state.

If an image is used it will be scaled to the size of the frame part, unless it's tiled property is set, in which case it will be tiled across the frame part.

(foreground . data)

(foreground . (normal focused highlighted clicked))

Specifies a foreground color or image for the frame part, either for all states, or for each individual state.

Unlike the background attribute, by default images are not scaled when used to define the foreground of a frame part.

(scale-foreground . value)

When value is non-nil, the foreground image of the frame part will be scaled to the size of the part.

(font . font)

(font . (normal focused highlighted clicked))

Specifies the font(s) of the part.

(text . value)

Specifies the string to draw in the foreground of the frame part (unless the foreground property is an image). Either a string, or a function, that will be called each time that the part is refreshed, that will return the string to draw.

(x-justify . value)

Defines the horizontal position of the foreground contents of the part (i.e. the text or foreground image). May be one of the symbols left, right or center, or a number. If a number it defines the number of pixels from the left edge if positive, or the right edge if negative.

(y-justify . value)

Similar to x-justify, but the accepted symbols are top, bottom or center instead.

(renderer . function)

This attribute may be used instead of the background attribute. When the part needs to be drawn function will be called with an image in which to render the background, and the current state of the part, a symbol focused, highlighted, clicked, or nil (for the normal state).

(render-scale . value)

This attribute causes the size of the image used with the renderer property to be reduced by a factor of value, an integer.

(left-edge . value)

Defines the position of the left edge of the part, in relation to the left edge of the client window.

(right-edge . value)

Defines the position of the right edge of the part, in relation to the right edge of the client window.

(top-edge . value)

Defines the position of the top edge of the part, in relation to the top edge of the client window.

(bottom-edge . value)

Defines the position of the bottom edge of the part, in relation to the bottom edge of the client window.

(width . value)

Defines the width of the frame part.

(height . value)

Defines the height of the frame part.

(keymap . value)

Defines the keymap to use when evaluating events originating in this frame part.

(cursor . cursor)

Defines the cursor to display when the mouse is in this part. May be either a cursor object, or the argument to get-cursor to create the required cursor object.

(removable . value)

When specified and value is non-nil, this frame part may be removed from the frame without being detrimental to the overall appearance of the frame. This is only important for button classes, which may sometimes be removed at the request of the client window.

(below-client . value)

When specified and value is non-nil, then this frame part will be displayed beneath the client window. The default action is for frame parts to be stacked above the client window.

(hidden . value)

When specified and value is non-nil, don't display this frame part.

The values specified for the background, foreground, render-scale, font, left-edge, right-edge, top-edge, bottom-edge, width, height, cursor, below-client and hidden attributes may actually be functions. In which case the function will be called (with a single argument, the window object) when the frame is constructed, the value returned will be used as the actual value of the attribute.

The coordinate system used for specifying the part's position is relative to the window edge that the position is defined against. Positive values count in from the window edge towards the center of the window, while negative values count out from the edge, away from the center of the window.

Consider the following example, a solid black title bar that is twenty pixels high, directly above the client window:

     `((background . "black")
       (foreground . "white")
       (text . ,window-name)
       (x-justify . 30)
       (y-justify . center)
       (left-edge . 0)
       (right-edge . 0)
       (top-edge . -20)
       (height . 20)
       (class . title))
     

The backquote operator is used since the definition is only mostly constant, the comma operator inserts the value of the window-name variable (a function giving the name of a window) into the definition; see Backquoting).

This function is then used to dynamically specify the string drawn in the foreground. The window manager will automatically refresh the foreground of all frame parts of a window whenever any X property of that window changes.

Given a framed window, and a particular frame part class, it is possible to retrieve the values of individual attributes from the complete list of definitions (including inherited or overrided definitions).

frame-part-get part property

Function

Returns the value of the property property for the frame part object part. Returns nil if no such attribute exists.

frame-part-put part prop value

Function

Set the property prop of frame part part to value.

frame-part-state part

Function

Return the current state for frame part part, one of the symbols focused, highlighted, clicked, inactive-highlighted, inactive-clicked, or nil if the part is inactive.