BeepAdvancedButton

Overview

BeepAdvancedButton is the flagship button control in the Beep WinForms library. It supports 30+ distinct visual styles through a pluggable painter system, each implemented as a separate class extending BaseButtonPainter. The control is organized as a partial class split across two files, with supporting enumerations, models, helpers, and painter classes in dedicated subdirectories.

Key Features

• 30+ painted visual styles — Solid, Icon, Text, Toggle, FAB, Ghost, Outlined, Link, Gradient, IconText, Chip, Contact, NavigationChevron, NeonGlow, NewsBanner, FlatWeb, LowerThird, StickerLabel, OutlinePill, AccentEdge, SpeechBubble, GradientSubButton, MiniGradientPill, GradientSpeechBubble, SplitGradient, IconCircleRight, SplitIconLeft, and more.
• Pluggable painter architecture — Each style is a standalone class implementing IAdvancedButtonPainter. The ButtonPainterFactory maps styles to painters at runtime.
• Semantic intent system — Six intents (Primary, Secondary, Tertiary, Destructive, Success, Neutral) provide automatic tokenized color mapping for consistent UX.
• Customizable shapes — 7 shape options: RoundedRectangle, Circle, Pill, Rectangle, Square, Split, Custom. Each style has a sensible default shape.
• Rich sub-variant selectors — NewsBanner (21 variants), Contact (16 variants), Chevron (4 variants), FlatWeb (7 variants), LowerThird (8 variants), StickerLabel (4 variants).
• Smooth animation pipeline — 16ms animation timer drives hover/press transitions, ripple effect on click, and continuous loading spinner rotation.
• Loading state — Rotating spinner replaces content; optional click suppression while loading.
• Toggle behavior — Full on/off toggle with ToggleChanged event. Split shape provides independently clickable left/right areas with dedicated events.
• Focus ring rendering — Keyboard-only focus ring with configurable thickness, offset, and radius delta.
• Accessible keyboard navigation — Full Space/Enter activation, Left/Right for split buttons, Tab support.
• Reduced motion support — ReduceMotion property disables all animation transitions for accessibility.
• DPI-aware sizing — Small (32px), Medium (40px), Large (48px) presets with automatic DPI scaling via DpiScalingHelper.
• Dual icon support — IconLeft and IconRight properties for left/right icon placement, plus ImagePath for main/leading icon.
• Complete theme integration — Extends BaseControl.ApplyTheme() to apply button-specific colors from the active IBeepTheme.
• Design-time safety — Fallback rendering with DrawDesignTimeFallback when theme is unavailable; error display with DrawDesignTimeError.

Inheritance & Architecture

Control
  └── BaseControl                         (TheTechIdea.Beep.Winform.Controls.Base)
        └── BeepAdvancedButton            (TheTechIdea.Beep.Winform.Controls.Buttons.BeepAdvancedButton)
              ├── partial: BeepAdvancedButton.cs          (1583 lines — core control, properties, events, overrides)
              └── partial: BeepAdvancedButton.Layout.cs   (143 lines — layout, shape logic, size helpers)

BaseControl provides double-buffering, classic painter fallback, border/shadow rendering, splash effects, hit-test infrastructure, and the full theme application pipeline. BeepAdvancedButton extends this with a custom painter system that bypasses traditional OnPaint in favor of DrawContent(Graphics g) where it assembles an AdvancedButtonPaintContext and delegates to the active IAdvancedButtonPainter.

The painter interface is intentionally minimal — a single void Paint(AdvancedButtonPaintContext context) method — allowing each style to have complete control over its rendering while consuming the same standardized context object that carries state, colors, bounds, shape, and animation data.

Styles & Sub-variants

The AdvancedButtonStyle enum defines 30 distinct visual styles. Each maps to a concrete painter class via ButtonPainterFactory. Changing ButtonStyle at runtime recreates the painter and resets the default shape for that style.

Enumerations

AdvancedButtonStyle

The primary visual variant selector. Has 30 values and determines which painter class renders the button.

