Upgrade your Internet Experience
Microsoft.com
Welcome Sign in
Windows Developer Center
Click to Rate and Give Feedback
MSDN
MSDN Library
DirectWrite
Interfaces
IDWriteTextLayout
IDWriteTextLayout Interface

The IDWriteTextLayout interface represents a block of text after it has been fully analyzed and formatted.

Methods

The IDWriteTextLayout interface inherits from IDWriteTextFormat.

In addition, IDWriteTextLayout defines the following methods.

MethodDescription

Draw

Draws text using the specified client drawing context.

GetClusterMetrics

Retrieves logical properties and measurements of each glyph cluster.

DetermineMinWidth

Determines the minimum possible width the layout can be set to without breaking between the characters of whole words.

GetDrawingEffect

Gets the application-defined drawing effect at the specified text position.

GetFontCollection

Gets the font collection associated with the text at the specified position.

GetFontFamilyName

Copies the font family name of the text at the specified position.

GetFontFamilyNameLength

Gets the length of the font family name at the current position.

GetFontSize

Gets the font em height of the text at the specified position.

GetFontStretch

Gets the font stretch of the text at the specified position.

GetFontStyle

Gets the font style (also known as slope) of the text at the specified position.

GetFontWeight

Gets the font weight of the text at the specified position.

GetInlineObject

Gets the inline object at the given position.

GetLineMetrics

Retrieves the information about each individual text line of the text string.

GetLocaleName

Gets the locale name of the text at the specified position.

GetLocaleNameLength

Gets the length of the locale name of the text at the specified position.

GetMaxHeight

Gets the layout maximum height.

GetMaxWidth

Gets the layout maximum width.

GetMetrics

Retrieves overall metrics for the formatted string.

GetOverhangMetrics

Returns the overhangs of the layout, in Device Independent Pixels (DIPs), and all objects contained in it, including text glyphs and inline objects.

GetStrikethrough

Gets the strikethrough presence of the text at the specified position.

GetTypography

Gets the typography setting of the text at the specified position.

GetUnderline

Gets the underline presence of the text at the specified position.

HitTestPoint

Gets a DWRITE_HIT_TEST_METRICS structure for the specified point in the layout box. It also reports whether the point is inside the text string represented by the text layout.

HitTestTextPosition

Gets a position relative to the top left of the layout box for the specified text position, and a DWRITE_HIT_TEST_METRICS structure with the output geometry enclosing the text position.

HitTestTextRange

Gets DWRITE_HIT_TEST_METRICS structures for the specified text positions, given an initial text position and text length.

SetDrawingEffect

Sets the application-defined drawing effect.

SetFontCollection

Sets the font collection.

SetFontFamilyName

Sets null-terminated font family name for text within a specified text range.

SetFontSize

Sets the font em height for text within a specified text range.

SetFontStretch

Sets the font stretch for text within a specified text range.

SetFontStyle

Sets the font style for text within a specified text range.

SetFontWeight

Sets the font weight for text within a specified text range.

SetInlineObject

Sets the inline object.

SetLocaleName

Sets the locale name for text within a specified text range.

SetMaxHeight

Sets the layout maximum height.

SetMaxWidth

Sets the layout maximum width.

SetStrikethrough

Sets strikethrough for text within a specified text range.

SetTypography

Sets font typography features for text within a specified text range.

SetUnderline

Sets underlining for text within a specified text range.

 

Remarks

To get a reference to the IDWriteTextLayout interface, the application must call the IDWriteFactory::CreateTextLayout method, as shown in the following code. 


// Create a text layout using the text format.
if (SUCCEEDED(hr))
{
    RECT rect;
    GetClientRect(hwnd_, &rect); 
    float width  = rect.right  / dpiScaleX_;
    float height = rect.bottom / dpiScaleY_;

    hr = pDWriteFactory_->CreateTextLayout(
        wszText_,      // The string to be laid out and formatted.
        cTextLength_,  // The length of the string.
        pTextFormat_,  // The text format to apply to the string (contains font information, etc).
        width,         // The width of the layout box.
        height,        // The height of the layout box.
        &pTextLayout_  // The IDWriteTextLayout interface pointer.
        );
}

