ListBox Internals

Overview

BeepListBox is structured across multiple partial class files, each handling a distinct aspect of the control's behavior. The list box integrates with the 42-item painter system (see listbox-painters.html), supports single and multi selection with keyboard modifiers, drag-drop reordering, full keyboard navigation including type-to-search, UIA accessibility patterns, and virtual scrolling for large datasets.

The internal architecture separates concerns via a helper decomposition similar to GridX, but simpler: rendering delegates to IListBoxPainter implementations, selection state is tracked in a dedicated SelectionManager, and drag-drop uses WinForms standard drag operations with custom rendering of drop indicators.

Partial File Map

BeepListBox is spread across multiple partial class files in the source tree:

Selection System

The SelectionManager class (internal) manages all selection state with three modes:

Selection events fire in order: SelectionChanging (cancelable) → selection changes → SelectedIndexChanged. The SelectedItems property returns a List<BeepListItem> of currently selected items. SelectedIndices returns List<int> index positions.

listBox.SelectionMode = SelectionMode.MultiExtended;

listBox.SelectionChanging += (s, e) =>
{
    if (someCondition) e.Cancel = true;
};

listBox.SelectedIndexChanged += (s, e) =>
{
    Console.WriteLine($"Selected: {listBox.SelectedItems.Count} items");
};

Drag-Drop

Drag-drop reordering is controlled by the AllowDragReorder property (default: false). When enabled, items can be dragged to reorder within the list.

Drop position resolution checks the Y-coordinate of the mouse relative to each item's bounds. If the mouse is in the top third, the drop position is before that item; bottom third = after; middle = onto (insert after). During drag, the dragged item is rendered semi-transparent at the cursor position.

Keyboard Navigation

BeepListBox implements full keyboard navigation in OnKeyDown:

The type-to-search feature maintains a StringBuilder buffer and a Timer. Each character press appends to the buffer and restarts the timer. When the timer expires, the buffer is cleared. The search is case-insensitive and wraps from the current position.

Accessibility

BeepListBox implements UI Automation (UIA) provider pattern via two custom accessible object classes:

Accessible properties set: Name (control label), Role (AccessibleRole.List), Description (from tooltip if set). The control overrides CreateAccessibilityInstance() to return BeepListBoxAccessibleObject. Item runtime IDs are constructed from Handle + item index for stable UIA identification.

Virtual Mode

Virtual mode is enabled via VirtualMode = true and ItemCount. Instead of storing items in memory, the list box fires RetrieveVirtualItem to fetch items on demand as they scroll into view.

Virtual scrolling is efficient for lists with millions of items. Only ~20-50 visible items are materialized at a time. The scrollbar uses ItemCount to compute its range, and RetrieveVirtualItem is called with the index each time an item enters the viewport.

Examples

Multi-Select with Drag Reorder

var listBox = new BeepListBox
{
    SelectionMode = SelectionMode.MultiExtended,
    AllowDragReorder = true,
    ItemStyle = ListBoxType.CardList
};

for (int i = 0; i < 20; i++)
    listBox.Items.Add(new BeepListItem { Text = $"Item {i + 1}" });

listBox.ItemsReordered += (s, e) =>
{
    Console.WriteLine($"Item moved: {e.OldIndex} → {e.NewIndex}");
};

listBox.SelectAll();

Virtual Mode

var listBox = new BeepListBox
{
    VirtualMode = true,
    ItemCount = 1000000
};

listBox.RetrieveVirtualItem += (s, e) =>
{
    e.Item = new BeepListItem
    {
        Text = $"Virtual Row {e.Index}",
        SubText = $"Index: {e.Index:N0}",
        Tag = _data[e.Index]  // backing array
    };
};

listBox.CacheVirtualItems += (s, e) =>
{
    for (int i = e.StartIndex; i <= e.EndIndex; i++)
    {
        if (!_cache.ContainsKey(i))
            _cache[i] = _fetchData(i);
    }
};

Type-to-Search

var listBox = new BeepListBox();

listBox.Items.Add(new BeepListItem { Text = "Apple" });
listBox.Items.Add(new BeepListItem { Text = "Application" });
listBox.Items.Add(new BeepListItem { Text = "Apricot" });
listBox.Items.Add(new BeepListItem { Text = "Banana" });
listBox.Items.Add(new BeepListItem { Text = "Blackberry" });

listBox.SetSelected(0, true);
listBox.Focus();