CDC::SetTextJustification

Syntax

int SetTextJustification( int nBreakExtra, int nBreakCount );

Parameters

nBreakExtra

Specifies the total extra space to be added to the line of text (in logical units). If the current mapping mode is not MM_TEXT, the value given by this parameter is converted to the current mapping mode and rounded to the nearest device unit.

nBreakCount

Specifies the number of break characters in the line.

Remarks

Adds space to the break characters in a string. An application can use GetTextMetrics to retrieve a font's break character.

After calling the SetTextJustification member function, a call to TextOut distributes the specified extra space evenly among the specified number of break characters. The break character is usually the space character (ASCII 32), but may be defined by a font as some other character.

The function GetTextExtent is typically used with SetTextJustification. GetTextExtent computes the width of a given line before justification. This width is compared to the width of the line after justification to determine how much space to add to the line.

The SetTextJustification function can be used to justify a line that contains multiple runs in different fonts. In this case, the line must be created piecemeal by justifying and writing each run separately.

Because rounding errors can occur during justification, the system keeps a running error term that defines the current error. When justifying a line that contains multiple runs, GetTextExtent automatically uses this error term when it computes the extent of the next run. This allows the text-output function to blend the error into the new run.

After each line has been justified, this error term must be cleared to prevent it from being incorporated into the next line. The term can be cleared by calling SetTextJustification with nBreakExtra set to 0.

Return Value

One if the function is successful; otherwise 0.