This subsection covers the general-purpose table formatting operators.
formatting-table [Macro]
Arguments: (
&optional
stream
&key
x-spacing y-spacing multiple-columns multiple-columns-x-spacing equalize-column-widths (move-cursor
t
) record-type)
&body
body
Summary: Binds the local environment in such a way the output of body will be done in a tabular format. This must be used in conjunction with formatting-row or formatting-column , and formatting-cell . The table is placed so that its upper left corner is at the current text cursor position of stream . If the boolean move-cursor is t (the default), then the text cursor will be moved so that it immediately follows the last cell of the table.
The returned value is the output record corresponding to the table.
stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms.
x-spacing specifies the number of units of spacing to be inserted between columns of the table; the default is the width of a space character in the current text style. y-spacing specifies the number of units of spacing to be inserted between rows in the table; the default is the default vertical spacing of the stream. Possible values for these two options option are:
An integer--a size in the current units to be used for spacing
A string or character--the spacing is the width or height of the string or character in the current text style
A function--the spacing is the amount of horizontal or vertical space the function would consume when called on the stream
A list--the list is of the form ( number unit ), where unit is one of :point , :pixel , :mm , :character , or :line . When unit is :character , the width of an "M" in the current text style is used as the width of one character.
multiple-columns is either nil , t , or an integer. If it is t or an integer, the table rows will be broken up into a multiple columns. If it is t , CLIM will determine the optimal number of columns. If it is an integer, it will be interpreted as the desired number of columns. multiple-columns-x-spacing has the same format as x-spacing . It controls the spacing between the multiple columns. It defaults to the value of the x-spacing option.
When the boolean equalize-column-widths is t , all the columns will have the same width (the width of the widest cell in any column in the entire table).
record-type specifies the class of output record to create. The default is standard-table-output-record . This argument should only be supplied by a programmer if there is a new class of output record that supports the table formatting protocol.
formatting-row [Macro]
Arguments: (
&optional
stream
&key
record-type)
&body
body
Summary: Binds the local environment in such a way the output of body will be grouped into a table row. All of the output performed by body becomes the contents of one row. This must be used inside of formatting-table , and in conjunction with formatting-cell .
stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms.
Once a table has had a row added to it via formatting-row , no columns may be added to it.
record-type specifies the class of output record to create. The default is standard-row-output-record . This argument should only be supplied by a programmer if there is a new class of output record that supports the row formatting protocol.
formatting-column [Macro]
Arguments: (
&optional
stream
&key
record-type)
&body
body
Summary: Binds the local environment in such a way the output of body will be grouped into a table column. All of the output performed by body becomes the contents of one column. This must be used inside of formatting-table , and in conjunction with formatting-cell .
stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms.
Once a table has had a column added to it via formatting-column , no rows may be added to it.
record-type specifies the class of output record to create. The default is standard-column-output-record . This argument should only be supplied if there is a new class of output record that supports the column formatting protocol.
formatting-cell [Macro]
Arguments: (
&optional
stream
&key
(align-x
':left
) (align-y
':baseline
) min-width min-height record-type)
&body
body
Summary: Controls the output of a single cell inside a table row or column, or of a single item inside formatting-item-list . All of the output performed by body becomes the contents of the cell.
stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms.
align-x specifies how the output in a cell will be aligned relative to other cells in the same table column. The default, :left , causes the cells to be flush-left in the column. The other possible values are :right (meaning flush-right in the column) and :center (meaning centered in the column). Each cell within a column may have a different alignment; thus it is possible, for example, to have centered legends over flush-right numeric data.
align-y specifies how the output in a cell will be aligned vertically. The default, :baseline , causes textual cells to be aligned along their baselines and graphical cells to be aligned at the bottom. The other possible values are :bottom (align at the bottom of the output), :top (align at the top of the output), and :center (center the output in the cell).
min-width and min-height are used to specify minimum width or height of the cell. The default, nil , causes the cell to be only as wide or high as is necessary to contain the cell's contents. Otherwise, min-width and min-height are specified in the same way as the :x-spacing and :y-spacing arguments to formatting-table .
record-type specifies the class of output record to create. The default is standard-cell-output-record . This argument should only be supplied by a programmer if there is a new class of output record that supports the cell formatting protocol.
formatting-item-list [Macro]
Arguments: (
&optional
stream
&key
x-spacing y-spacing n-columns n-rows stream-width stream-height max-width max-height initial-spacing (row-wise
t
) (move-cursor
t
) record-type)
&body
body
Summary: Binds the local environment in such a way that the output of body will be done in an item list (that is, menu) format. This must be used in conjunction with formatting-cell , which delimits each item. The item list is placed so that its upper left corner is at the current text cursor position of stream . If the boolean move-cursor is t (the default), then the text cursor will be moved so that it immediately follows the last cell of the item list.
"Item list output" means that each row of the item list consists of a single cell. The first row is on top, and each succeeding row has its top aligned with the bottom of the previous row (plus the specified y-spacing ). Multiple rows and columns are constructed after laying the item list out in a single column. Item list output takes place in a normalized + y -downward coordinate system.
The returned value is the output record corresponding to the table.
stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms.
x-spacing
specifies the number of units of spacing to be inserted between columns of the item list; the default is the width of a
#\Space
character in the current text style.
y-spacing
specifies the number of units of spacing to be inserted between rows in the item list; the default is default vertical spacing of the stream. The format of these arguments is as for
formatting-table
.
When the boolean equalize-column-widths is t , all the columns will have the same width (the width of the widest cell in any column in the entire item list).
n-columns and n-rows specify the number of columns or rows in the item list. The default for both is nil , which causes CLIM to pick an aesthetically pleasing layout, possibly constrained by the other options. If both n-columns and n-rows are supplied and the item list contains more elements than will fit according to the specification, CLIM will format the item list as if n-rows were supplied as nil .
max-width and max-height constrain the layout of the item list. max-width can be overridden by n-rows . max-height can be overridden by n-columns .
formatting-item-list normally spaces items across the entire width of the stream. When initial-spacing is t , it inserts some whitespace (about half as much space as is between each item) before the first item on each line. When it is nil (the default), the initial whitespace is not inserted. If row-wise is t (the default) and the item list requires multiple columns, each successive element in the item list is laid out from left to right. If row-wise is nil and the item list requires multiple columns, each successive element in the item list is laid out below its predecessor, as in a telephone book.
record-type specifies the class of output record to create. The default is standard-item-list-output-record . Supply this argument s only if there is a new class of output record that supports the item list formatting protocol.
format-items [Function]
Arguments: items
&key
stream printer presentation-type x-spacing y-spacing n-columns n-rows max-width max-height cell-align-x cell-align-y initial-spacing (move-cursor
t
) record-type
Summary: This is a function interface to the item list formatter. The elements of the sequence items are formatted as separate cells within the item list.
stream is an output recording stream to which output will be done. It defaults to *standard-output* .
printer (default is prin1 )is a function that takes two arguments, an item and a stream, and outputs the item on the stream. printer has dynamic extent.
presentation-type is a presentation-type. When printer is not supplied, the items will be printed as if printer were:
(present item presentation-type :stream stream))
When printer is supplied, each item will be enclosed in a presentation whose type is presentation-type .
x-spacing , y-spacing , n-columns , n-rows , max-width , max-height , initial-spacing , and move-cursor are as for formatting-item-list .
cell-align-x and cell-align-y are used to supply :align-x and :align-y to an implicitly used formatting-cell .
record-type is as for formatting-item-list .
format-textual-list[Function]
Arguments: sequence printer
&key
(:stream
*standard-output*
) (:separator
", "
) :conjunction
Summary: Outputs a sequence of items as a textual list.
Note that format-items is similar to formatting-item-list . Both operators do the same thing, except they accept their input differently:
formatting-item-list accepts its input as a body that calls formatting-cell for each item.
format-items accepts its input as a list of items with a specification of how to print them.
Note that menus use the one-dimensional table formatting model.