The IDWriteTextLayout interface allows the application to change the format for ranges of the text it represents, specified by a DWRITE_TEXT_RANGE structure. The following example shows how to set the font weight for a text range.


// Set the font weight to bold for the first 5 letters.
DWRITE_TEXT_RANGE textRange = {0, 4};

if (SUCCEEDED(hr))
{
    hr = pTextLayout_->SetFontWeight(DWRITE_FONT_WEIGHT_BOLD, textRange);
}

IDWriteTextLayout also provides methods for adding strikethrough, underline, and inline objects to the text.

To draw the block of text represented by an IDWriteTextLayout object, Direct2D provides the ID2D1RenderTarget::DrawTextLayout method. To draw using a custom renderer implement an IDWriteTextRenderer interface and call the IDWriteTextLayout::Draw method

DirectWrite and Direct2D

To draw a formatted string represented by an IDWriteTextLayout object, Direct2D provides the ID2D1RenderTarget::DrawTextLayout method.

Other Rendering Options

To render using a custom renderer, use the IDWriteTextLayout::Draw method, which takes a callback interface derived from IDWriteTextRenderer as an argument, as shown in the following code.


// Draw the text layout using DirectWrite and the CustomTextRenderer class.
hr = pTextLayout_->Draw(
        NULL,
        pTextRenderer_,  // Custom text renderer.
        origin.x,
        origin.y
        );

IDWriteTextRenderer declares methods for drawing a glyph run, underline, strikethrough and inline objects. It is up to the application to implement these methods. Creating a custom text renderer allows the application to apply additional effects when rendering text, such as a custom fill or outline.

Using a custom text renderer also enables you to render using another technology, such as GDI.

Requirements

Minimum supported clientWindows 7, Windows Vista with SP2 and Platform Update for Windows Vista
Minimum supported serverWindows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008
HeaderDwrite.h
LibraryDwrite.lib
DLLDwrite.dll

Send comments about this topic to Microsoft

Build date: 11/9/2009

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Layouts should not be shared by different threads      Dwayne Robinson   |   Edit   |   Show History
Being one of the higher-level mutable components, layout was designed to be a temporary object created by a UI thread and drawn by that UI thread. While two different layouts can be used on different threads, any single layout being modified by two different threads successfully is just good fortune. If you really must reuse the same exact one between threads, wrap and synchronize them. Alternately, you could create one for each thread (or, depending on your profiling results, just recreate them).
Tags What's this?: Add a tag
Flag as ContentBug
Kerning and ligation control      Dwayne Robinson   |   Edit   |   Show History

There are no explicit getters and setters to enable/disable these typographic features, but you can control them with SetTypography. By default, if no other typographic features are set, kerning (to move letters like A and V closer to each other) and basic ligation (such as 'fi') will apply. To disable them in the layout, create a typographic feature list that contains only the features you want (minus 'kern' and 'liga'), and apply it to the whole range:

// To create an empty feature list, disabling default typographic features,

// and apply it to the whole layout

DWRITE_TEXT_RANGE textRange = {0, UINT32_MAX};

ComPtr<IDWriteTypography> typoFeature;
g_DWriteFactory->CreateTypography(&typoFeature);
layout->SetTypography(typoFeature, textRange);

Some very bad fonts can actually even cause the layout process to fail (they may have invalid rules that point to nonexistant glyphs without metrics), in which case you may retry layout with typographic features explicitly disabled.

Note that even when you create an empty feature list, there are certain required features that are always applied {such as, I believe, rlig, ccmp, mark, and mkmk}. If they were not applied, it would lead to incorrect diacritic placement for decomposed Latin and Thai, and it could break joining for other languages like Arabic.

Tags What's this?: Add a tag
Flag as ContentBug
© 2010 Microsoft Corporation. All rights reserved. Terms of Use | Trademarks | Privacy Statement
Page view tracker