ARTICLE UNDER CONSTRUCTION

Tables

Version 6.1.0

In this article

This article describes how to add tables to a MigraDoc document.

Creating a table

Usually, you create a new table by adding one to a section. Additionally, there are also some other objects you can add tables to. You can call an AddTable method for example for a header or footer (see Headers & footers) or a text frame (see Text frames).

After creating the table, you define the columns, add rows, and add content to the cells of the rows. Here an example for the creation of a simple table:

// Add table.
var table = section.AddTable();
table.Borders.Visible = true;

// Add first column.
var columnA = table.AddColumn(Unit.FromCentimeter(2));

// Add second column.
var columnB = table.AddColumn(Unit.FromCentimeter(3));

// Add first row.
var row1 = table.AddRow();
            
// Add paragraph to first cell of row1.
var cellA1 = row1[0];
cellA1.AddParagraph("Text A1");

// Add paragraph to second cell of row1.
var cellB1 = row1[1];
cellB1.AddParagraph("Text B1 contains more text.");

See full SimpleTable sample in PDFsharp.Sample repository. Show resulting PDF

The width parameter of AddColumn is of the type Unit (see Formats / Unit for more information).

You can also call AddColumn without the width parameter. Usually you would then set a default column width by assigning a value to table.Columns.Width. The columns will then inherit this value (see Inheritance) for more information). If no column with is defined, a default value of 2.5 centimeters will be used.

Row height

As you can see in Creating a table, columns have always a fixed width value. The height of the rows however is not fixed by default and depends on the content.

You can set a row height like this:

// Set row height.
row.Height = Unit.FromCentimeter(2.5);

See full RowHeight sample in PDFsharp.Sample repository. Show resulting PDF

Height is a property of the type Unit (see Formats / Unit for more information).

The HeightRule property accepts values of the RowHeightRule enum. It defines how the height is applied to the row. If Height is set, but HeightRule is not, AtLeast will be used as default value. This ensures that all contents of the row will fit in its cell borders by increasing the actual row height, if needed.

If you want to set a definite row height, you have to set HeightRule to Exactly:

// Set row height.
row.HeightRule = RowHeightRule.Exactly;
row.Height = Unit.FromCentimeter(2.5);

See full RowHeight sample in PDFsharp.Sample repository. Show resulting PDF

Height is a property of the type Unit (see Formats / Unit for more information).

Now the row will be of the given height, even if the content of a cell would require more space. In this case, the text will exceed the cell’s bottom border.

You can set the first row of the table as the table header by setting its HeadingFormat property to true. This row will be repeated, if the table spans over multiple pages. HeadingFormat, however, has no effect on the appearance of that line. That can be changed like for every other object, for example by using styles (see Document / Formatting for more information).

You could create a table header row like this:

// Add first row as header.
var row1 = table.AddRow();
row1.HeadingFormat = true;
row1.Style = tableHeaderStyleName;

// Add paragraph to first cell of row1.
row1[0].AddParagraph("Header A1");

// Add paragraph to second cell of row1.
row1[1].AddParagraph("Header B1");

See full TableHeader sample in PDFsharp.Sample repository. Show resulting PDF

It is also possible to define a table header consisting of multiple rows. Therefore, those rows must be at the top of the table and for each of them HeadingFormat has to be set to true.

Table positioning

By default, a table is left aligned on the page. But its reference point is not its left border. It’s the beginning of text in the first column, which is defined by its left padding (see Text positioning). This way the first column’s content is in line with text outside of the table. A potential border or shading will start further left than the set page margin.

To make the left border the reference point for left alignment, you have to explicitly set the left indent of the table to 0. Therefore, use the LeftIndent property of the Rows object of the table:

// Set left indent to zero, so that table is aligned at its border, not at its text.
table.Rows.LeftIndent = Unit.Zero;

See full TablePositioning sample in PDFsharp.Sample repository. Show resulting PDF

LeftIndent is a property of the type Unit (see Formats / Unit for more information).

Of course, you can set LeftIndent to another value to position the table.

You can also choose a different alignment for the table:

// Make table center aligned.
table.Rows.Alignment = RowAlignment.Center;

See full TablePositioning sample in PDFsharp.Sample repository. Show resulting PDF

Alignment accepts values of the RowAlignment enum, which are Left, Center and Right. For other values than Left, assigned values to LeftIndent are ignored.

Text positioning

The position of the text in a cell depends on the alignment and the padding.

The horizontal alignment of the cell’s text equals the Alignment property of the paragraphs (see Formats / Paragraph for more information).

Usually, you would set the horizontal alignment to the same value for a whole column. Therefore, simply use the ParagraphFormat of a Column object. To set it for the whole table, set table.Format.Alignment. See Inheritance for information about how inheritance will carry these settings to the cell content.

For the vertical alignment of the cell’s text, there is an own property VerticalAlignment in the Cell class.
You can set it to the VerticalAlignment enum values Top, Center and Bottom.

Usually, you would set the vertical alignment to the same value for a whole row. Therefore, you find the VerticalAlignment property also in a Row object. To set the vertical alignment for the whole table, set table.Rows.VerticalAlignment. See Inheritance for information about how inheritance will carry these settings to the cell content.

In this example, the horizontal alignment is set for whole columns and the vertical alignment is set for whole rows:

…
// Add second column with center alignment.
var columnB = table.AddColumn(Unit.FromCentimeter(5));
columnB.Format.Alignment = ParagraphAlignment.Center;
…
// Add second row with center vertical alignment.
var row2 = table.AddRow();
row2.VerticalAlignment = VerticalAlignment.Center;
…

See full TextPositioning sample in PDFsharp.Sample repository. Show resulting PDF

The width parameter of AddColumn is of the type Unit (see Formats / Unit for more information).

The padding defines the space between the cell’s borders and its content. It cannot be set individually for a cell. But the LeftPadding and RightPadding properties can be set for a single column and the TopPadding and BottomPadding properties can be set for a single row:

// Add first column.
var columnA = table.AddColumn(Unit.FromCentimeter(15));

// Set LeftPadding and RightPadding for columnA.
columnA.LeftPadding = Unit.FromCentimeter(2);
columnA.RightPadding = Unit.FromCentimeter(1);

// Add first row.
var row1 = table.AddRow();

// Set TopPadding and BottomPadding for row1.
row1.TopPadding = Unit.FromCentimeter(0.5);
row1.BottomPadding = Unit.FromCentimeter(1.5);

See full TextPositioning sample in PDFsharp.Sample repository. Show resulting PDF

The padding properties are of the type Unit (see Formats / Unit for more information).

You can also set the padding properties for the whole table at the Table object.

Data alignment with tab stops

Inside a table, you can use tab stops (see Formats / Tab stops) to get more alignment options for data layout than using format.Alignment. Using tab stops, you can even align data to the decimal separator. You can add tab stops to the paragraph format or style of a Table, Column, Row and Cell object. They will then be inherited to the contained paragraphs. This way you can achieve a consistent layout for data of any size very quickly and easily to maintain. See Inheritance for information about how inheritance will carry these settings to the contained text. For specific information about inheritance of tab stops, see Formats / Tab stops.

Merging cells

You can merge cells to make them span over multiple columns or rows. To merge cells horizontally, use the MergeRight property, and to merge them vertically MergeDown. These both integer properties specify with how many columns respectively rows this cell should be merged. So, the cell itself is not included in counting, like it is in colspan and rowspan attributes in HTML, for example.

The cell in the example below merges with one row down and with one column right, so it spans over two rows and two columns:

// Merge cell one row down and one column right.
cell.MergeDown = 1;
cell.MergeRight = 1;

See full MergingCells sample in PDFsharp.Sample repository. Show resulting PDF

Avoiding page breaks

Page breaks are not always desirable at every position in the table. Using the KeepWith property of a Row object, you can build a group of rows, that shall not be separated by automatic page breaks. Analog to the merge properties of a cell (see Merging cells), the current row is not included in counting for the value of KeepWith. KeepWith instead specifies with how many following rows the current row shall build a non-separable group.

The row in the example below builds a non-separable group with the two following rows:

// Keep rows 3, 4 and 5 together.
row3.KeepWith = 2;

See full AvoidingPageBreaks sample in PDFsharp.Sample repository. Show resulting PDF

Borders & shading

Borders and shading are not explained in this article, as not only tables can be formatted using them. For information about how the format of borders is changed, see Formats / Borders & line format. For information about how to change the background color using a shading, see Formats / Shading & fill forma.

Rounded corners

Note

This feature is not supported for RTF rendering. When rendering to RTF, the border cells will be displayed, but without rounded corners.

Rounded corners are a special feature that exceeds the possibilities of RTF and Microsoft Word’s Automation model, which is used as a reference for most MigraDoc features. Therefore, it works only when rendering PDF files. In fact, it is kind of a workaround, as it requires the actual table to be surrounded with additional cells, we will further call border cells. Those cells shall have no content and realize the padding to the table’s edges, while the four corner cells realize the rounded corners.

