17.3 The Table and Item List Formatting Protocols
17.3.1 Table Formatting Protocol17.3.2 Row and Column Formatting Protocol17.3.3 Cell Formatting Protocol17.3.4 Item List Formatting ProtocolBoth table and item list formatting is implemented on top of the basic output recording protocol, using with-new-output-record to specify the appropriate type of output record. For example, 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. [annotate]
17.3.1 Table Formatting Protocol
Any output record class that implements the following generic functions is said to support the table formatting protocol. [annotate]
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 implementations are encouraged to detect 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. [annotate]
| table-output-record | | [Protocol Class] |
| | 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. All instantiable subclasses of table-output-record must obey the table output record protocol. [annotate] [annotate] |
| table-output-record-p | object | [Protocol Predicate] |
| :multiple-columns-x-spacing | | [Initarg] |
| :equalize-column-widths | | [Initarg] |
| | 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. [annotate] [annotate] |
| standard-table-output-record | | [Class] |
| | 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. [annotate] The restriction that only presentation output records are allowed as
intervening records seems a bit arbitrary to me. We'll implement this
to allow any composite output record in between and hope that the
intervening records do the right thing.
Further note that there exists code which for instance puts an
updating-output record in between (cl-reversi).
In general this raises the question if something like this:
(formatting-table ()
(surrounding-output-with-border ()
(formatting-row ()
...)))
ought or can be supported.
[edit]-- Gilbert Baumann 2003-06-05 18:03Z [annotate] About intervening border output records: as the last paragraph of the surrounding-output-with-border mentions, this _can_ be supported. And having seen the HTML, I'd say it probably should be, too.
[edit]-- Janis Dzerins 2011-01-26 08:56Z |
| map-over-table-elements | function table-record type | [Generic Function] |
| | 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 is responsible for ensuring that rows, columns, and cells are properly nested. It must skip over intervening non-table output record structure, such as presentations. [annotate] [annotate] |
| adjust-table-cells | table-record stream | [Generic Function] |
| | 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 (described above) 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. [annotate] [annotate] |
| adjust-multiple-columns | table-record stream | [Generic Function] |
17.3.2 Row and Column Formatting Protocol
Any output record class that implements the following generic functions is said to support the row (or column) formatting protocol. [annotate]
| row-output-record | | [Protocol Class] |
| | 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. All instantiable subclasses of row-output-record must obey the row output record protocol. [annotate] [annotate] |
| row-output-record-p | object | [Protocol Predicate] |
| standard-row-output-record | | [Class] |
| | 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. [annotate] Surprise, surprise! Here it talks about any non-tabular output records may
be in between this and its parent. Contracting
standard-table-output-record and supporting my annotation. However this is written as if the children of such a
standard-row-output-record must be cells. I think intervening
output records between a row and a cell are okay too.
[edit]-- Gilbert Baumann 2003-06-05 18:11Z [annotate] |
| map-over-row-cells | function row-record | [Generic Function] |
| | 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. [annotate] [annotate] |
| column-output-record | | [Protocol Class] |
| | 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. All instantiable subclasses of column-output-record must obey the column output record protocol. [annotate] [annotate] |
| column-output-record-p | object | [Protocol Predicate] |
| standard-column-output-record | | [Class] |
| | The instantiable class of output record that represent 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. [annotate] [annotate] |
| map-over-row-cells | function column-record | [Generic Function] |
| | 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. [annotate] [annotate] |
17.3.3 Cell Formatting Protocol
Any output record class that implements the following generic functions is said to support the cell formatting protocol. [annotate]
| cell-output-record | | [Protocol Class] |
| | 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. All instantiable subclasses of cell-output-record must obey the cell output record protocol. [annotate] [annotate] |
| cell-output-record-p | object | [Protocol Predicate] |
| | 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. [annotate] [annotate] |
| standard-cell-output-record | | [Class] |
| | The instantiable class of output record that represent 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. [annotate] [annotate] |
| cell-align-x | cell | [Generic Function] |
| cell-align-y | cell | [Generic Function] |
| cell-min-width | cell | [Generic Function] |
| cell-min-height | cell | [Generic Function] |
| | These functions return, respectively, the x and y alignment and minimum width and height of the cell output record cell. [annotate] [annotate] Should this be returned as simple coordinates or can this be
some spacing-value like e.g. (5 :character)? [edit]-- Gilbert Baumann 2003-06-07 05:29Z |
17.3.4 Item List Formatting Protocol
| item-list-output-record | | [Protocol Class] |
| | 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. All instantiable subclasses of item-list-output-record must obey the item list output record protocol. [annotate] [annotate] |
| item-list-output-record-p | object | [Protocol Predicate] |
| | Returns true if object is an item list output record, otherwise returns false. [annotate] [annotate] |
| :initial-spacing | | [Initarg] |
| | All subclasses of item-list-output-record must handle these initargs, which are used to specify, respectively, the x and y spacing, the initial spacing, row-wise, the desired number of rows and columns, and maximum width and height attributes of the item list. [annotate] [annotate] |
| standard-item-list-output-record | | [Class] |
| | The instantiable 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. [annotate] [annotate] |
| map-over-item-list-cells | function item-list-record | [Generic Function] |
| | Applies function to all of the cells in item-list-record. map-over-item-list-cells must skip 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. [annotate] [annotate] |
| adjust-item-list-cells | item-list-record stream | [Generic Function] |
| | 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. [annotate] [annotate] |