SuperEditor class

A rich text editor that displays a document in a single-column layout.

A SuperEditor brings together the key pieces needed to display a user-editable document:

  • An editor, which includes a document and a composer (which holds the user selection and styles).
  • A document layout, which positions components for every piece of content in the document.
  • User interactions with the document layout (tapping, dragging, typing, scrolling)

A SuperEditor applies visual styles based on:

  • stylesheet, which applies styles throughout the document layout, including text styles and block padding.
  • selectionStyles, which dictates the color of the caret and the color of selected text and components
  • componentStyles, which applies targeted styles to specific components in the document layout.
  • componentBuilders, which produce every visual component Widget within the document layout.

keyboardActions decides how physical keyboard key presses alter the document within a SuperEditor.

imePolicies, imeConfiguration, and softwareKeyboardController decide how user interactions with the operating system's Input Method Editor (IME) alters the document within a SuperEditor.

Deeper explanation of core artifacts:

A Document is responsible for holding the content of a document in a structured and query-able manner.

A DocumentComposer is responsible for holding the user's selection, as well as any inline text styles that should be applied as the user types.

An Editor is responsible for executing every request that alters a Document or DocumentComposer. The Editor provides hooks for reactions, which can further alter content after a command, such as parsing inline Markdown, or creating hash tags. The Editor implements undo/redo control.

A DocumentLayout is responsible for positioning and rendering the various visual components in the document. It's also responsible for linking logical document nodes to visual document components to facilitate user interactions like tapping and dragging.

Document interaction is responsible for taking appropriate actions in response to user taps, drags, and key presses.

Inheritance

Constructors

SuperEditor.new({Key? key, FocusNode? focusNode, bool autofocus = false, String? tapRegionGroupId, required Editor editor, @Deprecated("The document is now retrieved from the Editor. You should remove this property from your SuperEditor widget.") Document? document, @Deprecated("The composer is now retrieved from the Editor. You should remove this property from your SuperEditor widget.") DocumentComposer? composer, ScrollController? scrollController, GlobalKey<State<StatefulWidget>>? documentLayoutKey, Stylesheet? stylesheet, List<SingleColumnLayoutStylePhase> customStylePhases = const [], List<ComponentBuilder>? componentBuilders, SelectionStyles? selectionStyle, SuperEditorSelectionPolicies selectionPolicies = const SuperEditorSelectionPolicies(), TextInputSource? inputSource, SoftwareKeyboardController? softwareKeyboardController, SuperEditorImePolicies imePolicies = const SuperEditorImePolicies(), SuperEditorImeConfiguration? imeConfiguration, DeltaTextInputClientDecorator? imeOverrides, ValueNotifier<bool>? isImeConnected, List<DocumentKeyboardAction>? keyboardActions, Map<String, SuperEditorSelectorHandler>? selectorHandlers, DocumentGestureMode? gestureMode, List<SuperEditorContentTapDelegateFactory>? contentTapDelegateFactories = const [superEditorLaunchLinkTapHandlerFactory], SelectionLayerLinks? selectionLayerLinks, List<SuperEditorLayerBuilder> documentUnderlayBuilders = const [], List<SuperEditorLayerBuilder> documentOverlayBuilders = defaultSuperEditorDocumentOverlayBuilders, MagnifierAndToolbarController? overlayController, Color? androidHandleColor, WidgetBuilder? androidToolbarBuilder, Color? iOSHandleColor, WidgetBuilder? iOSToolbarBuilder, CustomClipper<Rect> createOverlayControlsClipper(BuildContext overlayContext)?, Set<SuperEditorPlugin> plugins = const {}, DebugPaintConfig debugPaint = const DebugPaintConfig(), bool shrinkWrap = false})
Creates a Super Editor with common (but configurable) defaults for visual components, text styles, and user interaction.

Properties

