Class EditorSession

Namespace

Icy.Design.Editor

Assembly

IcyUI.Design.dll

The headless part of the design-time editor for one Canvas: the selection, the Edit/Interact mode, hit resolution, and (through Commands and the gesture methods) every edit the editor makes.

public sealed class EditorSession : IDisposable

Inheritance

object

EditorSession

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

PropertyReferencesExtensions.ContainsProperty(object, IPropertyReference)

Remarks

The session works across every DesignDocument whose pages are on the canvas. Each gesture and command becomes MarkupEditor operations, so undo, saving and hot reload work as for any other edit.

Dispose() removes only the editor's own footprint: its key bindings, and the focus and navigation state it changed. Edits are never rolled back; save the documents through Save() before or after detaching.

The visual frame (EditorFrame) is built on top of a session. Tools such as an outline panel can share the same session, and therefore the same selection.

A canvas takes one session at a time; see FindAttached(Canvas).

Properties

Bindings

Gets the key gestures bound to Commands. Rebind them before or after attaching.

public EditorBindings Bindings { get; }

Property Value

EditorBindings

BlockedReason

Gets why IsBlocked is true, or null.

public string? BlockedReason { get; }

Property Value

string

Canvas

Gets the canvas this editor works on.

public Canvas Canvas { get; }

Property Value

Canvas

Commands

Gets the editor's actions as commands.

public EditorCommands Commands { get; }

Property Value

EditorCommands

Design

Gets the design session whose documents this editor edits.

public DesignSession Design { get; }

Property Value

DesignSession

IsBlocked

Gets a value indicating whether the selected element's document can't take edits right now, because its text has errors or the live page couldn't follow it (see IsInSync). Selection, undo and redo still work; gestures and editing commands are refused.

public bool IsBlocked { get; }

Property Value

bool

LargeNudge

Gets or sets how far the large nudges move, in layout units. Defaults to 10.

public int LargeNudge { get; set; }

Property Value

int

LastEdited

Gets the document the last gesture or command edited, or null. Undo and redo use it when nothing is selected.

public DesignDocument? LastEdited { get; }

Property Value

DesignDocument

Mode

Gets or sets the editor's mode.

public EditorMode Mode { get; set; }

Property Value

EditorMode

Remarks

• Entering Edit remembers and clears the canvas's focused element, so no text box takes typing, and sets IsKeyboardNavigationEnabled to false.
• Entering Interact puts both back; the focus only when that element is still on the canvas.

Exceptions

ObjectDisposedException

The session was disposed.

Placement

Gets the placement strategies, by container type. Register strategies for custom containers here.

public PlacementRegistry Placement { get; }

Property Value

PlacementRegistry

Scope

Gets the subtree this editor is limited to, or null when it edits the whole canvas.

public UIElement? Scope { get; }

Property Value

UIElement

Remarks

The editor sees only the scope's visible area: its bounds, clipped by every ancestor that clips and by the canvas surface. HitTest(Point) finds nothing outside that area, and Select(UIElement) refuses elements that are neither in the scope nor in a canvas overlay (the page's popups and dialogs).

The keyboard is not scoped: in Edit the editor's key bindings stay canvas-wide.

The scope is fixed for the session's lifetime; dispose the session and attach a new one to change it.

Selection

Gets the selected element, or null.

public EditorSelection? Selection { get; }

Property Value

EditorSelection

Methods

Attach(DesignSession, Canvas)

Attaches an editor to the whole of canvas, in Edit.

public static EditorSession Attach(DesignSession design, Canvas canvas)

Parameters

design DesignSession

The design session tracking the canvas's pages.

canvas Canvas

The canvas to edit.

Returns

EditorSession

The session; dispose it to detach.

Exceptions

ArgumentNullException

design or canvas is null.

InvalidOperationException

Another session is attached to canvas.

Attach(DesignSession, Canvas, UIElement?)

Attaches an editor to canvas, limited to scope, in Edit.

public static EditorSession Attach(DesignSession design, Canvas canvas, UIElement? scope)

Parameters

design DesignSession

The design session tracking the canvas's pages.

canvas Canvas

The canvas to edit.

scope UIElement

The subtree to edit (see Scope), or null for the whole canvas.

Returns

EditorSession

