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

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.