2.12 Data Table Support

The data table classes allow you to display data tables in your PDF document. PdfTable is the main class controlling the display of one table. A table is made out of a header row and data rows. Each row is divided into cells. PdfTableCell controls the display of one header cell or one data cell. If header is used it will be displayed at the top of the table. Optionally it will be displayed at the top of each additional page. To display data in a cell, you load the data into the Value property of PdfTableCell. Data can be text string, basic numeric value, Boolean, Char, TextBox, image, QR code or barcode. Independently of data, you can load the cell with document link, web link, video, audio or embedded file. Clicking anywhere within the cell's area will cause the PDF reader to activate the document link, web link, video, audio or embedded file. The display of the data is controlled by PdfTableStyle class. PdfTable class contains a default cell style and a default header style. You can override the default styles with private styles within PdfTableCell. To display a table, you create a PdfTable object. Next you initialize the table, header cells, data cells and styles objects. Finally, you set a loop and load the cell values of one row and then draw this row. This loop continues until all data was displayed. Below you will find the necessary sequence of steps to produce a table.

When DrawRow method is called, the software calculates the required row height. Row height is the height of the tallest cell. The row will be drawn if there is sufficient space within the table. When the available space at the bottom is too small, a new page is called, and optional heading and the current row are displayed at the top of the table. If the required row height is so large that it will not fit in full empty table, an exception is raised. In order to accommodate long multi-line Strings or TextBoxes, the software can handle these cases in a flexible way. Multi-line String is converted by PdfTable into a TextBox. The PdfTableStyle class has a TextBoxPageBreakLines property. If this property is set to zero (default), the TextBox is treated as other data values. TextBox height must fit the page. If TextBoxPageBreakLines is set to a positive integer, the system will calculate cell's height as TextBox height or the height the first few lines as specified by TextBoxPageBreakLines. The system will draw the row with as many lines that fit the page. A new page will be created, and the rest of the lines will be drawn. In other words, the first block of lines of a long TextBox will be at least TextBoxPageBreakLines long. TableExample.cs source contains an example of long TextBox cells.

Create a PdfTable object.

// create table
PdfTable Table = new PdfTable(Page, Contents, Font, FontSize);

Page is the current PdfPage. Contents is the current PdfContents. Font is the table default font. FontSize is the default font size in points.

Define table's area on the page.

// table's area on the page
Table.TableArea = new PdfRectangle(Left, Bottom, Right, Top);

// first page starting vertical position
Table.RowTopPosition = StartingTopPosition;

The four arguments are the four sides of the table relative to bottom left corner and in user units. If on the first page the table-top position is not at the top of the page set RowTopPosition to the starting top position. On subsequent pages the table will always start at the top. If TableArea is not specified, the library will set it to default page size less one inch margin.

Divide the table width into columns.

// divide table area width into columns
StockTable.SetColumnWidth(Width1, Width2, Width3, ...);

The number of arguments is the number of columns. The table width less total border lines will be divided in proportion to these arguments.

Once the number of columns is set with SetColumnWidth method the library creates two PdfTableCell arrays. One array for header cells and one array for data cells.

Rows and columns of the data table can be separated by border lines. Border lines properties are defined by PdfTableBorder and PdfTableBorderStyle. There are four horizontal border lines: TopBorder, BottomBorder, HeaderHorBorder between the header row and first data row and CellHorBorder between data rows. There are two sets of vertical border lines: HeaderVertBorder array for vertical border lines within the header row, and CellVertBorder array for vertical border lines between columns within the data part of the table. Arrays size is the number of columns plus one. Array element zero is the table's left border. Array element Columns is the table's right border. All other elements are lines separating columns. Each of these lines can be defined individually. There are methods to define all border lines at once or define each individual border line.

Methods to define all border lines:

// clear all border lines
Table.Borders.ClearAllBorders();

// set all border lines to default values (no need to call)
// All frame lines are one point (1/72") wide
// All grid lines are 0.2 of one point wide
// All borders are black
Table.Borders.SetDefaultBorders();

// set all borders to same width and black color
Table.Borders.SetAllBorders(Double Width);

// set all borders to same width and a specified color
Table.Borders.SetAllBorders(Double Width, Color LineColor);

// set all borders to one width and all grid lines to another width all lines are black
Table.Borders.SetAllBorders(Double FrameWidth, Double GridWidth);

// set all borders to one width and color and all grid lines to another width and color
Table.Borders.SetAllBorders(Double FrameWidth, Color FrameColor, Double GridWidth, Color GridColor);

// set all frame borders to same width and black color and clear all grid lines
Table.Borders.SetFrame(Double Width);

