BeepNavigationWidget

Overview

BeepNavigationWidget is a paint-based WinForms widget that inherits from BaseControl. It uses an IWidgetPainter pipeline to render rich visuals without child controls. The Style property selects one of 10 built-in render modes; changing it at runtime immediately swaps the painter and triggers a repaint.

Toolbox icon: 🧭
Category: Beep Widgets → Navigation
Default size: 400 × 50
Namespace: TheTechIdea.Beep.Winform.Controls.Widgets

Key Features

🧭 Ten Navigation Styles

Every navigation pattern from breadcrumb to tree — one widget.

✅ Step Progress

StepIndicator and WizardSteps track completed/active/pending visually.

🌳 Tree Support

TreeNavigation supports hierarchical items via NavigationItem.ParentId.

⚡ QuickActions

Row of icon+label buttons for toolbar-style quick access.

🖱️ NavigationChanged

Fires whenever the active item changes — no plumbing needed.

🔢 Pagination

Pagination style includes prev/next buttons and numbered page buttons.

Style Variants (10)

Style Value	Description
`Breadcrumb`	Horizontal breadcrumb trail showing the current page path.
`StepIndicator`	Numbered step progress bar with completed/active/upcoming states.
`TabContainer`	Clickable tab bar for switching content panels.
`Pagination`	Page number bar with prev/next buttons.
`MenuBar`	Horizontal menu bar with labelled items.
`SidebarNav`	Vertical sidebar navigation list with optional icons.
`WizardSteps`	Wizard-style step navigation with state indicators.
`ProcessFlow`	Left-to-right process milestone flow diagram.
`TreeNavigation`	Collapsible tree-style hierarchical navigation.
`QuickActions`	Row of icon + label quick-action buttons.

Properties

Property	Type	Default	Description
`Style`	NavigationWidgetStyle	Breadcrumb	Selects the navigation painter.
`Items`	List<NavigationItem>	(sample items)	Navigation items. Each has Id, Label, Icon, IsActive, IsEnabled, ParentId.
`CurrentIndex`	int	0	Index of the active/selected item.
`ShowIcons`	bool	true	Show/hide item icons.
`IsHorizontal`	bool	true	Horizontal or vertical layout (Sidebar uses vertical).
`Title`	string	"Navigation"	Header label for sidebar and tree styles.
`AccentColor`	Color	(theme primary)	Active item highlight colour.

Inherits all BaseControl properties (Border, Padding, Theme colors, etc.).

Events

Event	Args Type	Description
`ItemClicked`	BeepEventDataArgs	Fired when any navigation item is clicked. Data contains NavigationItem.
`NavigationChanged`	BeepEventDataArgs	Fired when CurrentIndex changes. Data contains new index.

Basic Usage

// Wizard step indicator
var wizard = new BeepNavigationWidget
{
    Style        = NavigationWidgetStyle.WizardSteps,
    CurrentIndex = 1,  // currently on step 2 (0-based)
    Items = new List
    {
        new NavigationItem { Label = "Account",  IsActive = false },
        new NavigationItem { Label = "Profile",  IsActive = true  },
        new NavigationItem { Label = "Payment",  IsActive = false },
        new NavigationItem { Label = "Confirm",  IsActive = false },
    },
    Size = new Size(480, 60)
};
this.Controls.Add(wizard);

Event Handling

wizard.NavigationChanged += (s, e) =>
{
    int step = (int)e.Data;
    ShowStepPanel(step);
};

Best Practices

Set Style before adding the widget to the form to avoid double repaints.
Adjust Size to fit your layout — defaults are minimum comfortable sizes.
Read BeepEventDataArgs.Data in event handlers for context-specific click data.
Call Invalidate() after updating data properties to trigger a repaint.
Let theme colors flow from BeepStyling.CurrentTheme — avoid overriding color properties unless customization is explicitly desired.