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

4.4.4.1 Layout Properties

In addition to the 10 highlight properties described in the previous section, Clon defines 6 layout properties. Here are the first 4 of them, along with their description and default value.

:visible

Whether the face’s contents is visible. Possible values are t (the default), or nil. You can also use the opposite property named :hidden. The ‘optlist’ and ‘refcard’ themes make use of this to avoid printing the options descriptions. Since the notions of hiding, concealing or making text visible are somewhat intermixed, Clon also provides a “bastard” property which, depending on its value, would be considered either a layout, or a highlight one. This property is named :display. Possible values are: visible (or revealed or t), concealed and hidden (or nil).

:padding-top

The face’s top padding, that is, the number of lines to skip before opening it and displaying its contents. This property can take the following forms.

nil

This face may be opened anywhere, including on the current line. This is the default.

0

This face should be opened on the next line.

<num> (positive)

This face should be opened after skipping <num> empty lines. Note that the empty lines are displayed in the enclosing face, not the face which specifies the top padding.

:padding-bottom

This face’s bottom padding, that is, the number of lines to skip before opening the next face and displaying its contents. This property can take the following forms.

nil

The next face may be opened anywhere, including on the current line. This is the default.

0

The next face should be opened on the next line.

<num> (positive)

The next face should be opened after skipping <num> lines. Note that the empty lines are displayed in the enclosing face, not the face which specifies the bottom padding.

:item-separator

The face’s item separator, that is, a piece of text to insert between every sub-face’s contents. The default value is #\space (a space character).

The default values above have been chosen because they are convenient for the majority of the faces, but not necessarily all the time. Let us now review some examples of non-default settings in the ‘raw’ theme.

In order to describe the last two layout properties, we need to introduce the notion of frame first. A frame is a rectangle in which Clon prints something. When Clon opens a face for printing its contents, it associates a frame with it. Usually, Clon doesn’t know the frame’s height because it doesn’t know in advance how many lines of output will be necessary to display the face’s contents. However, Clon usually knows the frame’s width: a frame starts at a certain column (the left one) and stops at another (the right one).

There is an isomorphic relation between frames and faces: when a face is a sub-face of a super-face, the corresponding frame is a sub-frame of the corresponding super-frame. Sub-frames are geometrically enclosed within their super-frames: a sub-frame can only draw in an equally large or narrower band than its super-frame. That’s how Clon handles vertical alignment of text.

In order to give you control on the starting and ending columns of every frame (in fact, every face), the following two layout properties are defined.

:padding-left

A face’s left padding determines its starting column. This property can take the following forms.

<num>

Skip <num> columns relatively to the enclosing face. The default value is 0, meaning to open this face at the same column number as the enclosing one.

(<num> :relative-to <face>)

As above, but relatively to a parent face named <face> instead of just the enclosing one. This lets you go more than one level up in the face tree.

(<num> absolute)

Open this face exactly at column <num>.

self

This face may be opened anywhere, and when it is, its left column is set to the current column number.

:padding-right

A face’s right padding, determines its ending column. This property can take the following forms.

<num>

Close this face <num> columns before the enclosing one.

(<num> :relative-to <face>)

As above, but relatively to a parent face named <face> instead of just the enclosing one. This lets you go more than one level up in the face tree.

(<num> absolute)

Close this face exactly at column <num>.

self

This face may be closed anywhere. This is the default.

The default values above have been chosen because they are convenient for the majority of the faces, but not necessarily all the time. Let us now review some examples of non-default settings in the ‘raw’ theme.

There is one important point to understand about self-ending faces (which, again, is the default setting). A self-ending face typically doesn’t know at which column it stops until it stops. In fact, this is not completely true: if the face’s contents needs to span across several lines, then the ending column will be known at the end of the first line, when the ending column of the enclosing face is reached. However, for a piece of contents that fits on a single line, the point holds.

Because of that, it is impossible for a face’s right padding to be relative to a self-ending face. This would be like saying “stop 2 columns before I don’t know where”. Here are two examples of such invalid settings (an error will be thrown if you try that in a theme): 

:face (option :face (syntax :padding-right 2))
:face (option
        :face (syntax
                :face (short
                        :padding-right (2 :relative-to option))))

Next: Layout Inheritance, Previous: Layout, Up: Layout   [Contents][Index]