Text output functions
[GDI functions]

Data Structures

struct _DTFIRSTLINE

Defines

#define GetTextCharacterExtra(hdc) GetDCAttr (hdc, DC_ATTR_CHAR_EXTRA)
Retrieves the current intercharacter spacing for the DC.
#define GetTextAboveLineExtra(hdc) GetDCAttr (hdc, DC_ATTR_ALINE_EXTRA)
Retrieves the current spacing above line for the DC.
#define GetTextBellowLineExtra(hdc) GetDCAttr (hdc, DC_ATTR_BLINE_EXTRA)
Retrieves the current spacing bellow line for the DC.
#define SetTextCharacterExtra(hdc, extra) SetDCAttr (hdc, DC_ATTR_CHAR_EXTRA, (DWORD) extra)
Sets the intercharacter spacing for the DC and returns the old spacing value.
#define SetTextAboveLineExtra(hdc, extra) SetDCAttr (hdc, DC_ATTR_ALINE_EXTRA, (DWORD) extra)
Sets the spacing above line for the DC and returns the old value.
#define SetTextBellowLineExtra(hdc, extra) SetDCAttr (hdc, DC_ATTR_BLINE_EXTRA, (DWORD) extra)
Sets the spacing bellow line for the DC and returns the old value.
#define GetTextAlign(hdc) GetDCAttr (hdc, DC_ATTR_TEXT_ALIGN)
Retrieves the current text-alignment flags of a DC.
#define SetTextAlign(hdc, ta_flags) SetDCAttr (hdc, DC_ATTR_TEXT_ALIGN, (DWORD)ta_flags)
Sets text-alignment flags of a DC.
#define TextOut(hdc, x, y, text) TextOutLen (hdc, x, y, text, -1)
Outputs text.
#define TabbedTextOut(hdc, x, y, text) TabbedTextOutLen (hdc, x, y, text, -1)
Outputs formatted text.
#define DrawText(hdc, text, n, rc, format) DrawTextEx2 (hdc, text, n, rc, 0, format, NULL)
Draws a formatted text in a rectangle.
#define DrawTextEx(hdc, text, n, rc, indent, format) DrawTextEx2 (hdc, text, n, rc, indent, format, NULL)
Draws a formatted text in a rectangle.

Typedefs

typedef struct _DTFIRSTLINE DTFIRSTLINE

Functions

MG_EXPORT int GUIAPI GetFontHeight (HDC hdc)
Retrieves the height of the current logical font in a DC.
MG_EXPORT int GUIAPI GetMaxFontWidth (HDC hdc)
Retrieves the maximal character width of the current logical font in a DC.
MG_EXPORT int GUIAPI GetTextExtent (HDC hdc, const char *spText, int len, SIZE *pSize)
Computes the output extent of a string of text.
MG_EXPORT int GUIAPI GetTabbedTextExtent (HDC hdc, const char *spText, int len, SIZE *pSize)
Computes the output extent of a formatted text.
MG_EXPORT int GUIAPI TextOutLen (HDC hdc, int x, int y, const char *spText, int len)
Outputs a string of text.
MG_EXPORT int GUIAPI TextOutOmitted (HDC hdc, int x, int y, const char *mtext, int len, int max_extent)
Outputs a string of text with omitted format.
MG_EXPORT int GUIAPI TabbedTextOutLen (HDC hdc, int x, int y, const char *spText, int len)
Outputs a formatted text.
MG_EXPORT int GUIAPI TabbedTextOutEx (HDC hdc, int x, int y, const char *spText, int nCount, int nTabPositions, int *pTabPositions, int nTabOrigin)
Writes a character string at a specified location, expanding tabs to the values specified in an anrry of tab-stop positions.
MG_EXPORT void GUIAPI GetLastTextOutPos (HDC hdc, POINT *pt)
Retrieves the last text output position.
MG_EXPORT int GUIAPI DrawTextEx2 (HDC hdc, const char *pText, int nCount, RECT *pRect, int nIndent, UINT nFormat, DTFIRSTLINE *firstline)
Draws a formatted text in a rectangle.

