IDWriteTextLayout interface (dwrite.h)

Article
07/27/2022

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

Inheritance

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

Methods

The IDWriteTextLayout interface has these methods.


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.GetMetrics)
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

Requirement	Value
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