MiniGUI/doc/man3/miniguiTextOutput.3

.\" This manpage is Copyright (C) 2000 Wei Yongming
.\"                               2000 BluePoint Software
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since MiniGUI is constantly changing, this
.\" manual page may be incorrect or out-of-date. The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.TH "TextOutput" "3" "August 2000" "MiniGUI"

.SH "NAME"
TextOutput \- Text output in MiniGUI.

.SH "SYNOPSIS"
.B #include <minigui/gdi.h>
.PP
.BI "int GUIAPI GetFontHeight" "(HDC hdc);"
.br
.BI "int GUIAPI GetMaxFontWidth" "(HDC hdc);"
.PP
.BI "void GUIAPI GetTextExtent" "(HDC hdc, const char* spText, int len, SIZE* pSize);"
.br
.BI "void GUIAPI GetTabbedTextExtent" "(HDC hdc, const char* spText, int len, SIZE* pSize);"
.PP
.BI "int GUIAPI GetTextCharacterExtra" "(HDC hdc);"
.br
.BI "int GUIAPI SetTextCharacterExtra" "(HDC hdc, int extra);"
.PP
.BI "int GUIAPI GetTextAboveLineExtra" "(HDC hdc);"
.br
.BI "int GUIAPI SetTextAboveLineExtra" "(HDC hdc, int extra);"
.br
.BI "int GUIAPI GetTextBellowLineExtra" "(HDC hdc);"
.br
.BI "int GUIAPI SetTextBellowLineExtra" "(HDC hdc, int extra);"
.PP
.BI "int GUIAPI TextOutLen" "(HDC hdc, int x, int y, const char* spText, int len);"
.br
.BI "int GUIAPI TabbedTextOutLen" "(HDC hdc, int x, int y, const char* spText, int len);"
.br
.BI "int GUIAPI TabbedTextOutEx" "(HDC hdc, int x, int y, const char* spText, int nCount, int nTabPositions, int *pTabPositions, int nTabOrigin);"
.PP
.BI "void GUIAPI GetLastTextOutPos" "(HDC hdc, POINT* pt);"
.PP
.BI "int GUIAPI DrawTextEx" "(HDC hdc, const char* pText, int nCount, RECT* pRect, int nIndent, UINT nFormat);"
.SH "DESCRIPTION"
.PP
\fBGetFontHeight\fP function retrives the height of the current logical font in the DC.
.PP
\fBGetMaxFontWidth\fP function retrives the maximal character width of the current logical font in the DC.
.PP
\fBGetTextExtent\fP function computes the output extent of the text \fB(spText)\fP with length of \fBlen\fP. This function returns the extent in a SIZE struct pointed to by \fBpSize\fP and the width of text as the return value.
.PP
\fBGetTabbedTextExtent\fP function computes the output extent of the formatted text \fB(spText)\fP with length of \fBlen\fP. This function returns the extent in a SIZE struct pointed to by \fBpSize\fP 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.
.PP
\fBGetTextCharacterExtra\fP function retrives the current intercharacter spacing for the DC.
.PP
\fBSetTextCharacterExtra\fP function sets the intercharacter spacing for the DC and returns the old spacing value.
.PP
\fBGetTextAboveLineExtra\fP function retrives the current spacing above line for the DC.
.PP
\fBSetTextAboveLineExtra\fP function sets the spacing above line for the DC and returns the old value.
.PP
\fBGetTextBellowLineExtra\fP function retrives the current spacing bellow line for the DC.
.PP
\fBSetTextBellowLineExtra\fP function sets the spacing bellow line for the DC and returns the old value.
.PP
\fBTextOutLen\fP function outputs the text \fBspText\fP with length of \fBlen\fP at \fB(x, y)\fP. This function returns the width of text.
.PP
\fBTabbedTextOutLen\fP function outputs the formatted text \fBspText\fP with length of \fBlen\fP at \fB(x, y)\fP. This function returns the width of text. The output will be affected by the default tab size if there are some TAB characters in the text.
.PP
\fBTabbedTextOutEx\fP function writes a character string at a specified location, expanding tabs to the values specified in an anrry of tab-stop positions. Text is written in the currently selected font, background color, and text color.
.PP
\fBGetLastTextOutPos\fP function retrives the last text output position. All above functions and \fBDrawText\fP will affect this position.
.PP
\fBDrawTextEx\fP function draws formatted text \fB(pText)\fP in the specified rectangle \fB(pRect)\fP. It formats the text according to the specified method (through \fBnFormat\fP, including expanding tabs, justifying characters, breaking lines, and so forth). MiniGUI support the following method to format text so far:
.IP \fBDT_TOP\fP
Top-justifies text (single line only).
.IP \fBDT_LEFT\fP
Aligns text to the left.
.IP \fBDT_CENTER\fP
Centers text horizontally in the rectangle.
.IP \fBDT_RIGHT\fP
Aligns text to the right.
.IP \fBDT_VCENTER\fP
Centers text vertically (single line only).
.IP \fBDT_BOTTOM\fP
Justify the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE.
.IP \fBDT_WORDBREAK\fP
Break words. Lines are automatically broken beteween words if a word would extend past the edge of the rectangle specified by the the \fBpRect\fP parameter. A carriage return or linefeed also breaks the line.
.IP \fBDT_SINGLELINE\fP
Display text ont the single line only. Carriage returns and linefeeds do not break the line.
.IP \fBDT_EXPANDTABS\fP
Expands tab characters. The default number of character per tab is eight.
.IP \fBDT_TABSTOP\fP
Set tab stops. Bits 15-8 (hight-order byte of the low-order word) of the \fBuForma\fP parameter specify the number of characters for each tab. The default number of characters per tab is eight.
.IP \fBDT_NOCLIP\fP
Draws without clipping. \fBDrawText\fP is somewhat faster when DT_NOCLIP is used.
.IP \fBDT_CALCRECT\fP
Determines the width and the height of the rectangle. If there are multiple lines of text, \fBDrawText\fP 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, \fBDrawText\fP modifies the right side of the rectangle so that it bounds the last character in the line. In either case, \fBDrawText\fP returns the height of the formatted text but does not draw the text.

.SH "NOTE"
.PP
When you specify the length of a string, you can pass \fB-1\fP to let MiniGUI calculates the length of a NULL-terminated string.

.SH "SEE ALSO"
.BR CreateLogFont (3),
.BR SelectFont (3),
.BR GetTextExtentPoint (3),
.BR SetTextColor (3)

.SH "AUTHOR"
.PP
This manual page was edited by WEI Yongming <ymwei@minigui.org>.
If you have any problems, comments or found some bugs, please send messages to me.