Control Reference > VSPrinter Control > VSPrinter Methods > AddTable Method |
Renders a table with row headers and special formatting.
[form!]VSPrinter.AddTable Format As String, Header As String, Body As String, [ HeaderShade As Variant ], [ BodyShade As Variant ], [ Append As Variant ]
The AddTable method is used to render tables. The parameters describe the table format, the contents of a header row, and the contents of the table body. VSPrinter renders the table, automatically sizing rows and breaking pages when necessary.
The parameters for the AddTable method are described below:
Format$
This parameter contains formatting information and is not printed. The formatting information describes each column using a sequence of formatting characters followed by the column width. The information for each column is delimited by the column separator character (by default a pipe ("|"), but may be modified using the TableSep property).
For example, the following string defines a table with four center-aligned, two-inch wide columns:
s$ = "^+2in|^+2in|^+2in|^+2in"
The following list shows all valid formatting characters and their effect:
Character |
Effect |
< |
Align column contents to the left |
^ |
Align column contents to the center |
> |
Align column contents to the right |
= |
Justify column contents |
+ |
Align column contents vertically to the center |
_ |
Align column contents vertically to the bottom |
* |
Align column contents according to the TextAlign property |
~ |
Prevent word wrapping on this column |
! |
Draw a vertical border to the right of the column (see also the TableBorder property) |
Column widths may be specified in twips, inches, points, millimeters, centimeters, pixels, or as a percentage of the age width. If units are not supplied, twips are used. If a width is not supplied, 0.5 inch is used as a default value. For details on using unit-aware measurements, see the Using Unit-Aware Properties topic.
Header$
This parameter contains the text to be printed on the first row of the table and after each column or page break (the header row). The text for each cell in the header row is delimited by the column separator character (by default a pipe ("|"), but may be modified using the TableSep property).
If you are appending to an existing table and would like the header to appear at the breaks but not in the beginning of the table, set the Append parameter to True.
Body$
This parameter contains the text for the table body. Cells are delimited by column separator characters, and rows are delimited by row separator characters. By default, cells pare separated by pipes ("|") and rows by semi-colons (";"), but these characters may be modified using the TableSep property.
Instead of supplying the table data as a string, you may create the table based on data from a Variant array. To do this, use the AddTableArray method.
You may also choose to supply data for individual cells separately. To do this, use the TableCell property.
HeaderShade, BodyShade (optional)
These parameters specify colors to be used for shading the cells in the header and in the body of the table. If omitted or set to zero, the cells are not shaded. If you want to use black shading, do not use zero or the vbBlack constant. Use a very dark shade of gray instead (for example, 1 or RGB(1,1,1)).
Append (optional)
Set this parameter to True if you want the Header string to appear at the top of each page, but not in the beginning of the table. This is useful if you are printing a table in parts, using several calls to the AddTable method, and don't want headers to be included between table sections.
If you are building a table in deferred mode (using the StartTable and EndTable methods), then setting the Append parameter to True adds the data to the table being build in memory. The Format and Header parameters are ignored in this case.
Aligning and indenting tables:
Tables may be aligned to the left, center, or right of the page depending on the setting of the TextAlign property. To indent a table by a specified amount, use the TableCell property with the tcIndent setting.
The vertical position of the table is determined by the CurrentY property.
Drawing borders around tables:
Tables may have borders drawn around them. To specify the type and appearance of the borders, use the TableBorder, PenColor, PenWidth, PenStyle, TablePen, TablePenLR, and TablePenTB properties.
You may also draw vertical and horizontal borders next to specific rows and columns using the TableCell property with the tcRowBorder and tcColBorder settings.
Formatting individual cells:
While measuring and rendering tables, the VSPrinter control fires the BeforeTableCell and AfterTableCell events, which allows you to change fonts and other formatting parameters while printing the table. This is the traditional method of applying custom formatting to cells.
A new and better alternative is to use the TableCell property to set the cell format, including font, back and foreground colors, alignment, and so on. This technique is efficient and easy to use.
You may also use RTF text in table cells. Just set the AutoRTF property to True and enclose the cell contents in curly brackets (for example, "{Show me \b BOLD}"), but this technique is much slower than the other alternatives.
Populating a table:
Instead of supplying the table data as a string, you may bind the table to a Variant array using the AddTableArray method, or set the contents of individual cells using the TableCell property with the tcText setting.
See also the Shaded Table example.