androidHandleColor → Color?
Color of the text selection drag handles on Android.
final
androidToolbarBuilder → WidgetBuilder?
Builder that creates a floating toolbar when running on Android.
final
autofocus → bool
Whether or not the SuperEditor should autofocus upon initial display.
final
componentBuilders → List<ComponentBuilder>
Priority list of widget factories that create instances of each visual component displayed in the document layout, e.g., paragraph component, image component, horizontal rule component, etc.
final
composer → DocumentComposer?
Owns the editor's current selection, the current attributions for text input, and other transitive editor configurations.
final
contentTapDelegateFactories → List<SuperEditorContentTapDelegateFactory>?
List of factories that creates a ContentTapDelegate, which is given an opportunity to respond to taps on content before the editor, itself.
final
createOverlayControlsClipper → CustomClipper<Rect> Function(BuildContext overlayContext)?
Creates a clipper that applies to overlay controls, like drag handles, magnifiers, and popover toolbars, preventing the overlay controls from appearing outside the given clipping region.
final
customStylePhases → List<SingleColumnLayoutStylePhase>
Custom style phases that are added to the standard style phases.
final
debugPaint → DebugPaintConfig
Paints some extra visual ornamentation to help with debugging.
final
document → Document?
The Document that's edited by the editor.
final
documentLayoutKey → GlobalKey<State<StatefulWidget>>?
GlobalKey that's bound to the DocumentLayout within this SuperEditor.
final
documentOverlayBuilders → List<SuperEditorLayerBuilder>
Layers that are displayed on top of the document layout, aligned with the location and size of the document layout.
final
documentUnderlayBuilders → List<SuperEditorLayerBuilder>
Layers that are displayed under the document layout, aligned with the location and size of the document layout.
final
editor → Editor
An editing pipeline, which is responsible for all changes made to a document from this SuperEditor.
final
focusNode → FocusNode?
FocusNode for the entire SuperEditor.
final
gestureMode → DocumentGestureMode?
The SuperEditor gesture mode, e.g., mouse or touch.
final
hashCode → int
The hash code for this object.
no setterinherited
imeConfiguration → SuperEditorImeConfiguration?
Preferences for how the platform IME should look and behave during editing.
final
imeOverrides → DeltaTextInputClientDecorator?
Overrides for IME actions.
final
imePolicies → SuperEditorImePolicies
Policies that dictate when and how SuperEditor should interact with the platform IME, such as automatically opening the software keyboard when SuperEditor's selection changes.
final
inputSource → TextInputSource?
The SuperEditor input source, e.g., keyboard or Input Method Engine.
final
iOSHandleColor → Color?
Color of the text selection drag handles on iOS.
final
iOSToolbarBuilder → WidgetBuilder?
Builder that creates a floating toolbar when running on iOS.
final
isImeConnected → ValueNotifier<bool>?
A (optional) notifier that's notified when the IME connection opens or closes.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
keyboardActions → List<DocumentKeyboardAction>?
All actions that this editor takes in response to key events, e.g., text entry, newlines, character deletion, copy, paste, etc.
final
overlayController → MagnifierAndToolbarController?
Shows, hides, and positions a floating toolbar and magnifier.
final
plugins → Set<SuperEditorPlugin>
Plugins that add sets of behaviors to the editing experience.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollController → ScrollController?
The ScrollController that governs this SuperEditor's scroll offset.
final
Leader links that connect leader widgets near the user's selection to carets, handles, and other things that want to follow the selection.
final
selectionPolicies → SuperEditorSelectionPolicies
Policies that determine how selection is modified by other factors, such as gaining or losing focus.
final
selectionStyles → SelectionStyles
Styles applied to selected content.
final
selectorHandlers → Map<String, SuperEditorSelectorHandler>?
Handlers for all Mac OS "selectors" reported by the IME.
final
shrinkWrap → bool
Whether the scroll view used by the editor should shrink-wrap its contents. Only used when editor is not inside an scrollable.
final
softwareKeyboardController → SoftwareKeyboardController?
Opens and closes the software keyboard.
final
stylesheet → Stylesheet
Style rules applied through the document presentation.
final
tapRegionGroupId → String?
A group ID for a tap region that surrounds the editor and also surrounds any related widgets, such as drag handles and a toolbar.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → SuperEditorState
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited