# TextNode
Class Inherits Node
## About
`TextNode` is the general-purpose rich-text paragraph node. It supports canvas-native caret and range editing, character styles, links, application-defined suggestions, background images, independent node and text alignment, and embedded text-service behavior.
Text nodes are registered by every editor automatically. Construct an instance and pass it to `Editor.AddNode` to insert a paragraph.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ActiveSuggestionProvider | (None) | GraffitiProEditor.Suggestions.Provider | Returns the provider that supplies suggestions for this editable content. |
| AddVectorPDFAnnotations | pdf As PDFDocument <br> pageNumber As Integer <br> offsetX As Double <br> offsetY As Double <br> usedNames As Dictionary <br> formAction As String = "" | (None) | Adds this node's interactive annotations and form controls to a vector PDF page. Override for custom nodes. |
| ApplyBackground | start As Integer <br> length As Integer <br> value As Color | (None) | Applies background to the specified content range. |
| ApplyBold | start As Integer <br> length As Integer <br> value As Boolean | (None) | Applies bold to the specified content range. |
| ApplyFontName | start As Integer <br> length As Integer <br> value As String | (None) | Applies font name to the specified content range. |
| ApplyFontSize | start As Integer <br> length As Integer <br> value As Double | (None) | Applies font size to the specified content range. |
| ApplyHTMLBlockStyle | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Applies the text alignment and line metrics of the supplied HTML block element to this node. |
| ApplyItalic | start As Integer <br> length As Integer <br> value As Boolean | (None) | Applies italic to the specified content range. |
| ApplyStrikethrough | start As Integer <br> length As Integer <br> value As Boolean = True | (None) | Applies strike through to the specified content range. |
| ApplyTextColor | start As Integer <br> length As Integer <br> value As Color | (None) | Applies text color to the specified content range. |
| ApplyUnderline | start As Integer <br> length As Integer <br> value As Boolean | (None) | Applies underline to the specified content range. |
| CanImportHTML | element As GraffitiProEditor.HTMLSupport.HTMLElement | Boolean | Returns whether this node type can import the supplied HTML element. |
| ClearFormatting | (None) | (None) | Removes supported formatting and restores this content's formatting defaults. |
| Constructor | value As String <br> size As Double = 0 | (None) | Creates a new text node instance initialized from the supplied values. |
| CopyTextPropertiesTo | target As TextNode | (None) | Copies this node's text content, styles, and text settings to the supplied node. |
| Duplicate | (None) | Node | Returns an independent copy of this node and its configurable state. |
| EditableContentPadding | (None) | Double | Returns the space between the node's edges and its text, in points. |
| EditableContentVerticalPadding | (None) | Double | Returns the space above and below the node's text, in points. Text smaller than 12 points gets proportionally less. |
| EditableTextWidth | g As Graphics | Double | Returns the width of the node's laid-out text, measured with the supplied graphics context. |
| EditingApplyStyle | start As Integer <br> length As Integer <br> style As TextStyle <br> fieldName As String | (None) | Applies the specified style field to a range in the active editable content. |
| EditingCaretFrame | position As Integer | Rect | Returns the document bounds of the caret at the specified text position. |
| EditingClearFormatting | start As Integer <br> length As Integer | (None) | Clears character formatting from the specified editable range. |
| EditingDrawOverlay | g As Graphics <br> selectionStart As Integer <br> selectionLength As Integer <br> caretPosition As Integer <br> caretVisible As Boolean | (None) | Draws the selection and caret overlay for the active editable content. |
| EditingHandleKey | key As String <br> shiftKey As Boolean <br> menuShortcutKey As Boolean <br> ByRef selectionStart As Integer <br> ByRef selectionLength As Integer <br> ByRef caretPosition As Integer <br> style As TextStyle | (None) | Handles a key press and updates the supplied selection and caret positions. |
| EditingHandleReturn | (None) | Boolean | Handles a Return key press and returns whether the content consumed it. |
| EditingHandlesKey | key As String <br> shiftKey As Boolean <br> menuShortcutKey As Boolean | Boolean | Returns whether the editable content handles the specified key combination. |
| EditingHitIndex | x As Double <br> y As Double | Integer | Returns the nearest text insertion index for the specified document coordinates. |
| EditingInsertText | position As Integer <br> value As String <br> style As TextStyle | (None) | Inserts styled text at the specified position. |
| EditingLength | (None) | Integer | Returns the number of editable characters in the active content. |
| EditingRemoveText | start As Integer <br> length As Integer | (None) | Removes the specified range from the active editable content. |
| EditingRestoreState | state As Variant | (None) | Restores a previously captured editing state. |
| EditingSelectedHTML | start As Integer <br> length As Integer | String | Returns the selected range as an HTML fragment. |
| EditingSelectedText | start As Integer <br> length As Integer | String | Returns the selected range as plain text. |
| EditingState | (None) | Variant | Returns a snapshot that can restore the current editing state. |
| EditingStyleAt | index As Integer | TextStyle | Returns the character style at the specified editable index. |
| EditingSupportsStyles | (None) | Boolean | Returns whether the editable content supports character-level styling. |
| EstimatedPreferredHeight | availableWidth As Double | Double | Returns an approximation of the preferred height based on text length and font size. |
| ExportStyles | stylesheet As GraffitiProEditor.Stylesheet | (None) | Adds the stylesheet rules this node type's HTML output uses. |
| FromHTML | element As GraffitiProEditor.HTMLSupport.HTMLElement | Boolean | Imports supported content and formatting from an HTML element and returns whether it succeeded. |
| FromJSON | data As JSONItem | Boolean | Restores state from JSON data and returns whether it succeeded. |
| GlyphLeadingEdge | position As Integer | Double | Returns the horizontal position of the leading edge of the glyph at the supplied text position, following its reading direction. |
| GlyphTrailingEdge | position As Integer | Double | Returns the horizontal position of the trailing edge of the glyph at the supplied text position, following its reading direction. |
| HTMLLineHeightCSS | (None) | String | Returns the CSS line-height declaration for this node's LineHeight and LineSpacing relative to the font's normal line height, or an empty string when both have their default values. |
| HTMLTags | (None) | String | Returns the HTML tag names supported by this node type. |
| HTMLText | start As Integer = 0 <br> length As Integer = -1 | String | Returns the supplied range of the node's text as HTML, with its character styles. |
| HTMLTextAlignmentCSS | (None) | String | Returns the CSS text-align declaration for this node's text alignment. |
| InsertText | position As Integer <br> value As String <br> style As TextStyle | (None) | Inserts the supplied text with the supplied style at the supplied position. |
| InspectorSections | (None) | InspectorSection | Returns the explicit inspector sections exposed by this node. |
| LastSearchSegmentIndex | (None) | Integer | Returns the last zero-based searchable segment index, or -1 when there are no searchable segments. |
| LinkAtPoint | x As Double <br> y As Double <br> ByRef linkNode As GraffitiProEditor.Node <br> ByRef url As String <br> ByRef linkText As String <br> ByRef title As String | Boolean | Finds the hyperlink at the specified document coordinates and returns whether one was found, with the node that holds it, its URL, its complete link text, and its title. |
| LocalizeToolbarItem | strings As GraffitiProEditor.Editor | (None) | Sets this node type's toolbar item text from the supplied editor's localization properties. The editor calls it when the type is registered, when the editor opens, and when a locale pack is applied to the editor. A custom node type can override it to localize its own toolbar item. |
| MarkdownText | start As Integer = 0 <br> length As Integer = -1 | String | Returns the supported Markdown for the specified text range. |
| PerformToolbarAction | editor As Editor <br> selectedItem As DesktopMenuItem | (None) | Handles activation of this node type's main-toolbar item. |
| PlainText | (None) | String | Returns the node's readable content as plain text. |
| PreferredHeight | g As Graphics <br> availableWidth As Double | Double | Returns the preferred node height for the available width. |
| Render | g As Graphics <br> bounds As Rect <br> selected As Boolean | (None) | Draws the node within the supplied document bounds. |
| RenderEditableText | g As Graphics <br> bounds As Rect | (None) | Draws the node's text within the supplied bounds and records the glyph frames used for hit testing and the caret. |
| ReplaceEditableText | value As String | (None) | Replaces all of the node's text with the supplied plain text. |
| ResolvedTextAlignment | (None) | GraffitiProEditor.Alignments | Returns the effective internal text alignment. |
| SearchSegmentText | index As Integer | String | Returns the text of the specified searchable segment. |
| StyleAt | index As Integer | TextStyle | Returns the character style at the specified text index. |
| SupportsTextAlignment | (None) | Boolean | Returns whether the node draws text that follows its TextAlignment. |
| ToHTML | (None) | String | Returns an HTML representation of this content. |
| ToJSON | (None) | JSONItem | Returns a JSON representation of this object's persistent state. |
| ToMarkdown | (None) | String | Returns a Markdown representation of this content. |
| TranslateLayout | offsetX As Double <br> offsetY As Double | (None) | Offsets this node and its cached descendant layout by the supplied distances. |
| TypeName | (None) | String | Returns the display name for this node type. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| Bold | Boolean | (None) | Gets or sets whether bold formatting is applied. |
| FontName | String | (None) | Gets or sets the font of all of this node's text. An empty name is Automatic and follows the editor's FontName. |
| FontSize | Double | (None) | Gets or sets the size of all of this node's text. Zero is Default and follows the editor's FontSize. |
| GlyphFrames() | Rect | (None) | The frame of each drawn glyph, in editor coordinates, from the most recent drawing. |
| GlyphRightToLeft() | Boolean | (None) | True for each storage position whose character was drawn right to left. Empty when the last drawing held only left-to-right text |
| Italic | Boolean | (None) | Gets or sets whether italic formatting is applied. |
| Styles() | TextStyle | (None) | The character style of each character in the node's text. |
| Text | String | (None) | Gets or sets the editable plain text. |
| TextAlignment | GraffitiProEditor.Alignments | (None) | Gets or sets the internal alignment of text within the node; Automatic uses the node type's default. |
| TextColor | Color | (None) | Gets or sets the foreground color used to draw text. |
| Underline | Boolean | (None) | Gets or sets whether underline formatting is applied. |
## Notes
Text nodes use the editor's shared rich-text editing implementation. `Alignment` positions the node within its parent, while `TextAlignment` positions text inside the node. `TextAlignment.Automatic` uses the node type's normal internal alignment, which is left alignment for `TextNode`, and does not inherit `Alignment`.
A text node fills the content width unless it can be resized, so its inspector offers Text Alignment but not Alignment, and the editor's document alignment has no visible effect on it. The main toolbar's alignment menu sets `TextAlignment`, whether or not the text is being edited. A resizable text node also offers Alignment in the inspector to position it as a block. See the `Editor` alignment notes for the complete inheritance rules.
### JSON Format
`content` is a `TextSnapshot` containing the node's text and the style of each character. `fontName`, numeric `fontSize`, and the Boolean `bold`, `italic`, and `underline` fields preserve the node's base appearance. `textAlignment` stores `GraffitiProEditor.Alignments` as `0` Automatic, `1` Left, `2` Center, or `3` Right, separately from the common node `alignment` field. Suggestion providers are runtime application objects and are not stored in document JSON.
Text-derived subclasses use fields inside `content` for semantic state such as heading level, alert type, or list type. They retain the common `Node` JSON fields supplied by the superclass.
`content` is always written. `bold`, `italic`, and `underline` are omitted when `False`, `fontName` when empty, `fontSize` when `0`, and `textAlignment` when Automatic; missing names restore those defaults.
### Rich Text
Styles are stored for each character. During HTML export, adjacent characters with the same style are combined into one HTML element. Toolbar commands apply to the selected character range while editing, or to the complete node when it is selected outside edit mode. Text inserted by a suggestion remains part of the text rather than becoming a separate child node.
## Examples
Text nodes are available without explicit registration.
### Insert Text
```xojo
Editor.AddNode(New GraffitiProEditor.TextNode("A new paragraph."))
```