VPE+ Concepts and Examples

PrintTab is a print method that outputs single-line text to a horizontal tab position pre-defined by the SetLineTab method. Typically, tabs are used to implement columnar style reports, but are also useful for other formatting tasks.

Example A: Defining Tab Stops

Tabs are created sequentially in the "active tab list" using SetLineTab. There is no restriction on where a tab is placed. This sample creates four tabs and saves them as "tab list #1":

Notes:

a) ClearLineTabs clears any currently defined "active tabs" in preparation for defining a new set of tabs.

b) The default left/right text margins for a tab are 0.5mm. Specifying NA leaves the left margin at its default, while the right text margin is set to 3mm.

c) ALeftPos of NA means "follow on immediately after the previous tab". For the first tab, this is taken as BandLeft.

d) PushTabList(1) saves the set of defined tabs to indexed position #1 (of 10 available positions).

You can use such a tab list on-the-fly, or you can save it for later retrieval and use. By saving the active list to an indexed position using PushTabList, you can define multiple tab lists for a report (eg in OnReportBefore). A specific list can then be automatically applied in a given report band, for example, or you can retrieve any list by index using PopTabList. A LIFO stack is also available to manage temporary tab lists.

Example B: Output to Tab Stops

A tab set relates to a given output line. With each new line, the tab set is re-initialised to the first tab. Use a call to ResetTabLine to force a reset. Every call to PrintTab then directs output to the next sequentially defined tab. PrintTab can also be directed to a specific tab stop by index, or you can skip one or more tabs with SkipTab.

Using the tab stops defined in Example A:, this code demonstrates output to line tabs:

The Code	The Output
PrintTab('1'); PrintTab('First One', tsB); PrintTab('1st'); NewLine; PrintTab('2'); PrintTab('Second Two', tsI); PrintTab('2nd'); NewLine; PrintTabSet(['3', 'Third Three', '3rd']);

Notes:

a) The first three lines sequentially output to the three defined line tabs. Newline then resets the tab line, returning the next-output to the first tab.

b) You can differentially print each tab with whatever text style you wish.

c) PrintTabSet is a shortcut method to output an array of strings to sequential tabs.

Example C: Boxing and Shading

Tab stops can be boxed, and the background shaded. Either aspect can be predefined as part of the tab definition using SetTabBox method. Settings are applied to the last defined tab, or you can target a tab by using its tab index. Alternatively, you can apply the same settings to all defined (active) tabs collectively using SetTabBoxes. This example uses the latter method to box and shade all tabs.

The Code	The Output
SetTabBoxes(pwNormal, clAqua);   ...with output code as per Example B

The various overloaded SetTabBox methods allow you to differentially set the line widths for each side of a tab box, and thus create tables with varied borders. A pen width of "NA" leaves a line unchanged (ie as previously defined) while the pen width pwNone (or 0) can be used to specify no line at all. Similarly, box shading can be differentially applied using "NA" for no change or clNone for no shading. Note also that the PrintTab method allows you to dynamically suppress the box or its shading with its DrawBox and ShadeBox parameters.

Tab boxes and their shading can be drawn on demand with methods DrawTabBox and DrawTabBoxes.

Example D: Adjusting Tabs On-the-Fly with "Bumps"

Pre-defined tabs work well in many cases - but often it is useful to dynamically tweak tab properties on-the-fly depending on report requirements. Perhaps tabbed column headings are justified differently from the subsequent column content? Or certain results need to be highlighted in a table? Or you want to apply differentially weighted lines to enhance table appearance?

This is achieved with the concept of "bumping". A tab bump is a temporary "1-off" change to tab settings made immediately before output to the target tab stop. Following output, the bump or bumps are automatically cleared, although you can also "hold" the same bumps for subsequent tabs by calling HoldTabBumps (and then clearing them yourself when ready with the ClearTabBumps method).

This example shows how you could box and highlight a specific tabbed item by bumping the box lines (BumpTabBox) and the brush colour (BumpTabBrushColour):

The Code	The Output
PrintTab('1'); PrintTab('First One', tsB); PrintTab('1st'); NewLine; PrintTab('2'); BumpTabBox(pwNormal, pwNormal, pwNormal, pwNormal); BumpTabBrush(clYellow); PrintTab('Second Two', tsI); PrintTab('2nd'); NewLine; PrintTabSet(['3', 'Third Three', '3rd']);

You can separately bump tab justification, margins, boxing (all four boundary lines independently), shading, and the pen colour and style using various BumpTab methods. There are corresponding methods to clear each bump type (or ClearTabBumps to remove all bumps).

Other Tab Features

Functions are available to return all manner of tab metrics - tab start, centre, and end positions; text start, centre, and end positions; tab width and text width; and text margins. These metrics, accessible by TabIndex, are useful when aligning other text elements or objects with tabbed output. You can retrieve and manipulate the tab object itself.