When creating the table, you have to add two additional columns for the border cells. Those columns shall have the width required for the border cells. Of course, a shading or borders are required to see the rounded corners.

// Add table.
var table = section.AddTable();
table.Shading.Color = Colors.LightBlue;

// Add first column (used for border cells).
table.AddColumn(Unit.FromCentimeter(0.25));

// Add second column.
table.AddColumn(Unit.FromCentimeter(3));

// Add third column.
table.AddColumn(Unit.FromCentimeter(3));

// Add fourth column (used for border cells).
table.AddColumn(Unit.FromCentimeter(0.25));

See full RoundedCorners sample in PDFsharp.Sample repository. Show resulting PDF

The width parameter of AddColumn is of the type Unit (see Formats / Unit for more information).

Before adding the actual content of the table, you have to add a first row for the top border cells. This row shall have no content and exactly the height required for the border cells (see Row height for more information). Set KeepWith to 1 to avoid page breaks directly after that border row (see Avoiding page breaks for more information). Set the RoundedCorner property of the first and last cell to the required RoundedCorner enum value to make them realize the top rounded corners.

// -- Add border cells row.

// Add first row.
var row1 = table.AddRow();

// Set height for border cells row.
row1.HeightRule = RowHeightRule.Exactly;
row1.Height = Unit.FromCentimeter(0.25);

// The border cells shall not be alone on one page.
row1.KeepWith = 1;

// The whole row consists of empty border cells.

// Make first cell of row1 TopLeft rounded corner.
row1[0].RoundedCorner = RoundedCorner.TopLeft;

// Make fourth cell of row1 TopRight rounded corner.
row1[3].RoundedCorner = RoundedCorner.TopRight;

See full RoundedCorners sample in PDFsharp.Sample repository. Show resulting PDF

Height is a property of the type Unit (see Formats / Unit for more information).

Then add the content rows of the table. Remember to leave each first and last cell empty, as they are the left and right border cells. For the last content row, set KeepWith to 1 to avoid page breaks directly before the following border row (see Avoiding page breaks for more information).

// -- Add content rows.
…
// Add fourth row.
var row4 = table.AddRow();

// The first cell is an empty border cell.

// Add paragraph to second cell of row4.
row4[1].AddParagraph("Text B4");

// Add paragraph to third cell of row4.
row4[2].AddParagraph("Text C4");

// The last cell is an empty border cell.

// The following border cells shall not be alone on one page.
row4.KeepWith = 1;

See full RoundedCorners sample in PDFsharp.Sample repository. Show resulting PDF

At last, add another row for the bottom border cells. This row shall also have no content and exactly the height required for the border cells (see Row height for more information). Set the RoundedCorner property of the first and last cell to the required RoundedCorner enum value to make them realize the bottom rounded corners.

// -- Add border cells row.

// Add fifth row.
var row5 = table.AddRow();

// Set height for border cells row.
row5.HeightRule = RowHeightRule.Exactly;
row5.Height = Unit.FromCentimeter(0.25);

// The whole row consists of empty border cells.

// Make first cell of row5 BottomLeft rounded corner.
row5[0].RoundedCorner = RoundedCorner.BottomLeft;

// Make fourth cell of row5 BottomRight rounded corner.
row5[3].RoundedCorner = RoundedCorner.BottomRight;

See full RoundedCorners sample in PDFsharp.Sample repository. Show resulting PDF

Height is a property of the type Unit (see Formats / Unit for more information).

Inheritance

Inside a table, inheritance works quite the same as in general (see Document / Formatting). You can set a format property at or assign a style to a table, row, column or cell. Table here inherits to each row and each column, which further inherit to each cell. When the values of a row and a column collide while inheriting to a cell, the row’s value is inherited instead of the column’s value. There are also format properties you can set on the table’s Rows object, which inherit to each row and on its Columns object, which inherit to each column.

Here an example for inheritance in tables:

// Set and use direct formatting at different levels to show, how inheritance works in tables.

// Add table and set format.
var table = section.AddTable();
table.Borders.Visible = true;
table.Format.Font.Size = Unit.FromPoint(8);

// Add first column.
var columnA = table.AddColumn();

// Add second column and set format.
var columnB = table.AddColumn();
columnB.Format.Font.Bold = true;

// Add third column and set format.
var columnC = table.AddColumn();
columnC.Format.Alignment = ParagraphAlignment.Center;
columnC.Format.Font.Color = Colors.Red;

