MiniGUI API Reference (MiniGUI-Threads)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Data Structures | Macros | Typedefs | Functions
Text output functions

Data Structures

struct  _DTFIRSTLINE
 

Macros

#define GetTextCharacterExtra(hdc)   GetDCAttr (hdc, DC_ATTR_CHAR_EXTRA)
 Retrieves the current intercharacter spacing for the DC. More...
 
#define GetTextAboveLineExtra(hdc)   GetDCAttr (hdc, DC_ATTR_ALINE_EXTRA)
 Retrieves the current spacing above line for the DC. More...
 
#define GetTextBellowLineExtra(hdc)   GetDCAttr (hdc, DC_ATTR_BLINE_EXTRA)
 Retrieves the current spacing bellow line for the DC. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#define GetTextAlign(hdc)   GetDCAttr (hdc, DC_ATTR_TEXT_ALIGN)
 Retrieves the current text-alignment flags of a DC. More...
 
#define SetTextAlign(hdc, ta_flags)   SetDCAttr (hdc, DC_ATTR_TEXT_ALIGN, (DWORD)ta_flags)
 Sets text-alignment flags of a DC. More...
 
#define TextOut(hdc, x, y, text)   TextOutLen (hdc, x, y, text, -1)
 Outputs text. More...
 
#define TabbedTextOut(hdc, x, y, text)   TabbedTextOutLen (hdc, x, y, text, -1)
 Outputs formatted text. More...
 
#define DrawText(hdc, text, n, rc, format)   DrawTextEx2 (hdc, text, n, rc, 0, format, NULL)
 Draws a formatted text in a rectangle. More...
 
#define DrawTextEx(hdc, text, n, rc, indent, format)   DrawTextEx2 (hdc, text, n, rc, indent, format, NULL)
 Draws a formatted text in a rectangle. More...
 

Typedefs

typedef struct _DTFIRSTLINE DTFIRSTLINE
 

Functions

MG_EXPORT int GUIAPI GetFontHeight (HDC hdc)
 Retrieves the height of the current logical font in a DC. More...
 
MG_EXPORT int GUIAPI GetMaxFontWidth (HDC hdc)
 Retrieves the maximal character width of the current logical font in a DC. More...
 
MG_EXPORT int GUIAPI GetTextExtent (HDC hdc, const char *spText, int len, SIZE *pSize)
 Computes the output extent of a string of text. More...
 
MG_EXPORT int GUIAPI GetTabbedTextExtent (HDC hdc, const char *spText, int len, SIZE *pSize)
 Computes the output extent of a formatted text. More...
 
MG_EXPORT int GUIAPI TextOutLen (HDC hdc, int x, int y, const char *spText, int len)
 Outputs a string of text. More...
 
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. More...
 
MG_EXPORT int GUIAPI TabbedTextOutLen (HDC hdc, int x, int y, const char *spText, int len)
 Outputs a formatted text. More...
 
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. More...
 
MG_EXPORT void GUIAPI GetLastTextOutPos (HDC hdc, POINT *pt)
 Retrieves the last text output position. More...
 
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. More...
 

Detailed Description

Macro Definition 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 7265 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 7276 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 6849 of file gdi.h.

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

Retrieves the current text-alignment flags of a DC.

Parameters
hdcThe 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 6952 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 6857 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 6841 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 6875 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
hdcThe device context.
ta_flagsThe 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 7010 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 6884 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 6866 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 7142 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 7132 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
hdcThe device context.
pTextThe formatted text.
nCountThe length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
pRectThe output rectangle.
nIndentThe indent value of the first line.
nFormatThe 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
firstlineIf 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;
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
hdcThe 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
hdcThe device context.
ptThe 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
hdcThe 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
hdcThe device context.
spTextThe pointer to the string of text.
lenThe length of the text.
pSizeThe 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
hdcThe device context.
spTextThe pointer to the string of text.
lenThe length of the text.
pSizeThe 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
hdcThe device context.
xx,y: The output start position.
yx,y: The output start position.
spTextThe formatted text.
nCountThe length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
nTabPositionsThe length of the array of the tab-stop positions.
pTabPositionsThe array of the tab-stop positions.
nTabOriginThe 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
hdcThe device context.
xx,y: The output start position.
yx,y: The output start position.
spTextThe formatted text.
lenThe 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
hdcThe device context.
xx,y: The output start position.
yx,y: The output start position.
spTextThe string of the text.
lenThe 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
hdcThe device context.
xx,y: The output start position.
yx,y: The output start position.
mtextThe string of the text.
lenThe length of the text. If it is less than 0, MiniGUI will treat it as a null-terminated string.
max_extentThe max extent of output text.
Returns
The output width of the text.
See also
TextOutLen