IDWriteTextLayout interface

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

The IDWriteTextLayout interface has these methods.

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



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

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Header

Dwrite.h

Library

Dwrite.lib

DLL

Dwrite.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft