BeepComboBox

Overview

BeepComboBox is a modern, fully themable combo box control built on the BaseControl framework. It uses a painter methodology where each visual variant (ComboBoxType) delegates rendering to a dedicated painter class, enabling consistent styling across 11 design-system variants while sharing core logic for selection, popup management, and keyboard navigation.

The control is implemented across 6 partial class files and supported by 11 painter classes, 5 helper engines, and the shared BeepContextMenu for dropdown popups. It inherits border rendering, DPI scaling, theme application, and hit-testing from BaseControl.

Key Features

ComboBoxType Variants

The ComboBoxType enum defines 11 design-system variants. Each variant maps to a dedicated IComboBoxPainter implementation and a set of ComboBoxVisualTokens (button width, inner padding, corner radius, text inset, row density). Changing ComboBoxType dynamically swaps the painter and re-applies layout defaults.

ControlStyle Mapping

When ComboBoxType has not been explicitly set, setting ControlStyle on the control automatically maps to a default ComboBoxType: Material* → FilledSoft, iOS15/Apple/PillRail → RoundedPill, Fluent*/Windows11Mica/Shadcn/RadixUI/NextJS/Linear → OutlineDefault, Minimal/NotionMinimal/VercelClean → MinimalBorderless, NeoBrutalist/Brutalist → SegmentedTrigger, Bootstrap/AntDesign/ChakraUI → OutlineSearchable.

Supporting Enums

BeepAutoCompleteMode

BeepComboBoxValidationState

BeepComboBoxSize

Properties

Data & Selection

Appearance

Behavior

Multi-Select

Layout

Accessibility

Methods

Value Access

Dropdown Management

Editing

Selection Helpers

Layout & Rendering

Events

The SelectedItemChangedEventArgs carries the newly selected SimpleItem.

Popup Behavior

The dropdown popup is implemented using BeepContextMenu, the same menu infrastructure used by the application menu bar. Each time the dropdown opens:

1. A fresh BeepContextMenu instance is created with DestroyOnClose = true.
2. The menu is configured with the combo box's current state: MultiSelect, ShowCheckBox, ShowSearchBox, Theme.
3. All ListItems are copied to MenuItems, with checkbox state synced for multi-select.
4. The menu is positioned at PointToScreen(Point(0, Height)) with width matching the control.
5. ItemClicked and MenuClosed events are wired for selection and state cleanup.

Popup Row Model System

The popup content is normalized through ComboBoxPopupModelBuilder, which converts raw SimpleItem collections into immutable ComboBoxPopupRowModel instances. Each row knows its RowKind:

The builder also detects group headers, manages keyboard focus state, and applies ComboBoxSearchEngine filtering. Search results include MatchStart and MatchLength metadata for highlight rendering.

Dropdown ListBoxType Mapping

Each ComboBoxType maps to a ListBoxType for popup appearance. When DropdownListBoxType is null: OutlineDefault → Outlined, FilledSoft → Filled, RoundedPill → Rounded, CommandMenu → CommandList, VisualDisplay → AvatarList, etc.

Inline Editor & Search

Inline Editor Lifecycle

The inline editor is a BeepTextBox child control (frameless, no shadow, ControlStyle.None) created lazily on first use. It overlays _textAreaRect when the user clicks the text area in an editable or searchable combo box.

• Creation: Theme and font applied once at creation — never on every show.
• Show: ShowInlineEditor() positions the editor over _textAreaRect, pre-fills with current display text, suppresses live-search during programmatic text assignment.
• Live Search: InlineEditor_TextChanged syncs _inputText and opens the dropdown if not already open.
• Free-Text Tokenization: When AllowFreeText + AllowMultipleSelection are enabled, typing , or ; creates a chip from the typed token and clears input.
• Key Handling: Enter commits, Escape discards, Down commits and shows dropdown.
• Commit: HideInlineEditor(true) matches typed text via FindItemByText. If found, selects the match; otherwise keeps free text.

Auto-Complete Engine

• Prefix: StartsWith(StringComparison.OrdinalIgnoreCase)
• Fuzzy: All typed characters must appear in order in the item text (character walk).
• Full: Contains(StringComparison.OrdinalIgnoreCase)

Configurable debounce via AutoCompleteDelay. Results capped at MaxSuggestions.

