Class MarkupControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A control that displays rich text content using Spectre.Console markup syntax. Supports text alignment, margins, word wrapping, and sticky positioning.

public class MarkupControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IMouseAwareControl, ICopyableControl, ISelectableControl, IFocusableControl, IWindowControl, IDisposable, IInteractiveControl, IDragAutoScrollTarget, IColorRoleableControl

Inheritance

object

BaseControl

MarkupControl

Implements

IDOMPaintable

INotifyPropertyChanged

IMouseAwareControl

ICopyableControl

ISelectableControl

IFocusableControl

IWindowControl

IDisposable

IInteractiveControl

IDragAutoScrollTarget

IColorRoleableControl

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.Invalidate(Invalidation)

BaseControl.Invalidate()

BaseControl.Invalidate(bool)

BaseControl.SetActualBounds(LayoutRect)

BaseControl.Dispose()

BaseControl.OnDisposing()

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

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

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>)

Constructors

MarkupControl(List<string>)

Initializes a new instance of the MarkupControl class with the specified lines of text.

public MarkupControl(List<string> lines)

Parameters

lines List<string>

The lines of text to display, supporting Spectre.Console markup syntax.

Properties

BackgroundColor

Gets or sets the background color for the control. If null, uses container's background color. When set with HorizontalAlignment.Stretch, this color will fill the entire width.

public Color? BackgroundColor { get; set; }

Property Value

Color?

Border

Optional border drawn around the markup. None (default) = no border.

public BorderStyle Border { get; set; }

Property Value

BorderStyle

BorderColor

Border color. Null falls back to the ColorRole border / foreground.

public Color? BorderColor { get; set; }

Property Value

Color?

CanFocusWithMouse

Gets whether a mouse click on this control grants it focus. True only when the control is focusable for the same reason it is Tab-focusable — visible, enabled, and containing at least one link (see CanReceiveFocus). A plain MarkupControl with no links is not a focus target and clicking it does not steal focus.

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

Gets whether this control can receive keyboard focus: only when visible, enabled, AND it has links.

public bool CanReceiveFocus { get; }

Property Value

bool

ColorRole

The semantic color role. Default = no role (normal resolution).

public ColorRole ColorRole { get; set; }

Property Value

ColorRole

ColorRoleMode

Optional ThemeMode override for role-colour derivation. When non-null, the role's dark/light seed colours are resolved as if the theme were in this mode, regardless of the theme's own Mode. When null (the default), the active theme's mode is used.

public ThemeMode? ColorRoleMode { get; set; }

Property Value

ThemeMode?

ContentWidth

Gets the actual rendered width of the control based on content.

public override int? ContentWidth { get; }

Property Value

int?

The maximum line width in characters.

CopyEnabled

Gets or sets whether the keyboard copy shortcut (default Ctrl+C) is enabled. Default: true. Programmatic copy via CopyToClipboard() / CopySelectionToClipboard() is unaffected by this setting.

public bool CopyEnabled { get; set; }

Property Value

bool

CopyKey

Gets or sets the key that triggers a copy. Default: C.

public ConsoleKey CopyKey { get; set; }

Property Value

ConsoleKey

CopyModifiers

Gets or sets the modifier keys required for the copy shortcut. Default: Control.

public ConsoleModifiers CopyModifiers { get; set; }

Property Value

ConsoleModifiers

DoubleClickEnabled

Gets or sets whether double-click events are enabled. Default: true.

public bool DoubleClickEnabled { get; set; }

Property Value

bool

DoubleClickThresholdMs

Gets or sets the double-click threshold in milliseconds. Default: 500ms, minimum: 100ms.

public int DoubleClickThresholdMs { get; set; }

Property Value

int

EnableSelection

Gets or sets whether mouse text selection (and Ctrl+C copy at the window level) is enabled. Default: false — when disabled the control behaves exactly as a display-only markup control.

public bool EnableSelection { get; set; }

Property Value

bool

FocusedLinkBackgroundColor

Gets or sets the background color used to highlight the keyboard-focused link. Null uses a default high-contrast color.

public Color? FocusedLinkBackgroundColor { get; set; }

Property Value

Color?

FocusedLinkForegroundColor

Gets or sets the foreground color used to highlight the keyboard-focused link. Null uses a default high-contrast color. (Used only when the control has focus and a link is focused.)

public Color? FocusedLinkForegroundColor { get; set; }

Property Value

Color?

ForegroundColor

Gets or sets the foreground (text) color for the control. If null, uses container's foreground color.

