Loading document parsing libraries...
# Node
Class
## About
`Node` is the base class for every document block. Subclasses define their default state in the constructor and can participate in rendering, editing, child containment, toolbar actions, inspector metadata, search, import, and export.
A node instance may be used as a registered prototype or inserted document content. Avoid storing editor-instance state on a prototype unless that state is intentionally copied into newly created nodes.
## Enumerations
| Name | Value | Description |
| --- | :---: | --- |
| WidthModes | Fill <br > Fixed <br > Intrinsic | (None) |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| AcceptsChild | node As Node | Boolean | Returns whether the supplied node can be embedded in this node. |
| AccessibilityValue | (None) | String | Returns the text value exposed for accessibility clients. |
| ActionItem | index As Integer | ToolbarItem | Returns the contextual toolbar item at the specified index. |
| AddChildAtPoint | node As Node <br> x As Double <br> y As Double | Boolean | Embeds a child node at the specified document coordinates and returns whether it was accepted. |
| AddClipboardData | clipboard As Clipboard | Boolean | Adds a ny native clipboard representations for this node and returns whether data was added. |
| 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. |
| AlignedLeft | containerLeft As Double <br> containerWidth As Double <br> nodeWidth As Double | Double | Returns the horizontal position for this node within the supplied container bounds. |
| AllowsToolbarItem | item As ToolbarItem | Boolean | Returns whether the toolbar item is applicable to this node's current state. |
| ApplyHTMLBackground | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Applies the background color, background image, and border declarations of the supplied HTML element to this node. |
| ApplyHTMLSize | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Applies the width and height declarations of the supplied HTML element to this node. |
| AttachEmbeddedControls | editor As Editor | (None) | Creates and attaches any native controls required while this node is active. |
| AttachToEditor | editor As Editor | (None) | Associates this node with the editor that owns it. |
| BackgroundToolbarItem | (None) | ToolbarItem | Returns the default node-background popover toolbar item. |
| BeginChanges | (None) | (None) | Starts a group of changes that the editor reports as one content change when the matching EndChanges is called. Calls can be nested. |
| BeginPointerInteraction | x As Double <br> y As Double | Boolean | Begins a node-specific pointer interaction at the supplied document coordinates and returns whether the node accepted it. |
| BorderColorFromJSON | data As JSONItem <br> name As String <br> fallback As Color | Color | Returns the color stored under the supplied name in border JSON data, or the fallback when it is missing. |
| BorderColorToJSON | value As Color | JSONItem | Returns the JSON representation of a border color. |
| CachedPreferredHeight | g As Graphics <br> availableWidth As Double | Double | Returns the preferred height, reusing the cached layout result when possible. |
| CacheRevision | (None) | Integer | Returns the revision used to invalidate cached layout and toolbar state. |
| CanAcceptChildAtPoint | node As Node <br> x As Double <br> y As Double | Boolean | Returns whether the supplied node can be embedded at the specified document coordinates. |
| CanAlignBlock | (None) | Boolean | Returns whether the node can be narrower than its container, so that block alignment applies. |
| CanImportHTML | element As GraffitiProEditor.HTMLSupport.HTMLElement | Boolean | Returns whether this node type can import the supplied HTML element. |
| ChildAt | index As Integer | Node | Returns the embedded child node at the specified index. |
| ClearFormatting | (None) | (None) | Removes supported formatting and restores this content's formatting defaults. |
| Constructor | (None) | (None) | Creates a new node instance initialized from the supplied values. |
| ContainsNode | node As Node | Boolean | Returns whether this node contains the supplied node, directly or recursively. |
| ContinuePointerInteraction | x As Double <br> y As Double | Boolean | Continues a node-specific pointer interaction at the supplied document coordinates and returns whether its state changed. |
| CopyPropertiesTo | target As Node | (None) | Copies the properties shared by every node type to the supplied node. |
| CornerPath | bounds As Rect | GraphicsPath | Returns the node's outline within the supplied bounds, with its corner radii. |
| CornerPath | bounds As Rect <br> insetTop As Double <br> insetRight As Double <br> insetBottom As Double <br> insetLeft As Double | GraphicsPath | Returns the node's outline within the supplied bounds inset on each side, with its corner radii reduced to match. |
| DefaultIsRightToLeft | (None) | Boolean | Returns True when content without a direction of its own, such as an empty paragraph, should read right to left. |
| Destructor | (None) | (None) | Releases resources owned by this node instance. |
| DetachEmbeddedControls | (None) | (None) | Stops and removes native controls created by this node. |
| DirectionForChildren | (None) | GraffitiProEditor.Directions | Returns the direction a container passes to the nodes inside it: its own Direction, or the one it inherited. |
| DiscardLayoutCache | recursive As Boolean = True | (None) | Invalidates cached layout measurements, optionally including embedded descendants. |
| DiscardRenderCache | recursive As Boolean = True | (None) | Invalidates cached node pictures, optionally including embedded descendants. |
| DrawAlignedText | g As Graphics <br> value As String <br> left As Double <br> baseline As Double <br> width As Double <br> rightToLeft As Boolean | (None) | Draws one line of text within the supplied width, starting at its reading side: the right side when rightToLeft is True. |
| DrawBackgroundImage | g As Graphics <br> bounds As Rect | (None) | Draws the node's background image within the supplied bounds. |
| DrawCached | g As Graphics <br> bounds As Rect <br> scaleFactor As Double = 1 | (None) | Draws the node using its cached representation when the cache is current. |
| DrawStrikethrough | g As Graphics <br> style As TextStyle <br> left As Double <br> right As Double <br> baseline As Double | (None) | Draws a strikethrough line for one run of text, in the current drawing color, through the middle of its lowercase letters. The thickness follows the drawn font size. |
| DrawTextBackground | g As Graphics <br> style As TextStyle <br> frame As Rect | (None) | Fills behind one character's frame for its style: the style's background color, a chip for inline code and keyboard keys, or the highlight color. Text renderers call it before drawing the character. |
| DroppedFileImportPriority | file As FolderItem | Integer | Returns this node type's priority for importing a dropped file, or a negative value when unsupported. |
| DroppedFileTypes | (None) | String | Returns the file MIME types this node wants the editor to accept for dropping. |
| DroppedRawDataImportPriority | type As String | Integer | Returns this node type's priority for an available raw drop payload. |
| DroppedRawDataTypes | (None) | String | Returns the platform raw-data or MIME types this node can import from a drop. |
| DroppedTextImportPriority | value As String | Integer | Returns this node type's priority for importing dropped text or a URL, or a negative value when unsupported. |
| Duplicate | (None) | Node | Returns an independent copy of this node and its configurable state. |
| EndChanges | changesDocument As Boolean = True <br> reportChange As Boolean = True | (None) | Ends a group of changes started with BeginChanges. When the outermost group ends, the editor redraws the node and reports one content change if anything changed. Pass False for changesDocument when the changes refresh content from elsewhere rather than edit it, so the editor reports them without setting IsChanged. Pass False for reportChange as well when the content is loading, so the editor only redraws. |
| EndPointerInteraction | (None) | (None) | Ends any node-specific pointer interaction. |
| EstimatedPreferredHeight | availableWidth As Double | Double | Returns a cheap approximation of the preferred height, used until the node is measured. |
| ExportCSS | (None) | String | Returns stylesheet rules for this node type's HTML output as CSS text. The editor merges them with the rules added in ExportStyles, which is the preferred way to add rules. |
| ExportStyles | stylesheet As GraffitiProEditor.Stylesheet | (None) | Adds the stylesheet rules this node type's HTML output uses. The editor calls it once for each node type in the document. |
| FindChildPlacement | node As Node <br> ByRef parent As Node <br> ByRef slot As Integer <br> ByRef index As Integer | Boolean | Finds an embedded node and returns its parent, slot, and index. |
| 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 was succeeded. |
| HandleKey | key As String | Boolean | Handles a key press for this node and returns whether it was consumed. |
| HandlePress | x As Double <br> y As Double | Boolean | Handles a pointer press at the specified coordinates and returns whether it was consumed. |
| HasCornerRadius | (None) | Boolean | Returns whether any corner of the node has a radius greater than zero. |
| HasExplicitSize | (None) | Boolean | Returns whether the node has a width or height set explicitly rather than following its natural size. |
| HitTest | x As Double <br> y As Double | Node | Returns the deepest selectable node at the specified document coordinates. |
| HTMLBackgroundCSS | (None) | String | Returns the CSS declarations for this node's background, borders, corners, size, and block alignment. |
| HTMLImportPriority | element As GraffitiProEditor.HTMLSupport.HTMLElement | Integer | Returns this node type's priority when resolving an HTML element importer. |
| HTMLSizeCSS | (None) | String | Returns the CSS width and height declarations for this node's explicit size. |
| HTMLTags | (None) | String | Returns the HTML tag names supported by this node type. |
| ImportDroppedFile | file As FolderItem | Boolean | Imports a dropped file into this node instance. |
| ImportDroppedRawData | type As String <br> value As String | Boolean | Imports a dropped raw payload into this node instance. |
| ImportDroppedText | value As String | Boolean | Imports dropped text or a URL into this node instance. |
| ImportEditableHTMLFragment | html As String <br> start As Integer <br> length As Integer <br> style As TextStyle | Integer | Imports a rich HTML fragment into this node's editable content and returns the new caret position, or -1 when unhandled. |
| ImportedNodeFromHTML | element As GraffitiProEditor.HTMLSupport.HTMLElement | Node | Resolves and restores a registered child node from an HTML element. |
| ImportedNodeFromJSON | data As JSONItem | Node | Resolves and restores a registered child node from JSON. |
| ImportMarkdown | markdown As String | Boolean | Imports a custom Markdown fragment into this node instance. |
| IncludeInVectorPDF | (None) | Boolean | Returns whether this node participates in vector PDF layout and export. |
| InsertChild | slot As Integer <br> index As Integer <br> node As Node | (None) | Inserts a child node into the specified container slot and index. |
| InsertHTML | html As String | (None) | Inserts html into the target container or root document. |
| InsertHTMLNode | node As Node | Boolean | Inserts an imported node into this container and returns whether it was accepted. |
| InsertionIndicatorAtPoint | node As Node <br> x As Double <br> y As Double | Rect | Returns the document bounds of the insertion indicator for a child dropped at the supplied coordinates. |
| InsertMarkdown | markdown As String | (None) | Inserts markdown into the target container or root document. |
| InspectorSections | (None) | InspectorSection | Returns the explicit inspector sections exposed by this node. |
| IntrinsicWidth | availableWidth As Double | Double | Returns the width the node needs for its content when its WidthMode is Intrinsic. |
| InvalidateAppearance | layoutChanged As Boolean = False | (None) | Invalidates cached drawing state and optionally cached layout measurements. |
| JSONIdentifier | (None) | String | Returns the stable type identifier used for JSON serialization and node registration. |
| LastActionIndex | (None) | Integer | Returns the last zero-based action index supplied by this node, or -1 when there are no actions. |
| LastChildIndex | (None) | Integer | Returns the last zero-based child index, or -1 when there are no children. |
| LastSearchSegmentIndex | (None) | Integer | Returns the last zero-based searchable segment index, or -1 when there are no searchable segments. |
| LayoutHeight | naturalHeight As Double | Double | Returns the effective layout height after applying explicit resize constraints. |
| LayoutWidth | availableWidth As Double | Double | Returns the effective layout width after applying explicit resize constraints. |
| 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. |
| MarkdownImportRange | markdown As String <br> ByRef start As Integer <br> ByRef length As Integer | Boolean | Finds the first custom Markdown construct this node type can import. |
| MarkdownWithBackground | content As String | String | Wraps Markdown content in the node's background-image HTML when needed. |
| Owner | (None) | Editor | Returns the editor this node belongs to, or Nil. |
| ParagraphLevel | characters() As String <br> firstIndex As Integer <br> lastIndex As Integer | Integer | Returns 1 when the paragraph in the supplied character range reads right to left and 0 when it reads left to right. |
| PerformAction | index As Integer <br> selectedItem As DesktopMenuItem | (None) | Handles the contextual toolbar action at the specified index. |
| PerformBackgroundAction | selectedItem As DesktopMenuItem | (None) | Handles a node-background popover menu selection. |
| 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. |
| PointerCursorAtPoint | x As Double <br> y As Double | MouseCursor | Returns the mouse cursor for the supplied document coordinates, or Nil to use the editor's default cursor. |
| PositionCachedLayout | bounds As Rect | (None) | Positions cached node and descendant layout within the supplied bounds. |
| PreferredHeight | g As Graphics <br> availableWidth As Double | Double | Returns the preferred node height for the available width. |
| RemoveChild | node As Node | Boolean | Removes the supplied embedded node and returns whether it was found. |
| Render | g As Graphics <br> bounds As Rect <br> selected As Boolean | (None) | Draws the node within the supplied document bounds. |
| RenderingForOutput | (None) | Boolean | Returns whether the node is being drawn for a picture, printing, or PDF instead of on screen. |
| RenderingForVectorPDF | (None) | Boolean | Returns whether the node is being drawn into a vector PDF. |
| RenderSelectionOverlay | g As Graphics | (None) | Draws the node-specific selection overlay. |
| RenderVectorPDF | g As Graphics <br> bounds As Rect | (None) | Draws this node's vector PDF appearance. Override for custom nodes. |
| ReplaceSearchText | segment As Integer <br> start As Integer <br> length As Integer <br> value As String | Boolean | Replaces a range in the specified searchable segment and returns whether it succeeded. |
| ResetHeight | (None) | (None) | Restores the node's automatic height. |
| ResetSize | (None) | (None) | Restores the node's automatic width and height. |
| ResetWidth | (None) | (None) | Restores the node's automatic width. |
| ResizeBounds | (None) | Rect | Returns the document bounds used for resize handles and hit testing. |
| ResizeHeight | (None) | Double | Returns the node's explicit height, or zero when height is automatic. |
| ResizeHeightTo | height As Double | (None) | Sets an explicit height without making an automatic width explicit. |
| ResizeTo | width As Double <br> height As Double | (None) | Applies explicit width and height values within the node's resize constraints. |
| ResizeWidth | (None) | Double | Returns the node's explicit width, or zero when width is automatic. |
| ResizeWidthTo | width As Double | (None) | Sets an explicit width without making an automatic height explicit. |
| ResolveBidiLevels | characters() As String <br> ByRef levels() As Integer <br> ByRef paragraphLevels() As Integer | Boolean | Fills the bidirectional level of every character and the level of its paragraph, splitting paragraphs at line breaks. Returns True when any paragraph holds right-to-left text or reads right to left. |
| ResolvedAlignment | (None) | GraffitiProEditor.Alignments | Returns the effective alignment for this node, inheriting the editor alignment when needed. |
| ResolvedDirection | (None) | GraffitiProEditor.Directions | Returns the direction this node's text follows: its own Direction, then its container's, then the editor's. Automatic means each paragraph takes its direction from its first letter. |
| ResolvedFontName | fontName As String | String | Returns the font to draw with for the supplied font name. An empty name means Automatic and resolves to the editor's FontName, or System outside an editor. |
| ResolvedFontSize | fontSize As Double | Double | Returns the size to draw with for the supplied font size. Zero means Default and resolves to the editor's FontSize, or 12 outside an editor. |
| ResolveSuggestionProvider | identifier As String | GraffitiProEditor.Suggestions.Provider | Returns the suggestion provider with the supplied identifier: the node's own provider, or one registered with its editor. |
| RestoreHTMLChildren | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Restores nested child nodes from the supplied HTML element after FromHTML completes. |
| RestoreJSONChildren | data As JSONItem | (None) | Restores nested child nodes from the supplied JSON after FromJSON completes. |
| ScrollChanged | bounds As Rect | (None) | Updates native child controls for the node's current visible bounds. |
| SearchSegmentName | index As Integer | String | Returns the display name of the searchable segment at the specified index. |
| SearchSegmentText | index As Integer | String | Returns the text of the searchable segment at the specified index. |
| ShowMessage | message As String <br> type As GraffitiProEditor.Notification.Types = GraffitiProEditor.Notification.Types.Danger | (None) | Shows a notification over the editor this node belongs to, as a Danger message unless another type is supplied. |
| Strings | (None) | GraffitiProEditor.Editor | Returns the editor whose Text properties supply this node's interface text: the editor that owns the node, or a shared editor with the built-in text when the node has none. |
| SupportsTextAlignment | (None) | Boolean | Returns whether the node draws text that follows its TextAlignment. |
| TextIsRightToLeft | value As String | Boolean | Returns True when the supplied text reads right to left: by this node's direction when it has one, otherwise by its first letter, and for text without letters by the editor's interface direction. |
| ThemeColor | kind As GraffitiProEditor.ThemeColors | Color | Returns the supplied color from the owning editor's theme, or its default when the node is not in an editor. The result is never Nil. |
| ThemeColor | kind As GraffitiProEditor.ThemeColors <br> alpha As Integer | Color | Returns the supplied theme color for the current appearance with the supplied alpha, where 0 is opaque and 255 is fully transparent. |
| ThemeCSSColor | kind As GraffitiProEditor.ThemeColors <br> alpha As Integer = 0 | String | Returns the supplied theme color as a CSS color value for use in ExportStyles. The alpha uses Xojo's scale, where 0 is opaque and 255 is fully transparent. |
| 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. |
| ToolbarIcon | svg As String | Picture | Returns a toolbar icon drawn from the supplied SVG in the current appearance's foreground color. |
| ToolbarIcon | item As ToolbarItem | Picture | Returns the default picture for the supplied contextual toolbar item. |
| ToPicture | (None) | Picture | Renders this node into a new picture at its natural layout size. |
| ToPicture | g As Graphics | (None) | Renders this node into the supplied graphics context at its top-left corner without scaling its 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. |
| VectorPDFSafeURL | value As String <br> submission As Boolean = False | String | Returns the supplied URL when a PDF link or form submission may use it, or an empty string. Links allow HTTP, HTTPS, email, and telephone URLs; submissions allow HTTP and HTTPS. |
| WidthMode | (None) | WidthModes | Returns how the node currently determines its width: filling its container, at an explicit width, or at the natural width of its content. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| AcceptedChildTypes() | String | (None) | Gets or sets the registered type identifiers accepted as embedded children; an empty array accepts any node type. |
| AccessibilityHint | String | (None) | Gets or sets the additional accessibility guidance for this node. |
| AccessibilityLabel | String | (None) | Gets or sets the accessible label, falling back to the node type name when empty. |
| AccessibilityRole | String | (None) | Gets or sets the semantic accessibility role for this node. |
| Alignment | GraffitiProEditor.Alignments | (None) | Gets or sets this node alignment; Automatic inherits the owning editor alignment. |
| AllowAutoCorrection | Boolean | True | Gets or sets whether automatic text correction is permitted while editing this node. |
| AllowCharacterInput | Boolean | True | Gets or sets whether registered character-input providers can insert text into this node. |
| AllowSpellChecking | Boolean | True | Gets or sets whether registered spelling providers can check editable text in this node. |
| Attributes | SpellingResults | Dictionary | Spelling results the editor cached for this node's text runs, keyed by run. |
| Attributes | InspectorWidth | (None) | Gets or sets the width edited by the visual inspector. |
| Attributes | InheritedDirection | (None) | Gets or sets the direction set by the node that contains this one. Containers assign it to their children. |
| Attributes | InspectorHeight | (None) | Gets or sets the height edited by the visual inspector. |
| Attributes | InspectorState | (None) | Returns or restores the serialized node state used by inspector actions. |
| BackgroundImage | GraffitiProEditor.BackgroundImage | (None) | Returns the node's background image configuration for runtime customization. |
| BorderBottomColor | Color | (None) | The bottom border color. |
| BorderBottomLeftRadius | Double | (None) | The bottom-left corner radius. Zero draws a square corner. |
| BorderBottomRightRadius | Double | (None) | The bottom-right corner radius. Zero draws a square corner. |
| BorderBottomSize | Double | 1 | The bottom border thickness. |
| BorderBottomVisible | Boolean | (None) | Whether the bottom border is drawn. |
| BorderLeftColor | Color | (None) | The left border color. |
| BorderLeftSize | Double | 1 | The left border thickness. |
| BorderLeftVisible | Boolean | (None) | Whether the left border is drawn. |
| BorderRightColor | Color | (None) | The right border color. |
| BorderRightSize | Double | 1 | The right border thickness. |
| BorderRightVisible | Boolean | (None) | Whether the right border is drawn. |
| BorderTopColor | Color | (None) | The top border color. |
| BorderTopLeftRadius | Double | (None) | The top-left corner radius. Zero draws a square corner. |
| BorderTopRightRadius | Double | (None) | The top-right corner radius. Zero draws a square corner. |
| BorderTopSize | Double | 1 | The top border thickness. |
| BorderTopVisible | Boolean | (None) | Whether the top border is drawn. |
| CanContainNodes | Boolean | (None) | Controls whether this node can contain nodes. |
| CanCopy | Boolean | (None) | Controls whether this node can copy. |
| CanDelete | Boolean | (None) | Controls whether this node can delete. |
| CanDuplicate | Boolean | (None) | Controls whether this node can duplicate. |
| CanEdit | Boolean | (None) | Controls whether this node can edit. |
| CanExportHTML | Boolean | (None) | Controls whether this node can export html. |
| CanExportMarkdown | Boolean | (None) | Controls whether this node can export markdown. |
| CanMove | Boolean | (None) | Controls whether this node can move. |
| CanResize | Boolean | (None) | Controls whether this node can resize. |
| CanSelect | Boolean | (None) | Controls whether this node can select. |
| Direction | GraffitiProEditor.Directions | (None) | Gets or sets this node's text direction. Automatic follows the containing node, then the editor's Direction. |
| FontOptions | GraffitiProEditor.FontOptions | (None) | Gets or sets node-specific font choices; Nil uses the editor-wide font options. |
| Frame | Rect | (None) | Gets or sets the node's current document bounds. |
| LineHeight | Double | (None) | Gets or sets the line-height multiplier used to lay out this node's text. |
| LineSpacing | Double | (None) | Gets or sets the additional spacing inserted between this node's text lines. |
| LockAspectRatio | Boolean | (None) | Gets or sets whether resizing preserves the node's aspect ratio. |
| MaximumResizeHeight | Double | (None) | Gets or sets the maximum resize height. |
| MaximumResizeWidth | Double | (None) | Gets or sets the maximum resize width. |
| MinimumResizeHeight | Double | 44 | Gets or sets the minimum resize height. |
| MinimumResizeWidth | Double | 80 | Gets or sets the minimum resize width. |
| NodeID | String | (None) | Gets or sets the node's document-unique identifier. |
| SuggestionProvider | GraffitiProEditor.Suggestions.Provider | (None) | Gets or sets the node-specific suggestion provider; Nil uses every provider registered with the editor. |
| ToolbarItem | GraffitiProEditor.ToolbarItem | (None) | Gets or sets the main-toolbar item supplied by this node type. |
## Notes
Override only the behavior required by the custom content type. The base class already handles selection, alignment, background images, resizing, accessibility information, drawing caches, common JSON fields, and default popover actions.
### Alignment
`Alignment` positions the node as a block within its container. `Automatic` inherits the alignment of the containing node, then the editor's `Alignment`; `ResolvedAlignment` returns the inherited result. Containers place children with `AlignedLeft`, which uses `ResolvedAlignment`, and the editor does the same for top-level nodes.
Block alignment is visible only when the node is narrower than the space available, for example after `LayoutWidth` is reduced by an explicit width. It does not align content drawn inside the node. The inspector offers the Alignment item when `WidthMode` is not `Fill` or the node can be resized; see the width notes. `SupportsTextAlignment` returns `False` by default and `True` for `TextNode`; override it to return `False` in a text-based node whose text is not laid out across the node. The main toolbar's alignment menu uses these to choose `TextAlignment` or `Alignment`, and is disabled for nodes that support neither. A node that draws text should offer its own text alignment, as `TextNode.TextAlignment` does, rather than reading `Alignment` for that purpose, so a block can be centered while its text stays left-aligned. See the `Editor` alignment notes for how the toolbar and inspector map to each setting.
### Batching Changes
Each call to `InvalidateAppearance` makes the editor redraw and raise `ContentChanged`. When one operation makes many changes, such as rebuilding a table's rows and cells, wrap it in `BeginChanges` and `EndChanges`. The node's caches still update immediately, but the editor redraws and raises `ContentChanged` once, when the outermost `EndChanges` is called, and only if something changed. Always call `EndChanges`, for example in a `Finally` block.
`EndChanges(False)` reports changes that refresh content from elsewhere, such as rows a node downloads, rather than edit it. The editor still redraws and raises `ContentChanged`, so collaborators receive the content, but `Editor.IsChanged` is not set. If any group in a nesting passes `True`, the whole change counts as an edit.
`EndChanges(False, False)` is for content that is loading, such as rows a node fetches while the document is built or opened. The editor redraws but raises no `ContentChanged`, so loading is not reported as a change at all. If any group in a nesting reports its changes, the whole change is reported.
```xojo
table.BeginChanges
Try
table.AddRow
table.AddColumn
Finally
table.EndChanges
End Try
```
### Colors
Draw with the editor's theme rather than fixed colors, so a node matches the rest of the document. `ThemeColor` returns a theme color, chosen with a `GraffitiProEditor.ThemeColors` value, for the current appearance; it uses the theme's defaults when the node is not in an editor, so it never fails. Pass an alpha for a translucent version. In `ExportStyles`, `ThemeCSSColor` returns the same color as a CSS value.
```xojo
g.DrawingColor = ThemeColor(GraffitiProEditor.ThemeColors.Surface)
g.FillRectangle(bounds.Left, bounds.Top, bounds.Width, bounds.Height)
If selected Then
g.DrawingColor = ThemeColor(GraffitiProEditor.ThemeColors.Selection)
g.DrawRectangle(bounds.Left, bounds.Top, bounds.Width, bounds.Height)
End If
```
A color the user can change and that is saved with the node, such as a text or line color, should take its default from `GraffitiProEditor.Editor.DefaultThemeColor` so saved documents do not depend on the current theme. A node with its own deliberate palette, such as `ExampleNode` in the demo, can keep fixed colors.
### Construction and Identity
Set defaults in the subclass constructor. Assign `ToolbarItem` when the type should appear in the main toolbar, and return a stable value from `JSONIdentifier`. The identifier must remain unique among registered node types.
`TypeName` is a stable, hardcoded implementation value used for diagnostics and editor state. It is not a localization property and must not be assembled from mutable user-facing text. `NodeID` identifies an individual instance and should not be reused as the type identifier.
### Container Nodes
Set `CanContainNodes` and implement the child APIs when a node owns other nodes. Child insertion, removal, hit testing, layout translation, and placement lookup must agree about the same slot and index model.
Return an insertion indicator from `InsertionIndicatorAtPoint` so drag operations show the exact destination. A container must clip child rendering to its content bounds when overflow is not allowed.
### Duplication and Cleanup
`Duplicate` must return an independent node with all user-editable state copied. Do not share mutable child collections, styles, or helper objects unintentionally.
A class that creates controls, timers, network requests, or event handlers must release them in `Destructor` or the appropriate closing path. Call the superclass destructor after subclass cleanup.
### Editing and Pointer Interaction
Editable nodes implement `EditableContent` so they can use the editor's shared caret, selection, clipboard, rich-text, suggestion-provider, and text-service features. Use `HandlePress`, `HandleKey`, and the pointer methods for other interactions owned by the node.
`LinkAtPoint` lets the editor raise `Editor.LinkPressed` for a modified click on a hyperlink. The base implementation asks the child nodes under the point. `TextNode` and `TableNode` find links in the text they last drew. A custom node that draws its own linked text should override it, return `True` with itself as `linkNode` and the link's URL, complete text, and title, and otherwise call `Super`.
Custom drawing and editing must agree about character positions. Use `TextIndexMap` when a visible character, such as emoji or a letter with a combining mark, occupies more than one position in the native string.
### Extension Checklist
A complete custom node should be reviewed in these areas before registration:
- Constructor defaults and a stable toolbar item, with `PerformToolbarAction` adding a node with its insertion defaults and any menu's default choice listed first.
- Natural measurement, rendering, hit testing, and cache invalidation.
- Duplication and cleanup of owned controls, timers, or handlers.
- Inspector metadata containing only user-editable state.
- JSON persistence for every persistent property.
- HTML and Markdown import/export for supported interoperable state.
- Vector PDF inclusion, rendering, annotations, and interactive controls.
- Search text and replacement where the node exposes textual content.
- Child APIs, clipping, and insertion indicators when it is a container.
- Accessibility label, hint, and role.
Register a prototype separately from inserting content, then test duplication and each supported round trip with nested content where applicable.
### Import Export and Saving
`HTMLTags`, `CanImportHTML`, and `HTMLImportPriority` identify blocks a node can import. `FromHTML` restores every supported instance property represented in the exported element. `ToHTML` must escape user text and attributes and keep instance-specific style on the node element.
Container nodes override `RestoreHTMLChildren` and `RestoreJSONChildren` to walk through their saved children after loading their own main properties. Use the protected `ImportedNodeFromHTML` and `ImportedNodeFromJSON` methods to create child nodes from the templates registered with the editor, including application-defined types. The editor does not interpret a container's cells, slots, or wrappers.
Override `ExportStyles` when `ToHTML` requires stylesheet rules, and add them to the supplied `Stylesheet` with `AddRule` or `SetProperty`. Call `Super.ExportStyles` when the node's HTML also uses its superclass's elements. The editor calls `ExportStyles` once for each node type in the document, including nodes nested in tables, columns, and forms, so types the document does not use add nothing. Rules from different node types that share a selector are merged into one rule. Keep instance-specific appearance inline in `ToHTML`; use `ExportStyles` for rules shared by every instance of the node type.
`ExportCSS` remains for nodes that supply their rules as CSS text. The editor reads that text with `Stylesheet.AddCSS` after calling `ExportStyles`, so its rules are merged the same way.
`FromJSON` and `ToJSON` save and restore the complete node without losing editor-specific properties. Always call the superclass implementation so shared properties are also preserved.
A node type handles its own custom Markdown. Its registered template uses `MarkdownImportRange` to find the first part it understands. The editor copies that template and passes the matching text to `ImportMarkdown`. Ordinary Markdown between custom sections continues through the shared Markdown importer.
`ImportEditableHTMLFragment` lets an editable node consume rich clipboard HTML directly. Return the new caret position when handled or `-1` to request the editor's built-in rich-text fallback. `AddClipboardData` can add a native picture or application-defined clipboard payload when a single node is copied.
When a file, text, or URL is dropped, each registered node template reports how well it can handle the data through `DroppedFileImportPriority` or `DroppedTextImportPriority`. The highest value of zero or greater wins. Negative values mean the type is not supported.
Return supported MIME types from `DroppedFileTypes` so the editor can register them with the operating system. The editor copies the winning template and calls its import method. Application-specific platform data follows the same pattern through `DroppedRawDataTypes`, `DroppedRawDataImportPriority`, and `ImportDroppedRawData`.
The same input should always produce the same result. Do not access the network until the host application approves an external URL.
### Inspector Metadata
Return explicit `InspectorSection` and `InspectorItem` objects from `InspectorSections`. Expose properties users should edit, not every public implementation switch. Bind helper objects only when their state is genuinely part of the node's editable model.
Inspector changes should flow through properties that invalidate the node appropriately. The editor records the node state before applying an inspector value so changes remain undoable.
### JSON Format
`Node.ToJSON` creates the common object inherited by every node serializer:
- `type` is the string returned by `JSONIdentifier` and selects a registered node prototype during restoration.
- `lineHeight` and `lineSpacing` are JSON numbers stored as `Double` values.
- `alignment` stores `GraffitiProEditor.Alignments` as `0` Automatic, `1` Leading, `2` Middle, or `3` Trailing. Leading and Trailing follow the node's direction.
- `backgroundImage` is an optional `BackgroundImage` object and is omitted when no source is assigned.
- `borderTopVisible`, `borderRightVisible`, `borderBottomVisible`, and `borderLeftVisible` independently enable the four node borders. The corresponding `border*Size` values are nonnegative `Double` values and `border*Color` values are color objects.
- `borderTopLeftRadius`, `borderTopRightRadius`, `borderBottomRightRadius`, and `borderBottomLeftRadius` are nonnegative `Double` corner radii in points.
- `width` and `height` are optional JSON numbers written only when `CanResize` is `True` and the node has an explicit size (`HasExplicitSize`). Each key is omitted when that dimension follows the node's natural size, and a missing key restores as natural.
Subclass serializers must begin with `Super.ToJSON`, append their persistent fields, and restore those fields after `Super.FromJSON` succeeds. Boolean, string, and numeric properties retain their corresponding JSON primitive type unless the subclass documentation specifies another conversion.
Values at their defaults are omitted, and `FromJSON` restores a missing name to that default rather than keeping the node's current value: `lineHeight` `1`, `lineSpacing` `0`, `alignment` Automatic, each `border*Visible` `False`, each `border*Size` `1`, each `border*Color` black with alpha `0`, and each corner radius `0`. `nodeId` and `type` are always written. Subclasses should follow the same rule with a fixed default for each field, so a node restores the same way whichever prototype it is created from.
### Rendering and Layout
Override `PreferredHeight` to measure natural content and `Render` to draw within the supplied document bounds. Use calculated geometry derived from the bounds; fixed values should be limited to intentional padding and margins.
The editor caches node representations. A node whose scaled dimensions exceed the cross-platform Picture limit is rendered directly instead of allocating an invalid cache. Call `InvalidateAppearance(False)` when drawing changes without affecting measurement, or `InvalidateAppearance(True)` when the preferred size or child layout may change. Override `ScrollChanged` to position embedded controls, but keep static previews while a media node is not selected.
Borders are opt-in and independent on every side. `BorderTopVisible`, `BorderRightVisible`, `BorderBottomVisible`, and `BorderLeftVisible` control whether a side is drawn; each side has its own `Size` and `Color`. The shared editor render paths draw these borders consistently in the editor, pictures, raster PDFs, and vector PDFs. Node implementations should not draw an additional default outline.
`BorderTopLeftRadius`, `BorderTopRightRadius`, `BorderBottomRightRadius`, and `BorderBottomLeftRadius` round each corner independently. They default to `0`. When any radius is set, the shared render paths clip the node's drawing (its background, content, and borders) to the rounded outline. Vector PDF output is the exception: PDFDocument graphics cannot restore a path clip, so content is not clipped there, and nodes that should look rounded in vector PDFs fill `CornerPath` instead of a rectangle, and borders follow the curve with inner radii reduced by the adjacent border sizes. Radii that do not fit a side shrink proportionally, as in CSS. HTML export writes `border-radius`, HTML import reads the shorthand and the four corner longhands, and `CornerPath` gives subclasses the same outline for drawing overlays.
`ToPicture()` returns a `Picture` of a single node at its natural size, and `ToPicture(Graphics)` draws the node at the top-left corner of a supplied destination. Both use the same output path as the editor's export methods, so custom nodes get them automatically from `PreferredHeight` and `Render`; subclasses do not need to override them. The width is the node's current laid-out width, or the editor's output content width before the node has been placed. A detached node uses 640 points. `ToPicture()` raises `OutOfBoundsException` if the result would exceed the shared picture-size limit.
### Text Direction
`Direction` sets which way this node's text reads. `Automatic`, the default, follows the node that contains it (`InheritedDirection`, which containers assign to their children), then `Editor.Direction`; when all of them are Automatic, each paragraph takes its direction from its first letter. `ResolvedDirection` returns the result. The direction is saved in JSON as `direction` when it is not Automatic and exported to HTML as CSS `direction` with `unicode-bidi: isolate`; HTML import reads the `dir` attribute or the CSS `direction` property.
A custom node that draws its own text can use the same rules. `ParagraphLevel` returns 1 for a right-to-left paragraph and 0 otherwise. `ResolveBidiLevels` resolves the level of every character in text split at line breaks, and `GraffitiProEditor.Bidi.VisualOrder` gives a line's characters in screen order. `TextIsRightToLeft` and `DrawAlignedText` cover single-line captions. Draw right-to-left runs whole, in reading order, so joined scripts connect. Nodes built on `TextNode` and its `RenderEditableText` get all of this without extra work.
`EditingVisualNeighbor` and `EditingIsRightToLeftAt` let the editor move the caret across the screen; nodes that implement `EditableContent` with right-to-left support override them.
### Toolbar and Context Menus
The registered prototype's `ToolbarItem` represents insertion in the main toolbar. `PerformToolbarAction` creates and adds a new node instance.
The editor's hover insertion chooser calls the same `PerformToolbarAction`, so set a new node's defaults there rather than relying on the registered template. Add the node with `Editor.AddNode`; the editor places it at the chooser's position instead of after the selection. When the toolbar item is a menu, the chooser does not show it and passes the menu's first enabled entry as `selectedItem`, so put the default choice first. `selectedItem` is `Nil` for toolbar items that are not menus. `ActionItem` and `PerformAction` define instance-specific popover commands. The base popover provides movement, duplication, and deletion where permitted.
Implement `ContextMenuProvider` when the node needs native contextual menu entries. Construct state-aware `DesktopMenuItem` objects and handle the selected item within the node.
### User-Facing Text
The built-in nodes' interface text lives on `Editor`, so it can be set in one place, including in the Xojo Inspector. A node reads it through the protected `Strings` method, which returns the editor the node belongs to, or a shared editor with the built-in English text when the node belongs to none. Read the text each time a menu, inspector section, prompt, or message is built, so changes to the editor apply.
A custom node can read the editor's text through `Strings` and can expose `Text`-prefixed String properties for text the editor doesn't have. Set a custom node type's toolbar item text in `LocalizeToolbarItem`, which the editor calls when the type is registered and when its localization changes, and check the item's identifier so a subclass with its own item keeps its text. When text ends in `Format`, preserve its documented named tokens. Code identifiers, serialized values, markup tokens, and programmatic diagnostics are not localization properties.
### Vector PDF Export
Vector PDF export follows the same node-owned extension model as HTML, Markdown, and JSON. The editor controls page layout and calls each node for its content; it does not inspect concrete node types.
Override `IncludeInVectorPDF` and return `False` for metadata or storage nodes that have no visible document representation. Override `RenderVectorPDF` when the normal `Render` implementation is unsuitable for PDF graphics. The default delegates to `Render`.
Override `AddVectorPDFAnnotations` to add links, annotations, or native PDF form controls after drawing. Coordinates in `Frame` are relative to the page content area; add `offsetX` and `offsetY` when creating PDF controls or link areas. Use `usedNames` to keep field names unique. Container implementations should pass the call to their included children, normally through `Super`.
### Width
`WidthMode` reports how the node is sized horizontally. It is read-only, calculated from the node's state, and returns `WidthModes`:
- `Fill`: the node takes the full width of its container. This is the default for nodes that cannot be resized, and for resizable nodes without an explicit width.
- `Fixed`: the node has an explicit width, set by resizing it, by `ResizeTo` or `ResizeWidthTo`, or by imported HTML or JSON.
- `Intrinsic`: the node is as wide as its content needs, from `IntrinsicWidth`, such as an image at its natural size.
Width and height are independent. `ResizeWidthTo` and `ResizeHeightTo` set one dimension and leave an automatic other dimension automatic, as the inspector and the toolbar's size fields do; `ResizeTo` sets both, as dragging a resize handle does. A node with `LockAspectRatio`, or one that keeps its size outside Node's resize fields, changes both to keep its proportions. `ResetWidth` and `ResetHeight` restore one automatic dimension.
`LayoutWidth` follows the mode: the available width for `Fill`, the explicit width for `Fixed`, and `IntrinsicWidth` for `Intrinsic`, each limited to the available width. Containers and the editor then position the node with `AlignedLeft`, so `Alignment` has a visible effect whenever the node is narrower than its container.
A custom node that sizes itself from its content overrides `WidthMode` to return `Intrinsic` and `IntrinsicWidth` to return the content's width, then draws within the frame it is given rather than centering content inside a full-width frame. A node that stores its explicit width outside Node's resize fields, as `ImageNode` does, overrides `ResizeWidth` and `WidthMode`.
## Examples
The `ExampleNode` class in the project examples folder demonstrates a broader custom implementation and is intended as a starting point for application plugins.
### Exporting HTML Styles
```xojo
// In StatusNode: rules shared by every status block in exported HTML.
Sub ExportStyles(stylesheet As GraffitiProEditor.Stylesheet)
Super.ExportStyles(stylesheet)
stylesheet.AddRule(".status", "padding: 12px; border-radius: 6px")
stylesheet.SetProperty(".status.ready", "background", "#ecfdf5")
End Sub
// ToHTML keeps per-instance appearance inline.
Function ToHTML() As String
Return "Ready"
End Function
```
### Minimal Custom Node
```xojo
Class StatusNode Inherits GraffitiProEditor.Node
Sub Constructor()
Super.Constructor
ToolbarItem = New GraffitiProEditor.ToolbarItem("node:status", "Status")
End Sub
Function TypeName() As String
Return "Status"
End Function
Function PreferredHeight(g As Graphics, availableWidth As Double) As Double
Return 44
End Function
Sub Render(g As Graphics, bounds As Rect, selected As Boolean)
g.DrawingColor = Color.TextColor
g.DrawText("Ready", bounds.Left + 12, bounds.Top + 28)
End Sub
End Class
```