Class DWriteTextLayout

The IDWriteTextLayout interface represents a block of text after it has been fully analyzed and formatted. All coordinates are in device independent pixels (DIPs).

Inheritance

object

DWriteTextLayout

Implements

IDisposable

IDWriteReleasable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: JeremyAnsel.DirectX.DWrite

Assembly: JeremyAnsel.DirectX.DWrite.dll

Syntax

public sealed class DWriteTextLayout : IDisposable, IDWriteReleasable

Properties

FlowDirection

Gets or sets paragraph flow direction.

Declaration

public DWriteFlowDirection FlowDirection { get; set; }

Property Value

Type	Description
DWriteFlowDirection

Remarks

The flow direction must be perpendicular to the reading direction. Setting both to a vertical direction or both to horizontal yields DWRITE_E_FLOWDIRECTIONCONFLICTS when calling GetMetrics or Draw.

Handle

Gets an handle representing the DWrite object interface.

Declaration

public object Handle { get; }

Property Value

Type	Description
object

IncrementalTabStop

Gets or sets the incremental tab stop position.

Declaration

public float IncrementalTabStop { get; set; }

Property Value

Type	Description
float

MaxHeight

Gets or sets the layout maximum height

Declaration

public float MaxHeight { get; set; }

Property Value

Type	Description
float

MaxWidth

Gets or sets the layout maximum width

Declaration

public float MaxWidth { get; set; }

Property Value

Type	Description
float

ParagraphAlignment

Gets or sets the alignment option of paragraph relative to layout box's top and bottom edge.

Declaration

public DWriteParagraphAlignment ParagraphAlignment { get; set; }

Property Value

Type	Description
DWriteParagraphAlignment

ReadingDirection

Gets or sets the paragraph reading direction.

Declaration

public DWriteReadingDirection ReadingDirection { get; set; }

Property Value

Type	Description
DWriteReadingDirection

Remarks

The flow direction must be perpendicular to the reading direction. Setting both to a vertical direction or both to horizontal yields DWRITE_E_FLOWDIRECTIONCONFLICTS when calling GetMetrics or Draw.

TextAlignment

Gets or sets the alignment option of text relative to layout box's leading and trailing edge.

Declaration

public DWriteTextAlignment TextAlignment { get; set; }

Property Value

Type	Description
DWriteTextAlignment

WordWrapping

Gets or sets the word wrapping option.

Declaration

public DWriteWordWrapping WordWrapping { get; set; }

Property Value

Type	Description
DWriteWordWrapping

Methods

DetermineMinWidth()

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

Declaration

public float DetermineMinWidth()

Returns

Type	Description
float	float

Dispose()

Immediately releases the unmanaged resources used by the DWrite object.

Declaration

public void Dispose()

GetFontCollection()

Get the font collection.

Declaration

public DWriteFontCollection GetFontCollection()

Returns

Type	Description
DWriteFontCollection	DWriteFontCollection

GetFontCollection(uint, out DWriteTextRange)

Get the font collection where the current position is at.

Declaration

