int SetTextJustification(hDC,nBreakExtra,nBreakCount)
This 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 the TextOut function. 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.
GetTextExtent is always used with the SetTextJustification function. The GetText-Extent 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, GetText-Extent 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.
| Parameter | Type/Description |
| hDC | HDC Identifies the device context. | |
| nBreakExtra | int 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 | int Specifies the number of break characters in the line. |
The return value specifies the outcome of the function. It is 1 if the function is successful. Otherwise, it is zero.