public Color? ForegroundColor { get; set; }

Property Value

Color?

HasFocus

Gets whether this control currently has focus.

public bool HasFocus { get; }

Property Value

bool

HasSelection

Gets whether this control currently has a non-empty text selection.

public bool HasSelection { get; }

Property Value

bool

Header

Optional header text rendered in the top border (only when bordered).

public string? Header { get; set; }

Property Value

string

HeaderAlignment

Horizontal alignment of the header text within the top border.

public TextJustification HeaderAlignment { get; set; }

Property Value

TextJustification

IsDragSelecting

True while a Button1 text-drag-select is in progress.

public bool IsDragSelecting { get; }

Property Value

bool

IsEnabled

Gets or sets whether this control is enabled for input.

public bool IsEnabled { get; set; }

Property Value

bool

IsViewportReady

True when the control has painted at least once and its viewport metrics are known. The autoscroll tick no-ops until this is true.

public bool IsViewportReady { get; }

Property Value

bool

LastDragRelativeY

The last drag Y in control-relative rows. May be negative (above the viewport top) or ≥ ViewportHeightRows (below the bottom) — that overshoot drives the scroll.

public int LastDragRelativeY { get; }

Property Value

int

MarkdownStyle

Optional per-control Markdown style for content set via SetMarkdown(string) or the [markdown] tag. When null, the global Default is used.

public MarkdownStyle? MarkdownStyle { get; set; }

Property Value

MarkdownStyle

Outline

When true and a role is set, renders outline style (role color on text + border, surface fill).

public bool Outline { get; set; }

Property Value

bool

Padding

Inner padding between the border (or edge) and the markup content.

public Padding Padding { get; set; }

Property Value

Padding

SelectionBackgroundColor

Gets or sets the background color used for selected text. Null uses a default highlight color.

public Color? SelectionBackgroundColor { get; set; }

Property Value

Color?

SelectionForegroundColor

Gets or sets the foreground color used for selected text. Null uses a default highlight color.

public Color? SelectionForegroundColor { get; set; }

Property Value

Color?

Text

Gets or sets the text content as a single string with newline separators.

public string Text { get; set; }

Property Value

string

TotalParseCount

Process-wide count of markup line-parses performed by all MarkupControls. A diagnostic: it stops climbing once the parse cache is warm (scrolling/drag-selecting static content) and only advances on a real content/width/colour change.

public static long TotalParseCount { get; }

Property Value

long

UseSafeBorder

Use ASCII-safe border characters for better terminal compatibility.

public bool UseSafeBorder { get; set; }

Property Value

bool

ViewportHeightRows

The control's effective visible viewport height, in rows.

public int ViewportHeightRows { get; }

Property Value

int

WantsMouseEvents

Gets whether this control wants to receive mouse events.

public bool WantsMouseEvents { get; }

Property Value

bool

WantsTabKey

We do not consume Tab; arrow keys navigate links. Default false so Tab traverses focus.

public bool WantsTabKey { get; }

Property Value

bool

Wrap

Gets or sets whether text should wrap to multiple lines when exceeding available width.

public bool Wrap { get; set; }

Property Value

bool

Methods

Append(string)

Appends markup to the end of the content without starting a new line, in the style of Append(string) / Console.Write: the text is joined onto the current last line, and a new line begins only at each embedded \n. Pairs with AppendLine(string).

public void Append(string text)

Parameters

text string

The text to append, supporting markup syntax. Embedded \n characters start new lines.

AppendInline(string)

Appends text to the current last line (Console.Write-style), starting new lines only at embedded \n characters. Equivalent to AppendText(string, bool) with inline: true.

public void AppendInline(string text)

Parameters

text string

The text to append. Embedded \n characters start new lines.

AppendLine(string)

Appends a single line of markup to the end of the content.

public void AppendLine(string line)

Parameters

line string

The line to append, supporting markup syntax.

AppendLines(IEnumerable<string>)

Appends multiple lines of markup to the end of the content.

public void AppendLines(IEnumerable<string> lines)

Parameters

lines IEnumerable<string>

The lines to append, supporting markup syntax.

AppendText(string, bool)

Appends text to the content, splitting on newlines into separate lines.

public void AppendText(string text, bool inline = false)

Parameters

text string

The text to append. Embedded \n characters start new lines.

inline bool

When false (the default), the appended text starts on a new line — each segment between \n characters becomes its own content line. When true, the first segment is joined onto the current last line (Console.Write-style), and a new line begins only at each embedded \n.

AutoScrollStep(int)