The session; dispose it to detach.

Remarks

A canvas takes one session at a time: two would both bind the editor's keys and fight over the focus and navigation state. Check FindAttached(Canvas) first when another tool might hold the canvas.

Exceptions

ArgumentNullException

design or canvas is null.

ArgumentException

scope is not on canvas.

InvalidOperationException

Another session is attached to canvas.

BeginMove(Point)

Starts moving the selected element from screenPoint.

public MoveGesture? BeginMove(Point screenPoint)

Parameters

screenPoint Point

Where the pointer went down, in screen space.

Returns

MoveGesture

The gesture, or null when nothing is selected, the selection is the root, or the session is IsBlocked.

Exceptions

ObjectDisposedException

The session was disposed.

BeginResize(ResizeHandle, Point)

Starts resizing the selected element from one of its handles.

public ResizeGesture? BeginResize(ResizeHandle handle, Point screenPoint)

Parameters

handle ResizeHandle

The dragged handle.

screenPoint Point

Where the pointer went down, in screen space.

Returns

ResizeGesture

The gesture, or null when nothing is selected or the session is IsBlocked.

Exceptions

ObjectDisposedException

The session was disposed.

Clear()

Clears the selection.

public void Clear()

DeleteSelection()

Removes the selected element and clears the selection.

public EditResult DeleteSelection()

Returns

EditResult

The outcome; a failure for the root, when nothing is selected, or while IsBlocked.

Exceptions

ObjectDisposedException

The session was disposed.

Dispose()

Detaches the editor: restores the canvas's focus and navigation, and stops watching documents. Edits stay.

public void Dispose()

FindAttached(Canvas)

Finds the editor session attached to canvas.

public static EditorSession? FindAttached(Canvas canvas)

Parameters

canvas Canvas

The canvas.

Returns

EditorSession

The attached session, or null when there's none.

Exceptions

ArgumentNullException

canvas is null.

HitTest(Point)

Finds the element under a screen point the way the editor sees the canvas: past the editor's own layers, but including the page's popups and dialogs, and only inside the Scope's visible area.

public UIElement? HitTest(Point screenPoint)

Parameters

screenPoint Point

A point in screen space, where pointer positions arrive.

Returns

UIElement

The topmost hit element, or null.

Nudge(int, int)

Moves the selected element by its margin, alignment-aware, in any container.

public EditResult Nudge(int dx, int dy)

Parameters

dx int

The horizontal offset, in layout units.

dy int

The vertical offset, in layout units.

Returns

EditResult

The outcome; a failure when nothing is selected or the session is IsBlocked.

Exceptions

ObjectDisposedException

The session was disposed.

ResolveSelectable(UIElement?)

Finds the element a click on hit selects: the nearest element, from hit up through its visual parents, that a tracked document owns and can edit.

public UIElement? ResolveSelectable(UIElement? hit)

Parameters

hit UIElement

The element under the pointer, or null.

Returns

UIElement

The selectable element, or null when there's none.

Remarks

A control's template parts and an items control's generated containers aren't elements of the document (or are opaque inside a property element), so a click on them selects the control that owns them.

Select(DesignDocument, NodeId)

Selects a document's element, picking its first live copy in the editor's scope on this canvas.

public void Select(DesignDocument document, NodeId node)

Parameters

document DesignDocument

The document.

node NodeId

The element's node.

Exceptions

ArgumentNullException

document is null.

ArgumentException

The element has no live copy in the editor's Scope on this canvas, or can't be edited.

ObjectDisposedException

The session was disposed.

Select(UIElement)

Selects instance.

public bool Select(UIElement instance)

Parameters

instance UIElement

A live element.

Returns

bool

false, changing nothing, when no tracked document can edit it, or when it's outside the Scope and not in an overlay.

Exceptions

ObjectDisposedException

The session was disposed.

Events

BlockedChanged

Occurs when IsBlocked or BlockedReason changed.

public event EventHandler? BlockedChanged

Event Type

EventHandler

ModeChanged

Occurs when Mode changed.

public event EventHandler? ModeChanged

Event Type

EventHandler

SelectionChanged

Occurs when Selection changed, including when its live instance was rebuilt.

public event EventHandler? SelectionChanged

Event Type

EventHandler