Table of Contents

Class NavigationView

Namespace
SharpConsoleUI.Controls
Assembly
SharpConsoleUI.dll

A navigation view control with a left navigation pane and a right content area. Inspired by WinUI's NavigationView pattern, encapsulating nav item selection, content switching, and header updates into a single reusable control.

public class NavigationView : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable, IContainer, IContainerControl, IFocusScope
Inheritance
NavigationView
Implements
Inherited Members
Extension Methods

Constructors

NavigationView()

Initializes a new instance of the NavigationView class.

public NavigationView()

Properties

AnimateTransitions

Gets or sets whether width transitions are animated.

public bool AnimateTransitions { 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

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

CompactPaneWidth

Gets or sets the width of the navigation pane in Compact display mode.

public int CompactPaneWidth { get; set; }

Property Value

int

CompactThreshold

Gets or sets the width threshold at or above which Auto mode resolves to Compact. Below this threshold, Auto resolves to Minimal.

public int CompactThreshold { get; set; }

Property Value

int

Container

Gets or sets the parent container that hosts this control.

public override IContainer? Container { get; set; }

Property Value

IContainer

ContentBackgroundColor

Gets or sets the background color for the content panel.

public Color? ContentBackgroundColor { get; set; }

Property Value

Color?

ContentBorderColor

Gets or sets the border color for the content panel.

public Color? ContentBorderColor { get; set; }

Property Value

Color?

ContentBorderStyle

Gets or sets the border style for the content panel.

public BorderStyle ContentBorderStyle { get; set; }

Property Value

BorderStyle

ContentPadding

Gets or sets the padding inside the content panel.

public Padding ContentPadding { get; set; }

Property Value

Padding

ContentPanel

Gets the content panel for direct access.

public ScrollablePanelControl ContentPanel { get; }

Property Value

ScrollablePanelControl

ContentToolbar

Gets the content toolbar control for direct access.

public ToolbarControl ContentToolbar { get; }

Property Value

ToolbarControl

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?

CurrentDisplayMode

Gets the currently resolved display mode (never Auto).

public NavigationViewDisplayMode CurrentDisplayMode { get; }

Property Value

NavigationViewDisplayMode

ExpandedThreshold

Gets or sets the width threshold at or above which Auto mode resolves to Expanded.

public int ExpandedThreshold { get; set; }

Property Value

int

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

IsDirty

Gets or sets whether this container needs to be redrawn.

public bool IsDirty { get; set; }

Property Value

bool

IsEnabled

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

public bool IsEnabled { get; set; }

Property Value

bool

IsPortalOpen

Gets whether the navigation portal overlay is currently open.

public bool IsPortalOpen { get; }

Property Value

bool

ItemForeground

Gets or sets the foreground color for unselected navigation items.

public Color ItemForeground { get; set; }

Property Value

Color

Items

Gets the read-only list of navigation items.

public IReadOnlyList<NavigationItem> Items { get; }

Property Value

IReadOnlyList<NavigationItem>

NavPaneWidth

Gets or sets the width of the left navigation pane in characters.

public int NavPaneWidth { get; set; }

Property Value

int

PaneDisplayMode

Gets or sets the pane display mode. When set to Auto, the mode is resolved based on available width and configured thresholds.

public NavigationViewDisplayMode PaneDisplayMode { get; set; }

Property Value

NavigationViewDisplayMode

PaneHeader

Gets or sets the markup text shown as the navigation pane header.

public string? PaneHeader { get; set; }

Property Value

string

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

Remarks

NavigationView ignores SavedFocus — it always delegates to child panels.

SelectedIndex

Gets or sets the index of the currently selected navigation item.

public int SelectedIndex { get; set; }

Property Value

int

SelectedItem

Gets the currently selected navigation item, or null if none is selected.

public NavigationItem? SelectedItem { get; }

Property Value

NavigationItem

SelectedItemBackground

Gets or sets the background color for the selected navigation item.

public Color SelectedItemBackground { get; set; }

Property Value

Color

SelectedItemForeground

Gets or sets the foreground color for the selected navigation item.

public Color SelectedItemForeground { get; set; }

Property Value

Color

SelectionIndicator

Gets or sets the character used as the selection indicator prefix.

public char SelectionIndicator { get; set; }

Property Value

char

ShowContentHeader

Gets or sets whether the content header (title + subtitle) is shown.

public bool ShowContentHeader { get; set; }

Property Value

bool

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

Methods

AddContentToolbarButton(string, EventHandler<ButtonControl>?)

Adds a button to the content toolbar with an optional click handler.

public ButtonControl AddContentToolbarButton(string text, EventHandler<ButtonControl>? onClick = null)

Parameters

text string
onClick EventHandler<ButtonControl>

Returns

ButtonControl

AddContentToolbarItem(IWindowControl)

Adds a control to the content toolbar.

public void AddContentToolbarItem(IWindowControl item)

Parameters

item IWindowControl

AddContentToolbarSeparator()

Adds a vertical separator to the content toolbar.

public void AddContentToolbarSeparator()

AddHeader(string, Color?)

Adds a header item that groups subsequent child items.

public NavigationItem AddHeader(string text, Color? color = null)

Parameters

text string
color Color?

Returns

NavigationItem

The created header NavigationItem.

AddItem(NavigationItem)

Adds a navigation item to the control.

public void AddItem(NavigationItem item)

Parameters

item NavigationItem

AddItem(string, string?, string?)

Adds a navigation item with the specified properties.

public NavigationItem AddItem(string text, string? icon = null, string? subtitle = null)

Parameters

text string
icon string
subtitle string

Returns

NavigationItem

The created NavigationItem.

AddItemToHeader(NavigationItem, string, string?, string?)

Adds a child item under the specified header. The item is inserted after the header's last existing child.

public NavigationItem AddItemToHeader(NavigationItem header, string text, string? icon = null, string? subtitle = null)

Parameters

header NavigationItem
text string
icon string
subtitle string

Returns

NavigationItem

The created child NavigationItem.

ClearContentToolbar()

Clears all items from the content toolbar.

public void ClearContentToolbar()

ClearItems()

Removes all navigation items.

public void ClearItems()

GetChildren()

Gets the direct child controls of this container. Does not recursively include grandchildren - recursion happens in caller.

public IReadOnlyList<IWindowControl> GetChildren()

Returns

IReadOnlyList<IWindowControl>

Read-only list of direct child controls (may include other containers)

Remarks

IMPORTANT: For HorizontalGridControl, this should return columns AND splitters in order: [Column1, Splitter1, Column2, Splitter2, Column3]

Splitters are IInteractiveControl and should be included in Tab navigation.

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.

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

InsertItem(int, NavigationItem)

Inserts a navigation item at the specified index.

public void InsertItem(int index, NavigationItem item)

Parameters

index int
item NavigationItem

Invalidate(bool, IWindowControl?)

Marks this container as needing to be redrawn.

public void Invalidate(bool redrawAll, IWindowControl? callerControl = null)

Parameters

redrawAll bool

If true, forces a complete redraw of all content.

callerControl IWindowControl

The control that triggered the invalidation, if any.

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

RemoveContentToolbarItem(IWindowControl)

Removes an item from the content toolbar.

public void RemoveContentToolbarItem(IWindowControl item)

Parameters

item IWindowControl

RemoveItem(NavigationItem)

Removes the specified navigation item.

public void RemoveItem(NavigationItem item)

Parameters

item NavigationItem

RemoveItem(int)

Removes the navigation item at the specified index. If the item is a header, its children are also removed.

public void RemoveItem(int index)

Parameters

index int

SetItemContent(NavigationItem, Action<ScrollablePanelControl>)

Registers a content factory delegate for a navigation item. The delegate is called to populate the content panel when the item is selected.

public void SetItemContent(NavigationItem item, Action<ScrollablePanelControl> populate)

Parameters

item NavigationItem
populate Action<ScrollablePanelControl>

SetItemContent(int, Action<ScrollablePanelControl>)

Registers a content factory delegate for the navigation item at the specified index.

public void SetItemContent(int index, Action<ScrollablePanelControl> populate)

Parameters

index int
populate Action<ScrollablePanelControl>

ToggleHeaderExpanded(NavigationItem)

Toggles the expanded state of a header item, showing or hiding its children.

public void ToggleHeaderExpanded(NavigationItem header)

Parameters

header NavigationItem

Events

DisplayModeChanged

Raised when the resolved display mode changes.

public event EventHandler<NavigationViewDisplayMode>? DisplayModeChanged

Event Type

EventHandler<NavigationViewDisplayMode>

ItemInvoked

Raised when the selected item is invoked (Enter/Space key or double-click on already-selected item).

public event EventHandler<NavigationItemChangedEventArgs>? ItemInvoked

Event Type

EventHandler<NavigationItemChangedEventArgs>

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>

SelectedItemChanged

Raised after the selected item has changed.

public event EventHandler<NavigationItemChangedEventArgs>? SelectedItemChanged

Event Type

EventHandler<NavigationItemChangedEventArgs>

SelectedItemChanging

Raised before the selected item changes. Can be canceled.

public event EventHandler<NavigationItemChangingEventArgs>? SelectedItemChanging

Event Type

EventHandler<NavigationItemChangingEventArgs>
Edit this page