Vyuh Document

Objects and commands ​

Looking for the typed API?

This page covers the editor runtime (DocumentEditorController and the canonical model). For DocumentController, typed commands and Result, see Typed Document API.

Everyday calls read directly: controller.insertText('Hello') or controller.setParagraphAlignment(TextAlignment.center). Extension packages supply those methods.

Core objects ​

Core objects The editor controller and the headless workflow session each own one DocumentEngineSession. The session's setup holds the DocumentElementRegistry of installed elements, and it publishes one immutable DocumentEditorState. That state holds the Document, the selection, the text selection, the viewport bookmark, the caret's preferred x, the schema policy and the revision counters. The Document holds sections, sections hold blocks, and text blocks hold runs with marks. A DocumentSelection's base and extent are DocumentPositions: a block id and an offset. DocumentEditorController DocumentWorkflowSession headless, no widget owns owns DocumentEngineSession dispatches transactions undo · redo · history admits commands setup.elements DocumentElementRegistry installed elements · commands state ONE IMMUTABLE SNAPSHOT DocumentEditorState documentDocument selectionDocumentSelectionContext textSelectionDocumentSelection viewportBookmarkDocumentViewportBookmark preferredVisualXthe caret's remembered x schemaPolicyDocumentSchemaPolicy revisioncontentRevision state.document Document what you save DocumentSection format · blocks DocumentBlock semantic content TextRun TextMark DocumentPosition blockId · offset a selection's base and extent
Core objects and how they relate
ObjectRole
DocumentImmutable content: sections, styles, notes, review records. The value you save.
DocumentEditorStateOne snapshot: document, selection, viewport bookmark, revision.
DocumentEditorControllerEdits, selection, undo and redo; connects your app.
DocumentWorkflowSessionThe same editing without a widget.
DocumentPosition / DocumentSelectionA block ID and offset; a base and extent.

Pages are derived from the document. Address content by ID and logical position, not by page or widget coordinates.

Start with paragraphs ​

dart
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
import 'package:vyuh_document/paragraph_extension.dart';

final controller = DocumentEditorController.richText(
  layoutMode: DocumentEditorLayoutMode.pageless,
);
controller.insertText('Hello');

// Mount inside your own bounded widget; no workspace shell is required.
DocumentEditor(
  controller: controller,
  configuration: DocumentEditorConfiguration.richText(),
);

Keep the controller in host state and dispose it with that state. The controller decides what can be edited; the configuration decides how it looks. Pass extensions and schema for a broader editor; the default constructor installs the full set. See the tutorial.

Configure the experience ​

DecisionAPI
ContentDocumentEditorController.richText() for paragraphs; extensions and schema for more. Fixed for the controller's lifetime.
LayoutlayoutMode at construction: paginated (default) or pageless. Use paged mode for headers, footers, notes and sections.
ControlsDocumentEditorConfiguration: toolbar, inspector, shortcuts, context menu. Hiding a control keeps the content capability.

See extension composition and toolbar configuration.

Extension-owned methods ​

Owner packageExamples of methods made visible by its import
vyuh_document (paragraph_extension.dart)insertText, deleteBackward, splitBlock, insertParagraph, insertHeading, toggleMark, setParagraphAlignment, setLink, requestLink
vyuh_document_extension_codeinsertCodeBlock, setCodeLanguage, setCodeBlockPresentation
vyuh_document_extension_checklistinsertChecklistItem, setChecklistChecked
vyuh_document_extension_listinsertListItem, setListMarker, setListNumberingSequence
vyuh_document_extension_tableinsertTable, insertRowBelow, setCellPadding, setTableAlignment
vyuh_document_extension_imageinsertImage, setImageSize, setImageFit, insertImageCaption, requestPictureChange
vyuh_document_extension_fieldinsertInlineField, insertFootnote, insertEndnote
vyuh_document_extension_block_quoteinsertBlockQuote, setBlockQuoteTone, setBlockQuotePadding
vyuh_document_extension_dividerinsertDivider, setDividerFormat
vyuh_document_extension_text_boxinsertTextBox
vyuh_document_extension_shapeinsertShape
vyuh_document_extension_table_of_contentsinsertTableOfContents, setSelectedTableOfContentsConfig
vyuh_document_extension_mermaidinsertMermaid, setMermaidGeometry, replaceMermaid
vyuh_document_extension_katexinsertEquation, setEquationGeometry, replaceEquation
vyuh_document_extension_diagraminsertDiagram, setDiagramGeometry, replaceDiagram

Import the families whose methods your code uses; the editor barrel does not re-export them. Commands act on the current selection, or on the next typing when the selection is a caret.

Import visibility and runtime availability ​

An import makes a method visible; installing its DocumentExtension makes it run. Calling a command that is not installed throws DocumentCommandUnavailableException and changes nothing.

Generic controls can take a DocumentCommandTarget (implemented by the controller) and test hasCommand(TableDocumentCommands.insertTable) before offering an action. undo, redo, replaceDocument, selection and transaction live on the controller itself.

For multi-step edits, use transactions.

Next ​