SetTextJustification

	BOOL SetTextJustification(hdc, nBreakExtra, nBreakCount)
	HDC hdc;
	int nBreakExtra;
	int nBreakCount;

The SetTextJustification function prepares GDI to justify a line of text using the justification parameters specified by the nBreakExtra and nBreakCount parameters. To justify text, GDI distributes extra pixels among break characters in a text line written by TextOut or by ExtTextOut (if no width vector is given). The break character, used to delimit words, is usually the space character (ASCII 32), but may be defined by a font as some other character. The GetTextMetrics function can be used to retrieve a font's break character.

The SetTextJustification function prepares the justification by defining the amount of space to be added. The nBreakExtra parameter specifies the total amount of space (in logical units) to be added to the line. The nBreakCount parameter specifies how many break characters are in the line. The subsequent TextOut function distributes the extra space evenly between each break character in the line.

GetTextExtentPoint is always used with the SetTextJustification function. The GetTextExtentPoint function computes the width of a given line before justification. This width must be known before an appropriate nBreakExtra value can be computed.

SetTextJustification 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, GDI keeps a running error term that defines the current error. When justifying a line that contains multiple runs, GetTextExtentPoint automatically uses this error term when it computes the extent of the next run, allowing TextOut 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 zero.

Parameters

hdc

Identifies the device context.

nBreakExtra

Specifies the total extra space (in logical units) to be added to the line of text. If the current mapping mode is not MM_TEXT, the value identified by the nBreakExtra parameter is transformed and rounded to the nearest pixel.

nBreakCount

Specifies the number of break characters in the line.

Return Value

The return value is TRUE if the function is successful. Otherwise, it is FALSE.