VPE+ Concepts and Examples

The Cursor

VPE+ maintains a positional (x, y) output cursor which initially defaults to the top left of any new page or report band. Generally, as text is output to the report document, the cursor advances accordingly. You can set or read the cursor position via properties XPos and YPos. Methods NewLine, AdvanceXPos and AdvanceYPos, CursorHome, CursorLeft, CursorTop and CursorTo all move the cursor.

Output proceeds rightward from the cursor XPos, and downward from the cursor YPos.

Line & Font Metrics

The cursor YPos represents the top of the current output line, and by default (with no extra line spacing defined) is the equivalent of property LineTop. Line spacing can be increased by adding extra space above the font line (set LineSpaceTop) and/or adding space below the font line (set LineSpaceBottom). Setting LineSpaceTop will displace the font line positional metrics downward, but will not change the LineHeight which reflects the line font only. Set both the top and bottom line spacing with the method SetLineSpacing.

The labelled metrics can all be accessed as properties or functions of the same name. Making a call to NewLine effectively advances the cursor YPos by the sum of (LineSpaceTop + LineHeight + LineSpaceBottom), and returns XPos to the leftmost position. It also restores the active tab to the first defined tab.

Cursor Font Versus Line Font

Since the active font or its size can be changed during the course of line output, the font applied at the start of a line (the line font) may be different from the font now applied at the cursor (the cursor font). Assuming that a font size change has occurred, then:

• it is the LineHeight of the line font (plus any extra line spacing, if applied) that determines how far the YPos value will be advanced with a call to NewLine.
• the YPos and LineTop values remain unchanged (the line still starts in the same place)
• the LineMiddle and LineBottom values remain unchanged (they still relate to the same line font)
• the font metrics FontTop, FontMiddle, FontBaseline and FontBottom will change (they relate to the cursor font)

Thus, a font change gives rise to two main issues:

• the effective LineHeight used to advance the YPos may not be appropriate to clear the different font sizes included in the line content
• the different sized fonts may not be aligned with respect to one another as intended

Both issues can be managed with suitable adjustments:

• you can reset the LineHeight to reflect the height of the largest font by calling ResetLineHeight after that font is applied. If appropriate, you can also force this (cursor) font to become the current line font by calling ResetLineFont (which also resets the LineHeight).
• aligning two differently size fonts is a matter of aligning a metric of one font (its top, middle, baseline or bottom) with the metric of another font. How you choose to do this is up to you. See the next section for the range of methods available to achieve the desired result.

Realigning Fonts by Line Metric

You can easily align different fonts to one another, or align fonts to given points or objects in a document. The points of reference by which you can align fonts, or line metrics, are illustrated above, and are represented by the following TLineMetric values:

• lmFontTop
• lmFontMiddle
• lmFontBaseline
• lmFontBottom
• lmLineTop
• lmLineMiddle
• lmLineBottom

By passing these metrics as AlignBy or AlignTo parameters to the various alignment methods, you can align fonts relative to one another, or to other fixed points in a document. To automatically shift the current YPos to achieve a given alignment, call one of these methods:

• AlignToCursorFont
• AlignToLineFont
• AlignToSavedFont
• AlignToYPos

To return the YPos that would achieve a given alignment, call one of these functions:

• YPosAlignToCursorFont
• YPosAlignToLineFont
• YPosAlignToSavedFont
• YPosAlignToYPos

Font and line metrics are fairly logical and predictable, but manipulating text placement can get confusing, especially when some positional function calls force changes in these metrics that may not have been anticipated. Generally this becomes an exercise in correctly recognising what cursor position, font and line height are active at any given time.