pintos-os.org Git - pspp/blob - src/output/table-provider.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997, 1998, 1999, 2000, 2009, 2011, 2013, 2014 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #ifndef OUTPUT_TABLE_PROVIDER
  18 #define OUTPUT_TABLE_PROVIDER 1
  19
  20 #include "output/table.h"
  21
  22 /* An item of contents within a table cell. */
  23 struct cell_contents
  24   {
  25     unsigned int options;       /* TAB_*. */
  26
  27     /* Exactly one of these must be nonnull. */
  28     char *text;                 /* A paragraph of text. */
  29     struct table *table;        /* A table nested within the cell. */
  30   };
  31
  32 /* A cell in a table. */
  33 struct table_cell
  34   {
  35     /* Occupied table region.
  36
  37        d[TABLE_HORZ][0] is the leftmost column.
  38        d[TABLE_HORZ][1] is the rightmost column, plus 1.
  39        d[TABLE_VERT][0] is the top row.
  40        d[TABLE_VERT][1] is the bottom row, plus 1.
  41
  42        For an ordinary cell:
  43            d[TABLE_HORZ][1] == d[TABLE_HORZ][0] + 1
  44        and d[TABLE_VERT][1] == d[TABLE_VERT][0] + 1
  45
  46        For a joined cell:
  47           d[TABLE_HORZ][1] > d[TABLE_HORZ][0] + 1
  48        or d[TABLE_VERT][1] > d[TABLE_VERT][0] + 1
  49        or both. */
  50     int d[TABLE_N_AXES][2];
  51
  52     /* The cell's contents.
  53
  54        Most table cells contain only one item (a paragraph of text), but cells
  55        are allowed to be empty (n_contents == 0) or contain a nested table, or
  56        multiple items.
  57
  58        'inline_contents' provides a place to store a single item to handle the
  59        common case.
  60     */
  61     const struct cell_contents *contents;
  62     size_t n_contents;
  63     struct cell_contents inline_contents;
  64
  65     /* Called to free the cell's data, if nonnull. */
  66     void (*destructor) (void *destructor_aux);
  67     void *destructor_aux;
  68   };
  69
  70 void table_cell_free (struct table_cell *);
  71
  72 /* Returns the number of columns that CELL spans.  This is 1 for an ordinary
  73    cell and greater than one for a cell that joins multiple columns. */
  74 static inline int
  75 table_cell_colspan (const struct table_cell *cell)
  76 {
  77   return cell->d[TABLE_HORZ][1] - cell->d[TABLE_HORZ][0];
  78 }
  79
  80 /* Returns the number of rows that CELL spans.  This is 1 for an ordinary cell
  81    and greater than one for a cell that joins multiple rows. */
  82 static inline int
  83 table_cell_rowspan (const struct table_cell *cell)
  84 {
  85   return cell->d[TABLE_VERT][1] - cell->d[TABLE_VERT][0];
  86 }
  87
  88 /* Returns true if CELL is a joined cell, that is, if it spans multiple rows
  89    or columns.  Otherwise, returns false. */
  90 static inline bool
  91 table_cell_is_joined (const struct table_cell *cell)
  92 {
  93   return table_cell_colspan (cell) > 1 || table_cell_rowspan (cell) > 1;
  94 }
  95 \f
  96 /* Declarations to allow defining table classes. */
  97
  98 struct table_class
  99   {
 100     /* Frees TABLE.
 101
 102        The table class may assume that any cells that were retrieved by calling
 103        the 'get_cell' function have been freed (by calling their destructors)
 104        before this function is called. */
 105     void (*destroy) (struct table *table);
 106
 107     /* Initializes CELL with the contents of the table cell at column X and row
 108        Y within TABLE.  All members of CELL must be initialized, except that if
 109        'destructor' is set to a null pointer, then 'destructor_aux' need not be
 110        initialized.  The 'contents' member of CELL must be set to a nonnull
 111        value.
 112
 113        The table class must allow any number of cells in the table to be
 114        retrieved simultaneously; that is, TABLE must not assume that a given
 115        cell will be freed before another one is retrieved using 'get_cell'.
 116
 117        The table class must allow joined cells to be retrieved, with identical
 118        contents, using any (X,Y) location inside the cell.
 119
 120        The table class must not allow cells to overlap.
 121
 122        The table class should not allow a joined cell to cross the border
 123        between header rows/columns and the interior of the table.  That is, a
 124        joined cell should be entirely within headers rows and columns or
 125        entirely outside them.
 126
 127        The table class may assume that CELL will be freed before TABLE is
 128        destroyed. */
 129     void (*get_cell) (const struct table *table, int x, int y,
 130                       struct table_cell *cell);
 131
 132     /* Returns one of the TAL_* enumeration constants (declared in
 133        output/table.h) representing a rule running alongside one of the cells
 134        in TABLE.
 135
 136        See table_get_rule() in table.c for a detailed explanation of the
 137        meaning of AXIS and X and Y, including a diagram. */
 138     int (*get_rule) (const struct table *table,
 139                      enum table_axis axis, int x, int y);
 140
 141     /* This function is optional and most table classes will not implement it.
 142
 143        If provided, this function must take ownership of A and B and return a
 144        table that consists of tables A and B "pasted together", that is, a
 145        table whose size is the sum of the sizes of A and B along the axis
 146        specified by ORIENTATION.  A and B will ordinarily have the same size
 147        along the axis opposite ORIENTATION; no particular handling of tables
 148        that have different sizes along that axis is required.
 149
 150        The handling of rules at the seam between A and B is not specified, but
 151        table_rule_combine() is one reasonable way to do it.
 152
 153        Called only if neither A and B is shared (as returned by
 154        table_is_shared()).
 155
 156        Called if A or B or both is of the class defined by this table class.
 157        That is, the implementation must be prepared to deal with the case where
 158        A or B is not the ordinarily expected table class.
 159
 160        This function may return a null pointer if it cannot implement the paste
 161        operation, in which case the caller will use a fallback
 162        implementation.
 163
 164        This function is used to implement table_paste(). */
 165     struct table *(*paste) (struct table *a, struct table *b,
 166                             enum table_axis orientation);
 167
 168     /* This function is optional and most table classes will not implement it.
 169
 170        If provided, this function must take ownership of TABLE and return a new
 171        table whose contents are the TABLE's rows RECT[TABLE_VERT][0] through
 172        RECT[TABLE_VERT][1], exclusive, and the TABLE's columns
 173        RECT[TABLE_HORZ][0] through RECT[TABLE_HORZ][1].
 174
 175        Called only if TABLE is not shared (as returned by table_is_shared()).
 176
 177        This function may return a null pointer if it cannot implement the
 178        select operation, in which case the caller will use a fallback
 179        implementation.
 180
 181        This function is used to implement table_select(). */
 182     struct table *(*select) (struct table *table, int rect[TABLE_N_AXES][2]);
 183   };
 184
 185 void table_init (struct table *, const struct table_class *);
 186
 187 /* Table class implementations can call these functions or just set the
 188    table's n[] and h[][] members directly. */
 189 void table_set_nc (struct table *, int nc);
 190 void table_set_nr (struct table *, int nr);
 191 \f
 192 /* For use primarily by output drivers. */
 193
 194 void table_get_cell (const struct table *, int x, int y, struct table_cell *);
 195 int table_get_rule (const struct table *, enum table_axis, int x, int y);
 196
 197 #endif /* output/table-provider.h */