45
7.4 Table Formatting 165
When placing the table the size of its fitbox and the ruling and shading of table rows
or columns can be specified. Use the Matchbox feature for details such as cell-specific
shading (see Section 7.5, »Matchboxes«, page 177, for more information).
In this section the most important options for defining the table cells and fitting the
table will be discussed. All examples demonstrate the relevant calls of PDF_add_table_
cell( ) and PDF_fit_table( ) only, assuming that the required font has already been loaded.
Note Table processing is independent from the current graphics state. Table cells can be defined in
document scope while the actual table placement must be done in page scope.
Cookbook A full code sample can be found in the Cookbook topic tables/starter_table.
7.4.1 Placing a Simple Table
Before we describe the table concepts in more detail, we will demonstrate a simple ex-
ample for creating a table. The table contains six cells which are arranged in three rows
and two columns. Four cells contain text lines, and one cell contains a multi-line Text-
flow. All cell contents are horizontally aligned to the left, and vertically aligned to the
center with a margin of 4 points.
To create the table we first prepare the option list for the text line cells by defining
the required options font and fontsize and a position of {left center} in the fittextline sub-
option list. In addition, we define cell margins of 4 points. Then we add the text line cells
one after the other in their respective column and row, with the actual text supplied di-
rectly in the call to PDF_add_table_cell( ).
In the next step we create a Textflow, use the Textflow handle to assemble the option
list for the Textflow table cell, and add that cell to the table.
Finally we place the table with PDF_fit_table( )
while visualizing the table frame and
cell borders with black lines. Since we didn’t supply any column widths, they will be cal-
culated automatically from the supplied text lines plus the margins.
Cookbook A full code sample can be found in the Cookbook topic tables/vertical_text_alignment.
The following code fragment shows how to create the simple table. The result is shown
in Figure 7.35a.
/* Text for filling a table cell with multi-line Textflow */
String tf_text = "It is amazingly robust and can even do aerobatics. " +
"But it is best suited to gliding.";
/* Define the column widths of the first and the second column */
int c1 = 80, c2 = 120;
/* Define the lower left and upper right corners of the table instance (fitbox) */
double llx=100, lly=500, urx=300, ury=600;
/* Load the font */
font = p.load_font("Helvetica", "unicode", "");
if (font == -1)
throw new Exception("Error: " + p.get_errmsg());
/* Define the option list for the text line cells placed in the first column */
optlist = "fittextline={position={left center} font=" + font + " fontsize=8} margin=4" +
colwidth=" + c1;
/* Add a text line cell in column 1 row 1 */
47
166
Chapter 7: Formatting Features
tbl = p.add_table_cell(tbl, 1, 1, "Our Paper Planes", optlist);
if (tbl == -1)
throw new Exception("Error: " + p.get_errmsg());
/* Add a text line cell in column 1 row 2 */
tbl = p.add_table_cell(tbl, 1, 2, "Material", optlist);
if (tbl == -1)
throw new Exception("Error: " + p.get_errmsg());
/* Add a text line cell in column 1 row 3 */
tbl = p.add_table_cell(tbl, 1, 3, "Benefit", optlist);
if (tbl == -1)
throw new Exception("Error: " + p.get_errmsg());
/* Define the option list for a text line placed in the second column */
optlist = "fittextline={position={left center} font=" + font + " fontsize=8} " +
"colwidth=" + c2 + " margin=4";
/* Add a text line cell in column 2 row 2 */
tbl = p.add_table_cell(tbl, 2, 2, "Offset print paper 220g/sqm", optlist);
if (tbl == -1)
throw new Exception("Error: " + p.get_errmsg());
/* Add a Textflow */
optlist = "font=" + font + " fontsize=8 leading=110%";
tf = p.add_textflow(-1, tf_text, optlist);
/* Define the option list for the Textflow cell using the handle retrieved above */
optlist = "textflow=" + tf + " margin=4 colwidth=" + c2";
/* Add the Textflow table cell in column 2 row 3 */
tbl = p.add_table_cell(tbl, 2, 3, "", optlist);
if (tbl == -1)
throw new Exception("Error: " + p.get_errmsg());
p.begin_page_ext(0, 0, "width=200 height=100");
/* Define the option list for fitting the table with table frame and cell ruling */
optlist = "stroke={{line=frame linewidth=0.8} {line=other linewidth=0.3}}";
/* Place the table instance */
result = p.fit_table(tbl, llx, lly, urx, ury, optlist);
/* Check the result; "_stop" means all is ok. */
if (!result.equals("_stop")) {
if (result.equals( "_error"))
throw new Exception("Error: " + p.get_errmsg());
else {
/* Any other return value requires dedicated code to deal with */
}
}
p.end_page_ext("");
/* This will also delete Textflow handles used in the table */
p.delete_table(tbl, "");
Fine-tuning the vertical alignment of cell contents. When we vertically center con-
tents of various types in the table cells, they will be positioned with varying distance
47
7.4 Table Formatting 167
from the borders. In Figure 7.35a, the four text line cells have been placed with the fol-
lowing option list:
optlist = "fittextline={position={left center} font=" + font +
" fontsize=8} colwidth=80 margin=4";
The Textflow cell is added without any special options. Since we vertically centered the
text lines, the Benefit line will move down with the height of the Textflow.
Fig. 7.35 Aligning text lines and Textflow in table cells
As shown in Figure 7.35b, we want all cell contents to have the same vertical distance
from the cell borders regardless of whether they are Textflows or text lines. To accom-
plish this we first prepare the option list for the text lines. We define a fixed row height
of 14 points, and the position of the text line to be on the top left with a margin of 4
points.
The fontsize=8 option which we supplied before doesn’t exactly represent the letter
height but adds some space below and above. However, the height of an uppercase let-
ter is exactly represented by the capheight value of the font. For this reason we use
fontsize={capheight=6} which will approximately result in a font size of 8 points and
(along with margin=4), will sum up to an overall height of 14 points corresponding to the
rowheight option. The complete option list of PDF_add_table_cell( ) for our text line cells
looks as follows:
/* option list for the text line cells */
optlist = "fittextline={position={left top} font=" + font +
" fontsize={capheight=6}} rowheight=14 colwidth=80 margin=4";
To add the Textflow we use fontsize={capheight=6} which will approximately result in a
font size of 8 points and (along with margin=4), will sum up to an overall height of 14
points as for the text lines above.
/* option list for adding the Textflow */
optlist = "font=" + font + " fontsize={capheight=6} leading=110%";
In addition, we want the baseline of the Benefit text aligned with the first line of the
Textflow. At the same time, the Benefit text should have the same distance from the top
Generated output
a)
b)
Our Paper Planes
Material
Benefit
Offset print paper 220g/sqm
It is amazingly robust and can
even do aerobatics. But it is
best suited to gliding.
Our Paper Planes
Material
Benefit
Offset print paper 220g/sqm
It is amazingly robust and can
even do aerobatics. But it is
best suited to gliding.
49
168
Chapter 7: Formatting Features
cell border as the Material text. To avoid any space from the top we add the Textflow cell
using fittextflow={firstlinedist=capheight}. Then we add a margin of 4 points, the same as
for the text lines:
/* option list for adding the Textflow cell */
optlist = "textflow=" + tf + " fittextflow={firstlinedist=capheight} "
"colwidth=120 margin=4";
Cookbook A full code sample can be found in the Cookbook topic tables/vertical_text_alignment.
7.4.2 Contents of a Table Cell
When adding a cell to a table with PDF_add_table_cell( ), you can specify various kinds of
cell contents. For example, the cells of the paper plane table contain the elements illus-
trated in Figure 7.36.
Single-line text. The text is supplied in the text parameter of PDF_add_table_cell( ). In
the fittextline option all of the formatting options of PDF_fit_textline( ) can be specified.
The default fit method is fitmethod=nofit. The cell will be enlarged if the text doesn’t
completely fit into the cell. To avoid this, use fitmethod=auto to shrink the text subject
to the shrinklimit option. If no row height is given it will be calculated as the font size
times 1.5. The same applies to the row width for rotated text.
Multi-line text with Textflow. The Textflow must have been prepared outside the ta-
ble functions and created with PDF_create_textflow( ) or PDF_add_textflow( ) before call-
ing PDF_add_table_cell( ). The Textflow handle is supplied in the textflow option. In the
fittextflow option all of the formatting options of PDF_fit_textflow( ) can be specified.
The default fit method is fitmethod=clip. This means: First it is attempted to com-
pletely fit the text into the cell. If the cell is not large enough its height will be increased.
If the text do not fit anyway it will be clipped at the bottom. To avoid this, use
fitmethod=auto to shrink the text subject to the minfontsize option.
When the cell is too narrow the Textflow could be forced to split single words at un-
desired positions. If the checkwordsplitting option is true the cell width will be enlarged
until no word splitting occurs any more.
Images and templates. Images must be loaded with PDF_load_image( ) before calling
PDF_add_table_cell( ). Templates must be created with PDF_begin_template( ). The image
or template handle is supplied in the image option. In the fitimage option all of the for-
matting options of PDF_fit_image( ) can be specified. The default fit method is
fitmethod=meet. This means that the image/template will be placed completely inside
the cell without distorting its aspect ratio. The cell size will not be changed due to the
size of the image/template.
Text line
Text line
Text line
Text line
Text line
Textflow ................................
..............................................
..............................................
Text line
Fig. 7.36
Contents of the
table cells
69
7.4 Table Formatting 169
Pages from an imported PDF document. The PDI page must have been opened with
PDF_open_pdi_page( ) before calling PDF_add_table_cell( ). The PDI page handle is sup-
plied in the pdipage option. In the fitpdipage option all of the formatting options of PDF_
fit_pdi_page( ) can be specified. The default fit method is fitmethod=meet. This means
that the PDI page will be placed completely inside the cell without distorting its aspect
ratio. The cell size will not be changed due to the size of the PDI page.
Multiple content types in a cell. Table cells can contain one or more of those content
types at the same time. Additional ruling and shading is available, as well as matchbox-
es for interactive features such as links or form fields.
Positioning cell contents. By default, cell contents are positioned with respect to the
cell box. The margin options of PDF_add_table_cell( ) can be used to specify some dis-
tance from the cell borders. The resulting rectangle is called the inner cell box. If any of
the margins is defined, the cell contents will be placed with respect to the inner cell box
(see Figure 7.37). If no margins are defined the inner cell box will be identical to the cell
box.
In addition, the cell contents may be subject to further options supplied in the content-
specific fit options, as described in section Section 7.4.4, »Mixed Table Contents«, page
170.
7.4.3 Table and Column Widths
When adding a cell to the table, you define the number of columns and/or rows
spanned by the cell with the colspan and rowspan options. By default, a cell spans one
column and one row. The total number of columns and rows in the table is implicitly in-
creased by the respective values when adding a cell. Figure 7.38 shows an example of a
table containing three columns and four rows.
Furthermore you can explicitly supply the width of the first column spanned by the cell
with the colwidth option. By supplying each cell with a defined first column width all
inner cell box
cell box
left margin
top margin
bottom margin
right margin
Fig. 7.37
Fitting contents in
the inner cell box
cell ............ spanning ............ three ............ columns
cell ...... spanning ...... two ...... columns
2
4
3
3
4
2
1
1
1
1
1
2
2
3
simple cell
simple cell
simple cell
simple cell
row 1
row 2
row 3
row 4
column 1
column 2
column 3
cell ....
.... spanning ....
.... three rows
Fig. 7.38
Simple cells and cells spanning
several rows or columns
83
170
Chapter 7: Formatting Features
those width values will implicitly add up to the total table width. Figure 7.39 shows an
example.
Alternatively, you can specify the column widths as percentages if appropriate. In this
case the percentages refer to the width of the table’s fitbox. Either none or all column
widths must be supplied as percentages.
If some columns are combined to a column scaling group with the colscalegroup op-
tion of PDF_add_table_cell( ), their widths will be adjusted to the widest column in the
group (see Figure 7.40),
If absolute coordinates are used (as opposed to percentages) and there are cells left
without any column width defined, the missing widths are calculated as follows: First,
for each cell containing a text line the actual width is calculated based on the column
width or the text width (or the text height in case of rotated text). Then, the remaining
table width is evenly distributed among the column widths which are still missing.
7.4.4 Mixed Table Contents
In the following sections we will create the sample table containing various kinds of
contents as shown in Figure 7.41 step by step.
Cookbook A full code sample can be found in the Cookbook topic tables/mixed_table_contents.
As a prerequisite we need to load two fonts. We define the dimensions of the table’s fit-
box in terms of the coordinates of the lower left and upper right corners and specify the
widths of the three table columns. Then, we start a new page with A4 size:
double llx = 100, lly = 500, urx = 360, ury = 600; // coordinates of the table
int c1 = 50, c2 = 120, c3 = 90; // widths of the three table columns
2
4
3
3
4
2
1
1
1
1
1
2
2
3
colspan=1
colwidth=100
colspan=1
colwidth=50
colspan=1
colwidth=50
colspan=1
colwidth=100
50
100
90
colspan=2
colwidth=50
rowspan=3
colwidth=90
colspan=3
colwidth=50
total table width of 240
Fig. 7.39
Column widths define
the total table width.
Long Distance Glider
Giant Wing
Cone Head Rocket
Max. Load
Range
12g
Weight
14g
11.2g
12.4g
5g
7g
30m
7m
18m
Speed
8m/s
5m/s
6m/s
column scaling group
Fig. 7.40
The last four cells in the first row are in the
same column scaling group. They will have
the same widths.
Documents you may be interested
Documents you may be interested