Search Engine (Popup)

ComboBoxSearchEngine.FilterRows provides scored search:

• Prefix: baseWeight + 300 - lengthDiff
• Substring: baseWeight + 200 - startIndex
• Fuzzy: baseWeight + 100 - spread

Group headers are kept only when at least one child item matches. Best match tracked for keyboard focus.

Multi-Select Mode

Enabling

Set AllowMultipleSelection = true or use ComboBoxType.MultiChipCompact / MultiChipSearch. The popup switches to checkbox rows; selected items render as chip tokens.

Chip Layout Engine

ComboBoxChipLayoutEngine computes chip positions left-to-right, wrapping to a second row if needed (up to 2 rows). Each chip has body, text, and close button (16px ×) rectangles. Exceeding space produces a +N overflow badge.

Chip Rendering

ComboBoxChipPainter draws rounded-rect chips using theme tokens (SelectedBackColor, SelectedForeColor, SelectedBorderColor). Disabled chips use muted colours. Contrast ratio checked (2.5:1 minimum). Overflow badge shows +N text centered. Close buttons render SVG X at 75% opacity.

Hit-test rects for chip bodies and close buttons are registered in ChipCloseRects and ChipBodyRects dictionaries, keyed by item identity. Chip body click opens popup and can scroll to item.

Chip Animation

When SelectedItems is set, the setter diffs old/new lists and starts animations for added/removed chips. A 16 ms (~60 FPS) timer drives linear progress 0→1 (add) or 1→0 (remove) over ChipAnimationDuration.

Popup Selection Flow

• Immediate: Checkbox toggle updates SelectedItems via deferred BeginInvoke. Popup stays open.
• Apply/Cancel: Pending list; Apply commits, Cancel restores snapshot.
• Primary Action: Single CTA button with {count} placeholder.
• Select All: Virtual _selectall row toggles all/none.

Validation & Skeleton Loading

Validation States

ValidationState controls:

• Border: Resolved from ErrorBorderColor, WarningBorderColor, SuccessBorderColor.
• Background tint: 20-alpha overlay over the text area.
• Status icon: Trailing SVG: AlertCircle (error), AlertTriangle (warning), Check (success).
• Text colour: Error state uses ComboBoxErrorForeColor.

Loading Spinner

When IsLoading = true: translucent haze covers the text area (90-alpha of ComboBoxBackColor). Rotating CircleArrowRight SVG animates in the dropdown button area at 20 FPS (15°/tick, 50 ms). All mouse interaction disabled.

Skeleton Shimmer

When ShowSkeleton = true: all normal content replaced by shimmer. Base gray fill with an animated highlight band sweeping left-to-right using a triangular-blend LinearGradientBrush. Sweep advances at ~42 FPS (24 ms interval, SkeletonOffset 0→1). Clipped to text area.

Theming & Visual Tokens

Theme Token Resolution

ComboBoxStateFactory.Build resolves 40+ colour and font tokens into a ComboBoxThemeTokens snapshot once per paint frame:

A Fallback() method provides sensible Material-style defaults when no theme is active.

Visual Token Catalog

ComboBoxVisualTokenCatalog.Resolve returns layout geometry per type:

ApplyTheme Override

Copies ComboBoxBackColor/ForeColor/BorderColor, hover/selected state colours, syncs inline editor colours from TextBoxBackColor/ForeColor, resolves TextFont via BeepThemesManager.ToFont(ComboBoxItemFont) when UseThemeFont = true. Batched via InvalidateOnce().

Architecture

The BeepComboBox follows a layered architecture with strict separation of concerns:

Partial Class Breakdown

Render Pipeline (per frame)

1. DrawContent(g) calls base.DrawContent(g) (border + background via BaseControl).
2. ComboBoxStateFactory.Build(this) snapshots all live state into an immutable ComboBoxRenderState.
3. ComboBoxLayoutEngine.Compute(DrawingRect, renderState, this) calculates sub-rectangles (text area, dropdown button, clear button, image, chips).
4. If IsRtl, all rectangles are mirrored horizontally.
5. The painter is lazily created via ComboBoxTypeRegistry.CreatePainter.
6. _comboBoxPainter.Paint(g, this, state, layout) renders chips → text → decorations → clear button → validation icon → dropdown button → spinner/skeleton.
7. RegisterHitAreas() registers interactive zones for mouse hover/cursor changes.

