D2DrawText command

Requires: Direct2D.lg32

Purpose

Draws text with a single format to the current render target.

Syntax

D2DrawText x1!, y1!, x2!, y2!, text$, format [, param] [, D2Brush][, options]

x1!, y1!, x2!, y2!	: float expression
text$	: string expression
format, param	: integer expression
D2Brush	: Object
options	: integer expression

Description

D2DrawText mimics the behavior of GFABASIC’s DrawText command and is used to draw text from a string using the font set with D2SetFont (default is DEFAULT_GUI_FONT). The coordinates x1, y1, x2, y2 specify the rectangle in which the text is drawn. The format value can be a combination of the DrawText mode constants like DT_NOCLIP, DT_LEFT, etc. Not all DT_* settings can be emulated by Direct2D. Instead of the DrawText compatible format constants you could use the D2T_* formatting constants, which are specific to D2DrawText.

Most D2T_* settings call a method (property) on the current font selection , which is a IDWriteTextFormat object (which is created by D2Font and/or D2SetFont).

The format parameter can be one or more of the following values. Depending on the format value additional information should be specified in the param argument:

D2T_LEFT(= DT_LEFT), D2T_CENTER(=DT_CENTER), D2T_RIGHT(=DT_RIGHT), D2T_JUSTIFIED	Text alignment, only one value can be specified. Invokes the IDWriteTextFormat::SetTextAlignment method.
D2T_PARTOP, D2T_PARCENTER (= DT_VCENTER), D2T_PARBOTTOM (= DT_BOTTOM)	Paragraph alignment, only one value can be specified. Invokes the IDWriteTextFormat::SetParagraphAlignment method.
D2T_TABSTOP (= DT_TABSTOP)	Sets tab stops. Set the hi-word of the additional parameter param to the number of pixels for the tab stop. Excludes the use of D2T_TRIMCHAR and D2T_TRIMWORD. Invokes the IDWriteTextFormat::SetIncrementalTabStop method.
D2T_NOCLIP (= DT_NOCLIP)	Draws the text without clipping it to the layout rectangle. This is not a property, but an option to be passed to the render target’s DrawText method. The default for D2DrawText is to clip the text. D2T_NOCLIP overrules any clipping set with the option argument.
D2T_PATH_ELLIPSES (= DT_PATH_ELLIPSIS)	Replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash. Invokes the IDWriteTextFormat::SetTrimming method. May need to be combined with D2T_NOWRAP. Cannot be combined with another trimming option.
D2T_END_ELLIPSES (= DT_END_ELLIPSIS)	Replaces characters at the end of the string with ellipses so that the result fits in the specified rectangle. Invokes the IDWriteTextFormat::SetTrimming method. May need to be combined with D2T_NOWRAP. Cannot be combined with another trimming option.
D2T_TRIMCHAR, D2T_TRIMWORD	Sets trimming for text overflowing the layout rectangle. Additional information must be specified in the extra param. The hi-word specifies the character code to use as the delimiter that signals the beginning of the portion of text to be preserved. The lo-word specifies the delimiter count, counting from the end of the text, to preserve text from. Set the param value using MakeLong(charcode, count). Invokes the IDWriteTextFormat::SetTrimming method. Cannot be combined with D2T_PATH_ELLIPSIS or D2T_END_ELLIPSIS or D2T_LINESPACING or D2T_TABSTOP.
D2T_READTOLEFT (= DT_RTLREADING), D2T_READTORIGHT	Sets the reading direction from right to left. Only one value can be specified. Invokes the IDWriteTextFormat::SetReadingDirection method.
D2T_LINESPACING	Sets the linespacing for multiple line text. Actually, sets the line height, the distance between one baseline to another. Set the lo-word of the additional parameter to specify the height in pixels. Invokes the IDWriteTextFormat::SetLineSpacing method. Cannot be combined with D2T_TRIMCHAR or D2_TRIMWORD.
D2T_NOWRAP (= DT_SINGLELINE)	Disables word wrapping, words are kept within the same line even when it overflows the layout box. Default is to wrap whole words. Invokes the IDWriteTextFormat::SetWordWrapping method. Cannot be combined with D2T_WORDWRAP.
D2T_WORDWRAP (= DT_WORDBREAK)	Sets the word wrapping option, words are broken across lines to avoid text overflowing the layout box, this is the default behavior. Invokes the IDWriteTextFormat::SetWordWrapping method. Cannot be combined with D2T_NOWRAP.
D2T_FLOWDOWN, D2T_FLOWUP, D2T_FLOWTOLEFT, D2T_FLOWTORIGHT	Sets the paragraph flow direction. Only one value can be specified. Invokes the IDWriteTextFormat::SetFlowDirection method.

The optional D2brush argument specifies a brush object to draw with. If omitted, a solid color brush based on the foreground color is used.

The optional options argument can be a combination of the DWRITE_DRAW_TEXT_OPTIONS constants (default is D2D1_DRAW_TEXT_OPTIONS_CLIP) :

D2D1_DRAW_TEXT_OPTIONS_NONE = 0x00000000	Text is snapped to pixel boundaries and not clipped.
D2D1_DRAW_TEXT_OPTIONS_NO_SNAP = 0x00000001	Do not snap the baseline of the text vertically.
D2D1_DRAW_TEXT_OPTIONS_CLIP = 0x00000002	(Default for D2DrawText) Clip the text to the content bounds. If the format parameter specifies D2T_NOCLIP (or DT_NOCLIP) this bit is cleared when the text is drawn.
D2D1_DRAW_TEXT_OPTIONS_ENABLE_COLOR_FONT = 0x00000004	Render color versions of glyphs if defined by the font.
D2D1_DRAW_TEXT_OPTIONS_DISABLE_COLOR_BITMAP_SNAPPING = 0x00000008	Bitmap origins of color glyph bitmaps are not snapped.

Example

' D2DrawText sample (dpi-unaware)

$Library "direct2d"

Global Object Win1RT

OpenW 1, 0, 0, 320, 300, ~15

Local m$() : Array m$() = "File"#10"Exit"

Menu m$() ' First create menu

Set Win1RT = D2GetRT() ' then render target

Sleep

Until Me Is Nothing

Sub Win_1_Paint

D2BeginDraw Win1RT, D2C_White

D2ForeColor = D2C_DarkMagenta

D2Box 16, 16, 100, 56

D2DrawText 16, 16, 100, 56, "Hello" #10"Direct2D", D2T_PARCENTER | D2T_CENTER

D2DrawText 16, 60, 140, 100, App.FileName, _

D2T_NOWRAP | D2T_TRIMWORD, MakeLong(Asc("\"), 2)

D2DrawText 16, 100, 140, 120, App.FileName, D2T_PATH_ELLIPSIS | D2T_NOWRAP

D2EndDraw

EndSub

Sub Win_1_ReSize

D2ResizeRT Win1RT, _X, _Y

Sub Win_1_MenuEvent(idx%)

If idx% == 1 Then Win_1.Close

Remarks

As with all drawing operations, D2DrawText must be embedded between D2BeginDraw and D2EndDraw. D2DrawText invokes the ID2D1RenderTarget::DrawText method.

Some D2T_ constants have the same value as DT_ constants used with GB's DrawText and the DT_ constants may be used instead. However, the following DT_ constants are not supported: DT_CALCRECT, DT_EDITCONTROL, DT_EXPANDTABS, DT_INTERNAL, DT_MODIFYSTRING, DT_NOFULLWIDTHCHARBREAK, DT_HIDEPREFIX, DT_NOPREFIX, DT_PREFIXONLY, DT_WORD_ELLIPSIS.

For more information on drawing text, see here.