Scrolls by rows (sign = direction). The control chooses how (host IScrollableContainer, Window.ScrollBy, or its own offset) and clamps at the scroll extent. A no-op when no scrollable host exists.

public void AutoScrollStep(int rows)

Parameters

rows int

ClearSelection()

Clears the current selection. Does not notify the window manager (re-entrancy guard).

public void ClearSelection()

CopySelectionToClipboard()

Copies the current selection (plain text, markup stripped) to the clipboard. Returns true if something was copied.

public bool CopySelectionToClipboard()

Returns

bool

CopyToClipboard()

Copies the control's entire content (plain text, markup stripped) to the clipboard, regardless of the current selection. Returns true if something was copied.

public bool CopyToClipboard()

Returns

bool

Create()

Creates a fluent builder for constructing a MarkupControl.

public static MarkupBuilder Create()

Returns

MarkupBuilder

A new MarkupBuilder instance.

ExtendSelectionToRevealedEdge(int)

After a scroll step, extends the selection's end to the edge row now revealed: direction -1 = the new top row, +1 = the new bottom row. Computes the row from the post-scroll position arithmetically (never from the stale pre-paint cache).

public void ExtendSelectionToRevealedEdge(int direction)

Parameters

direction int

GetLogicalContentSize()

Gets the logical size of the control's content without rendering.

public override Size GetLogicalContentSize()

Returns

Size

The size representing the content's natural dimensions.

GetSelectedText()

Gets the selected text as plain text (markup stripped). Rows belonging to the same logical (source) line — i.e. produced by soft-wrapping — are joined without a line break; a newline is inserted only at genuine logical-line boundaries.

public string GetSelectedText()

Returns

string

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.

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 defaultFg, Color defaultBg)

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).

defaultFg Color

defaultBg Color

ProcessKey(ConsoleKeyInfo)

Keyboard handling for link navigation. Left/Right move between links (no wrap; at the first/last link the key bubbles by returning false). Enter activates the focused link. All other keys bubble.

public bool ProcessKey(ConsoleKeyInfo key)

Parameters

key ConsoleKeyInfo

The key to process.

Returns

bool

True if the key was consumed; false to let it bubble to the host.

ProcessMouseEvent(MouseEventArgs)

Processes mouse events for this control.

public bool ProcessMouseEvent(MouseEventArgs args)

Parameters

args MouseEventArgs

The mouse event arguments.

Returns

bool

True if the event was handled; otherwise, false.

SetContent(List<string>)

Sets the content of the control to the specified lines of text.

public void SetContent(List<string> lines)

Parameters

lines List<string>

The lines of text to display, supporting Spectre.Console markup syntax.

SetMarkdown(string)

Sets the control's content from Markdown. The content is wrapped in a [markdown] region and rendered through the markup pipeline; copied text remains plain.

public void SetMarkdown(string markdown)

Parameters

markdown string

The Markdown source to render.

Events

LinkClicked

Occurs when a click lands on a rendered link. The argument carries the link Url and visible Text.

public event EventHandler<LinkClickedEventArgs>? LinkClicked

Event Type

EventHandler<LinkClickedEventArgs>

MouseClick

Occurs when the control is clicked.

public event EventHandler<MouseEventArgs>? MouseClick

Event Type

EventHandler<MouseEventArgs>

MouseDoubleClick

Occurs when the control is double-clicked.

public event EventHandler<MouseEventArgs>? MouseDoubleClick

Event Type

EventHandler<MouseEventArgs>

MouseEnter

Occurs when the mouse enters the control area.

public event EventHandler<MouseEventArgs>? MouseEnter

Event Type

EventHandler<MouseEventArgs>

MouseLeave

Occurs when the mouse leaves the control area.

public event EventHandler<MouseEventArgs>? MouseLeave

Event Type

EventHandler<MouseEventArgs>

MouseMove

Occurs when the mouse moves over the control.

public event EventHandler<MouseEventArgs>? MouseMove

Event Type

EventHandler<MouseEventArgs>

MouseRightClick

Occurs when the control is right-clicked.

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>

SelectionChanged

Occurs when the selection changes. Argument is the selected plain text, or empty when cleared.

public event EventHandler<string>? SelectionChanged

Event Type

EventHandler<string>

TextSelectionChanged

Occurs when the selection changes, carrying both the selection state and the selected text. Richer companion to SelectionChanged; both fire together.

public event EventHandler<TextSelectionChangedEventArgs>? TextSelectionChanged

Event Type

EventHandler<TextSelectionChangedEventArgs>