// set all frame borders to same width and a specified color and clear all grid lines
Table.Borders.SetFrame(Double Width, Color LineColor);

Each horizontal border line can be cleared or set. The example is for top border line:

// clear border
Table.Borders.ClearTopBorder();

// set border with default color set to black
// Zero width means one pixel of the output device.
Table.Borders.SetTopBorder(Double LineWidth);

// set border
Table.Borders.SetTopBorder(Double LineWidth, Color LineColor);

Each vertical border line can be cleared or set. The example is for cell's vertical border lines:

// clear border
Table.Borders.ClearCellVertBorder(Int32 Index);

// set border with default color set to black
Table.Borders.SetCellVertBorder(Int32 Index, Double LineWidth);

// set border
Table.Borders.SetCellVertBorder(Int32 Index, Double LineWidth, Color LineColor);

Set other optional table properties. The values given in the example below are the defaults.

// header on each page
HeaderOnEachPage = true;

// minimum row height
MinRowHeight = 0.0;

Table information is processed one row at a time. Each row is made of cells. One cell per column. The display of cell's information is controlled by PdfTableStyle class. There are about 20 style properties. For the complete list view the source code or the help file. Some of these styles are specific to the type of information to be displayed. Here is an example

// make some changes to default header style
Table.DefaultHeaderStyle.Alignment = ContentAlignment.BottomRight;

// create private style for header first column
Table.Header[0].Style = Table.HeaderStyle;
Table.Header[0].Style.Alignment = ContentAlignment.MiddleLeft;

// load header value
Table.Header[0].Value = "Date";

// make some changes to default cell style
Table.DefaultCellStyle.Alignment = ContentAlignment.MiddleRight;
Table.DefaultCellStyle.Format = "#,##0.00";

// create private style for date column
Table.Cell[0].Style = StockTable.CellStyle;
Table.Cell[0].Style.Alignment = ContentAlignment.MiddleLeft;
Table.Cell[0].Style.Format = null;

After initialization is done it is time to display the data. The example below is from TableExample.cs. It is a table of stock prices. There are 6 columns.

// open stock daily price
StreamReader Reader = new StreamReader("SP500.csv");

// ignore header
Reader.ReadLine();

// read all daily prices
for(;;)
	{
	String TextLine = Reader.ReadLine();
	if(TextLine == null) break;

	String[] Fld = TextLine.Split(new Char[] {','});

	Table.Cell[ColDate].Value = Fld[ColDate];
	Table.Cell[ColOpen].Value = Double.Parse(Fld[ColOpen], NFI.PeriodDecSep);
	Table.Cell[ColHigh].Value = Double.Parse(Fld[ColHigh], NFI.PeriodDecSep);
	Table.Cell[ColLow].Value = Double.Parse(Fld[ColLow], NFI.PeriodDecSep);
	Table.Cell[ColClose].Value = Double.Parse(Fld[ColClose], NFI.PeriodDecSep);
	Table.Cell[ColVolume].Value = Int32.Parse(Fld[ColVolume]);
	StockTable.DrawRow();
	}

StockTable.Close();

The DrawRow(NewPage) method has an optional argument Boolean NewPage = false. The default value is false. If you want the next row to be printed at the top of the next page, set the argument to true.

Interactive features example.

// set cell number 6 with web link
BookList.Cell[6].WebLink = WebLinkString;

// another way to set weblink
BookList.Cell[6].AnnotAction = new AnnotWebLink(WebLinkString);

// set cell with document link to chapter 3
BookList.Cell[6].AnnotAction = new AnnotLinkAction("Chapter3");

// play video
PdfDisplayMedia Omega = new PdfDisplayMedia(PdfEmbeddedFile.CreateEmbeddedFile(Document, "Omega.mp4"));
BookList.Cell[6].AnnotAction = new AnnotDisplayMedia(Omega);

// play audio
PdfDisplayMedia RingSound = new PdfDisplayMedia(PdfEmbeddedFile.CreateEmbeddedFile(Document, "Ring01.wav"));
BookList.Cell[6].AnnotAction = new AnnotDisplayMedia(RingSound);

// allow user to save or view embedded file
PdfEmbeddedFile EmbeddedFile = PdfEmbeddedFile.CreateEmbeddedFile(Document, "BookList.txt");
BookList.Cell[6].AnnotAction = new AnnotFileAttachment(EmbeddedFile, FileAttachIcon.NoIcon);

For more examples of data table source code look into ArticleExample.cs and TableExample.cs. For more detail documentation of PdfTable, PdfTableCell, PdfTableStyle and PdfTableBorder classes look into PdfFileWriter.chm help file.