Rendering > VpeComputeSingleLineChars

[Not supported by the Community Edition]

Computes the maximum number of characters that fit in a single line of given width (i.e. horizontal space in a document). Only the first line of the supplied text is considered. Any subsequent lines are ignored.

VpeComputeSingleLineChars() accounts for the current font settings. It also allows for a left and right border line drawn at width given by the current pen size (i.e. the width passed to this method is reduced by the pen width plus a gap to account for these lines, exactly as done by VpePrintBox() and VpeWriteBox()). Typically, you would set the pen size to zero and thus use the full width for the text (i.e. no border lines drawn).

This method is useful if you wish to truncate a single line of text to fit within a given width (and not have it wrap to a further line). It is also useful for more complex text rendering tasks where there is a need for piecemeal text output. However, as a rule, the other rendering methods described in this chapter are better suited and more efficient at managing the complex layout of whole text objects.

int VpeComputeSingleLineChars(

VpeHandle hDoc,

LPCSTR text,

VpeCoord width,

int mode

)

VpeHandle hDoc

Document Handle

LPCSTR text

the text to be rendered

VpeCoord width

the width for which the number of characters is computed

int mode

the method can be used in two different modes:

Constant Name	Value	Comment
VSLC_MODE_WORD	0	Truncate the line at the last complete word that fits in the width.
VSLC_MODE_CHAR	1	Truncate the line at the last character that fits in the width.

Returns:

The number of characters in the leftmost words that fit completely within the given width (mode = VSLC_MODE_WORD) or the maximum number of leftmost characters that fit completely within the given width (mode = VSLC_MODE_CHAR) based on the currently selected font and pen size.

Remarks:

This method only works for plain text. It does not support RTF (Rich Text). There is no equivalent method for RTF.

Example:

VpeSetPenSize(hDoc, 0)

n = VpeComputeSingleLineChars(hDoc, "this is a test", 3, VSLC_MODE_WORD)

Computes which of the leftmost words in the string "this is a test" fit completely within the horizontal width of 3 cm (without border lines) using the currently selected font, and returns the number of characters (n) included in those words.