# ImageNode
Class Inherits Node
## About
`ImageNode` displays an image from a `Picture`, local file, URL, data URI, or Base64 value. It supports resizing, fill behavior, replacement, alignment, accessibility metadata, and an editable centered caption.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ActionItem | index As Integer | ToolbarItem | Returns the contextual toolbar item at the specified index. |
| AddClipboardData | clipboard As Clipboard | Boolean | Adds a ny native clipboard representations for this node and returns whether data was added. |
| AttachEmbeddedControls | editor As Editor | (None) | Creates and attaches any native controls required while this node is active. |
| BackgroundToolbarItem | (None) | ToolbarItem | Returns the default node-background popover toolbar item. |
| ClearFormatting | (None) | (None) | Removes supported formatting and restores this content's formatting defaults. |
| Constructor | value As Picture = Nil | (None) | Creates a new image node instance initialized from the supplied values. |
| Destructor | (None) | (None) | Releases resources owned by this image node instance. |
| DetachEmbeddedControls | (None) | (None) | Stops and removes native controls created by this node. |
| 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. |
| 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. |
| 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. |
| 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. |
| HasExplicitSize | (None) | Boolean | Returns whether the node has a width or height set explicitly rather than following its natural 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. |
| ImportDroppedText | value As String | Boolean | Imports dropped text or a URL into this node instance. |
| InspectorSections | (None) | InspectorSection | Returns the user-editable image value properties exposed by the inspector. |
| IntrinsicWidth | availableWidth As Double | Double | Returns the width the node needs for its content when its WidthMode is Intrinsic. |
| LastActionIndex | (None) | Integer | Returns the last zero-based action index supplied by this node, or -1 when there are no actions. |
| 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. |
| PerformAction | index As Integer <br> selectedItem As DesktopMenuItem | (None) | Handles the contextual toolbar action at the specified index. |
| 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. |
| RenderSelectionOverlay | g As Graphics | (None) | Draws the node-specific selection overlay. |
| 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. |
| 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. |
| SetImage | value As Picture <br> resizeToFit As Boolean = True | (None) | Assigns the displayed picture and optionally resets its fitted dimensions. |
| SetResource | file As FolderItem | (None) | Assigns the node's local image file. |
| SetResource | url As String | (None) | Assigns the node's remote resource URL. |
| 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. |
| 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 |
| --- | :---: | :---: | --- |
| Caption | String | (None) | Gets or sets the user-visible caption text. |
| CaptionGlyphFrames() | Rect | (None) | Gets or sets the cached document bounds for image-caption characters. |
| CaptionStyles() | TextStyle | (None) | Gets or sets the character styles used by the image caption. |
| DisplayHeight | Double | (None) | Gets or sets the display height. |
| DisplayWidth | Double | (None) | Gets or sets the display width. |
| FillMode | Integer | (None) | Gets or sets the fill mode. |
| Image | Picture | (None) | Gets or sets the displayed picture. |
| LocalFile | FolderItem | (None) | Gets or sets the local image file selected in the inspector. |
| SourceURL | String | (None) | Gets or sets the source URL associated with this image. |
| URL | String | (None) | Gets or sets the remote image URL selected in the inspector. |
## Notes
The node keeps its image source portable across supported export formats.
### JSON Format
`caption` and `sourceURL` are strings. `displayWidth` and `displayHeight` are JSON numbers. `captionStyles` contains positional `TextStyle` objects, each listing only what differs from a new `TextStyle`; it is omitted when every character has the default caption style. `image` contains the Base64-encoded picture file without a data-URI prefix. It is the file the picture was read from, downloaded, or loaded, such as a JPEG, so it is not enlarged by encoding again; a picture assigned in code, which has no file, is written as PNG. `image` is omitted when there is no picture.
`fillMode` is an integer: `0` Fit (`object-fit: contain`), `1` Fill (`object-fit: cover`), and `2` Stretch (`object-fit: fill`).
Values at their defaults are omitted and restored when missing: an empty `caption` and `sourceURL`, `displayWidth` and `displayHeight` `0`, and `fillMode` `0`.
### Portable Sources
Local files and `Picture` values are converted to data URIs so HTML, Markdown, and JSON output remain usable without the original file path. URL sources retain their URL. Use the inspector or popover actions to change or remove the image.
Importing HTML or JSON preserves an HTTP or HTTPS source but does not download it. This prevents untrusted documents from initiating network requests. After validating a URL against the application's network policy, call `SetResource(url)` explicitly to load it. Image files, downloads, and encoded image payloads are bounded to prevent excessive memory use.
The shared editor resize implementation handles pointer resizing and custom width or height entry. Empty or invalid custom dimensions reset that dimension to its natural value.
### Size and Alignment
An image node is as wide as its picture: its `WidthMode` is `Intrinsic` at the picture's natural display size, scaled down to at most 420 points wide, and `Fixed` once it is resized. The node's frame is the image's width, so `Alignment` positions the image within its container. New image nodes use `Automatic`, which follows the container and then the document, so they are left-aligned unless the document or container alignment says otherwise. Set `Alignment` to `Left`, `Center`, or `Right` to position an individual image. The caption is centered below the image and wraps within its width.
HTML export shrinks the `figure` to the image with `width: fit-content`, so its alignment margins position it as the editor does.
## Examples
Register an image prototype before inserting or importing images.
### Add a Picture
```xojo
Editor.AddNode(New GraffitiProEditor.ImageNode(myPicture))
```