SetTextJustification

2.x

int SetTextJustification(hdc, nExtraSpace, cBreakChars)
HDC hdc;	/* handle of device context	*/
int nExtraSpace;	/* space to add to string	*/
int cBreakChars;	/* number of break characters in the string	*/

The SetTextJustification function adds space to the break characters in a string. An application can use the GetTextMetrics function to retrieve a font's break character.

Parameters

hdc

Identifies the device context.

nExtraSpace

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 given by this parameter is converted to the current mapping mode and rounded to the nearest device unit.

cBreakChars

Specifies the number of break characters in the line.

Return Value

The return value is 1 if the function is successful. Otherwise, it is zero.

Comments

After the SetTextJustification function is called, a call to a text-output function (for example, 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 it may be defined by a font as some other character.

The GetTextExtent function is typically used with SetTextJustification. The GetTextExtent function computes the width of a given line before alignment. An application can determine how much space to specify in the nExtraSpace parameter by subtracting the value returned by GetTextExtent from the width of the string after alignment.

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

Because rounding errors can occur during alignment, the system keeps a running error term that defines the current error. When aligning a line that contains multiple runs, GetTextExtent automatically uses this error term when it computes the extent of the next run, allowing the text-output function to blend the error into the new run. After each line has been aligned, 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 the nExtraSpace parameter set to zero.

Example

The following example writes two lines of text inside a box; one of the lines is aligned, and the other is not. The GetTextExtent function determines the width of the unaligned string. The GetTextMetrics function determines the break character that is used by the current font; this information is then used to determine how many break characters the string contains. The SetTextJustification function specifies the total amount of extra space and the number of break characters to distribute it among. After writing a line of aligned text, SetTextJustification is called again, to set the error term to zero.

POINT aPoints[5];
int iLMargin = 10, iRMargin = 10, iBoxWidth;
int cchString;
LPSTR lpszJustified = "Text to be justified in this test.";
DWORD dwExtent;
WORD wTextWidth;
TEXTMETRIC tm;
int j, cBreakChars;

aPoints[0].x = 100; aPoints[0].y =  50;
aPoints[1].x = 600; aPoints[1].y =  50;
aPoints[2].x = 600; aPoints[2].y = 200;
aPoints[3].x = 100; aPoints[3].y = 200;
aPoints[4].x = 100; aPoints[4].y =  50;

Polyline(hdc, aPoints, sizeof(aPoints) / sizeof(POINT));

TextOut(hdc, 100 + iLMargin, 100, "Unjustified text.", 17);
cchString = lstrlen(lpszJustified);
dwExtent = GetTextExtent(hdc, lpszJustified, cchString);
wTextWidth = LOWORD(dwExtent);

iBoxWidth = aPoints[1].x - aPoints[0].x;
GetTextMetrics(hdc, &tm);



for (cBreakChars = 0, j = 0; j < cchString; j++)
    if (*(lpszJustified + j) == (char) tm.tmBreakChar)
        cBreakChars++;

SetTextJustification(hdc,
    iBoxWidth - wTextWidth - (iLMargin + iRMargin),
    cBreakChars);

TextOut(hdc, 100 + iLMargin, 150, lpszJustified, cchString);

SetTextJustification(hdc, 0, 0);     /* clears error term */