public DWriteFontCollection GetFontCollection(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	Text range to which this change applies.

Returns

Type	Description
DWriteFontCollection	DWriteFontCollection

GetFontFamilyName()

Get a copy of the font family name.

Declaration

public string GetFontFamilyName()

Returns

Type	Description
string	string

GetFontFamilyName(uint, out DWriteTextRange)

Copy the font family name where the current position is at.

Declaration

public string GetFontFamilyName(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
string	string

GetFontSize()

Gets the font em height.

Declaration

public float GetFontSize()

Returns

Type	Description
float	float

GetFontSize(uint, out DWriteTextRange)

Get the font em height where the current position is at.

Declaration

public float GetFontSize(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
float	float

GetFontStretch()

Gets the font stretch.

Declaration

public DWriteFontStretch GetFontStretch()

Returns

Type	Description
DWriteFontStretch	DWriteFontStretch

GetFontStretch(uint, out DWriteTextRange)

Get the font stretch where the current position is at.

Declaration

public DWriteFontStretch GetFontStretch(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
DWriteFontStretch	DWriteFontStretch

GetFontStyle()

Gets the font style.

Declaration

public DWriteFontStyle GetFontStyle()

Returns

Type	Description
DWriteFontStyle	DWriteFontStyle

GetFontStyle(uint, out DWriteTextRange)

Get the font style where the current position is at.

Declaration

public DWriteFontStyle GetFontStyle(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
DWriteFontStyle	DWriteFontStyle

GetFontWeight()

Gets the font weight.

Declaration

public DWriteFontWeight GetFontWeight()

Returns

Type	Description
DWriteFontWeight	DWriteFontWeight

GetFontWeight(uint, out DWriteTextRange)

Get the font weight where the current position is at.

Declaration

public DWriteFontWeight GetFontWeight(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
DWriteFontWeight	DWriteFontWeight

GetLineSpacing(out DWriteLineSpacingMethod, out float, out float)

Get line spacing.

Declaration

public void GetLineSpacing(out DWriteLineSpacingMethod lineSpacingMethod, out float lineSpacing, out float baseline)

Parameters

Type	Name	Description
DWriteLineSpacingMethod	lineSpacingMethod	How line height is determined.
float	lineSpacing	The line height, or rather distance between one baseline to another.
float	baseline	Distance from top of line to baseline.

GetLocaleName()

Get a copy of the locale name.

Declaration

public string GetLocaleName()

Returns

Type	Description
string	string

GetLocaleName(uint, out DWriteTextRange)

Get the locale name where the current position is at.

Declaration

public string GetLocaleName(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
string	string

GetMetrics()

GetMetrics retrieves overall metrics for the formatted string.

Declaration

public DWriteTextMetrics GetMetrics()

Returns

Type	Description
DWriteTextMetrics	DWriteTextMetrics

Remarks

Drawing effects like underline and strikethrough do not contribute to the text size, which is essentially the sum of advance widths and line heights. Additionally, visible swashes and other graphic adornments may extend outside the returned width and height.

GetOverhangMetrics()

GetOverhangMetrics returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.

Declaration

public DWriteOverhangMetrics GetOverhangMetrics()

Returns

Type	Description
DWriteOverhangMetrics	DWriteOverhangMetrics

Remarks

Any underline and strikethrough do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.

GetStrikethrough(uint, out DWriteTextRange)

Get the strikethrough presence where the current position is at.

Declaration

public bool GetStrikethrough(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
bool	bool

GetTrimming()

Get trimming options for text overflowing the layout width.

Declaration

public DWriteTrimming GetTrimming()

Returns

Type	Description
DWriteTrimming	DWriteTrimming

GetTypography(uint, out DWriteTextRange)

Get the typography setting where the current position is at.

Declaration

public DWriteTypography GetTypography(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
DWriteTypography	DWriteTypography

GetUnderline(uint, out DWriteTextRange)

Get the underline presence where the current position is at.

Declaration

public bool GetUnderline(uint currentPosition, out DWriteTextRange textRange)

Parameters

Type	Name	Description
uint	currentPosition	The current text position.
DWriteTextRange	textRange	The position range of the current format.

Returns

Type	Description
bool	bool

HitTestPoint(float, float, out bool, out bool)

Given a coordinate (in DIPs) relative to the top-left of the layout box, this returns the corresponding hit-test metrics of the text string where the hit-test has occurred. This is useful for mapping mouse clicks to caret positions. When the given coordinate is outside the text string, the function sets the output value isInside to false but returns the nearest character position.

Declaration

public DWriteHitTestMetrics HitTestPoint(float pointX, float pointY, out bool isTrailingHit, out bool isInside)

Parameters

Type	Name	Description
float	pointX	X coordinate to hit-test, relative to the top-left location of the layout box.
float	pointY	Y coordinate to hit-test, relative to the top-left location of the layout box.
bool	isTrailingHit	Output flag indicating whether the hit-test location is at the leading or the trailing side of the character. When the output isInside value is set to false, this value is set according to the output position value to represent the edge closest to the hit-test location.
bool	isInside	Output flag indicating whether the hit-test location is inside the text string. When false, the position nearest the text's edge is returned.

Returns

Type	Description
DWriteHitTestMetrics	DWriteHitTestMetrics

HitTestTextPosition(uint, bool, out float, out float)

Given a text position and whether the caret is on the leading or trailing edge of that position, this returns the corresponding coordinate (in DIPs) relative to the top-left of the layout box. This is most useful for drawing the caret's current position, but it could also be used to anchor an IME to the typed text or attach a floating menu near the point of interest. It may also be used to programmatically obtain the geometry of a particular text position for UI automation.

Declaration

public DWriteHitTestMetrics HitTestTextPosition(uint textPosition, bool isTrailingHit, out float pointX, out float pointY)

Parameters

Type	Name	Description
uint	textPosition	Text position to get the coordinate of.
bool	isTrailingHit	Flag indicating whether the location is of the leading or the trailing side of the specified text position.
float	pointX	Output caret X, relative to the top-left of the layout box.
float	pointY	Output caret Y, relative to the top-left of the layout box.

Returns

Type	Description
DWriteHitTestMetrics	DWriteHitTestMetrics

Remarks

When drawing a caret at the returned X,Y, it should be centered on X and drawn from the Y coordinate down. The height will be the size of the hit-tested text (which can vary in size within a line). Reading direction also affects which side of the character the caret is drawn. However, the returned X coordinate will be correct for either case. You can get a text length back that is larger than a single character. This happens for complex scripts when multiple characters form a single cluster, when diacritics join their base character, or when you test a surrogate pair.

Release()

Releases the managed reference to the COM DWrite interface.

Declaration

public void Release()

SetFontCollection(DWriteFontCollection, DWriteTextRange)

Set the font collection.

Declaration

public void SetFontCollection(DWriteFontCollection fontCollection, DWriteTextRange textRange)

Parameters

Type	Name	Description
DWriteFontCollection	fontCollection	The font collection to set
DWriteTextRange	textRange	Text range to which this change applies.

SetFontFamilyName(string, DWriteTextRange)

Set null-terminated font family name.

Declaration

public void SetFontFamilyName(string fontFamilyName, DWriteTextRange textRange)

Parameters

Type	Name	Description
string	fontFamilyName	Font family name
DWriteTextRange	textRange	Text range to which this change applies.

SetFontSize(float, DWriteTextRange)

Set font em height.

Declaration

public void SetFontSize(float fontSize, DWriteTextRange textRange)

Parameters

Type	Name	Description
float	fontSize	Font em height
DWriteTextRange	textRange	Text range to which this change applies.

SetFontStretch(DWriteFontStretch, DWriteTextRange)

Set font stretch.

Declaration

public void SetFontStretch(DWriteFontStretch fontStretch, DWriteTextRange textRange)

Parameters

Type	Name	Description
DWriteFontStretch	fontStretch	font stretch
DWriteTextRange	textRange	Text range to which this change applies.

SetFontStyle(DWriteFontStyle, DWriteTextRange)

Set font style.

Declaration

public void SetFontStyle(DWriteFontStyle fontStyle, DWriteTextRange textRange)

Parameters

Type	Name	Description
DWriteFontStyle	fontStyle	Font style
DWriteTextRange	textRange	Text range to which this change applies.

SetFontWeight(DWriteFontWeight, DWriteTextRange)

Set font weight.

Declaration

public void SetFontWeight(DWriteFontWeight fontWeight, DWriteTextRange textRange)

Parameters

Type	Name	Description
DWriteFontWeight	fontWeight	Font weight
DWriteTextRange	textRange	Text range to which this change applies.

SetLineSpacing(DWriteLineSpacingMethod, float, float)

Set line spacing.

Declaration

public void SetLineSpacing(DWriteLineSpacingMethod lineSpacingMethod, float lineSpacing, float baseline)

Parameters

Type	Name	Description
DWriteLineSpacingMethod	lineSpacingMethod	How to determine line height.
float	lineSpacing	The line height, or rather distance between one baseline to another.
float	baseline	Distance from top of line to baseline. A reasonable ratio to lineSpacing is 80%.

Remarks

For the default method, spacing depends solely on the content. For uniform spacing, the given line height will override the content.

SetLocaleName(string, DWriteTextRange)

Set locale name.

Declaration

public void SetLocaleName(string localeName, DWriteTextRange textRange)

Parameters

Type	Name	Description
string	localeName	Locale name
DWriteTextRange	textRange	Text range to which this change applies.

SetStrikethrough(bool, DWriteTextRange)

Set strikethrough.

Declaration

public void SetStrikethrough(bool hasStrikethrough, DWriteTextRange textRange)

Parameters

Type	Name	Description
bool	hasStrikethrough	The Boolean flag indicates whether strikethrough takes place
DWriteTextRange	textRange	Text range to which this change applies.

SetTrimming(DWriteTrimming)

Set trimming options for any trailing text exceeding the layout width or for any far text exceeding the layout height.

Declaration

public void SetTrimming(DWriteTrimming trimmingOptions)

Parameters

Type	Name	Description
DWriteTrimming	trimmingOptions	Text trimming options.

SetTypography(DWriteTypography, DWriteTextRange)

Set font typography features.

Declaration

public void SetTypography(DWriteTypography typography, DWriteTextRange textRange)

Parameters

Type	Name	Description
DWriteTypography	typography	Pointer to font typography setting.
DWriteTextRange	textRange	Text range to which this change applies.

SetUnderline(bool, DWriteTextRange)

Set underline.

Declaration

public void SetUnderline(bool hasUnderline, DWriteTextRange textRange)

Parameters

Type	Name	Description
bool	hasUnderline	The Boolean flag indicates whether underline takes place
DWriteTextRange	textRange	Text range to which this change applies.

ToBoolean()

Gets a boolean indicating if the handle is not null.

Declaration

public bool ToBoolean()

Returns

Type	Description
bool	A boolean

Operators

implicit operator bool(DWriteTextLayout)

Gets a boolean indicating if the handle is not null.

Declaration

public static implicit operator bool(DWriteTextLayout value)

Parameters

Type	Name	Description
DWriteTextLayout	value	A DWrite object.

Returns

Type	Description
bool	A boolean

Implements

IDisposable

IDWriteReleasable