1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997, 1998, 1999, 2000, 2009, 2011, 2013, 2014 Free Software Foundation, Inc.
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.
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.
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/>. */
17 #ifndef OUTPUT_TABLE_PROVIDER
18 #define OUTPUT_TABLE_PROVIDER 1
20 #include "output/table.h"
22 /* An item of contents within a table cell. */
25 unsigned int options; /* TAB_*. */
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. */
32 /* A cell in a table. */
35 /* Occupied table region.
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.
43 d[TABLE_HORZ][1] == d[TABLE_HORZ][0] + 1
44 and d[TABLE_VERT][1] == d[TABLE_VERT][0] + 1
47 d[TABLE_HORZ][1] > d[TABLE_HORZ][0] + 1
48 or d[TABLE_VERT][1] > d[TABLE_VERT][0] + 1
50 int d[TABLE_N_AXES][2];
52 /* The cell's contents.
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
58 'inline_contents' provides a place to store a single item to handle the
61 const struct cell_contents *contents;
63 struct cell_contents inline_contents;
65 /* Called to free the cell's data, if nonnull. */
66 void (*destructor) (void *destructor_aux);
70 void table_cell_free (struct table_cell *);
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. */
75 table_cell_colspan (const struct table_cell *cell)
77 return cell->d[TABLE_HORZ][1] - cell->d[TABLE_HORZ][0];
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. */
83 table_cell_rowspan (const struct table_cell *cell)
85 return cell->d[TABLE_VERT][1] - cell->d[TABLE_VERT][0];
88 /* Returns true if CELL is a joined cell, that is, if it spans multiple rows
89 or columns. Otherwise, returns false. */
91 table_cell_is_joined (const struct table_cell *cell)
93 return table_cell_colspan (cell) > 1 || table_cell_rowspan (cell) > 1;
96 /* Declarations to allow defining table classes. */
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);
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
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'.
117 The table class must allow joined cells to be retrieved, with identical
118 contents, using any (X,Y) location inside the cell.
120 The table class must not allow cells to overlap.
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.
127 The table class may assume that CELL will be freed before TABLE is
129 void (*get_cell) (const struct table *table, int x, int y,
130 struct table_cell *cell);
132 /* Returns one of the TAL_* enumeration constants (declared in
133 output/table.h) representing a rule running alongside one of the cells
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);
141 /* This function is optional and most table classes will not implement it.
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.
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.
153 Called only if neither A and B is shared (as returned by
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.
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
164 This function is used to implement table_paste(). */
165 struct table *(*paste) (struct table *a, struct table *b,
166 enum table_axis orientation);
168 /* This function is optional and most table classes will not implement it.
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].
175 Called only if TABLE is not shared (as returned by table_is_shared()).
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
181 This function is used to implement table_select(). */
182 struct table *(*select) (struct table *table, int rect[TABLE_N_AXES][2]);
185 void table_init (struct table *, const struct table_class *);
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);
192 /* For use primarily by output drivers. */
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);
197 #endif /* output/table-provider.h */