Class ScrollablePanelControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A scrollable panel control that can host child controls with automatic scrolling support. Supports vertical and horizontal scrolling, mouse wheel, and visual scrollbars.

public class ScrollablePanelControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable, IContainer, IContainerControl, IControlHost, IScrollableContainer, IFocusScope, ILogicalCursorProvider, IColorRoleableControl

Inheritance

object

BaseControl

ScrollablePanelControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

IContainer

IContainerControl

IControlHost

IScrollableContainer

IFocusScope

ILogicalCursorProvider

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

BaseControl.Invalidate(Invalidation)

BaseControl.Invalidate()

BaseControl.Invalidate(bool)

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

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

ScrollablePanelControl()

Initializes a new instance of the ScrollablePanelControl class.

public ScrollablePanelControl()

Properties

ArrowKeyScrolling

Gets or sets whether arrow / page / home-end keys scroll the viewport. When false, those keys are left unhandled by ProcessKey(ConsoleKeyInfo) so they can bubble to an owning control that wants them for its own navigation (e.g. the NavigationView nav pane, which moves the selected item on arrows and relies on focus-driven auto-scroll to keep it visible). Mouse-wheel scrolling and the scrollbar are unaffected. Defaults to true.

public bool ArrowKeyScrolling { get; set; }

Property Value

bool

AutoScroll

Gets or sets whether to automatically scroll to bottom when content is added. When enabled, scrolls to bottom on AddControl if currently at/near bottom. Disables automatically when user scrolls up, re-enables when user scrolls to bottom.

public bool AutoScroll { get; set; }

Property Value

bool

BackgroundColor

Gets or sets the background color for the container and its child controls.

public Color BackgroundColor { get; set; }

Property Value

Color

BorderColor

Gets or sets the border color. When null, uses the foreground color.

public Color? BorderColor { get; set; }

Property Value

Color?

BorderStyle

Gets or sets the border style for the panel. Default is None (no border).

public BorderStyle BorderStyle { get; set; }

Property Value

BorderStyle

CanFocusWithMouse

Whether this control can receive focus via mouse clicks

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

ScrollablePanel is focusable when it has anything to interact with: either scrollable content or focusable children. The panel acts as an opaque focus container — it owns its children's focus lifecycle entirely.

public bool CanReceiveFocus { get; }

Property Value

bool

CanScrollDown

Gets whether the content can be scrolled downward (more content exists below the viewport).

public bool CanScrollDown { get; }

Property Value

bool

CanScrollLeft

Gets whether the content can be scrolled left (horizontal offset is greater than zero).

public bool CanScrollLeft { get; }

Property Value

bool

CanScrollRight

Gets whether the content can be scrolled right (more content exists beyond the visible content width). The visible width excludes the vertical scrollbar columns, so the last columns of content remain reachable even when a vertical scrollbar is present.

public bool CanScrollRight { get; }

Property Value

bool

CanScrollUp

Gets whether the content can be scrolled upward (vertical offset is greater than zero).

public bool CanScrollUp { get; }

Property Value

bool

Children

Gets the collection of child controls.

public IReadOnlyList<IWindowControl> Children { get; }

Property Value

IReadOnlyList<IWindowControl>

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?

ContentHeight

public int? ContentHeight { get; }

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?

EnableMouseWheel

Gets or sets whether mouse wheel scrolling is enabled.

public bool EnableMouseWheel { get; set; }

Property Value

bool

ForceReceiveFocus

When true, forces CanReceiveFocus to return true regardless of whether the panel has scrollable content or focusable children. Use this when the panel must be focusable as a scroll/container target even when its children are non-interactive (e.g., the NavigationView nav pane).

public bool ForceReceiveFocus { get; set; }

Property Value

bool

ForegroundColor

Gets or sets the foreground (text) color for the container and its child controls.

public Color ForegroundColor { get; set; }

Property Value

Color

GetConsoleWindowSystem

Gets the console window system instance, or null if not attached to a window system.

public ConsoleWindowSystem? GetConsoleWindowSystem { get; }

Property Value

ConsoleWindowSystem

HasFocus

public bool HasFocus { get; }

Property Value

bool

HasHorizontalScrollbar

Gets whether a horizontal scrollbar is currently shown: scrollbars are enabled, the horizontal scroll mode is Scroll, and content overflows the (vertical-scrollbar-reduced) viewport width.

public bool HasHorizontalScrollbar { get; }

Property Value

bool

HasVerticalScrollbar