// Set format for all rows.
table.Rows.Height = Unit.FromPoint(25);

// Add first row and set format.
var row1 = table.AddRow();
row1.VerticalAlignment = VerticalAlignment.Center;

// Get first cell of row1.
var cellA1 = row1[0];

// Add paragraph to cellA1.
cellA1.AddParagraph("Text A1");

// Get second cell of row1.
var cellB1 = row1[1];

// Add paragraph to cellB1.
cellB1.AddParagraph("Text B1");

// Get third cell of row1.
var cellC1 = row1[2];

// Add paragraph to cellC1.
cellC1.AddParagraph("Text C1");

// Add second row and set format.
var row2 = table.AddRow();
row2.Format.Font.Italic = true;

// Get first cell of row2.
var cellA2 = row2[0];

// Add paragraph to cellA2.
cellA2.AddParagraph("Text A2");

// Get second cell of row2.
var cellB2 = row2[1];

// Add paragraph to cellB2.
cellB2.AddParagraph("Text B2");

// Get third cell of row2.
var cellC2 = row2[2];

// Add paragraph to cellC2.
cellC2.AddParagraph("Text C2");

// Add third row and set format.
var row3 = table.AddRow();
row3.VerticalAlignment = VerticalAlignment.Bottom;
row3.Format.Font.Color = Colors.Green;

// Get first cell of row3.
var cellA3 = row3[0];

// Add paragraph to cellA3.
cellA3.AddParagraph("Text A3");

// Get second cell of row3.
var cellB3 = row3[1];

// Add paragraph to cellB3.
cellB3.AddParagraph("Text B3");

// Get third cell of row3.
var cellC3 = row3[2];

// Add paragraph to cellC3.
cellC3.AddParagraph("Text C3");

See full Inheritance sample in PDFsharp.Sample repository. Show resulting PDF

Height and Size are properties of the type Unit (see Formats / Unit for more information).

Color is a property of the type Color (see Formats / Colors for more information).

This is the same code, with comments added for every inherited or overridden property:

// Set and use direct formatting at different levels to show, how inheritance works in tables.
// Overridden and inherited values are explained for each document object in the following comments.

// Add table and set format.
var table = section.AddTable();
table.Borders.Visible = true;
table.Format.Font.Size = Unit.FromPoint(8);

// Add first column.
var columnA = table.AddColumn();
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.

// Add second column and set format.
var columnB = table.AddColumn();
columnB.Format.Font.Bold = true;
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.

// Add third column and set format.
var columnC = table.AddColumn();
columnC.Format.Alignment = ParagraphAlignment.Center;
columnC.Format.Font.Color = Colors.Red;
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.

// Set format for all rows.
table.Rows.Height = Unit.FromPoint(25);

// Add first row and set format.
var row1 = table.AddRow();
row1.VerticalAlignment = VerticalAlignment.Center;
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.
// 'Height = Unit.FromPoint(25)' will be inherited from rows.

// Get first cell of row1.
var cellA1 = row1[0];
// 'Borders.Visible = true' will be inherited from row1 (same value as columnA) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row1 (same value as columnA) > table.
// 'Height = Unit.FromPoint(25)' will be inherited from row1 > rows.
// 'VerticalAlignment = Center' will be inherited from row1.

// Add paragraph to cellA1.
cellA1.AddParagraph("Text A1");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellA1 > row1 (same value as columnA) > table.

// Get second cell of row1.
var cellB1 = row1[1];
// 'Borders.Visible = true' will be inherited from row1 (same value as columnB) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row1 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from columnB.
// 'Height = Unit.FromPoint(25)' will be inherited from row1 > rows.
// 'VerticalAlignment = Center' will be inherited from row1.

// Add paragraph to cellB1.
cellB1.AddParagraph("Text B1");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellB1 > row1 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from cellB1 > columnB.

// Get third cell of row1.
var cellC1 = row1[2];
// 'Borders.Visible = true' will be inherited from row1 (same value as columnC) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row1 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from columnC.
// 'Format.Font.Color = Red' will be inherited from columnC.
// 'Height = Unit.FromPoint(25)' will be inherited from row1 > rows.
// 'VerticalAlignment = Center' will be inherited from row1.

// Add paragraph to cellC1.
cellC1.AddParagraph("Text C1");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellC1 > row1 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from cellC1 > columnC.
// 'Format.Font.Color = Red' will be inherited from cellC1 > columnC.