Painter Hierarchy

IComboBoxPainter
 ├─ ComboBoxFieldPainterBase           (background, text, icons, spinner, skeleton, RTL)
    ├─ DesignSystemComboBoxFieldPainterBase (filled, segmented, borderless, search-icon)
       ├─ OutlineDefaultComboBoxPainter     ─ FilledSoftComboBoxPainter
       ├─ RoundedPillComboBoxPainter         ─ SegmentedTriggerComboBoxPainter
       ├─ MultiChipCompactComboBoxPainter    ─ MultiChipSearchComboBoxPainter
       ├─ DenseListComboBoxPainter           ─ MinimalBorderlessComboBoxPainter
       ├─ CommandMenuComboBoxPainter         ─ VisualDisplayComboBoxPainter
       ├─ OutlineSearchableComboBoxPainter

Helper Classes

Code Examples

Basic Dropdown

var combo = new BeepComboBox
{
    Location = new Point(12, 12),
    Size = new Size(240, 32),
    ComboBoxType = ComboBoxType.OutlineDefault,
    PlaceholderText = "Select a category..."
};

combo.ListItems.Add(new SimpleItem { Text = "Electronics", Name = "Elec" });
combo.ListItems.Add(new SimpleItem { Text = "Books", Name = "Books" });
combo.ListItems.Add(new SimpleItem { Text = "Clothing", Name = "Cloth" });

combo.SelectedItemChanged += (s, e) =>
{
    Console.WriteLine($"Selected: {combo.SelectedItem.Text}");
};

this.Controls.Add(combo);

Multi-Select with Chips

var multiCombo = new BeepComboBox
{
    ComboBoxType = ComboBoxType.MultiChipSearch,
    MaxDisplayChips = 2,
    ChipAnimationDuration = 150,
    ShowSelectAll = true,
    PlaceholderText = "Choose tags..."
};

multiCombo.ListItems.Add(new SimpleItem { Text = "UI/UX", GuidId = "tag1" });
multiCombo.ListItems.Add(new SimpleItem { Text = "Backend", GuidId = "tag2" });
multiCombo.ListItems.Add(new SimpleItem { Text = "DevOps", GuidId = "tag3" });
multiCombo.ListItems.Add(new SimpleItem { Text = "Data Science", GuidId = "tag4" });
multiCombo.ListItems.Add(new SimpleItem { Text = "Security", GuidId = "tag5" });

multiCombo.SelectedItemsChanged += (s, e) =>
{
    Console.WriteLine($"Selected {multiCombo.SelectedItems.Count} tag(s)");
};

Searchable with Auto-Complete

var searchCombo = new BeepComboBox
{
    ComboBoxType = ComboBoxType.OutlineSearchable,
    IsEditable = true,
    AutoComplete = true,
    AutoCompleteMode = BeepAutoCompleteMode.Fuzzy,
    AutoCompleteDelay = 300,
    MaxSuggestions = 8,
    ShowClearButton = true
};

Command Palette Style

var cmdCombo = new BeepComboBox
{
    ComboBoxType = ComboBoxType.CommandMenu,
    IsEditable = true
};

cmdCombo.ListItems.Add(new SimpleItem
{
    Text = "New File",
    SubText = "Create a new document",
    ShortcutText = "Ctrl+N"
});
cmdCombo.ListItems.Add(new SimpleItem
{
    Text = "Open Folder",
    SubText = "Browse and open a directory",
    ShortcutText = "Ctrl+O"
});

Validation & Loading

combo.IsLoading = true;

// After data arrives
combo.ListItems = new BindingList<SimpleItem>(fetchedItems);
combo.IsLoading = false;

if (!combo.SelectedItem?.IsEnabled == true)
{
    combo.ValidationState = BeepComboBoxValidationState.Error;
}

RTL Support

var rtlCombo = new BeepComboBox
{
    IsRtl = true,
    ComboBoxType = ComboBoxType.RoundedPill,
    PlaceholderText = "اختر عنصرًا..."
};
rtlCombo.ListItems.Add(new SimpleItem { Text = "الخيار الأول" });
rtlCombo.ListItems.Add(new SimpleItem { Text = "الخيار الثاني" });