public enum AdvancedButtonStyle
{
    Solid, Outlined, OutlinePill, Ghost, Text, Link,
    FAB, Chip, Icon, IconText, Toggle,
    Gradient, NeonGlow, AccentEdge,
    Contact, LowerThird, SpeechBubble,
    SplitIconLeft, SplitGradient, IconCircleRight,
    FlatWeb, StickerLabel, NewsBanner, NavigationChevron,
    GradientSubButton, MiniGradientPill, GradientSpeechBubble,
    SplitColor, // alias for IconText
    IconTextButton, // value unused but reserved
    GradientBadge // value unused but reserved
}

AdvancedButtonSize

Controls the DPI-scaled size preset. FAB buttons get special square sizing (40px, 56px, 72px).

public enum AdvancedButtonSize { Small, Medium, Large }
// Small  = 80×32 (FAB: 40×40)
// Medium = 100×40 (FAB: 56×56) [default]
// Large  = 120×48 (FAB: 72×72)

AdvancedButtonState

State machine for painter rendering. Determines color selection in GetBackgroundColor() and GetForegroundColor().

public enum AdvancedButtonState { Normal, Hover, Pressed, Disabled, Focused }

ButtonIntent

Semantic intent drives automatic color token mapping for consistent UX. Colors are derived from the active theme.

public enum ButtonIntent
{
    Primary,      // Accent color + lightened/darkened variants
    Secondary,    // Theme secondary color
    Tertiary,     // Theme default color
    Destructive,  // Red (220,53,69) palette
    Success,      // Green (25,135,84) palette
    Neutral       // Gray (108,117,125) palette
}

ButtonShape

Determines how the ButtonShapeHelper creates the GraphicsPath for clipping and border rendering.

public enum ButtonShape { RoundedRectangle, Circle, Pill, Rectangle, Square, Split, Custom }

NewsBannerVariant

21 explicit layout variants for news broadcast banners. When set to Auto, the painter uses heuristics to select a layout based on content and size.

public enum NewsBannerVariant
{
    Auto,
    CircleBadgeLeft, RectangleBadgeLeft, AngledBadgeLeft,
    ChevronRight, ChevronBoth, FlagLeft,
    AngledTwoTone, SlantedEdges, PillWithIcon,
    BNLiveCircleBanner, BNSquareGreenBanner,
    BreakingNewsGlobe, LightningBreakingNews, LightningBreakingNewsLive,
    LiveWorldNewsPill, MorningLiveYellowBanner,
    NewsLiveCirclePink, SportNewsCirclePill,
    TwentyFourTVNews, TwentyFourWorldNewsHexagon,
    WorldNewsGlobePill
}

ContactVariant

16 layout variants for contact/CTA buttons with icon-centric layouts. Auto heuristics select based on available icon paths and text length.

public enum ContactVariant
{
    Auto, Standard, Outlined,
    IconLeftSplit, IconRightSplit,
    IconLeftCircle, IconRightCircle,
    IconLeftAngled, IconLeftArrow,
    IconCircleLeft1, IconSquareLeft2, IconCirclesLeftPill3,
    IconCircleRightPill4, IconDiagonalLeft5, IconSquareLeft6,
    IconArrowLeftPill7, IconInsidePillBorder8
}

ChevronVariant

public enum ChevronVariant { Auto, LeftIconRightChevron, LeftChevronRightIcon, BothChevrons, LeftIconCenterChevron }

FlatWebVariant

public enum FlatWebVariant
{
    Auto, LeftBadgeAction, RightNotchSearch, SegmentedIconAction,
    SearchPillNotch, ToolbarSegment, RightArrowTagSearch,
    LeftPointTagSearch, MagnifierBubbleLeft
}

LowerThirdVariant

public enum LowerThirdVariant
{
    Auto, HeadlineBar, LiveTagHeadline, ReportSplit,
    TickerStrip, TickerChevron, LocationHeadlineBlock,
    CompactLiveTag, ReportStacked
}

StickerLabelVariant

public enum StickerLabelVariant { Auto, SpeechBubble, CloudTag, BurstBadge, ComicRibbon }

Properties

All browsable properties are organized into Appearance, Behavior, and Variants categories in the Visual Studio property grid. Properties marked with [DefaultValue] have their defaults shown.

