17.3 The Table and Item List Formatting Protocols

  • 17.3.1 Table Formatting Protocol
  • 17.3.2 Row and Column Formatting Protocol
  • 17.3.3 Cell Formatting Protocol
  • 17.3.4 Item List Formatting Protocol
  • Both 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]
              

    Returns true if object is a table output record, otherwise returns false. [annotate]

    [annotate]

    :x-spacing   [Initarg]
    :y-spacing   [Initarg]
    :multiple-columns-x-spacing   [Initarg]
    :equalize-column-widths   [Initarg]
    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]

    Note: 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]

    Note: 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]
              

    This is called after adjust-table-cells to account for the case where the programmer wants the table to have multiple columns. table-record and stream are as for adjust-table-cells. [annotate]

    [annotate]

    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]
              

    Returns true if object is a row output record, otherwise returns false. [annotate]

    [annotate]

    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]

    Note:

    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]
              

    Returns true if object is a column output record, otherwise returns false. [annotate]

    [annotate]

    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]

    Note: map-over-column-cells should be the name of this generic function, since the map-over-row-cells is described above. [edit]-- Janis Dzerins 2011-01-26 09:03Z
     

    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]
              

    Returns true if object is a cell output record, otherwise returns false. [annotate]

    [annotate]

    :align-x   [Initarg]
    :align-y   [Initarg]
    :min-width   [Initarg]
    :min-height   [Initarg]
    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]

    Note: 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]

    :x-spacing   [Initarg]
    :y-spacing   [Initarg]
    :initial-spacing   [Initarg]
    :row-wise   [Initarg]
    :n-rows   [Initarg]
    :n-columns   [Initarg]
    :max-width   [Initarg]
    :max-height   [Initarg]
    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]