BeepPanel

Overview

BeepPanel is an enhanced container control that extends the standard Windows Forms Panel with optional title bars, improved theming support, border customization, and flexible layout options for organizing content in your applications.

Built on the BeepControl foundation, BeepPanel provides a clean, modern container that can display titles, icons, and action buttons while maintaining seamless integration with the Beep theming system.

Key Features

Basic Usage

// Create a basic panel
var panel = new BeepPanel
{
    Size = new Size(300, 200),
    Location = new Point(10, 10),
    BorderStyle = BorderStyle.FixedSingle
};

// Add some content
var label = new Label
{
    Text = "Panel Content",
    Dock = DockStyle.Fill,
    TextAlign = ContentAlignment.MiddleCenter
};

panel.Controls.Add(label);
this.Controls.Add(panel);

// Create panel with title bar
var titlePanel = new BeepPanel
{
    ShowTitle = true,
    TitleText = "Settings Panel",
    TitleHeight = 30,
    Size = new Size(400, 300),
    Location = new Point(10, 10),
    BorderRadius = 8
};

// Add content to the panel
var contentArea = new BeepPanel
{
    Dock = DockStyle.Fill,
    Padding = new Padding(10)
};

// Add some controls to content area
var checkBox1 = new BeepCheckBox
{
    Text = "Enable notifications",
    Location = new Point(10, 10),
    AutoSize = true
};

var checkBox2 = new BeepCheckBox
{
    Text = "Auto-save changes",
    Location = new Point(10, 40),
    AutoSize = true
};

contentArea.Controls.AddRange(new Control[] { checkBox1, checkBox2 });
titlePanel.Controls.Add(contentArea);
this.Controls.Add(titlePanel);

Title Bar

The title bar provides a clean header area for your panel with support for text, icons, and action buttons.

var panel = new BeepPanel
{
    ShowTitle = true,
    TitleText = "Data Panel",
    TitleIcon = "📊", // Emoji or use SVG
    ShowMinimizeButton = true,
    ShowMaximizeButton = true,
    ShowCloseButton = true,
    TitleHeight = 35,
    Size = new Size(500, 400),
    Dock = DockStyle.Fill
};

// Handle title bar button events
panel.MinimizeClicked += (s, e) => {
    panel.Height = panel.TitleHeight;
    panel.Minimized = true;
};

panel.MaximizeClicked += (s, e) => {
    if (panel.WindowState == FormWindowState.Maximized)
    {
        panel.WindowState = FormWindowState.Normal;
    }
    else
    {
        panel.WindowState = FormWindowState.Maximized;
    }
};

panel.CloseClicked += (s, e) => {
    panel.Visible = false;
    // Or remove from parent container
    // panel.Parent.Controls.Remove(panel);
};

Title Bar Customization

Properties

Layout Properties

Appearance Properties

Examples

private void CreateDashboardLayout()
{
    var mainContainer = new BeepPanel
    {
        Dock = DockStyle.Fill,
        Padding = new Padding(10)
    };

    // Header panel
    var headerPanel = new BeepPanel
    {
        ShowTitle = true,
        TitleText = "Dashboard Overview",
        TitleIcon = "📊",
        Dock = DockStyle.Top,
        Height = 80,
        Margin = new Padding(0, 0, 0, 10),
        BorderRadius = 8
    };

    // Left sidebar panel
    var sidebarPanel = new BeepPanel
    {
        ShowTitle = true,
        TitleText = "Navigation",
        Dock = DockStyle.Left,
        Width = 200,
        Margin = new Padding(0, 0, 10, 0),
        BorderRadius = 8
    };

    // Main content panel
    var contentPanel = new BeepPanel
    {
        ShowTitle = true,
        TitleText = "Main Content",
        TitleIcon = "📋",
        ShowMaximizeButton = true,
        Dock = DockStyle.Fill,
        BorderRadius = 8
    };

    // Add navigation items to sidebar
    var navItems = new string[] { "Home", "Reports", "Settings", "Help" };
    var yPosition = 10;

    foreach (var item in navItems)
    {
        var navButton = new BeepButton
        {
            Text = item,
            Size = new Size(180, 35),
            Location = new Point(10, yPosition),
            UIVariant = ReactUIVariant.Text,
            UIColor = ReactUIColor.Primary
        };

        sidebarPanel.Controls.Add(navButton);
        yPosition += 45;
    }

    mainContainer.Controls.AddRange(new Control[]
    {
        headerPanel, sidebarPanel, contentPanel
    });

    this.Controls.Add(mainContainer);
}

private void CreateInfoCards()
{
    var cardContainer = new FlowLayoutPanel
    {
        Dock = DockStyle.Fill,
        FlowDirection = FlowDirection.LeftToRight,
        WrapContents = true,
        Padding = new Padding(20)
    };

    // Create multiple info cards
    var cardData = new[]
    {
        new { Title = "Total Sales", Value = "$125,430", Icon = "💰", Color = Color.FromArgb(76, 175, 80) },
        new { Title = "New Customers", Value = "1,234", Icon = "👥", Color = Color.FromArgb(33, 150, 243) },
        new { Title = "Orders Today", Value = "567", Icon = "📦", Color = Color.FromArgb(255, 152, 0) },
        new { Title = "Revenue Growth", Value = "+12.5%", Icon = "📈", Color = Color.FromArgb(156, 39, 176) }
    };

    foreach (var data in cardData)
    {
        var card = new BeepPanel
        {
            ShowTitle = true,
            TitleText = data.Title,
            TitleIcon = data.Icon,
            Size = new Size(250, 120),
            Margin = new Padding(10),
            BorderRadius = 12,
            ShadowEnabled = true,
            BorderColor = data.Color
        };

        // Add value label
        var valueLabel = new BeepLabel
        {
            Text = data.Value,
            Font = new Font("Segoe UI", 24, FontStyle.Bold),
            ForeColor = data.Color,
            Dock = DockStyle.Fill,
            TextAlign = ContentAlignment.MiddleCenter
        };

        card.Controls.Add(valueLabel);
        cardContainer.Controls.Add(card);
    }

    this.Controls.Add(cardContainer);
}

