The material in this subsection is advanced; most CLIM programmers can skip to the next section. This section discusses Table, Item List, and Graph Formatting Protocols.
All of table, item list, and graph formatting is implemented on top of the basic output recording protocol, using with-new-output-record to specify the appropriate type of output record. The following examples show specifically how tables and graphs are implemented.
| Example 1: Tables |
formatting-table first collects all the output that belongs in the table into a collection of row, column, and cell output records, all of which are children of a single table output record. During this phase, stream-drawing-p is bound to nil and stream-recording-p is bound to t. When all the output has been generated, the table layout constraint solver (adjust-table-cells or adjust-item-list-cells) is called to compute the table layout, taking into account such factors as the widest cell in a given column. If the table is to be split into multiple columns, adjust-multiple-columns is now called. Finally, the table output record is positioned on the stream at the current text cursor position and then displayed by calling replay on the table (or item list) output record. |
| Example 2: Graphs |
format-graph-from-roots first collects all the graph node output records that belong in the graph by calling generate-graph-nodes. All these output records are children of a single graph output record. During this phase, stream-drawing-p is bound to nil and stream-recording-p is bound to t. When all the output has been generated, the graph layout code (layout-graph-nodes and layout-graph-edges) is called to compute the graph layout. Finally, the graph output record is positioned on the stream at the current text cursor position and then displayed by calling replay on the graph output record. |
Any output record class that implements the following generic functions is said to support the table formatting protocol.
In the following subsections, the term "non-table output records" will be used to mean any output record that is not a table, row, column, cell, or item list output record. When CLIM "skips over intervening non-table output records," this means that it will bypass all the output records between two such table output records (such as a table and a row, or a row and a cell) that are not records of those classes (most notably, presentation output records). CLIM detects invalid nesting of table output records, such as a row within a row, a cell within a cell, or a row within a cell. Note that this does not prohibit the nesting of calls to formatting-table, it simply requires that programmers include the inner table within one of the cells of the outer table.
table-output-record Protocol Class
Summary: The protocol class that represents tabular output records; a subclass of output-record. If you want to create a new class that behaves like a table output record, it should be a subclass of table-output-record. Subclasses of table-output-record must obey the table output record protocol.
table-output-record-p Function
table-output-record-p object
Summary: Returns t if object is a table output record; otherwise, it returns nil.
:x-spacing
:y-spacing
:multiple-columns-x-spacing
:equalize-column-widths Initargs
Summary: All subclasses of table-output-record must handle these initargs, which are used to specify, respectively, the x and y spacing, the multiple column x spacing, and equal-width columns attributes of the table.
standard-table-output-record Class
Summary: The instantiable class of output record that represents tabular output. Its children will be a sequence of either rows or columns, with presentation output records possibly intervening. This is a subclass of table-output-record.
map-over-table-elements Generic Function
map-over-table-elements function table-record type
Summary: Applies function to all the rows or columns of table-record that are of type type. type is either :row, :column, or :row-or-column. function is a function of one argument, an output record; it has dynamic extent. map-over-table-elements ensures that rows, columns, and cells are properly nested. It skips over intervening non-table output record structure, such as presentations.
adjust-table-cells Generic Function
adjust-table-cells table-record stream
Summary: This function is called after the tabular output has been collected, but before it has been replayed. The method on standard-table-output-record implements the usual table layout constraint solver by moving the rows or columns of the table output record table-record and the cells within the rows or columns. stream is the stream on which the table is displayed.
adjust-multiple-columns Generic Function
adjust-multiple-columns table-record stream
Summary: This is called after adjust-table-cells to account for the case where the programmer wants to break the entire table up into multiple columns. Each of those columns will have some of the rows of the "original" table, and those rows may each have several columns. For example:
Original table:
a 1 alpha b 2 beta c 3 gamma d 4 delta
Multiple column version:
a 1 alpha c 3 gamma b 2 beta d 4 delta
table-record and stream are as for adjust-table-cells.
Any output record class that implements the following generic functions is said to support the row (or column) formatting protocol.
row-output-record Protocol Class
Summary: The protocol class that represents one row in a table; a subclass of output-record. If you want to create a new class that behaves like a row output record, it should be a subclass of row-output-record. Subclasses of row-output-record must obey the row output record protocol.
row-output-record-p object
Summary: Returns t if object is a row output record; otherwise, it returns nil.
standard-row-output-record Class
Summary: The instantiable class of output record that represents a row of output within a table. Its children will be a sequence of cells, and its parent (skipping intervening non-tabular records such as presentations) will be a table output record. This is a subclass of row-output-record.
map-over-row-cells Generic Function
map-over-row-cells function row-record
Summary: Applies function to all the cells in the row row-record, skipping intervening non-table output record structure. function is a function of one argument, an output record corresponding to a table cell within the row; it has dynamic extent.
column-output-record Protocol Class
Summary: The protocol class that represents one column in a table; a subclass of output-record. If you want to create a new class that behaves like a column output record, it should be a subclass of column-output-record. Subclasses of column-output-record must obey the column output record protocol.
column-output-record-p Function
column-output-record-p object
Summary: Returns t if object is a column output record; otherwise, it returns nil.
standard-column-output-record Class
Summary: The instantiable class of output record that represents a column of output within a table. Its children will be a sequence of cells, and its parent (skipping intervening non-tabular records such as presentations) will be a table output record; presentation output records may intervene. This is a subclass of column-output-record.
map-over-column-cells Generic Function
map-over-column-cells function column-record
Summary: Applies function to all the cells in the column column-record, skipping intervening non-table output record structure. function is a function of one argument, an output record corresponding to a table cell within the column; it has dynamic extent.
Any output record class that implements the following generic functions is said to support the cell formatting protocol.
cell-output-record Protocol Class
Summary: The protocol class that represents one cell in a table or an item list; a subclass of output-record. If you want to create a new class that behaves like a cell output record, it should be a subclass of cell-output-record. Subclasses of cell-output-record must obey the cell output record protocol.
cell-output-record-p object
Summary: Returns t if object is a cell output record; otherwise. it returns nil.
:align-x
:align-y
:min-width
:min-height Initargs
Summary: All subclasses of cell-output-record must handle these initargs, which are used to specify, respectively, the x and y alignment, and the minimum width and height attributes of the cell.
standard-cell-output-record Class
Summary: The instantiable class of output record that represents a single piece of output within a table row or column, or an item list. Its children will either be presentations or output records that represent displayed output. This is a subclass of cell-output-record.
cell-align-x cell
cell-align-y cell
cell-min-width Generic Function
cell-min-width cell
cell-min-height Generic Function
cell-min-height cell
Summary: These functions return, respectively, the x and y alignment and minimum width and height of the cell output record cell.
item-list-output-record Protocol Class
Summary: The protocol class that represents an item list; a subclass of output-record. If you want to create a new class that behaves like an item list output record, it should be a subclass of item-list-output-record. Subclasses of item-list-output-record must obey the item list output record protocol.
item-list-output-record-p Function
item-list-output-record-p object
Summary: Returns t if object is an item list output record; otherwise, it returns nil.
:x-spacing
:y-spacing
:initial-spacing
:n-rows
:n-columns
:max-width
:max-height Initargs
Summary: All subclasses of item-list-output-record must handle these initargs, which specify, respectively, the x and y spacing, the initial spacing, the desired number of rows and columns, and maximum width and height attributes of the item list.
standard-item-list-output-record Class
Summary: The output record that represents item list output. Its children will be a sequence of cells, with presentations possibly intervening. This is a subclass of item-list-output-record.
map-over-item-list-cells Generic Function
map-over-item-list-cells function item-list-record
Summary: Applies function to all of the cells in item-list-record. map-over-item-list-cells skips over intervening non-table output record structure, such as presentations. function is a function of one argument, an output record corresponding to a cell in the item list; it has dynamic extent.
adjust-item-list-cells Generic Function
adjust-item-list-cells item-list-record stream
Summary: This function is called after the item list output has been collected, but before the record has been replayed. The method on standard-item-list-output-record implements the usual item list layout constraint solver. item-list-record is the item list output record, and stream is the stream on which the item list is displayed.
graph-output-record Protocol Class
Summary: The protocol class that represents a graph; a subclass of output-record. If you want to create a new class that behaves like a graph output record, it should be a subclass of graph-output-record. Subclasses of graph-output-record must obey the graph output record protocol.
graph-output-record-p Function
graph-output-record-p object
Summary: Returns t if object is a graph output record, otherwise returns nil.
:orientation
:center-nodes
:cutoff-depth
:merge-duplicates
:generation-separation
:within-generation-separation
:hash-table Initargs
Summary: All the graph output records must handle these seven initargs, which are used to specify, respectively, the orientation, node centering, cutoff depth, merge duplicates, generation and within-generation spacing, and the node hash table of a graph output record.
define-graph-type graph-type class
Summary: Defines a new graph type graph-type that is implemented by the class class (a subclass of graph-output-record). Neither of the arguments is evaluated.
graph-root-nodes Generic Function
graph-root-nodes graph-record
Summary: Returns a sequence of the graph node output records corresponding to the root objects for the graph output record graph-record.
(setf graph-root-nodes) Generic Function
(setf graph-root-nodes) roots graph-record
Summary: Sets the root nodes of graph-record to roots.
generate-graph-nodes Generic Function
generate-graph-nodes graph-record stream root-objects object-printer inferior-producer &key duplicate-key duplicate-test
Summary: This function is responsible for generating all the graph node output records of the graph. graph-record is the graph output record, and stream is the output stream. The graph node output records are generating by calling the object printer on the root objects, then (recursively) calling the inferior producer on the root objects and calling the object printer on all inferiors. After all the graph node output records have been generated, the value of graph-root-nodes of graph-record must be set to be a sequence of those graph node output records that correspond to the root objects.
root-objects, object-printer, inferior-producer, duplicate-key, and duplicate-test are as for format-graph-from-roots.
layout-graph-nodes Generic Function
layout-graph-nodes graph-record stream
Summary: This function is responsible for laying out the nodes in the graph contained in the output record graph-record. It is called after the graph output has been collected, but before the graph record has been displayed. The method on standard-graph-output-record implements the usual graph layout constraint solver. stream is the stream on which the graph is displayed.
layout-graph-edges Generic Function
layout-graph-edges graph-record stream arc-drawer arc-drawing-options
Summary: This function is responsible for laying out the edges in the graph. It is called after the graph nodes have been laid out, but before the graph record has been displayed. The method on standard-graph-output-record simply causes thin lines to be drawn from each node to all of its children. graph-record and stream are as for layout-graph-nodes.
graph-node-output-record Protocol Class
Summary: The protocol class that represents a node in graph; a subclass of output-record. If you want to create a new class that behaves like a graph node output record, it should be a subclass of graph-node-output-record. Subclasses of graph-node-output-record must obey the graph node output record protocol.
graph-node-output-record-p Function
graph-node-output-record-p object
Summary: Returns t if object is a graph node output record; otherwise, it returns nil.
standard-graph-node-output-record Class
Summary: The instantiable class of output record that represents a graph node. Its parent will be a graph output record. This is a subclass of graph-node-output-record.
graph-node-parents Generic Function
graph-node-parents graph-node-record
Summary: Returns a sequence of the graph node output records whose objects are "parents" of the object corresponding to the graph node output record graph-node-record. This differs from output-record-parent, as graph-node-parents can return output records that are not the parent records of graph-node-record.
(setf graph-node-parents) Generic Function
(setf graph-node-parents) parents graph-node-record
Summary: Sets the parents of graph-node-record to be parents. parents must be a list of graph node records.
graph-node-children Generic Function
graph-node-children graph-node-record
Summary: Returns a sequence of the graph node output records whose objects are "children" of the object corresponding to the graph node output record graph-node-record. This differs from output-record-children, as graph-node-children can return output records that are not child records of graph-node-record.
(setf graph-node-children) Generic Function
(setf graph-node-children) children graph-node-record
Summary: Sets the children of graph-node-record to be children. children must be a list of graph node records.
graph-node-object Generic Function
graph-node-object graph-node-record
Summary: Returns the object that corresponds to the output record graph-node-record. This function only works correctly while inside the call to format-graph-from-roots. Unspecified results are returned outside format-graph-from-roots, as CLIM does not capture application objects that might have dynamic extent.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:01