Loading document parsing libraries...
# Inspector
Class Inherits DesktopCanvas
## About
`Inspector` is a scrollable visual property editor for an `Editor`, its document, and its selected nodes. It uses native inline editors and a reusable native color picker while drawing its property grid directly.
## Event Definitions
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Opening | (None) | (None) | Raised when the inspector is about to open. |
| ValueChanged | node As GraffitiProEditor.Node <br> item As GraffitiProEditor.InspectorItem | (None) | Raised after an inspector item successfully changes its target value. |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Constructor | (None) | (None) | Creates a new inspector control. |
| Destructor | (None) | (None) | Releases event handlers owned by this inspector. |
| Inspect | node As Node | (None) | Displays the supplied node without changing the editor selection. |
| RefreshValues | (None) | (None) | Rebuilds the visible property metadata and redraws the inspector. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| InspectedEditor | Editor | (None) | Associates this inspector with an editor and follows its primary selection. |
| Target | Node | (None) | Returns the node currently displayed by the inspector. |
| TextAutomaticCaption | String | "Automatic" | Gets or sets the user-visible text. |
| TextChooseDialogTitleFormat | String | "Choose | Gets or sets the user-visible format string. Use %caption% for the inspector item caption. |
| TextChooseFileCaption | String | "Choose | Gets or sets the user-visible text. |
| TextCommentsTabCaption | String | "Comments" | Gets or sets the user-visible text. |
| TextDocumentCaption | String | "Document" | Gets or sets the user-visible text. |
| TextMultipleValuesCaption | String | "Multiple | Gets or sets the user-visible text. |
| TextNoCommentsCaption | String | "No | Gets or sets the user-visible text. |
| TextNoSelectionCaption | String | "No | Gets or sets the user-visible text. |
| TextNumberRangeTooltipFormat | String | "Enter | Gets or sets the user-visible format string. Use %minimum% and %maximum% for the numeric limits. |
| TextObjectCaption | String | "Object" | Gets or sets the user-visible text. |
| TextOneReplyCaption | String | "1 | Gets or sets the user-visible text. |
| TextPropertiesTabCaption | String | "Properties" | Gets or sets the user-visible text. |
| TextReplyCountFormat | String | "%count% | Gets or sets the user-visible format string. Use %count% for the number of replies. |
| TextResetToDefaultMenuCaption | String | "Reset | Gets or sets the user-visible text. |
## Notes
The inspector displays only the explicit metadata supplied by the editor or selected node. Nil sections, empty sections, and sections whose items are all unavailable for the current target are omitted automatically.
### Association and Selection
Set `InspectedEditor` to associate the control with an editor. The inspector follows the editor's primary selection through an internal observer mechanism, leaving the editor's public events available to application code. With no selected node it displays document-level properties.
Calling `Inspect` directly can display a particular node, but the normal application integration is to assign `InspectedEditor` and let selection drive the target.
### Comments Tab
The inspector has two tabs below its title when the editor's `AllowAnnotations` is True, the default: Properties, the property sections, and Comments, the discussion threads from `Editor.Annotations`. The Comments tab lists the inspected node's threads, or every thread in the document when the document is inspected, and a badge beside its caption counts them.
Each thread is a card with its status, Open or Resolved, its first comment's author and date, the quoted text, the comment, and the number of replies, with Resolve or Reopen and Delete buttons. Clicking a card opens the thread in the editor's comment popover, scrolling to it first, to read it and reply. Add Comment above the cards starts a thread on the editor's selection. The thread open in the popover has a highlighted border.
When `AllowAnnotations` is False, the tab bar is hidden and the inspector shows only the property sections. The tab works in a read-only editor, such as one with `Annotate` access, and redraws whenever annotations change. Its text is localized with `TextPropertiesTabCaption`, `TextCommentsTabCaption`, `TextNoCommentsCaption`, `TextOneReplyCaption`, and `TextReplyCountFormat`, and with the editor's comment strings. It is mirrored in a right-to-left interface.
### Editing Behavior
Single-click a value cell to begin editing. Text and numeric values use inline controls, menu values use native menus, colors use one reusable `DesktopColorPicker`, and action values use button-like controls. Live edits are recorded as one undoable inspector operation.
A value that differs from its default shows a reset button at the trailing edge of its value cell, and the Reset to Default contextual action is available on every value. With several nodes selected, the button appears when any of them differs, and a reset applies to all of them. `InspectorItem.DefaultValueFor` supplies the default. A number whose default is zero while zero is below its minimum, such as a node's width or height, shows Automatic at zero; clearing it or typing Automatic restores it.
Changing a value with a toggle, menu, file, or reset rebuilds the inspector's items, so items and defaults that depend on other values, such as a heading's size default, which follows its level, stay current. Collapsed sections stay collapsed.
Clicking a section header collapses or expands it. Its rows slide in or out under the header over about 180 milliseconds while the disclosure chevron turns, and clicking again mid-animation reverses it from where it is.
Rows have no separator lines. Each caption is drawn in the muted chrome color on the leading side. Text, number, menu, and file values sit in a rounded field on the trailing side; a file field shows a folder icon and a Choose File… prompt until a file is chosen, and checkboxes, color swatches, and action buttons line up with that field's edges. The focus and validation rings follow the field's rounded shape.
Clicking elsewhere or losing inspector focus ends the current editor. Invalid numeric input remains visibly marked rather than silently applying an unsuitable value.
While the inspected editor is `ReadOnly`, every item is shown dimmed and cannot be edited, focused, or reset. This includes a collaboration session with `Read` access and a node another user has locked. A value being edited when the editor becomes read-only is discarded.
While a value is being edited, Return commits it and Escape cancels it. Tab commits it and moves to the next editable row, and Shift-Tab to the previous one, skipping read-only, disabled, and unavailable rows. A text or number row opens for editing; a toggle, menu, color, file, or action row receives the keyboard focus and opens with Return or Space. A value that fails validation keeps its editor open instead of moving. In a multiline text value, Tab moves to the next row rather than inserting a tab character. Tab also moves between rows when a row is focused without an editor open, so a toggle, menu, or color row passes Tab on to the next row rather than to the next control in the window. The inspector turns on `AllowFocus` and `AllowTabs` before raising `Opening`, even when a window layout saved them as `False`. When no editor is open, the Up and Down Arrow keys move the focused row.
### Localization
Inspector-owned UI strings are ordinary public properties. `TextChooseDialogTitleFormat` requires `%caption%`. `TextNumberRangeTooltipFormat` requires `%minimum%` and `%maximum%`. Preserve these named tokens while translating, but reorder them as required by the target language. See the module localization notes for the complete formatting contract.
### Text Direction
The inspector follows its editor's interface direction: the editor's `Direction` when it is `LeftToRight` or `RightToLeft`, and the system language when it is `Automatic`. An inspector without an editor follows the system language. Changing the editor's `Direction` redraws the inspector.
In a right-to-left interface the inspector is mirrored. Captions are on the right and values on the left; values, Multiple Values, toggles, and color swatches start at the right edge of the value column; a menu's arrow is at its left, and its menu opens from the value's right edge. The inline text editors align right. Captions and values are drawn after a right-to-left mark, so text that starts with a number or Latin letters still reads right to left.
## Examples
Associate the inspector once and allow it to follow editor selection.
### Attach to an Editor
```xojo
Inspector1.InspectedEditor = Editor1
```