Style & Variant Properties

Shape & Size Properties

Content Properties

State Properties

Animation & Behavior Properties

Focus Ring Properties

Color Override Properties

Public Methods

Events

ToggleChangedEventArgs

public class ToggleChangedEventArgs : EventArgs
{
    public bool IsToggled { get; set; }
    public string? AreaClicked { get; set; }  // "Left", "Right", or null

    public ToggleChangedEventArgs(bool isToggled, string? areaClicked = null)
    {
        IsToggled = isToggled;
        AreaClicked = areaClicked;
    }
}

Theming & Color Tokens

BeepAdvancedButton integrates deeply with the Beep theming system. The ApplyTheme() override reads these theme tokens and applies them to corresponding control properties:

Intent Color Resolution

The ResolveIntentColors() method maps each ButtonIntent to a set of colors. For Primary, it uses the theme's accent color; for Secondary, the secondary color. Destructive, Success, and Neutral use hardcoded industry-standard palettes. The method returns an internal IntentColors struct containing Background, Foreground, HoverBackground, and PressedBackground.

// Intent color mapping (simplified)
ButtonIntent.Primary:      Accent color palette (theme-driven)
ButtonIntent.Secondary:    Theme secondary color palette
ButtonIntent.Tertiary:     Theme default button color palette
ButtonIntent.Destructive:  RGB(220,53,69) red palette
ButtonIntent.Success:      RGB(25,135,84) green palette
ButtonIntent.Neutral:      RGB(108,117,125) gray palette

Animation Pipeline

The control uses a single System.Windows.Forms.Timer running at ~60 FPS (16ms interval). The OnAnimationTick handler updates four animation variables that feed into the painter via AdvancedButtonPaintContext:

The timer is automatically started/stopped via UpdateAnimationTimerState() which checks if any animation is in progress. When ReduceMotion is true, all animations snap to their target instantly and ripple is disabled.

The BaseButtonPainter class provides a Blend(Color from, Color to, float amount) utility used by GetBackgroundColor() and GetForegroundColor() to smoothly interpolate between state colors during hover and press transitions.

Rendering Pipeline

1. OnPaint → BaseControl draws background/border via classic painter, then calls DrawContent(g).
2. DrawContent (override) → Ensures painter is initialized, creates AdvancedButtonPaintContext with all current state, colors, shape, and animation data. Resolves intent colors. Delegates to _currentPainter.Paint(context).
3. After painter completes → DrawFocusRing(g, context) is called if ShowFocusRing is enabled and the control has keyboard focus.
4. Error fallback → If painter is null or throws, DrawDesignTimeFallback(g) renders a simple bordered rectangle with centered text and a dashed design-time indicator.

The AdvancedButtonPaintContext object (26+ properties) carries everything the painter needs: bounds, state, text, icon paths, toggle/loading flags, shape, border/thickness, all color states, shadow config, animation progress values, focus ring parameters, font, intent, and size.

Accessibility & Keyboard

• Tab stop — TabStop = true by default. CanBeFocused = true.
• Space / Enter — Activate the button. Triggers ripple animation at center. For Toggle+Split, Space/Enter activates the currently focused side (Left or Right).
• Arrow keys — For Split toggle buttons: Left selects left area, Right selects right area. _keyboardSplitSelectRight tracks the selection.
• Focus ring — Keyboard-only (visible when _keyboardFocusVisible = true). Hidden on mouse click. Uses configurable thickness/offset/radius-delta.
• Tab/ArrowKeys — Set _keyboardFocusVisible = true to show the focus ring.
• Reduce motion — Disables all animation for users with motion sensitivity. Snaps hover/press states to target and disables ripple.
• Cursor — Hand on hover; Default on leave; No when disabled (via helper).

Examples

Example 1: Solid Primary CTA Button

A standard call-to-action button with a primary intent, medium size, and pill shape. The colors are automatically derived from the active theme's accent color via the intent system.

