Class CanvasControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A free-form drawing surface control that exposes CharacterBuffer drawing primitives through a local-coordinate API. Supports both async/on-demand painting via BeginPaint()/EndPaint() and event-driven painting via the Paint event. Both modes can be combined.

public class CanvasControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable

Inheritance

object

BaseControl

CanvasControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

Inherited Members

BaseControl.PropertyChanged

BaseControl.GotFocus

BaseControl.LostFocus

BaseControl.Bindings

BaseControl.OnPropertyChanged(string)

BaseControl.SubscribeToFocusManager()

BaseControl.SetProperty<T>(ref T, T, string)

BaseControl.SetProperty<T>(ref T, T, Func<T, T>, string)

BaseControl.ActualX

BaseControl.ActualY

BaseControl.ActualWidth

BaseControl.ActualHeight

BaseControl.HorizontalAlignment

BaseControl.VerticalAlignment

BaseControl.Container

BaseControl.Margin

BaseControl.StickyPosition

BaseControl.Name

BaseControl.Tag

BaseControl.Visible

BaseControl.Width

BaseControl.Height

BaseControl.GetLogicalContentSize()

BaseControl.Invalidate()

BaseControl.SetActualBounds(LayoutRect)

BaseControl.Dispose()

BaseControl.ComputeHasFocus()

BaseControl.ComputeIsInFocusPath()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BindingExtensions.BindTwoWay<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.Bind<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

Constructors

CanvasControl()

Initializes a new CanvasControl with default dimensions.

public CanvasControl()

CanvasControl(int, int)

Initializes a new CanvasControl with the specified dimensions.

public CanvasControl(int canvasWidth, int canvasHeight)

Parameters

canvasWidth int

The initial canvas width in characters.

canvasHeight int

The initial canvas height in characters.

Properties

AutoClear

When true, the internal buffer is cleared after compositing each frame, so the Paint event redraws from scratch. Default is false (retained mode).

public bool AutoClear { get; set; }

Property Value

bool

AutoSize

When true, the internal buffer automatically resizes to match the layout bounds assigned by the parent container. Enable this when using Stretch/Fill alignment so the canvas adapts to the available window space.

public bool AutoSize { get; set; }

Property Value

bool

BackgroundColor

Gets or sets the background color. Falls back to container, then black.

public Color BackgroundColor { get; set; }

Property Value

Color

CanFocusWithMouse

Whether this control can receive focus via mouse clicks

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

Whether this control can receive focus

public bool CanReceiveFocus { get; }

Property Value

bool

CanvasHeight

Gets or sets the canvas height in characters. Clamped to MinCanvasSize. Setting this recreates the internal buffer (previous content is lost).

public int CanvasHeight { get; set; }

Property Value

int

CanvasWidth

Gets or sets the canvas width in characters. Clamped to MinCanvasSize. Setting this recreates the internal buffer (previous content is lost).

public int CanvasWidth { get; set; }

Property Value

int

ContentWidth

Gets the minimum width needed to display the control's content, including margins. Returns null if width cannot be determined. This is calculated based on content (text length, child controls, etc.) and represents the natural/intrinsic size.

public override int? ContentWidth { get; }

Property Value

int?

ForegroundColor

Gets or sets the foreground color. Falls back to container, then white.

public Color ForegroundColor { get; set; }

Property Value

Color

HasFocus

public bool HasFocus { get; }

Property Value

bool

IsEnabled

Gets or sets whether the control is enabled and can receive input.

public bool IsEnabled { get; set; }

Property Value

bool

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

Methods

BeginPaint()

Returns a CanvasGraphics wrapping the internal buffer for async drawing. Must be paired with EndPaint(). Thread-safe via monitor lock.

public CanvasGraphics BeginPaint()

Returns

CanvasGraphics

A drawing context for the internal canvas buffer.

Clear()

Clears the internal buffer with the control's background color.

public void Clear()

Clear(Color)

Clears the internal buffer with the specified background color.

public void Clear(Color bg)

Parameters

bg Color

The background color to fill with.

EndPaint()

Releases the paint lock and triggers a repaint.

public void EndPaint()

MeasureDOM(LayoutConstraints)

Measures the control's desired size given the available constraints.

public override LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

The layout constraints (min/max width/height).

Returns

LayoutSize

The desired size of the control.

OnDisposing()

Called during Dispose() before Container is set to null. Override to perform control-specific cleanup (null events, close portals, clear data, etc.).

protected override void OnDisposing()

PaintDOM(CharacterBuffer, LayoutRect, LayoutRect, Color, Color)

Paints the control's content directly to a CharacterBuffer.

public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect, Color defaultForeground, Color defaultBackground)

Parameters

buffer CharacterBuffer

The buffer to paint to.

bounds LayoutRect

The absolute bounds where the control should paint.

clipRect LayoutRect

The clipping rectangle (visible area).

defaultForeground Color

The default foreground color from the container.

defaultBackground Color

The default background color from the container.

ProcessKey(ConsoleKeyInfo)

Processes a keyboard input event.

public bool ProcessKey(ConsoleKeyInfo key)

Parameters

key ConsoleKeyInfo

The key information for the pressed key.

Returns

bool

True if the key was handled by this control; otherwise, false.

ProcessMouseEvent(MouseEventArgs)

Processes a mouse event for this control

public bool ProcessMouseEvent(MouseEventArgs args)

Parameters

args MouseEventArgs

Mouse event arguments with control-relative coordinates

Returns

bool

True if the event was handled and should not propagate further

Refresh()

Triggers a repaint without painting.

public void Refresh()

Events

CanvasKeyPressed

Fires when a key is pressed while the canvas has focus.

public event EventHandler<ConsoleKeyInfo>? CanvasKeyPressed

Event Type

EventHandler<ConsoleKeyInfo>

CanvasMouseClick

Fires when the canvas is left-clicked, with canvas-local coordinates.

public event EventHandler<CanvasMouseEventArgs>? CanvasMouseClick

Event Type

EventHandler<CanvasMouseEventArgs>

CanvasMouseMove

Fires when the mouse moves over the canvas, with canvas-local coordinates.

public event EventHandler<CanvasMouseEventArgs>? CanvasMouseMove

Event Type

EventHandler<CanvasMouseEventArgs>

CanvasMouseRightClick

Fires when the canvas is right-clicked, with canvas-local coordinates.

public event EventHandler<CanvasMouseEventArgs>? CanvasMouseRightClick

Event Type

EventHandler<CanvasMouseEventArgs>

MouseClick

Event fired when the control is clicked

public event EventHandler<MouseEventArgs>? MouseClick

Event Type

EventHandler<MouseEventArgs>

MouseDoubleClick

Event fired when the control is double-clicked

public event EventHandler<MouseEventArgs>? MouseDoubleClick

Event Type

EventHandler<MouseEventArgs>

MouseEnter

Event fired when the mouse enters the control area

public event EventHandler<MouseEventArgs>? MouseEnter

Event Type

EventHandler<MouseEventArgs>

MouseLeave

Event fired when the mouse leaves the control area

public event EventHandler<MouseEventArgs>? MouseLeave

Event Type

EventHandler<MouseEventArgs>

MouseMove

Event fired when the mouse moves over the control

public event EventHandler<MouseEventArgs>? MouseMove

Event Type

EventHandler<MouseEventArgs>

MouseRightClick

Event fired when the control is right-clicked (Button3)

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>

Paint

Fires during each render cycle after the internal buffer is composited. The Graphics context draws directly to the window buffer.

public event EventHandler<CanvasPaintEventArgs>? Paint

Event Type

EventHandler<CanvasPaintEventArgs>