IDWriteTextLayout interface

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

Methods

The IDWriteTextLayout interface has these methods.

Method Description
IDWriteTextLayout::DetermineMinWidth Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
IDWriteTextLayout::Draw Draws text using the specified client drawing context.
IDWriteTextLayout::GetClusterMetrics Retrieves logical properties and measurements of each glyph cluster.
IDWriteTextLayout::GetDrawingEffect Gets the application-defined drawing effect at the specified text position.
IDWriteTextLayout::GetFontCollection Gets the font collection associated with the text at the specified position.
IDWriteTextLayout::GetFontFamilyName Copies the font family name of the text at the specified position.
IDWriteTextLayout::GetFontFamilyNameLength Get the length of the font family name at the current position.
IDWriteTextLayout::GetFontSize Gets the font em height of the text at the specified position.
IDWriteTextLayout::GetFontStretch Gets the font stretch of the text at the specified position.
IDWriteTextLayout::GetFontStyle Gets the font style (also known as slope) of the text at the specified position.
IDWriteTextLayout::GetFontWeight Gets the font weight of the text at the specified position.
IDWriteTextLayout::GetInlineObject Gets the inline object at the specified position.
IDWriteTextLayout::GetLineMetrics Retrieves the information about each individual text line of the text string.
IDWriteTextLayout::GetLocaleName Gets the locale name of the text at the specified position.
IDWriteTextLayout::GetLocaleNameLength Gets the length of the locale name of the text at the specified position.
IDWriteTextLayout::GetMaxHeight Gets the layout maximum height.
IDWriteTextLayout::GetMaxWidth Gets the layout maximum width.
IDWriteTextLayout::GetMetrics Retrieves overall metrics for the formatted string.
IDWriteTextLayout::GetOverhangMetrics Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
IDWriteTextLayout::GetStrikethrough Get the strikethrough presence of the text at the specified position.
IDWriteTextLayout::GetTypography Gets the typography setting of the text at the specified position.
IDWriteTextLayout::GetUnderline Gets the underline presence of the text at the specified position.
IDWriteTextLayout::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.
IDWriteTextLayout::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.
IDWriteTextLayout::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.
IDWriteTextLayout::SetDrawingEffect Sets the application-defined drawing effect.
IDWriteTextLayout::SetFontCollection Sets the font collection.
IDWriteTextLayout::SetFontFamilyName Sets null-terminated font family name for text within a specified text range.
IDWriteTextLayout::SetFontSize Sets the font size in DIP units for text within a specified text range.
IDWriteTextLayout::SetFontStretch Sets the font stretch for text within a specified text range.
IDWriteTextLayout::SetFontStyle Sets the font style for text within a text range specified by a DWRITE_TEXT_RANGE structure.
IDWriteTextLayout::SetFontWeight Sets the font weight for text within a text range specified by a DWRITE_TEXT_RANGE structure.
IDWriteTextLayout::SetInlineObject Sets the inline object.
IDWriteTextLayout::SetLocaleName Sets the locale name for text within a specified text range.
IDWriteTextLayout::SetMaxHeight Sets the layout maximum height.
IDWriteTextLayout::SetMaxWidth Sets the layout maximum width.
IDWriteTextLayout::SetStrikethrough Sets strikethrough for text within a specified text range.
IDWriteTextLayout::SetTypography Sets font typography features for text within a specified text range.
IDWriteTextLayout::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 | UWP apps]
Minimum supported server Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header dwrite.h

See Also

IDWriteTextFormat