WinForms events, enums and data types

Documentation index

All types are in CODE.Editor.WinForms. The wrapper converts enum values to the JavaScript protocol, so ordinary .NET callers do not need magic strings.

Events

State notifications can occur frequently and need not correspond one-to-one with a user keystroke. During a native method call, the bridge suppresses intermediate browser events and returns accepted state with its reply. Therefore EditorEvent is not a complete unfiltered replication log of all JavaScript events.

For ordinary UI events such as SaveRequested, an async event handler is reasonable if it catches its exceptions. For result-producing preview/image events, assign Result synchronously to a Task. Do not await inside an async-void handler and then assign fields after the bridge has continued.

Event argument members

Without an image Result handler, an import fails with an instruction to handle the relevant event. Without a preview handler, the built-in renderer runs. A handled preview requires Html. Prefer one composed handler for a result-producing event, since competing assignments to Result are not independently composed by the control.

Data records

The constructor/property shapes are:

EditorSelection(int Anchor, int Head)
SearchMatch(int From, int To)
SearchOptions(bool CaseSensitive = false, bool WholeWord = false)
TextEdit(int From, int To, string Text)
EditorTransaction(string SessionId, int Revision, TextEdit[] Edits,
                  string Label = "Host transaction")
CommandState(bool Enabled, JsonElement Active)
EditorSnapshot(string Value, EditorFormat Format, EditorViewMode Mode,
               EditorLanguage Language, string SessionId, int Generation,
               int Revision, EditorSelection Selection, bool Dirty,
               JsonElement Policy)
EditorDiagnostic(string BlockId, string Feature, string Message, int? From)
ImageImportResult(string Src, string? AssetId = null, string? Alt = null)
PreviewRenderResult(string? Markdown = null, string? Html = null,
                    bool Handled = false)

These are record signatures, not executable declarations to paste without record/namespace context. JsonElement members preserve the dynamic protocol shape. For a mark state, Active can be Boolean or a mixed-state string; do not call GetBoolean unconditionally. Policy contains JavaScript-style property names, including the effective features object.

ImageImportResult.Src must be a durable accepted URL. AssetId is optional host identity, useful for ownership/cleanup bookkeeping. PreviewRenderResult with only Markdown asks for normal conversion; with Html and Handled true it bypasses conversion, while retaining preview sanitization/isolation.

Format and view enums

Native enums use explicit mappings in EditorWire.cs for serialization and deserialization. JavaScript uses javascript, TSql uses sql; unknown values are rejected. Package version, API/bridge contract version (the retained version: 3 ready field), and document schema version are independent. The reorganization does not change saved-document shapes.

Feature and formatting enums

ContentFont maps Default to no override, Serif to serif, and Monospace to mono. ContentColor Default clears the override. ContentFontSize numbers are supported CSS pixel values, not arbitrary named font sizes. BlockStyle Paragraph/BulletedList/NumberedList/ThematicBreak map to p/ul/ol/hr; heading names map to lowercase h1–h6.

Error handling pattern

SuggestionsRequested carries a typed SuggestionRequest, cancellation token and assignable Task<SuggestionItem[]> Result. ContextActionRequested carries a typed request, cancellation token, progress callback and assignable Task<ContextActionResult> Result. ReviewChanged signals companion-state updates. See extension/review records and examples.

Subscribe to EditorError for automatic initialization/property-update failures, and also catch exceptions from methods you explicitly await. LastError preserves the last reported exception. PreviewError is a separate signal for preview work. Pending image failure is also represented in the document; query pending images and let the user retry or remove the item.

Cancellation on disposal or obsolete preview work is expected lifecycle behavior. Do not present every cancellation as a failure dialog. Avoid silently ignoring genuine import/save failures, since a document with unresolved image state cannot be saved through the validated snapshot contract.

EditorExtensionOptions adds ToolbarPlacement and per-kind ToolbarPlacements. ReviewOptions adds Presentation (margin/panel) and MarginWidth (240–600). ReviewAnchorRect carries X/Y/Width/Height in current viewport coordinates. Details and examples are in chapter 20.

EditorUITheme carries Palette/Variables/Css; CommentPresentation carries Id/Expanded. ReviewOptions also supports SingleOpen and CommentMarkers. UIThemeChanged and CommentPresentationChanged report presentation changes; the latter uses EditorEventArgs.Data with id/expanded. These do not mark the article dirty. See chapter 21.

EditorUIStrings(string Locale = "en", Dictionary<string,string>? Values = null) provides text overrides; UIStringsChanged fires after a shared runtime wording update. See localization.

EditorLanguage.Xml maps to xml independently of EditorLanguage.Html (html). Both support markup syntax highlighting and default two-space indentation. The storage format remains a separate choice; XML Source does not acquire a Visual XML document model.