TextLayout Class

Represents one or more paragraphs of multi-formatted text. Provides text analysis and layout functionality.

Inheritance

TextLayout

Namespace: GrapeCity.Documents.Text

Assembly: DS.Documents.Imaging.dll

Syntax

public class TextLayout

Public Class TextLayout

Remarks

In the simplest scenario, these steps can be followed to render a text on a graphics object using TextLayout:

Get a TextLayout objectCreate a new instance of the TextLayout class, or call Clear() on an existing instance to clear its content.
Define the desired layoutSet the layout properties (such as MaxWidth, MaxHeight, MarginLeft etc.) to the desired values.
Add content (text and formatting)Use Append(string) and its overloads to add text and formatting to the TextLayout instance. Use DefaultFormat to specify the default formatting for text fragments that are added without an explicitly associated format.
Calculate and shape glyphsCall RecalculateGlyphs() to calculate the glyphs needed to render the text. This also performs the required shaping. (If the content is modified (e.g. new text added) after this step, it can/should be repeated to recalculate the glyphs.)
Layout the textCall PerformLayout(bool) to layout the formatted paragraphs within the specified bounds. This step can be done multiple times to layout the text within different bounds.

Constructors

Name	Description
TextLayout()	Initializes a new instance of the TextLayout class with Resolution set to 72 graphic units per inch.
TextLayout(float)	Initializes a new instance of the TextLayout class. If a TextLayout is created to be used with a GrapeCity.Documents.Drawing.GcGraphics, it is recommended to use the GrapeCity.Documents.Drawing.GcGraphics.CreateTextLayout method instead, as it ensures that properties such as Resolution and FontCollection are set up properly to be used with the graphics.

Name

Description

TextLayout()

Initializes a new instance of the TextLayout class with Resolution set to 72 graphic units per inch.

TextLayout(float)

Initializes a new instance of the TextLayout class.

If a TextLayout is created to be used with a GrapeCity.Documents.Drawing.GcGraphics, it is recommended to use the GrapeCity.Documents.Drawing.GcGraphics.CreateTextLayout method instead, as it ensures that properties such as Resolution and FontCollection are set up properly to be used with the graphics.

Properties

Name	Description
AddSpacingAfterLastLine	Gets or sets a value indicating whether the line spacing should be added after the last line of text. The default is false.
AlignmentDelayToSplit	Gets or sets a value indicating whether to delay full text alignment till when any of the Split* methods is called. Do not use this property unless you are calling any of the Split* methods to render the text.
AllowOverhangingWords	Gets or sets a value indicating whether long words can overhang beyond the layout box bounds. The default is false.
AnchoredObjects	Gets the list of anchored objects.
BidiLevels	Gets the array with bidi levels of the code points.
CanSkipFirstLineWithIndentation	Gets or sets whether the whole first line of a paragraph with indentation can be skipped. The default is true.
ClusterMap	Gets the array mapping code points to glyphs.
CodePointCount	Gets the number of code points.
CodePointFlags	Gets the array of CodePointFlags, one for each code point.
CodePoints	Gets the array of UTF-32 characters (code points). Only the first CodePointCount elements should be taken into account.
ColumnWidth	Gets or sets the width of the layout box measured from the left margin (for positive values) or from the right margin (for negative values), in graphic units.
ContentHeight	Gets the height of the formatted text, in graphic units.
ContentHeightFitsInBounds	Gets a value indicating whether the height of the formatted text fits in the specified MaxHeight.
ContentHeightIncludingTrailingWhitespace	Gets the height of the formatted text, taking into account the trailing whitespace at the end of each line, in graphic units.
ContentRectangle	Gets the rectangle containing the formatted text, in graphic units.
ContentWidth	Gets the width of the formatted text, in graphic units.
ContentWidthFitsInBounds	Gets a value indicating whether the width of the formatted text fits in the specified MaxWidth.
ContentWidthIncludingTrailingWhitespace	Gets the width of the formatted text, taking into account the trailing whitespace at the end of each line, in graphic units.
ContentWithWhitespaceBounds	Get the rectangle of the formatted text, taking into account the trailing whitespace at the end of each line.
ContentX	Gets the X coordinate of the rectangle containing the formatted text, in graphic units.
ContentY	Gets the Y coordinate of the rectangle containing the formatted text, in graphic units.
DefaultFormat	Gets the default text format for the current text layout.
DefaultTabStops	Gets or sets the spacing between the default tab stops, in graphic units.
DelimiterCharCode	Gets or sets a UTF-32 character code used as a delimiter that signals the beginning of the portion of text to be preserved (for text trimming).
DelimiterCharCount	Gets or sets the delimiter count, counting from the end of the text, to preserve text from (for text trimming).
EllipsisCharCode	Gets or sets a UTF-32 code of the omission sign (ellipsis character) for text trimming. Setting this property to 0 prevents the ellipsis character from showing.
FirstLineIndent	Gets or sets the indent of the first line after paragraph separator, in graphic units.
FirstLineIsStartOfParagraph	Gets or sets a value indicating whether the first line of text is the start of paragraph. The default is true.
FlowDirection	Gets or sets the flow direction (how lines of text are placed relative to one another).
FontCollection	Gets or sets the custom font collection used for searching fonts and font fallbacks.
FontFallbackScope	Gets or sets a value specifying the scope for searching fallback fonts for the glyphs missing in the font defined in TextFormat.
FontScaleFactor	Gets or sets the uniform scale factor for all fonts used in the current text layout. Valid values are from 0.001 to 1000. The default is 1.
Formats	Gets the array of TextFormat objects, one for each code point.
GeneralCategories	Gets the array with general classification of the code points.
GlyphCount	Gets the number of resulting glyphs.
GlyphLinkedList	Gets the linked list with each glyph info.
GlyphRunMap	Gets the array mapping code points to glyph runs.
HasMissingFontCharacters	Gets a value indicating whether TextRuns contain some characters that are not present in the specified fonts and fallback fonts, so those characters cannot be displayed correctly.
HonorIdeographicBaseline	Gets or sets a value indicating whether the ideographic baseline should be used instead of the Roman baseline for hieroglyph characters. The default is false.
HonorLastLineSpacing	Gets or sets a value indicating whether line spacing for the last line is considered a part of the layout content. The default is false.
HonorTrailingLineBreak	Gets or sets a value indicating whether the trailing line break causes a blank line to be added to the output text layout. The default is false.
InlineObjects	Gets the list of inline objects.
Inlines	Gets the list of inline elements derived from Inline, such as TextRun and LineBreak.
JustifiedSpaceExtension	Gets or sets the maximum white space extension factor before applying extension to other characters when text is justified. Valid values are from 0 to 10000. The default is 2.5.
JustifiedSpaceShrinking	Gets or sets the white space shrinking factor when text is justified. Valid values are from 0.0 to 1.0. The default is 0.2.
JustifiedTextExtension	Gets or sets the maximum text extension factor when text is justified. Valid values are from 0 to 10000. The default is 0.3.
JustifyLastLine	Gets or sets a value indicating whether for paragraphs that have TextAlignment set to Distributed, the last line will be justified (typical in East Asian typography). The default is false.
LastLineIsEndOfParagraph	Gets or sets a value indicating whether the last line of text is the end of paragraph. The default is true.
LayoutPerformed	Gets a value indicating if PerformLayout(bool) method was executed at least once.
LineBreakingRules	Gets or sets a value specifying the line breaking algorithm. The default is Unicode.
LineGapBeforeFirstLine	Gets or sets a value indicating whether the typographic line gap should be added before the first line of text. The default is false.
LineSpacingScaleFactor	Gets or sets the scaling factor to be applied to the computed line height. Valid values are from 0 to 1000. The default is 1.
Lines	Gets the list of text lines after executing the PerformLayout(bool) method.
LinesBetweenConsecutiveHyphens	Gets or sets the minimum number of lines not using hyphens after breaking a word across lines and displaying a visible hyphen at the position of soft hyphen. The default is zero.
MarginAll	Gets or sets all margins of the layout box, in graphic units. Returns null if the margins have different values.
MarginBottom	Gets or sets the bottom margin of the layout box, in graphic units.
MarginLeft	Gets or sets the left margin of the layout box, in graphic units.
MarginRight	Gets or sets the right margin of the layout box, in graphic units.
MarginTop	Gets or sets the top margin of the layout box, in graphic units.
MaxHeight	Gets or sets the height of the layout box, in graphic units.
MaxLastLineOverflowFactor	Gets or sets the maximum fraction of the last line's height overflowing beyond the layout bounds for that line not to be truncated. The default is 0 (last line must completely fit within the layout bounds). Valid values are from 0 to 1. This property does not affect values returned by ContentHeightFitsInBounds or ContentWidthFitsInBounds. This property is ignored if ObjectRects is not null.
MaxWidth	Gets or sets the width of the layout box, in graphic units.
MinimalLineSpacing	Gets or sets the explicit minimal distance between lines, in graphic units.
NoExcelAlignment	Gets or sets a value indicating whether justified or distributed text alignment should be applied as if the SimplifiedWordBreak is always false. In other words, when this property is set to true the value of SimplifiedWordBreak does not affect the text alignment rules, it affects only the line breaking behavior. The default is false.
ObjectRects	Gets or sets the list of areas occupied by embedded objects.
ParagraphAlignment	Gets or sets the alignment of paragraphs along the flow direction axis.
ParagraphSpacing	Gets or sets the additional spacing between paragraphs, in graphic units.
Resolution	Gets or sets the resolution (graphic units per inch) used by the current text layout.
RestrictedFontLookup	Gets or sets a value indicating whether the fonts should be searched in the custom collection only, if any specified. The default is false.
RightToLeft	Gets or sets the base direction for horizontal and sideways text. The default is false.
RotateSidewaysCounterclockwise	Gets or sets a value indicating whether sideways text should be rotated counterclockwise. The default is false.
RowHeight	Gets or sets the height of the layout box measured from the top margin (for positive values) or from the bottom margin (for negative values), in graphic units.
ScriptCodes	Gets the array of ScriptCode's, one for each code point.
ScriptTags	Gets the array of ScriptTag's, one for each code point.
SimplifiedAlignment	Gets or sets a value indicating whether to use simplified text alignment rules. In particular, the same rules will be applied to narrow and wide (East Asian) characters. This property has effect only for horizontal text, and only if SimplifiedWordBreak is true and NoExcelAlignment is false. The default is false.
SimplifiedWordBreak	Gets or sets a value indicating whether to use simplified rules when determining word boundaries and line breaks. Setting this property to true prevents word breaking on certain non-whitespace characters to make word breaking behavior similar to that of MS Excel. The default is false.
SoftHyphenReplacementCharCode	Gets or sets a UTF-32 character code used as replacement for soft hyphen characters (0x00AD) at ends of lines when breaking words across lines. The default is 0x002D (the Unicode hyphen-minus character). Setting this to 0 breaks words without showing any visible hyphen character. Setting this to -1 prevents breaking words at soft hyphens. Note that if this property is changed, either RecalculateGlyphs() or PerformLayout(bool) with true as the parameter must be called for the changes to be processed correctly.
SplitCodePointIndex	Gets the first code point index of the current split rest, if this TextLayout contains the rest lines after calling the Split(TextSplitOptions, out TextLayout) or SplitAndBalance(PageSplitArea[], TextSplitOptions, out TextLayout) methods.
SuppressShaping	Gets or sets a value indicating if shaping and positioning of graphemes should be skipped for the sake of speed. The default is false.
TabStops	Gets or sets the list of tab stops.
TextAlignment	Gets or sets the alignment of text along the reading direction axis.
TextExtensionStrategy	Gets or sets a value specifying the rules used for justified text extension. If LineBreakingRules is Simplified, this property also affects the rules used for line breaking. The default is Default.
TrimmingGranularity	Gets or sets the text granularity used to trim text overflowing the layout box.
UniformLineSpacing	Gets or sets the explicit distance between lines, in graphic units.
UseEmbeddableFonts	Gets or sets a value indicating if the linked and fallback fonts have to be embeddable. The default is false.
UseOldScriptTags	Gets or sets a value indicating whether the following scripts should use their old tags: Bengali, Devanagari, Gujarati, Gurmukhi, Kannada, Malayalam, Myanmar, Odia, Tamil, Telugu. The default is false.
VerticalDirection	Gets a value indicating whether the FlowDirection was vertical when RecalculateGlyphs() was last called.
WordBoundaryRules	Gets or sets a value specifying the word breaking algorithm. The default is Unicode.
WrapMode	Gets or sets a value specifying how text lines are broken to avoid text overflowing the layout box.

Methods

Name	Description
Append(AnchoredObject, bool)	Adds an anchored object, or a copy of it, to the end of the Inlines collection. If adding the same anchored object multiple times, make sure to pass true as the `addCopy` parameter.
Append(InlineObject, bool)	Adds an inline object, or a copy of it, to the end of the Inlines collection. If adding the same inline object multiple times, make sure to pass true as the `addCopy` parameter.
Append(int[])	Adds a text run with default formatting to the end of the Inlines collection.
Append(int[], TextFormat)	Adds a text run with the specified format to the end of the Inlines collection.
Append(int[], TextFormat, IGcTag)	Adds a text run with the specified format to the end of the Inlines collection.
Append(int[], int, int)	Adds a text run with default formatting to the end of the Inlines collection.
Append(int[], int, int, TextFormat)	Adds a text run with the specified format to the end of the Inlines collection.
Append(int[], int, int, TextFormat, IGcTag)	Adds a text run with the specified format to the end of the Inlines collection.
Append(string)	Adds a text run with default formatting to the end of the Inlines collection.
Append(string, TextFormat)	Adds a text run with the specified format to the end of the Inlines collection.
AppendAnchoredObject(float, float, bool)	Adds an anchored object with specified dimensions to the end of the Inlines collection.
AppendInlineObject(object, float, float)	Adds an inline object with specified dimensions to the end of the Inlines collection.
AppendInlineObject(object, float, float, TextFormat)	Adds an inline object with specified dimensions and formatting to the end of the Inlines collection.
AppendLine()	Adds a line break element to the end of the Inlines collection.
AppendLine(TextFormat)	Adds a line break element to the end of the Inlines collection.
AppendLine(string)	Adds a text run with default formatting, followed by a line break, to the end of the Inlines collection.
AppendLine(string, TextFormat)	Adds a text run with the specified format, followed by a line break, to the end of the Inlines collection.
AppendParagraphBreak()	Adds a special character (0x2029) that causes a paragraph break but prevents a page break between paragraphs (GrapeCity specifics).
AppendParagraphBreak(TextFormat)	Adds a special character (0x2029) that causes a paragraph break but prevents a page break between paragraphs (GrapeCity specifics).
AppendSectionBreak()	Appends a form feed character ('\f', character code 0x000C) to the text. This causes any text added after it to "not fit" - if the text layout is drawn, that text will not be rendered. If the Split() method is called, the text will be split at this point.
AppendSectionBreak(TextFormat)	Appends a form feed character ('\f', character code 0x000C) to the text. This causes any text added after it to "not fit" - if the text layout is drawn, that text will not be rendered. If the Split() method is called, the text will be split at this point.
AppendSoftBreak()	Adds a line separator character (0x2028) that causes a line break without ending the paragraph.
AppendSoftBreak(TextFormat)	Adds a line separator character (0x2028) that causes a line break without ending the paragraph.
ApplyOffset(float, float)	Adjusts the positions of content rectangle, inline and anchored objects by a specified amount.
Clear()	Clears the current text layout, removing all text and formatting associated with individual text runs.
Clone(bool, bool)	Creates a copy of the current TextLayout instance.
GetInlineObjectAt(int)	Gets the InlineObject at the specified code point index.
GetTextRects(int, int, bool, bool)	Returns the list of TextRect objects for the specified range of code points.
MapCharRangeToCodePoints(ref int, ref int)	Maps a character range to the corresponding code point range.
MapCodePointsToCharRange(ref int, ref int)	Maps a code point range to the corresponding character range.
PerformLayout(bool)	Determines the coordinates for all lines and glyph runs. Optionally calls RecalculateGlyphs() prior to performing the layout.
RecalculateGlyphs()	Converts characters in the current TextLayout to glyphs, and performs text shaping. In order to layout the text (e.g. when rendering it on a graphics), a call to this method must precede the call(s) to PerformLayout(bool), or alternatively the PerformLayout method should be called with true as the parameter.
ResolveAmbiguousEastAsianWidths(CodePointFlags[], int)	Resolves characters with ambiguous East Asian width to either narrow or wide.
ResolveAmbiguousLineBreakingClasses(LineBreakingClass[], int)	Resolves the ambiguous AI, CJ, SA, SG, XX line-breaking classes.
ResolveAmbiguousScriptCodes(ScriptCode[], int)	Resolves the Inherited, Common, and Unknown script codes, if possible.
Split(TextSplitOptions, out TextLayout)	Fits all or the first portion of the current text layout into the current layout bounds. If the whole text did not fit into the bounds, the rest is moved into a new TextLayout instance specified by the output parameter `rest`.
SplitAndBalance(PageSplitArea[], TextSplitOptions, out TextLayout)	Fits all or the first portion of the current text layout into one or more layout areas (such as page columns). If the whole text did not fit into the provided areas, the rest is moved into a new TextLayout instance specified by the output parameter `rest`. If the whole text fits in the specified areas (i.e. `rest` is empty), the content is equally distributed between all areas, which in the case of page columns results in columns of equal height (balanced).
SplitAndBalanceRef(PageSplitArea[], TextSplitOptions, ref TextLayout)	Fits all or the first portion of the current text layout into one or more layout areas (such as page columns). If the whole text did not fit into the provided areas, the rest is moved into a new TextLayout instance specified by the output parameter `rest`. If the whole text fits in the specified areas (i.e. `rest` is empty), the content is equally distributed between all areas, which in the case of page columns results in columns of equal height (balanced). For details on why providing a reference to an existing TextLayout may be beneficial, see the remarks on the SplitRef(TextSplitOptions, ref TextLayout) method.
SplitRef(TextSplitOptions, ref TextLayout)	Fits all or the first portion of the current text layout into the current layout bounds. If the whole text did not fit into the bounds, the rest is moved into the TextLayout instance specified by the reference parameter `rest`. If it is null, a new TextLayout instance is created.
Truncate(TrimmingGranularity)	If a portion of the text content does not fit into the current layout bounds, removes that portion so that the remaining text fits. If the text is truncated and `lastLineTrimming` is not None, ellipsis (specified by EllipsisCharCode) is appended to the last line to indicate that it was trimmed.