Gets whether a vertical scrollbar is currently shown: scrollbars are enabled, the vertical scroll mode is Scroll, and content overflows the (horizontal- scrollbar-reduced) viewport height.

public bool HasVerticalScrollbar { get; }

Property Value

bool

Header

Gets or sets the header text displayed in the top border.

public string? Header { get; set; }

Property Value

string

HeaderAlignment

Gets or sets the alignment of the header text.

public TextJustification HeaderAlignment { get; set; }

Property Value

TextJustification

Height

Gets or sets the explicit height of the control, or null for automatic sizing.

public override int? Height { get; set; }

Property Value

int?

HorizontalScrollMode

Gets or sets the horizontal scroll mode.

public ScrollMode HorizontalScrollMode { get; set; }

Property Value

ScrollMode

HorizontalScrollOffset

Gets the current horizontal scroll offset in characters.

public int HorizontalScrollOffset { get; }

Property Value

int

IsEnabled

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

public bool IsEnabled { get; set; }

Property Value

bool

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

Gets or sets the padding inside the border.

public Padding Padding { get; set; }

Property Value

Padding

SavedFocus

Saved focus position. FocusManager sets this before exiting the scope (if scope opts in). GetInitialFocus should return this when set, then clear it.

public IFocusableControl? SavedFocus { get; set; }

Property Value

IFocusableControl

ScrollbarColor

Gets or sets the scrollbar track color. When null (the default), the track uses the built-in focus-aware default (lighter when focused, darker when not).

public Color? ScrollbarColor { get; set; }

Property Value

Color?

ScrollbarOverlay

When true, the vertical scrollbar is painted on the panel's border instead of reserving an interior column, freeing that space for content. Only takes effect when the panel has a border; a borderless panel falls back to the normal reserved-column scrollbar. Default false. Orthogonal to ScrollbarPosition (overlays whichever side).

public bool ScrollbarOverlay { get; set; }

Property Value

bool

ScrollbarPosition

Gets or sets the position of the scrollbar.

public ScrollbarPosition ScrollbarPosition { get; set; }

Property Value

ScrollbarPosition

ScrollbarThumbColor

Gets or sets the scrollbar thumb (handle and arrow) color. When null (the default), the thumb uses the built-in focus-aware default (cyan when focused, grey when not).

public Color? ScrollbarThumbColor { get; set; }

Property Value

Color?

ShowScrollbar

Gets or sets whether to show the scrollbar.

public bool ShowScrollbar { get; set; }

Property Value

bool

TotalContentHeight

