Home Library Learn Downloads Support Community
Sign in | United States - English | |
2 out of 2 rated this helpful - Rate this topic

IDWriteFactory::CreateTextLayout method

Applies to: desktop apps | Metro style apps

Takes a string, text format, and associated constraints, and produces an object that represents the fully analyzed and formatted result.

Syntax

Copy 
virtual HRESULT CreateTextLayout(
  [in]   const WCHAR * string,
  UINT32  stringLength,
  IDWriteTextFormat * textFormat,
  FLOAT  maxWidth,
  FLOAT  maxHeight,
  [out]  IDWriteTextLayout ** textLayout
) = 0;

Parameters

string [in]

Type: const WCHAR*

An array of characters that contains the string to create a new IDWriteTextLayout object from. This array must be of length stringLength and can contain embedded NULL characters.

stringLength

Type: UINT32

The number of characters in the string.

textFormat

Type: IDWriteTextFormat*

A pointer to an object that indicates the format to apply to the string.

maxWidth

Type: FLOAT

The width of the layout box.

maxHeight

Type: FLOAT

The height of the layout box.

textLayout [out]

Type: IDWriteTextLayout**

When this method returns, contains an address of a pointer to the resultant text layout object.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Requirements

Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008

Header
Dwrite.h

Library
Dwrite.lib

DLL
Dwrite.dll

See also

IDWriteFactory

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Pixel aligned layout modes
Layout has no SetMeasuringMode() setter, so if you want to use pixel-aligned modes DWRITE_MEASURING_MODE_GDI_CLASSIC or GDI_NATURAL (with sharper positioning but less accurate/faithful spacing), call CreateGdiCompatibleTextLayout instead. This CreateTextLayout call will set DWRITE_MEASURING_MODE_NATURAL onto the layout, using subpixel measurement and positioning.
History
Lazy layout
The implementation reserves the right to lazily lay out the content, which is desirable for performance sake, since you could call several setters on the layout before actually drawing or measuring, and re-laying the entire content every setter call would be unecessarily inefficient. Success on this function just means that the object was successfully created, not that it fully analyzed the text, formatted it, and laid out all the glyph runs.
History
Intended purpose
Layouts were intended to draw and measure UI text mostly, for things such as single/multiline labels, menus, buttons, and such, and anything else you would normally call User32 DrawText for. While they may be utilized by simple text editor controls (with support for hit-testing and cluster information), since they must be recreated and must redraw the entire text when changing the text, writing a custom layout stacked atop the lower levels would be more efficient for larger, more complex editors. Though, the layout can still play a role in larger editors, as you could use one to measure and draw the lines currently in view.
History