Define Documentation

#define DrawText	(	hdc,
		text,
		n,
		rc,
		format	)	DrawTextEx2 (hdc, text, n, rc, 0, format, NULL)

Draws a formatted text in a rectangle.

Defined as a macro calling DrawTextEx2 passing nIndent as 0 and firstline as NULL.

See also:: DrawTextEx2

Definition at line 7248 of file gdi.h.

#define DrawTextEx	(	hdc,
		text,
		n,
		rc,
		indent,
		format	)	DrawTextEx2 (hdc, text, n, rc, indent, format, NULL)

Draws a formatted text in a rectangle.

Defined as a macro calling DrawTextEx2 passing firstline as NULL.

See also:: DrawTextEx2

Definition at line 7259 of file gdi.h.

#define GetTextAboveLineExtra ( hdc ) GetDCAttr (hdc, DC_ATTR_ALINE_EXTRA)

Retrieves the current spacing above line for the DC.

See also:: SetTextAboveLineExtra

Definition at line 6832 of file gdi.h.

#define GetTextAlign ( hdc ) GetDCAttr (hdc, DC_ATTR_TEXT_ALIGN)

Retrieves the current text-alignment flags of a DC.

Parameters:

hdc

The device context.

Returns:: The return value is one or more of the following values:

TA_TOP
Specifies alignment of the x-axis and the top of the bounding rectangle.
TA_BASELINE
Specifies alignment of the x-axis and the baseline of the chosen font within the bounding rectangle.
TA_BOTTOM
Specifies alignment of the x-axis and the bottom of the bounding rectangle.
TA_LEFT
Specifies alignment of the y-axis and the left side of the bounding rectangle.
TA_RIGHT
Specifies alignment of the y-axis and the right side of the bounding rectangle.
TA_CENTER
Specifies alignment of the y-axis and the center of the bounding rectangle. Note that MiniGUI does not support TA_CENTER so far.
TA_NOUPDATECP
Specifies that the current position is not updated.
TA_UPDATECP
Specifies that the current position is updated.

Note:: The text-alignment flags determine how the TextOut, TabbedTextOut, and TabbedTextOutEx functions align a string of text in relation to the string's starting point. The text-alignment flags are not necessarily single-bit flags and may be equal to 0. To test whether a flag is set, an application should follow these steps:

1. Apply the bitwise OR operator to the flag and its related flags, grouped as follows:

TA_LEFT, TA_RIGHT, TA_CENTER (TA_X_MASK)
TA_BASELINE, TA_BOTTOM, and TA_TOP (TA_Y_MASK)
TA_NOUPDATECP and TA_UPDATECP (TA_CP_MASK)

2. Apply the bitwise-AND operator to the result and the return value of GetTextAlign.

3. Test for the equality of this result and the flag.

See also:: SetTextAlign

Definition at line 6935 of file gdi.h.

#define GetTextBellowLineExtra ( hdc ) GetDCAttr (hdc, DC_ATTR_BLINE_EXTRA)

Retrieves the current spacing bellow line for the DC.

See also:: SetTextBellowLineExtra

Definition at line 6840 of file gdi.h.

#define GetTextCharacterExtra ( hdc ) GetDCAttr (hdc, DC_ATTR_CHAR_EXTRA)

Retrieves the current intercharacter spacing for the DC.

See also:: SetTextCharacterExtra

Definition at line 6824 of file gdi.h.

#define SetTextAboveLineExtra	(	hdc,
		extra		)	SetDCAttr (hdc, DC_ATTR_ALINE_EXTRA, (DWORD) extra)

Sets the spacing above line for the DC and returns the old value.

See also:: GetTextAboveLineExtra

Definition at line 6858 of file gdi.h.

#define SetTextAlign	(	hdc,
		ta_flags		)	SetDCAttr (hdc, DC_ATTR_TEXT_ALIGN, (DWORD)ta_flags)

Sets text-alignment flags of a DC.

