BeepStepperBreadCrumb

Overview

BeepStepperBreadCrumb provides a modern, chevron-shaped breadcrumb navigation control designed for wizard-style interfaces and multi-step processes. Unlike traditional breadcrumbs, it features distinctive arrow-shaped segments that visually connect to create a flowing navigation experience.

Built on the BeepControl foundation, BeepStepperBreadCrumb features precise click detection using custom graphics paths, smooth color animations, dual orientation support, and comprehensive theming. Perfect for setup wizards, checkout processes, form workflows, and any application requiring clear step-by-step navigation.

Key Features

Visual Preview

Horizontal Chevron Layout

Vertical Chevron Layout

Basic Usage

// Create a horizontal chevron breadcrumb
var breadcrumb = new BeepStepperBreadCrumb
{
    Size = new Size(600, 80),
    Location = new Point(20, 20),
    Orientation = Orientation.Horizontal,
    Direction = ChevronDirection.Forward
};

// Add steps
breadcrumb.ListItems.Add(new SimpleItem 
{ 
    Name = "Personal Info", 
    Text = "Basic details",
    IsChecked = true 
});

breadcrumb.ListItems.Add(new SimpleItem 
{ 
    Name = "Account Setup", 
    Text = "Credentials",
    IsChecked = true 
});

breadcrumb.ListItems.Add(new SimpleItem 
{ 
    Name = "Preferences", 
    Text = "Settings",
    IsChecked = false 
});

breadcrumb.ListItems.Add(new SimpleItem 
{ 
    Name = "Review", 
    Text = "Confirm",
    IsChecked = false 
});

breadcrumb.ListItems.Add(new SimpleItem 
{ 
    Name = "Complete", 
    Text = "Finish",
    IsChecked = false 
});

// Handle step selection
breadcrumb.SelectedItemChanged += (sender, e) =>
{
    MessageBox.Show($"Selected step: {e.Item.Name}");
};

this.Controls.Add(breadcrumb);

var verticalBreadcrumb = new BeepStepperBreadCrumb
{
    Size = new Size(200, 400),
    Location = new Point(20, 20),
    Orientation = Orientation.Vertical,
    CheckImage = "check.svg" // Display checkmarks for completed steps
};

// Add process steps
var processSteps = new[]
{
    new SimpleItem { Name = "Initialize", Text = "Setup environment", IsChecked = true },
    new SimpleItem { Name = "Configure", Text = "Apply settings", IsChecked = true },
    new SimpleItem { Name = "Test", Text = "Validate setup", IsChecked = false },
    new SimpleItem { Name = "Deploy", Text = "Go live", IsChecked = false },
    new SimpleItem { Name = "Monitor", Text = "Track performance", IsChecked = false }
};

foreach (var step in processSteps)
{
    verticalBreadcrumb.ListItems.Add(step);
}

// Set current step to "Test"
verticalBreadcrumb.UpdateCurrentStep(2);

this.Controls.Add(verticalBreadcrumb);

Properties

Core Properties

Selection Properties

ChevronDirection Enumeration

Events

var breadcrumb = new BeepStepperBreadCrumb();

// Handle step selection with validation
breadcrumb.SelectedItemChanged += (sender, e) =>
{
    var selectedItem = e.Item;
    var currentIndex = breadcrumb.SelectedIndex;
    
  //  Console.WriteLine($"Step selected: {selectedItem.Name} (Index: {currentIndex})");
    
    // Validate step selection
    if (ValidateStepSelection(currentIndex))
    {
        // Update UI based on selection
        UpdateContentForStep(selectedItem);
        
        // Mark previous steps as completed
        breadcrumb.UpdateCurrentStep(currentIndex);
    }
    else
    {
        MessageBox.Show("Please complete the current step before proceeding.", 
                       "Step Validation", MessageBoxButtons.OK, MessageBoxIcon.Warning);
    }
};

private bool ValidateStepSelection(int stepIndex)
{
    // Implement your validation logic
    switch (stepIndex)
    {
        case 0: // Personal Info
            return ValidatePersonalInfo();
        case 1: // Account Setup
            return ValidateAccountSetup();
        case 2: // Preferences
            return ValidatePreferences();
        default:
            return true;
    }
}

private void UpdateContentForStep(SimpleItem step)
{
    // Update main content area based on selected step
    switch (step.Name)
    {
        case "Personal Info":
            ShowPersonalInfoPanel();
            break;
        case "Account Setup":
            ShowAccountSetupPanel();
            break;
        case "Preferences":
            ShowPreferencesPanel();
            break;
        case "Review":
            ShowReviewPanel();
            break;
        case "Complete":
            ShowCompletionPanel();
            break;
    }
}

Methods

// Programmatically navigate to a specific step
breadcrumb.UpdateCurrentStep(2); // Move to third step (0-based)

// Mark a specific step as completed
var completedStep = breadcrumb.ListItems[1];
completedStep.IsChecked = true;
breadcrumb.UpdateCheckedState(completedStep);

// Apply theme after changing theme settings
breadcrumb.Theme = "DarkTheme";
breadcrumb.ApplyTheme();

Examples

public class CheckoutForm : Form
{
    private BeepStepperBreadCrumb checkoutBreadcrumb;
    private Panel contentPanel;
    private List checkoutPages;
    private CheckoutData checkoutData;

    public CheckoutForm()
    {
        InitializeCheckoutForm();
        SetupCheckoutSteps();
        LoadCheckoutPages();
    }

    private void InitializeCheckoutForm()
    {
        this.Text = "Checkout Process";
        this.Size = new Size(800, 600);
        this.StartPosition = FormStartPosition.CenterScreen;

        checkoutData = new CheckoutData();

        // Create breadcrumb
        checkoutBreadcrumb = new BeepStepperBreadCrumb
        {
            Dock = DockStyle.Top,
            Height = 80,
            Orientation = Orientation.Horizontal,
            Direction = ChevronDirection.Forward
        };

        // Content panel
        contentPanel = new Panel
        {
            Dock = DockStyle.Fill,
            Padding = new Padding(20)
        };

        checkoutBreadcrumb.SelectedItemChanged += OnBreadcrumbStepChanged;

        this.Controls.AddRange(new Control[] { contentPanel, checkoutBreadcrumb });
    }

    private void SetupCheckoutSteps()
    {
        var steps = new[]
        {
            new SimpleItem { Name = "Cart", Text = "Review items", IsChecked = true },
            new SimpleItem { Name = "Shipping", Text = "Delivery info", IsChecked = false },
            new SimpleItem { Name = "Payment", Text = "Billing details", IsChecked = false },
            new SimpleItem { Name = "Review", Text = "Confirm order", IsChecked = false },
            new SimpleItem { Name = "Complete", Text = "Order placed", IsChecked = false }
        };

        foreach (var step in steps)
        {
            checkoutBreadcrumb.ListItems.Add(step);
        }

        // Start with cart step
        checkoutBreadcrumb.UpdateCurrentStep(0);
    }

    private void LoadCheckoutPages()
    {
        checkoutPages = new List
        {
            new CartReviewPage(checkoutData),
            new ShippingInfoPage(checkoutData),
            new PaymentDetailsPage(checkoutData),
            new OrderReviewPage(checkoutData),
            new OrderCompletePage(checkoutData)
        };

        // Show initial page
        ShowPage(0);
    }

    private void OnBreadcrumbStepChanged(object sender, SelectedItemChangedEventArgs e)
    {
        int stepIndex = checkoutBreadcrumb.SelectedIndex;
        
        // Validate step progression
        if (!ValidateStepProgression(stepIndex))
        {
            MessageBox.Show("Please complete the current step before proceeding.",
                          "Checkout Validation", MessageBoxButtons.OK, MessageBoxIcon.Warning);
            return;
        }

        ShowPage(stepIndex);
        UpdateBreadcrumbProgress(stepIndex);
    }

    private bool ValidateStepProgression(int targetStep)
    {
        // Don't allow skipping steps forward
        int currentStep = GetCurrentCompletedStep();
        return targetStep <= currentStep + 1;
    }

    private int GetCurrentCompletedStep()
    {
        for (int i = checkoutBreadcrumb.ListItems.Count - 1; i >= 0; i--)
        {
            if (checkoutBreadcrumb.ListItems[i].IsChecked)
                return i;
        }
        return -1;
    }

    private void ShowPage(int pageIndex)
    {
        contentPanel.Controls.Clear();
        
        if (pageIndex >= 0 && pageIndex < checkoutPages.Count)
        {
            var page = checkoutPages[pageIndex];
            page.Dock = DockStyle.Fill;
            contentPanel.Controls.Add(page);
            
            // Handle page-specific events
            SetupPageEvents(page, pageIndex);
        }
    }

    private void SetupPageEvents(UserControl page, int pageIndex)
    {
        switch (page)
        {
            case CartReviewPage cartPage:
                cartPage.ProceedToShipping += () => AdvanceToStep(1);
                break;
                
            case ShippingInfoPage shippingPage:
                shippingPage.ShippingCompleted += () => AdvanceToStep(2);
                shippingPage.BackToCart += () => checkoutBreadcrumb.UpdateCurrentStep(0);
                break;
                
            case PaymentDetailsPage paymentPage:
                paymentPage.PaymentValidated += () => AdvanceToStep(3);
                paymentPage.BackToShipping += () => checkoutBreadcrumb.UpdateCurrentStep(1);
                break;
                
            case OrderReviewPage reviewPage:
                reviewPage.OrderConfirmed += () => ProcessOrder();
                reviewPage.BackToPayment += () => checkoutBreadcrumb.UpdateCurrentStep(2);
                break;
        }
    }

    private void AdvanceToStep(int stepIndex)
    {
        checkoutBreadcrumb.UpdateCurrentStep(stepIndex);
        ShowPage(stepIndex);
    }

    private void UpdateBreadcrumbProgress(int completedStep)
    {
        // Mark all steps up to and including the completed step as checked
        for (int i = 0; i <= completedStep && i < checkoutBreadcrumb.ListItems.Count; i++)
        {
            checkoutBreadcrumb.ListItems[i].IsChecked = true;
        }
    }

    private void ProcessOrder()
    {
        try
        {
            // Process the order
            OrderProcessor.ProcessOrder(checkoutData);
            
            // Advance to completion
            AdvanceToStep(4);
            
            MessageBox.Show("Order placed successfully!", "Order Complete",
                          MessageBoxButtons.OK, MessageBoxIcon.Information);
        }
        catch (Exception ex)
        {
            MessageBox.Show($"Order processing failed: {ex.Message}", "Error",
                          MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}

public class CheckoutData
{
    public List CartItems { get; set; } = new();
    public ShippingInfo ShippingDetails { get; set; } = new();
    public PaymentInfo PaymentDetails { get; set; } = new();
    public decimal TotalAmount { get; set; }
}

public class InstallationWizard : Form
{
    private BeepStepperBreadCrumb sidebarBreadcrumb;
    private Panel mainPanel;
    private BeepLabel titleLabel;
    private BeepLabel descriptionLabel;
    private Dictionary wizardPages;

    public InstallationWizard()
    {
        InitializeWizard();
        SetupSidebarNavigation();
        CreateWizardPages();
    }

    private void InitializeWizard()
    {
        this.Text = "Software Installation Wizard";
        this.Size = new Size(900, 700);
        this.StartPosition = FormStartPosition.CenterScreen;
        this.FormBorderStyle = FormBorderStyle.FixedDialog;
        this.MaximizeBox = false;

        // Create layout panels
        var sidePanel = new Panel
        {
            Dock = DockStyle.Left,
            Width = 250,
            BackColor = Color.FromArgb(240, 240, 240),
            Padding = new Padding(10)
        };

        mainPanel = new Panel
        {
            Dock = DockStyle.Fill,
            Padding = new Padding(20)
        };

        // Title and description
        titleLabel = new BeepLabel
        {
            Text = "Welcome to Installation",
            Font = new Font("Segoe UI", 18, FontStyle.Bold),
            Dock = DockStyle.Top,
            Height = 40,
            TextAlign = ContentAlignment.MiddleLeft
        };

        descriptionLabel = new BeepLabel
        {
            Text = "Follow the steps to install the software on your computer.",
            Font = new Font("Segoe UI", 10),
            Dock = DockStyle.Top,
            Height = 30,
            TextAlign = ContentAlignment.MiddleLeft
        };

        // Sidebar breadcrumb
        sidebarBreadcrumb = new BeepStepperBreadCrumb
        {
            Dock = DockStyle.Fill,
            Orientation = Orientation.Vertical,
            Direction = ChevronDirection.Forward
        };

        sidePanel.Controls.Add(sidebarBreadcrumb);
        mainPanel.Controls.AddRange(new Control[] { titleLabel, descriptionLabel });

        this.Controls.AddRange(new Control[] { mainPanel, sidePanel });
    }

    private void SetupSidebarNavigation()
    {
        var installationSteps = new[]
        {
            new SimpleItem { Name = "Welcome", Text = "Getting started", IsChecked = true },
            new SimpleItem { Name = "License", Text = "Accept terms", IsChecked = false },
            new SimpleItem { Name = "Destination", Text = "Choose folder", IsChecked = false },
            new SimpleItem { Name = "Components", Text = "Select features", IsChecked = false },
            new SimpleItem { Name = "Install", Text = "Copy files", IsChecked = false },
            new SimpleItem { Name = "Finish", Text = "Installation complete", IsChecked = false }
        };

        foreach (var step in installationSteps)
        {
            sidebarBreadcrumb.ListItems.Add(step);
        }

        sidebarBreadcrumb.SelectedItemChanged += OnNavigationStepChanged;
        sidebarBreadcrumb.UpdateCurrentStep(0);
    }

    private void OnNavigationStepChanged(object sender, SelectedItemChangedEventArgs e)
    {
        string stepName = e.Item.Name;
        
        // Update page content
        ShowStepPage(stepName);
        
        // Update title and description
        UpdatePageHeader(stepName);
    }

    private void ShowStepPage(string stepName)
    {
        // Remove current page
        var currentPage = mainPanel.Controls.OfType().FirstOrDefault();
        currentPage?.Dispose();
        mainPanel.Controls.Remove(currentPage);

        // Add new page
        if (wizardPages.ContainsKey(stepName))
        {
            var newPage = wizardPages[stepName];
            newPage.Dock = DockStyle.Fill;
            mainPanel.Controls.Add(newPage);
            newPage.BringToFront();
        }
    }

    private void UpdatePageHeader(string stepName)
    {
        var stepInfo = GetStepInfo(stepName);
        titleLabel.Text = stepInfo.Title;
        descriptionLabel.Text = stepInfo.Description;
    }

    private (string Title, string Description) GetStepInfo(string stepName)
    {
        return stepName switch
        {
            "Welcome" => ("Welcome to Installation", "This wizard will guide you through the installation process."),
            "License" => ("License Agreement", "Please read and accept the license terms to continue."),
            "Destination" => ("Choose Destination", "Select where you want to install the software."),
            "Components" => ("Select Components", "Choose which features you want to install."),
            "Install" => ("Installing", "Please wait while files are being copied to your computer."),
            "Finish" => ("Installation Complete", "The software has been successfully installed."),
            _ => ("Installation", "Follow the steps to complete installation.")
        };
    }
}

Theming

BeepStepperBreadCrumb provides comprehensive theming with automatic color application to chevron shapes and text:

var breadcrumb = new BeepStepperBreadCrumb
{
    Theme = "DarkTheme",
    Orientation = Orientation.Horizontal
};

// Theme automatically applies:
// - ButtonSelectedBackColor: Completed steps
// - ButtonBackColor: Current step
// - DisabledBackColor: Pending steps
// - ButtonForeColor: Step text color
// - AccentTextColor: Selected step text
// - ShadowColor: Chevron borders

// Manual theme application
breadcrumb.ApplyTheme();

Breadcrumb Theme Properties

• ButtonSelectedBackColor - Completed chevron steps background
• ButtonBackColor - Current/selected step background
• DisabledBackColor - Pending/incomplete steps background
• ButtonForeColor - General step text color
• AccentTextColor - Current step text highlight color
• ShadowColor - Chevron borders and outlines

Best Practices

?? Navigation Design

• Clear step naming: Use concise, descriptive names for each chevron step
• Logical progression: Ensure steps follow a natural workflow sequence
• Visual hierarchy: Use completed/current/pending states effectively
• Click feedback: Provide clear visual feedback when steps are clicked

?? Layout Considerations

• Horizontal layout: Best for 3-6 steps in headers or top navigation
• Vertical layout: Ideal for sidebar navigation with many steps
• Responsive sizing: Ensure chevrons maintain proper proportions at different sizes
• Text fitting: Keep step names short enough to fit within chevron shapes

?? Step Management

• Validation: Implement proper step validation before allowing progression
• State persistence: Save step progress for complex workflows
• Error handling: Provide clear feedback for invalid step transitions
• Completion tracking: Use UpdateCurrentStep to mark progress accurately

? Performance

• Hit testing: Built-in graphics path hit testing provides accurate click detection
• Animation efficiency: Color animations are optimized for smooth transitions
• Drawing optimization: Custom drawing is efficient and scales well
• Memory management: Graphics paths are properly disposed of