var saveButton = new BeepAdvancedButton
{
    Text = "Save Changes",
    ButtonStyle = AdvancedButtonStyle.Solid,
    ButtonSize = AdvancedButtonSize.Large,
    Shape = ButtonShape.Pill,
    Intent = ButtonIntent.Primary,
    ImagePath = "/icons/save.svg"
};
saveButton.Click += (s, e) => SaveDocument();

Example 2: Loading State with Click Suppression

Shows a spinning loader while an async operation runs. Click events are suppressed during loading by default via SuppressClickWhileLoading. The button's Text is hidden when loading and a rotating arc is displayed in its place.

var submitBtn = new BeepAdvancedButton
{
    Text = "Submit Order",
    ButtonStyle = AdvancedButtonStyle.Gradient,
    Intent = ButtonIntent.Success,
    SuppressClickWhileLoading = true
};

submitBtn.Click += async (s, e) =>
{
    submitBtn.IsLoading = true;
    try
    {
        await SubmitOrderAsync();
        submitBtn.Text = "Order Placed!";
    }
    finally
    {
        submitBtn.IsLoading = false;
    }
};

Example 3: Split Toggle Button with Left/Right Areas

A Toggle-style button with a Split shape that divides the button into independently clickable left and right halves. Left click sets IsToggled = true, right click sets IsToggled = false. Each side fires its own event, and ToggleChanged provides which area was clicked.

var modeToggle = new BeepAdvancedButton
{
    Text = "Edit / Preview",
    ButtonStyle = AdvancedButtonStyle.Toggle,
    Shape = ButtonShape.Split,
    ButtonSize = AdvancedButtonSize.Medium,
    IsToggled = false
};

modeToggle.ToggleChanged += (s, e) =>
{
    if (e.IsToggled)
        SwitchToEditMode();
    else
        SwitchToPreviewMode();
};

modeToggle.LeftAreaClicked += (s, e) =>
    Console.WriteLine("Left (Edit) area clicked");

modeToggle.RightAreaClicked += (s, e) =>
    Console.WriteLine("Right (Preview) area clicked");

Example 4: FAB (Floating Action Button) with Reduced Motion

A circular floating action button. FAB automatically uses Circle shape and DPI-scaled square dimensions. Motion is disabled for accessibility, so hover/press transitions snap instantly and ripple is suppressed.

var fab = new BeepAdvancedButton
{
    ButtonStyle = AdvancedButtonStyle.FAB,
    ButtonSize = AdvancedButtonSize.Medium,  // 56×56 at 96 DPI
    ImagePath = "/icons/plus.svg",
    Intent = ButtonIntent.Primary,
    ReduceMotion = true,
    ShowFocusRing = true,
    FocusRingThickness = 3,
    FocusRingOffset = 4
};
fab.Click += (s, e) => CreateNewProject();
Controls.Add(fab);
fab.Location = new Point(ClientSize.Width - 80, ClientSize.Height - 80);
fab.Anchor = AnchorStyles.Bottom | AnchorStyles.Right;

Example 5: News Banner with Explicit Variant

A news/broadcast-style banner button with a breaking news globe icon, LIVE badge, and red-themed destructive intent for visual urgency.

var breakingNews = new BeepAdvancedButton
{
    Text = "Markets Surge on Policy Shift",
    ButtonStyle = AdvancedButtonStyle.NewsBanner,
    NewsBannerVariant = NewsBannerVariant.BreakingNewsGlobe,
    Intent = ButtonIntent.Destructive,
    ButtonSize = AdvancedButtonSize.Large
};
breakingNews.Click += (s, e) => NavigateToNewsArticle();

Example 6: Contact Button with Right Circle Icon

A contact-styled CTA button with a circular icon container on the right side, useful for messaging or contact actions.

var contactBtn = new BeepAdvancedButton
{
    Text = "Chat with Support",
    ButtonStyle = AdvancedButtonStyle.Contact,
    ContactVariant = ContactVariant.IconCircleRightPill4,
    IconRight = "/icons/chat.svg",
    Intent = ButtonIntent.Success,
    ButtonSize = AdvancedButtonSize.Medium
};
contactBtn.Click += (s, e) => OpenChatWindow();

File Architecture

The BeepAdvancedButton control is spread across 42 files organized into a clean directory structure:

Complete Painter Directory