Parameters:

	hdc	The device context.
	ta_flags	The flags specify the relationship between a point and a rectangle that bounds the text. The point can be either the current position or coordinates specified by a text-output function. The rectangle that bounds the text is defined by the adjacent character cells in the text string. The ta_flags parameter can be one or more flags from the following three categories. Choose only one flag from each category.

The first category affects text alignment in the x-direction:

TA_LEFT
Aligns the point with the left side of the bounding rectangle. This is the default setting.
TA_RIGHT
Aligns the point with the right side of the bounding rectangle.
TA_CENTER
Aligns the point with the horizontal center of the bounding rectangle. Note that MiniGUI does not support TA_CENTER so far.

The second category affects text alignment in the y-direction:

TA_BASELINE
Aligns the point with the base line of the chosen font.
TA_BOTTOM
Aligns the point with the bottom of the bounding rectangle.
TA_TOP
Aligns the point with the top of the bounding rectangle. This is the default setting.

The third category determines whether the current position is updated when text is written:

TA_NOUPDATECP
Does not update the current position after each call to a text-output function. This is the default setting.
TA_UPDATECP
Updates the current x-position after each call to a text-output function. The new position is at the right side of the bounding rectangle for the text. When this flag is set, the coordinates specified in calls to the TextOut function are ignored.

Returns:: The previous text-alignment setting, if successful. The low-order word contains the horizontal setting and the high-order word contains the vertical setting; otherwise 0.

Note:: The TextOut, TabbedTextOut, and TabbedTextOutEx functions use these flags when positioning a string of text on a DC. The flags specify the relationship between a specific point and a rectangle that bounds the text. The coordinates of this point are passed as parameters to the TextOut function. The rectangle that bounds the text is formed by the adjacent character cells in the text string.

See also:: GetTextAlign

Definition at line 6993 of file gdi.h.

#define SetTextBellowLineExtra	(	hdc,
		extra		)	SetDCAttr (hdc, DC_ATTR_BLINE_EXTRA, (DWORD) extra)

Sets the spacing bellow line for the DC and returns the old value.

See also:: GetTextBellowLineExtra

Definition at line 6867 of file gdi.h.

#define SetTextCharacterExtra	(	hdc,
		extra		)	SetDCAttr (hdc, DC_ATTR_CHAR_EXTRA, (DWORD) extra)

Sets the intercharacter spacing for the DC and returns the old spacing value.

See also:: GetTextCharacterExtra

Definition at line 6849 of file gdi.h.

#define TabbedTextOut	(	hdc,
		x,
		y,
		text	)	TabbedTextOutLen (hdc, x, y, text, -1)

Outputs formatted text.

Defined as a macro calling TabbedTextOutLen passing len as -1.

See also:: TextOutLen

Definition at line 7125 of file gdi.h.

#define TextOut	(	hdc,
		x,
		y,
		text	)	TextOutLen (hdc, x, y, text, -1)

Outputs text.

Defined as a macro calling TextOutLen passing len as -1.

See also:: TextOutLen

Definition at line 7115 of file gdi.h.

Typedef Documentation

typedef struct _DTFIRSTLINE DTFIRSTLINE

First line information of DrawTextEx2

Function Documentation

int GUIAPI DrawTextEx2	(	HDC	hdc,
		const char *	pText,
		int	nCount,
		RECT *	pRect,
		int	nIndent,
		UINT	nFormat,
		DTFIRSTLINE *	firstline
	)

Draws a formatted text in a rectangle.

This function draws formatted text (pText) in the specified rectangle (pRect). It formats the text according to the specified method (through nFormat, including expanding tabs, justifying characters, breaking lines, and so forth).

Parameters:

	hdc	The device context.
	pText	The formatted text.
	nCount	The length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
	pRect	The output rectangle.
	nIndent	The indent value of the first line.
	nFormat	The methods used to format the text. MiniGUI support the following method to format text so far:

DT_TOP
Top-justifies text (single line only).
DT_LEFT
Aligns text to the left.
DT_CENTER
Centers text horizontally in the rectangle.
DT_RIGHT
Aligns text to the right.
DT_VCENTER
Centers text vertically (single line only).
DT_BOTTOM
Justify the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE.
DT_WORDBREAK
Break words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the the pRect parameter. A carriage return or linefeed also breaks the line.
DT_CHARBREAK
Break characters. Lines are automatically broken between characters if a character would extend past the edge of the rectangle specified by the the pRect parameter. A carriage return or linefeed also breaks the line. DT_CHARBREAK will override DT_WORDBREAK.
DT_SINGLELINE
Display text on the single line only. Carriage returns and linefeeds do not break the line.
DT_EXPANDTABS
Expands tab characters. The default number of character per tab is eight.
DT_TABSTOP
Set tab stops. Bits 15-8 (high-order byte of the low-order word) of the uForma parameter specify the number of characters for each tab. The default number of characters per tab is eight.
DT_NOCLIP
Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.
DT_CALCRECT
Determines the width and the height of the rectangle. If there are multiple lines of text, DrawText uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.

Parameters:

firstline

If not null, DrawTextEx2 will only calculate the first line will be output in the rectangle, and return the number of the characters and the output width.

Returns:: The output height of the formatted text.

See also:: DrawText

Example:

void OnModeDrawText (HDC hdc)
{
    RECT rc1, rc2, rc3, rc4;
    const char* szBuff1 = "This is a good day. \n"
            "This text is drawn by calling DrawText.";
    const char* szBuff2 = "This is a good day. \n"
            "This text is drawn by calling DrawText.";
    const char* szBuff3 = "Single line text, center.";
    const char* szBuff4 = 
            "This text is drawn by calling DrawText.";

    rc1.left = 1; rc1.top  = 1; rc1.right = 401; rc1.bottom = 101;
    rc2.left = 0; rc2.top  = 110; rc2.right = 401; rc2.bottom = 351;
    rc3.left = 0; rc3.top  = 361; rc3.right = 401; rc3.bottom = 451;
    rc4.left = 0; rc4.top  = 461; rc4.right = 401; rc4.bottom = 551;

    SetBkColor (hdc, COLOR_lightwhite);

    Rectangle (hdc, rc1.left, rc1.top, rc1.right, rc1.bottom);
    Rectangle (hdc, rc2.left, rc2.top, rc2.right, rc2.bottom);
    Rectangle (hdc, rc3.left, rc3.top, rc3.right, rc3.bottom);
    Rectangle (hdc, rc4.left, rc4.top, rc4.right, rc4.bottom);

    InflateRect (&rc1, -1, -1);
    InflateRect (&rc2, -1, -1);
    InflateRect (&rc3, -1, -1);
    InflateRect (&rc4, -1, -1);

    SelectFont (hdc, logfontgb12);
    DrawText (hdc, szBuff1, -1, &rc1, DT_NOCLIP | DT_CENTER | DT_WORDBREAK);

    SelectFont (hdc, logfontgb16);
    DrawText (hdc, szBuff2, -1, &rc2, DT_NOCLIP | DT_RIGHT | DT_WORDBREAK);

    SelectFont (hdc, logfontgb24);
    DrawText (hdc, szBuff3, -1, &rc3, DT_NOCLIP | DT_SINGLELINE | DT_CENTER | DT_VCENTER);

    SelectFont (hdc, logfontgb16);
    DrawTextEx (hdc, szBuff4, -1, &rc4, 32, DT_NOCLIP | DT_LEFT | DT_WORDBREAK);
}

int GUIAPI GetFontHeight ( HDC hdc )

Retrieves the height of the current logical font in a DC.

This function retrieves the height of the current logical font in the DC hdc.

Parameters:

hdc

The device context.

Returns:: The height of the current logical font.

See also:: GetMaxFontWidth

void GUIAPI GetLastTextOutPos	(	HDC	hdc,
		POINT *	pt
	)

Retrieves the last text output position.

Parameters:

	hdc	The device context.
	pt	The last text output position will be returned through this pointer.

int GUIAPI GetMaxFontWidth ( HDC hdc )

