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, 2018 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 <stdint.h>
  21 #include "output/table.h"
  22
  23 struct pool;
  24 struct string;
  25
  26 enum table_halign table_halign_interpret (enum table_halign, bool numeric);
  27
  28 struct footnote
  29   {
  30     size_t idx;
  31     char *content;
  32     char *marker;
  33     struct area_style *style;
  34   };
  35
  36 /* A cell in a table. */
  37 struct table_cell
  38   {
  39     /* Occupied table region.
  40
  41        d[TABLE_HORZ][0] is the leftmost column.
  42        d[TABLE_HORZ][1] is the rightmost column, plus 1.
  43        d[TABLE_VERT][0] is the top row.
  44        d[TABLE_VERT][1] is the bottom row, plus 1.
  45
  46        For an ordinary cell:
  47            d[TABLE_HORZ][1] == d[TABLE_HORZ][0] + 1
  48        and d[TABLE_VERT][1] == d[TABLE_VERT][0] + 1
  49
  50        For a joined cell:
  51           d[TABLE_HORZ][1] > d[TABLE_HORZ][0] + 1
  52        or d[TABLE_VERT][1] > d[TABLE_VERT][0] + 1
  53        or both. */
  54     int d[TABLE_N_AXES][2];
  55
  56     unsigned int options;       /* TAB_*. */
  57     char *text;                 /* A paragraph of text. */
  58
  59     /* Optional footnote(s). */
  60     const struct footnote **footnotes;
  61     size_t n_footnotes;
  62
  63     const struct area_style *style;
  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 void table_cell_format_footnote_markers (const struct table_cell *,
  73                                          struct string *);
  74
  75 /* Returns the number of columns that CELL spans.  This is 1 for an ordinary
  76    cell and greater than one for a cell that joins multiple columns. */
  77 static inline int
  78 table_cell_colspan (const struct table_cell *cell)
  79 {
  80   return cell->d[TABLE_HORZ][1] - cell->d[TABLE_HORZ][0];
  81 }
  82
  83 /* Returns the number of rows that CELL spans.  This is 1 for an ordinary cell
  84    and greater than one for a cell that joins multiple rows. */
  85 static inline int
  86 table_cell_rowspan (const struct table_cell *cell)
  87 {
  88   return cell->d[TABLE_VERT][1] - cell->d[TABLE_VERT][0];
  89 }
  90
  91 /* Returns true if CELL is a joined cell, that is, if it spans multiple rows
  92    or columns.  Otherwise, returns false. */
  93 static inline bool
  94 table_cell_is_joined (const struct table_cell *cell)
  95 {
  96   return table_cell_colspan (cell) > 1 || table_cell_rowspan (cell) > 1;
  97 }
  98 \f
  99 /* Declarations to allow defining table classes. */
 100
 101 struct table_class
 102   {
 103     /* Frees TABLE.
 104
 105        The table class may assume that any cells that were retrieved by calling
 106        the 'get_cell' function have been freed (by calling their destructors)
 107        before this function is called. */
 108     void (*destroy) (struct table *table);
 109
 110     /* Initializes CELL with the contents of the table cell at column X and row
 111        Y within TABLE.  All members of CELL must be initialized, except that if
 112        'destructor' is set to a null pointer, then 'destructor_aux' need not be
 113        initialized.  The 'contents' member of CELL must be set to a nonnull
 114        value.
 115
 116        The table class must allow any number of cells in the table to be
 117        retrieved simultaneously; that is, TABLE must not assume that a given
 118        cell will be freed before another one is retrieved using 'get_cell'.
 119
 120        The table class must allow joined cells to be retrieved, with identical
 121        contents, using any (X,Y) location inside the cell.
 122
 123        The table class must not allow cells to overlap.
 124
 125        The table class should not allow a joined cell to cross the border
 126        between header rows/columns and the interior of the table.  That is, a
 127        joined cell should be entirely within headers rows and columns or
 128        entirely outside them.
 129
 130        The table class may assume that CELL will be freed before TABLE is
 131        destroyed. */
 132     void (*get_cell) (const struct table *table, int x, int y,
 133                       struct table_cell *cell);
 134
 135     /* Returns one of the TAL_* enumeration constants (declared in
 136        output/table.h) representing a rule running alongside one of the cells
 137        in TABLE.
 138
 139        See table_get_rule() in table.c for a detailed explanation of the
 140        meaning of AXIS and X and Y, including a diagram. */
 141     int (*get_rule) (const struct table *table,
 142                      enum table_axis axis, int x, int y,
 143                      struct cell_color *color);
 144
 145     /* This function is optional and most table classes will not implement it.
 146
 147        If provided, this function must take ownership of A and B and return a
 148        table that consists of tables A and B "pasted together", that is, a
 149        table whose size is the sum of the sizes of A and B along the axis
 150        specified by ORIENTATION.  A and B will ordinarily have the same size
 151        along the axis opposite ORIENTATION; no particular handling of tables
 152        that have different sizes along that axis is required.
 153
 154        The handling of rules at the seam between A and B is not specified, but
 155        table_rule_combine() is one reasonable way to do it.
 156
 157        Called only if neither A and B is shared (as returned by
 158        table_is_shared()).
 159
 160        Called if A or B or both is of the class defined by this table class.
 161        That is, the implementation must be prepared to deal with the case where
 162        A or B is not the ordinarily expected table class.
 163
 164        This function may return a null pointer if it cannot implement the paste
 165        operation, in which case the caller will use a fallback
 166        implementation.
 167
 168        This function is used to implement table_paste(). */
 169     struct table *(*paste) (struct table *a, struct table *b,
 170                             enum table_axis orientation);
 171
 172     /* This function is optional and most table classes will not implement it.
 173
 174        If provided, this function must take ownership of TABLE and return a new
 175        table whose contents are the TABLE's rows RECT[TABLE_VERT][0] through
 176        RECT[TABLE_VERT][1], exclusive, and the TABLE's columns
 177        RECT[TABLE_HORZ][0] through RECT[TABLE_HORZ][1].
 178
 179        Called only if TABLE is not shared (as returned by table_is_shared()).
 180
 181        This function may return a null pointer if it cannot implement the
 182        select operation, in which case the caller will use a fallback
 183        implementation.
 184
 185        This function is used to implement table_select(). */
 186     struct table *(*select) (struct table *table, int rect[TABLE_N_AXES][2]);
 187   };
 188
 189 void table_init (struct table *, const struct table_class *);
 190
 191 /* Table class implementations can call these functions or just set the
 192    table's n[] and h[][] members directly. */
 193 void table_set_nc (struct table *, int nc);
 194 void table_set_nr (struct table *, int nr);
 195 \f
 196 /* For use primarily by output drivers. */
 197
 198 void table_get_cell (const struct table *, int x, int y, struct table_cell *);
 199 int table_get_rule (const struct table *, enum table_axis, int x, int y,
 200                     struct cell_color *);
 201 size_t table_collect_footnotes (const struct table_item *,
 202                                 const struct footnote ***);
 203
 204 #endif /* output/table-provider.h */