private void CreateCollapsiblePanel()
{
    var settingsPanel = new BeepPanel
    {
        ShowTitle = true,
        TitleText = "Advanced Settings",
        TitleIcon = "⚙️",
        ShowMinimizeButton = true,
        Size = new Size(400, 300),
        Location = new Point(20, 20),
        BorderRadius = 10
    };

    // Create content that can be collapsed
    var contentPanel = new BeepPanel
    {
        Dock = DockStyle.Fill,
        Padding = new Padding(15),
        AutoScroll = true
    };

    // Add settings controls
    var settings = new Control[]
    {
        new BeepCheckBox { Text = "Enable auto-save", Location = new Point(0, 0), AutoSize = true },
        new BeepCheckBox { Text = "Show notifications", Location = new Point(0, 30), AutoSize = true },
        new BeepCheckBox { Text = "Dark mode", Location = new Point(0, 60), AutoSize = true },
        new BeepComboBox {
            DropDownStyle = ComboBoxStyle.DropDownList,
            Location = new Point(0, 90),
            Size = new Size(200, 25)
        }
    };

    contentPanel.Controls.AddRange(settings);
    settingsPanel.Controls.Add(contentPanel);

    // Handle collapse/expand
    bool isCollapsed = false;
    int originalHeight = settingsPanel.Height;

    settingsPanel.MinimizeClicked += (s, e) => {
        if (isCollapsed)
        {
            // Expand
            settingsPanel.Height = originalHeight;
            contentPanel.Visible = true;
            isCollapsed = false;
        }
        else
        {
            // Collapse
            originalHeight = settingsPanel.Height;
            settingsPanel.Height = settingsPanel.TitleHeight;
            contentPanel.Visible = false;
            isCollapsed = true;
        }
    };

    this.Controls.Add(settingsPanel);
}

Theming

BeepPanel integrates seamlessly with the Beep theming system, automatically adapting colors, fonts, and visual effects.

// Apply theme to individual panel
panel.Theme = "DarkTheme";
panel.ApplyTheme();

// Apply theme to all panels recursively
private void ApplyThemeToPanels(Control container, string themeName)
{
    foreach (Control control in container.Controls)
    {
        if (control is BeepPanel panel)
        {
            panel.Theme = themeName;
            panel.ApplyTheme();
        }

        // Recursively apply to nested containers
        if (control.HasChildren)
        {
            ApplyThemeToPanels(control, themeName);
        }
    }
}

// Apply to entire form
ApplyThemeToPanels(this, "DarkTheme");

Theme-Responsive Properties

• Background colors - Automatically use theme background colors
• Border colors - Adapt to theme accent and border colors
• Title bar styling - Use theme colors for title text and buttons
• Shadow effects - Adjust shadow colors based on theme

2026 Header/Border Pipeline

BeepPanel now uses a typed layout pipeline for title and border rendering to provide stable GroupBox/card header alignment across DPI scales and border styles.

• Typed contracts: panel rendering uses internal state and layout context models.
• Deterministic GroupBox gap: the border reserves a precise title gap segment before text paint.
• Final title overlay pass: title text is painted after base background and border for clean layering.
• Header-safe content bounds: child controls are constrained to content insets below header regions.
• DPI-safe geometry: title gap, line thickness, and offsets are scaled through DPI helpers.
• Designer presets: quick verbs are available for GroupBox, Card, Flat, and Header Hidden modes.

Icon + TitleLine (2026 update)

BeepPanel header now supports icon-aware title composition and deterministic title-line anchoring. This makes card/groupbox headers behave consistently across left/center/right alignment and DPI scales.

• IconPath: set icon key or resource/path directly for header icon rendering.
• ShowTitleIcon: enables/disables icon rendering without clearing icon path.
• TitleIconSize / TitleIconGap: defines icon sizing and spacing before DPI scaling.
• TitleIconTintWithForeColor: toggles icon tint behavior using current title foreground color.
• Compact TitleLine: when full-width is off, line follows icon+title cluster width.
• Full-width TitleLine: when full-width is on, line spans the header rail inside border insets.

var cardPanel = new BeepPanel
{
    ShowTitle = true,
    TitleText = "Orders",
    TitleStyle = PanelTitleStyle.TopHeader,
    TitleAlignment = ContentAlignment.TopLeft,
    ShowTitleIcon = true,
    IconPath = "AlertCircle",   // SvgsUI/Svgs key or resource/path
    TitleIconSize = 16,
    TitleIconGap = 6,
    TitleIconTintWithForeColor = true,
    ShowTitleLine = true,
    ShowTitleLineinFullWidth = false
};

Best Practices

🎨 Visual Design

• Consistent spacing: Use consistent margins and padding across panels
• Logical grouping: Group related content within panels
• Visual hierarchy: Use title bars to establish content importance
• Appropriate sizing: Size panels based on their content and context

⚡ Performance

• Minimize nesting: Avoid excessive panel nesting for better performance
• Use AutoScroll wisely: Enable only when necessary to avoid layout issues
• Batch updates: Suspend layout when adding multiple controls

♿ Accessibility

• Meaningful titles: Use descriptive title text for screen readers
• Keyboard navigation: Ensure panel contents are keyboard accessible
• High contrast support: Test panels with high contrast themes
• Focus management: Handle focus properly when collapsing/expanding