Retrieves the maximal character width of the current logical font in a DC.

This function retrieves the maximal character width of the current logical font in the DC hdc.

Parameters:

hdc

The device context.

Returns:: The maximal character width of the current logical font.

See also:: GetFontHeight

int GUIAPI GetTabbedTextExtent	(	HDC	hdc,
		const char *	spText,
		int	len,
		SIZE *	pSize
	)

Computes the output extent of a formatted text.

This function computes the output extent of the formatted text (spText) with length of len. This function returns the extent in a SIZE struct pointed to by pSize and the width of text as the return value. The output extent will be affected by the default tab size if there are some TAB characters in the text.

Parameters:

	hdc	The device context.
	spText	The pointer to the string of text.
	len	The length of the text.
	pSize	The output extent will be returned through this buffer.

Returns:: The width of the text in baseline direction.

See also:: GetTextExtent

int GUIAPI GetTextExtent	(	HDC	hdc,
		const char *	spText,
		int	len,
		SIZE *	pSize
	)

Computes the output extent of a string of text.

This function computes the output extent of the text (spText) with length of len. This function returns the extent in a SIZE struct pointed to by pSize and the width of text as the return value.

Parameters:

	hdc	The device context.
	spText	The pointer to the string of text.
	len	The length of the text.
	pSize	The output extent will be returned through this buffer.

Returns:: The width of the text in baseline direction.

See also:: GetTabbedTextExtent

int GUIAPI TabbedTextOutEx	(	HDC	hdc,
		int	x,
		int	y,
		const char *	spText,
		int	nCount,
		int	nTabPositions,
		int *	pTabPositions,
		int	nTabOrigin
	)

Writes a character string at a specified location, expanding tabs to the values specified in an anrry of tab-stop positions.

This function writes the string spText with length of nCount at a specified locations, expanding tabs to the value spcified in the array pTabPositions of tab-stop positions. The output will start a new line if there is a line feed character '
' in the text.

Parameters:

	hdc	The device context.
	x	x,y: The output start position.
	y	x,y: The output start position.
	spText	The formatted text.
	nCount	The length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
	nTabPositions	The length of the array of the tab-stop positions.
	pTabPositions	The array of the tab-stop positions.
	nTabOrigin	The origin of the tab-stops.

Returns:: The output width of the text.

See also:: TabbedTextOutLen

int GUIAPI TabbedTextOutLen	(	HDC	hdc,
		int	x,
		int	y,
		const char *	spText,
		int	len
	)

Outputs a formatted text.

This function outputs the formatted text spText with length of len at (x,y). This function returns the width of text. The output will start a new line if there is a line feed character '
' in the text. The output will be affected by the default tab size if there are some TAB characters in the text.

Parameters:

	hdc	The device context.
	x	x,y: The output start position.
	y	x,y: The output start position.
	spText	The formatted text.
	len	The length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.

Returns:: The output width of the text.

See also:: TextOutLen

int GUIAPI TextOutLen	(	HDC	hdc,
		int	x,
		int	y,
		const char *	spText,
		int	len
	)

Outputs a string of text.

This function outputs the text spText with length of len at a (x,y). This function returns the width of text.

Parameters:

	hdc	The device context.
	x	x,y: The output start position.
	y	x,y: The output start position.
	spText	The string of the text.
	len	The length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.

Returns:: The output width of the text.

See also:: TabbedTextOutLen

int GUIAPI TextOutOmitted	(	HDC	hdc,
		int	x,
		int	y,
		const char *	mtext,
		int	len,
		int	max_extent
	)

Outputs a string of text with omitted format.

This function outputs the text mtext with length of len at a (x,y) with omitted format, if width of the text more than max_extent.This function returns the output width of the text.

Parameters:

	hdc	The device context.
	x	x,y: The output start position.
	y	x,y: The output start position.
	mtext	The string of the text.
	len	The length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
	max_extent	The max extent of output text.

Returns:: The output width of the text.

See also:: TextOutLen

Text output functions [GDI functions]

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

Text output functions
[GDI functions]