Gets the total height of the scrollable content area in lines. Unlike ContentHeight (which returns the control's own height), this returns the height of the inner content that may extend beyond the viewport.

public int TotalContentHeight { get; }

Property Value

int

TotalContentWidth

Gets the total width of the scrollable content area in characters. Unlike ContentWidth (which returns the control's own width), this returns the width of the inner content that may extend beyond the viewport.

public int TotalContentWidth { get; }

Property Value

int

VerticalScrollMode

Gets or sets the vertical scroll mode.

public ScrollMode VerticalScrollMode { get; set; }

Property Value

ScrollMode

VerticalScrollOffset

Gets the current vertical scroll offset in lines.

public int VerticalScrollOffset { get; }

Property Value

int

ViewportHeight

Gets the height of the visible viewport area in lines.

public int ViewportHeight { get; }

Property Value

int

ViewportWidth

Gets the width of the visible viewport area in characters.

public int ViewportWidth { get; }

Property Value

int

Visible

Gets or sets whether this control is visible.

public override bool Visible { get; set; }

Property Value

bool

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

Methods

AddControl(IWindowControl)

Adds a child control to the panel. This method is not thread-safe and must be called from the UI thread. For multi-threaded scenarios, queue additions and process them during paint.

public void AddControl(IWindowControl control)

Parameters

control IWindowControl

ClearContents()

Removes all child controls from the panel.

public void ClearContents()

Create()

Creates a new builder for configuring a ScrollablePanelControl

public static ScrollablePanelBuilder Create()

Returns

ScrollablePanelBuilder

A new builder instance

GetChildren()

Gets the children of this container for Tab navigation traversal. Required by IContainerControl interface.

public IReadOnlyList<IWindowControl> GetChildren()

Returns

IReadOnlyList<IWindowControl>

GetInitialFocus(bool)

Returns the first child to focus when Tab enters this scope. backward=true means Shift+Tab entered from the right — return last child.

public IFocusableControl? GetInitialFocus(bool backward)

Parameters

backward bool

Returns

IFocusableControl

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.

GetLogicalCursorPosition()

Gets the logical cursor position within the control's content coordinate system. This should be the raw position without any visual adjustments for margins, scrolling, etc.

public Point? GetLogicalCursorPosition()

Returns

Point?

Logical cursor position or null if no cursor.

GetNextFocus(IFocusableControl, bool)

Returns the next child to focus after Tab from 'current'. Returns null when Tab should exit this scope.

public IFocusableControl? GetNextFocus(IFocusableControl current, bool backward)

Parameters

current IFocusableControl

backward bool

Returns

IFocusableControl

GetVisibleHeightForControl(IWindowControl)

Gets the actual visible height for a control within the container viewport. Returns null if the control is not found or visibility cannot be determined.

public int? GetVisibleHeightForControl(IWindowControl control)

Parameters

control IWindowControl

The control to check

Returns

int?

The number of visible lines, or null if unknown

InsertControl(int, IWindowControl)

Inserts a child control at the specified index in the panel. This method is not thread-safe and must be called from the UI thread.

public void InsertControl(int index, IWindowControl control)

Parameters

index int

The zero-based index at which to insert the control.

control IWindowControl

The control to insert.

Invalidate(Invalidation, IWindowControl?)

Marks this container as needing the specified work on the next frame. The request propagates up the container chain and folds into the owning window's frame-intent accumulator.

public void Invalidate(Invalidation work, IWindowControl? callerControl = null)

Parameters

work Invalidation

The kind of work requested: Repaint (appearance-only, Measure skipped) or Relayout (full layout).

callerControl IWindowControl

The control that triggered the invalidation, if any (cycle guard).

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

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

RemoveControl(IWindowControl)

Removes a child control from the panel. This method is not thread-safe and must be called from the UI thread.

public void RemoveControl(IWindowControl control)

Parameters

control IWindowControl

ScrollChildIntoView(IWindowControl)

Automatically scrolls to bring a child control into view when it receives focus. This is called by the focus system when a child within this panel gains focus.

public void ScrollChildIntoView(IWindowControl child)

Parameters

child IWindowControl

Remarks

Horizontal scrolling is not applied for children (children typically fit the width).

ScrollChildRegionIntoView(IWindowControl, int, int)

Scrolls so that a sub-region of child is visible. The region is given in the child's own content coordinates: childRelativeTop rows from the child's top, spanning regionHeight rows. Mirrors ScrollChildIntoView(IWindowControl)'s clamp, applied to the region instead of the whole child — used to bring a focused element's row into view when the child itself does not scroll.

public void ScrollChildRegionIntoView(IWindowControl child, int childRelativeTop, int regionHeight)

Parameters

child IWindowControl

The (direct) child whose sub-region should be made visible.

childRelativeTop int

Row offset of the region from the child's top edge. A negative value is clamped to 0.

regionHeight int

Height of the region in rows. A value less than 1 is treated as 1.

ScrollHorizontalBy(int)

Scrolls the content horizontally by the specified number of characters. Positive values scroll right, negative values scroll left. The offset is clamped to valid bounds automatically.

public void ScrollHorizontalBy(int chars)

Parameters

chars int

Number of characters to scroll (positive = right, negative = left).

Remarks

No-op when HorizontalScrollMode is None, consistent with ScrollToPosition(int, int).

ScrollToBottom()

Scrolls to the bottom of the content.

public void ScrollToBottom()

Remarks

This is a one-shot scroll — it does not enable AutoScroll. When called before the panel has been laid out (e.g. immediately after AddWindow), the scroll is deferred to the first paint. When called right after adding content, the content height is recomputed on demand so the new content is included in the target.

ScrollToPosition(int, int)

Scrolls to a specific position.

public void ScrollToPosition(int vertical, int horizontal = 0)

Parameters

vertical int

horizontal int

ScrollToTop()

Scrolls to the top of the content.

public void ScrollToTop()

ScrollVerticalBy(int)

Scrolls the content vertically by the specified number of lines. Positive values scroll down, negative values scroll up. The offset is clamped to valid bounds automatically.

public void ScrollVerticalBy(int lines)

Parameters

lines int

Number of lines to scroll (positive = down, negative = up).

SetLogicalCursorPosition(Point)

Sets the logical cursor position within the control's content coordinate system.

public void SetLogicalCursorPosition(Point position)

Parameters

position Point

Events

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.

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>

Scrolled

Event fired when the panel is scrolled.

public event EventHandler<ScrollEventArgs>? Scrolled

Event Type

EventHandler<ScrollEventArgs>