// Add second row and set format.
var row2 = table.AddRow();
row2.Format.Font.Italic = true;
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.
// 'Height = Unit.FromPoint(25)' will be inherited from rows.

// Get first cell of row2.
var cellA2 = row2[0];
// 'Borders.Visible = true' will be inherited from row2 (same value as columnA) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row2 (same value as columnA) > table.
// 'Height = Unit.FromPoint(25)' will be inherited from row2 > rows.
// 'Format.Font.Italic = true' will be inherited from row2.

// Add paragraph to cellA2.
cellA2.AddParagraph("Text A2");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellA2 > row2 (same value as columnA) > table.
// 'Format.Font.Italic = true' will be inherited from cellA2 > row2.

// Get second cell of row2.
var cellB2 = row2[1];
// 'Borders.Visible = true' will be inherited from row2 (same value as columnB) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row2 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from columnB.
// 'Height = Unit.FromPoint(25)' will be inherited from row2 > rows.
// 'Format.Font.Italic = true' will be inherited from row2.

// Add paragraph to cellB2.
cellB2.AddParagraph("Text B2");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellB2 > row2 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from cellB2 > columnB.
// 'Format.Font.Italic = true' will be inherited from cellB2 > row2.

// Get third cell of row2.
var cellC2 = row2[2];
// 'Borders.Visible = true' will be inherited from row2 (same value as columnC) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row2 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from columnC.
// 'Format.Font.Color = Red' will be inherited from columnC.
// 'Height = Unit.FromPoint(25)' will be inherited from row2 > rows.
// 'Format.Font.Italic = true' will be inherited from row2.

// Add paragraph to cellC2.
cellC2.AddParagraph("Text C2");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellC2 > row2 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from cellC2 > columnC.
// 'Format.Font.Color = Red' will be inherited from cellC2 > columnC
// 'Format.Font.Italic = true' will be inherited from cellC2 > row2.

// Add third row and set format.
var row3 = table.AddRow();
row3.VerticalAlignment = VerticalAlignment.Bottom;
row3.Format.Font.Color = Colors.Green;
// 'Borders.Visible = true' will be inherited from table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from table.
// 'Height = Unit.FromPoint(25)' will be inherited from rows.

// Get first cell of row3.
var cellA3 = row3[0];
// 'Borders.Visible = true' will be inherited from row3 (same value as columnA) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row3 (same value as columnA) > table.
// 'Height = Unit.FromPoint(25)' will be inherited from row3 > rows.
// 'VerticalAlignment = Bottom' will be inherited from row3.
// 'Format.Font.Color = Green' will be inherited from row3.

// Add paragraph to cellA3.
cellA3.AddParagraph("Text A3");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellA3 > row3 (same value as columnA) > table.
// 'Format.Font.Color = Green' will be inherited from cellA3 > row3.

// Get second cell of row3.
var cellB3 = row3[1];
// 'Borders.Visible = true' will be inherited from row3 (same value as columnB) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row3 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from columnB.
// 'Height = Unit.FromPoint(25)' will be inherited from row3 > rows.
// 'VerticalAlignment = Bottom' will be inherited from row3.
// 'Format.Font.Color = Green' will be inherited from row3.

// Add paragraph to cellB3.
cellB3.AddParagraph("Text B3");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellB3 > row3 (same value as columnB) > table.
// 'Format.Font.Bold = true' will be inherited from cellB3 > columnB.
// 'Format.Font.Color = Green' will be inherited from cellB3 > row3.

// Get third cell of row3.
var cellC3 = row3[2];
// 'Borders.Visible = true' will be inherited from row3 (same value as columnC) > table.
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from row3 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from columnC.
// 'Format.Font.Color = Red' will NOT be inherited from columnC, as the value from row3 (see below) has priority.
// 'Height = Unit.FromPoint(25)' will be inherited from row3 > rows.
// 'VerticalAlignment = Bottom' will be inherited from row3.
// 'Format.Font.Color = Green' will be inherited from row3.

// Add paragraph to cellC3.
cellC3.AddParagraph("Text C3");
// 'Format.Font.Size = Unit.FromPoint(8)' will be inherited from cellC3 > row3 (same value as columnC) > table.
// 'Format.Alignment = Center' will be inherited from cellC3 > columnC.
// 'Format.Font.Color = Green' will be inherited from cellC3 > row3.

See full Inheritance sample in PDFsharp.Sample repository. Show resulting PDF

Height and Size are properties of the type Unit (see Formats / Unit for more information).

Color is a property of the type Color (see Formats / Colors for more information).