IDWriteTextLayout interface (Windows)

The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

This topic has not yet been rated - Rate this topic

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

Members

The IDWriteTextLayout interface inherits from IDWriteTextFormat. IDWriteTextLayout also has these types of members:

Methods

Methods

The IDWriteTextLayout interface has these methods.

Method	Description
DetermineMinWidth	Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
Draw	Draws text using the specified client drawing context.
GetClusterMetrics	Retrieves logical properties and measurements of each glyph cluster.
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	Get 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 specified 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 (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
GetStrikethrough	Get 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	The application calls this function passing in a specific pixel location relative to the top-left location of the layout box and obtains the information about the correspondent hit-test metrics of the text string where the hit-test has occurred. When the specified pixel location is outside the text string, the function sets the output value isInside to FALSE*.
HitTestTextPosition	The application calls this function to get the pixel location relative to the top-left of the layout box given the text position and the logical side of the position. This function is normally used as part of caret positioning of text where the caret is drawn at the location corresponding to the current text editing position. It may also be used as a way to programmatically obtain the geometry of a particular text position in UI automation.
HitTestTextRange	The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string. The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), when the buffer size of hitTestMetrics is too small to hold all the regions calculated by the function. In this situation, the function sets the output value actualHitTestMetricsCount to the number of geometries calculated. The application is responsible for allocating a new buffer of greater size and calling the function again. A good value to use as an initial value for maxHitTestMetricsCount may be calculated from the following equation: maxHitTestMetricsCount = lineCount maxBidiReorderingDepth where lineCount is obtained from the value of the output argument actualLineCount (from the function IDWriteTextLayout::GetLineLengths), and the maxBidiReorderingDepth value from the DWRITE_TEXT_METRICS* structure of the output argument textMetrics (from the function IDWriteFactory::CreateTextLayout*).
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 size in DIP units 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 text range specified by a DWRITE_TEXT_RANGE structure.
SetFontWeight	Sets the font weight for text within a text range specified by a DWRITE_TEXT_RANGE structure.
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.

C++



// 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.

C++



// 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.

C++



// 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 client	Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps \| Windows Store apps]
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps \| Windows Store apps]
Header	Dwrite.h
Library	Dwrite.lib
DLL	Dwrite.dll

Send comments about this topic to Microsoft

Build date: 11/22/2012

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

IDWriteTextLayout interface