BeepListofValuesBox

Overview

Namespace: TheTechIdea.Beep.Winform.Controls

Assembly: TheTechIdea.Beep.Winform.Controls

Inheritance: BeepListofValuesBox → BaseControl → System.Windows.Forms.UserControl

BeepListofValuesBox is an Oracle Forms-inspired List-of-Values (LOV) selector control. It combines an editable key textbox (left ~22% of the control width) with a read-only value display area (right ~78%), and a dropdown popup (BeepLovPopup) providing a multi-column BeepGridPro-backed search grid. Full key validation ensures typed keys exist in the list; invalid entries trigger error text + red background + notification tooltips.

The popup supports optional async item loading with cancellation and spinner feedback, a recent-selection chip strip (max 5), search filtering across Value/Text/Description fields, custom column definitions, and complete keyboard navigation (F9 / Alt+Down / Escape / Enter).

Key Features

• Split Layout: Editable key (BeepTextBox, ~22%) + painted read-only value area (~78%).
• Key Validation: ValidateKey() checks typed keys against ListItems. Invalid keys show inline ErrorText + notification + revert to last valid key.
• Multi-Column Popup: BeepGridPro popup with optional explicit column definitions (LovColumns). Falls back to auto-generated Key + Display Value columns.
• Async Loading: Optional ItemsLoader delegate. Popup opens immediately with spinner, loads on background thread, populates grid on completion. CancellationToken-aware.
• Recent History: Last 5 selections persisted across popup opens. Clickable chips in the popup. Getters/setters for external persistence (e.g. user settings).
• Search Filtering: Text-box in popup filters by Value, Text, and Description on every keystroke. Shows "X of Y records" count label.
• Keyboard Shortcuts: F9 (Oracle Forms standard — pre-seeds search from key field), Alt+Down (Windows combo standard), Delete/Backspace (clear selection when key field unfocused), Escape (close popup).
• Key Badge Pill: Optional coloured rounded pill displaying the raw key in the value area. Accent-colour background with auto-contrasting text (black or white).
• DPI-Aware Painting: Value area, badge pill, and placeholder text scaled via BeepThemesManager.DpiScaleX/Y.
• Theme Propagation: Theme forwarded to key TextBox, popup form, popup grid, popup buttons, search box, and recent-panel chips.
• Trailing Icon: ChevronDown icon from SvgsUI as the dropdown trigger. Clickable, handled by BaseControl's built-in trailing-icon infrastructure (no separate BeepButton child).
• IBeepComponent: SetValue (SimpleItem or string), GetValue (returns SimpleItem), LabelText/HelperText shadow with auto-enable.

Properties (12 total)

Methods

Events

The Popup (BeepLovPopup)

BeepLovPopup is a borderless Form with the following components:

• Header Panel (44px): BeepTextBox search box + BeepButton close ("✕").
• Recent Items Panel (34px, optional): FlowLayoutPanel of BeepButton chips showing recent selections, most recent first. Each chip click accepts the item immediately.
• Grid (BeepGridPro, Fill dock): Configurable columns, single-select, read-only. RowSelectionChanged tracks _pendingSelection. Double-click = Accept.
• Footer Panel (44px): Count label ("12 records" / "5 of 20"), Cancel + OK BeepButtons.
• Loading Overlay: Semi-transparent panel with animated Braille spinner ("⠇ Loading…") and "⚠ Load failed: ..." error state. Positioned over grid area.

Layout constants: HeaderH=44, FooterH=44, MinPopupW=280, MaxVisRows=12, BorderPx=1. The form paints a 1px themed border in OnPaint. Position is calculated below the owner control (or above if insufficient space) using Screen.WorkingArea bounds.

Key methods: ShowAt(items, screenOrigin, ownerWidth, preloadSearch), ApplyLovTheme() (themes all child BeepControls and the grid), BeginLoading() / EndLoading(items) (spinner lifecycle), LoadItemsAsync(loader, preloadSearch) (cancellable async load), Accept() (pushes recent + fires ItemAccepted + hides), Cancel() (cancels in-flight load + fires Cancelled + hides).

The popup auto-closes on OnDeactivate and handles keyboard (Escape=Cancel, Enter/F9=Accept). Grid is auto-configured with Key + Display Value columns when LovColumns is empty.

Layout & Painting

The control uses a two-region layout:

• Key TextBox (left): A BeepTextBox with IsChild=true and IsFrameless=true. Positioned at contentRect.Left + padding, width = 22% of content area (min 40px). Height = _keyTextBox.PreferredHeight. Vertically centred.
• Value Area (right): Painted directly in PaintValueArea, not a child control. Width = content area minus key width minus spacing. Background filled with _currentTheme.PanelBackColor. Contains:
  • Placeholder text: "Select a value…" when no key and no display value.
  • Key badge pill: When ShowKeyBadge && hasKey && _badgeFont != null. Rounded rectangle with AccentColor fill, contrast text (black/white via perceived luminance).
  • Display text: _selectedDisplayValue in theme ForeColor.

AdjustLayout() is called from InitLayout and OnResize. It calls GetAdjustedContentRect() (painter-aware, excludes trailing icon area), computes key and value widths, and positions the internal TextBox. DPI scaling uses BeepThemesManager.DpiScaleX/Y for all pixel calculations.

Keyboard Navigation

All handled via ProcessCmdKey(ref Message, Keys) override. Returns true for handled keys, preventing further processing.

Recent-Selection History

The popup maintains a Queue<SimpleItem> _recentItems capped at MaxRecentItems = 5. On Accept(), PushRecent(item): removes any duplicate, enqueues the new item, evicts oldest if >5.

History is synchronised between the popup and the owner control via: _recentHistory field in BeepListofValuesBox, RecentItems get/set on BeepLovPopup, and RecentSelections get/set on BeepListofValuesBox. The history survives popup open/close cycles. Users can persist RecentSelections to application settings and restore on next session.

The recent panel (_recentPanel) is a FlowLayoutPanel with a strip of BeepButton chips ordered most-recent first, showing the item's Text or Value truncated to 18 characters. Each chip has a themed appearance and its Tag holds the SimpleItem for click handling.

Theming

• Fonts: LovFontHelpers.GetLovFontFromTheme(theme) and GetBadgeFontFromTheme(theme) resolve fonts. Cached in _fieldFont/_badgeFont, rebuilt on ApplyTheme. Disposed on theme change if different instances.
• Key TextBox: Theme, UseThemeColors, Font set via _keyTextBox.Theme, _keyTextBox.UseThemeColors, and _keyTextBox.Font. ApplyTheme called.
• Popup: _lovPopup.LovTheme, _lovPopup.UseThemeColors, _lovPopup.CurrentTheme set. ApplyLovTheme() propagates to header/footer panels, grid, search box, all BeepButton children, count label, loading overlay, and recent-panel chips.
• Badge Pill: Background = _currentTheme.AccentColor. Foreground = ContrastForeColor(bg) — black (Color.FromArgb(30,30,30)) if luminance > 0.55, white otherwise. Perceived luminance via ITU-R BT.601 formula.
• Value Area: Background = _currentTheme.PanelBackColor. Text = _currentTheme.ForeColor. Placeholder = _currentTheme.SecondaryTextColor.
• Trailing Icon: TrailingIconPath = SvgsUI.ChevronDown, set in InitializeComponents(). BaseControl paints it with theming support.

Examples

Basic Usage — Static Items

var lov = new BeepListofValuesBox
{
    ListItems = new List<SimpleItem>
    {
        new SimpleItem { Value = "US", Text = "United States" },
        new SimpleItem { Value = "GB", Text = "United Kingdom" },
        new SimpleItem { Value = "FR", Text = "France" },
        new SimpleItem { Value = "DE", Text = "Germany" }
    },
    LovTitle = "Select Country",
    ShowKeyBadge = true,
    Width = 400
};
lov.SelectionChanged += (s, e) =>
    Console.WriteLine($"{lov.SelectedKey} = {lov.SelectedDisplayValue}");

Programmatic Selection

lov.SelectedKey = "FR";  // ok
lov.SelectedKey = "XX";  // error + revert + tooltip
lov.SetValue(new SimpleItem { Value = "DE", Text = "Germany" });
lov.SetValue("GB");  // string key
lov.Reset(); // clear everything

Async Loading

var asyncLov = new BeepListofValuesBox
{
    LovTitle = "User Search", Width = 400,
    ItemsLoader = async (ct) =>
    {
        await Task.Delay(500, ct);
        return new List<SimpleItem>
        {
            new SimpleItem { Value = "1", Text = "Alice" },
            new SimpleItem { Value = "2", Text = "Bob" }
        };
    }
};

Custom Columns

var columns = new BeepListofValuesBox
{
    ListItems = products, LovTitle = "Products",
    LovColumns = new List<BeepColumnConfig>
    {
        new BeepColumnConfig { ColumnName = "Value", ColumnCaption = "SKU", Width = 100 },
        new BeepColumnConfig { ColumnName = "Text", ColumnCaption = "Name", Width = 200 },
        new BeepColumnConfig { ColumnName = "Description", ColumnCaption = "Category", Width = 150 }
    }
};

Persisting Recent History

// Restore
lov.RecentSelections = Properties.Settings.Default.LovHistory;
// Save on close
FormClosing += (_,_) => {
    Properties.Settings.Default.LovHistory = lov.RecentSelections;
    Properties.Settings.Default.Save();
};

Label and Helper Text

var labeled = new BeepListofValuesBox
{
    LabelText = "Country Code",
    HelperText = "Type or press F9 to search",
    ListItems = countries, Width = 400
};

Validation & Error Feedback

When a key is typed that doesn't exist in ListItems:

• ErrorText (BaseControl) is set to "Invalid key — not in the list."
• HasError is set to true, which triggers BaseControl's error visual (typically red border or background).
• A notification tooltip is shown via ShowNotification("Invalid key. Please enter a valid value from the list.", ToolTipType.Warning, 2000).
• The key field text reverts to _lastValidKey (the most recent valid key).
• When a valid key is subsequently entered, HasError is cleared and ErrorText is set to string.Empty.

Popup Lifecycle

1. Open: User presses F9, Alt+Down, or clicks the trailing chevron icon. OpenPopup() creates/configures BeepLovPopup (lazy created, reused).
2. Configure: Popup receives LovTitle, LovColumns, MaxPopupHeight, theme, and RecentItems. Columns auto-generated if LovColumns is empty.
3. Load: If ItemsLoader is non-null, LoadItemsAsync() shows spinner, runs the loader on a background thread with CancellationToken, and calls EndLoading on completion. Otherwise uses ListItems synchronously.
4. Interact: User types in search (filters by Value/Text/Description), browses grid rows, and accepts (OK/double-click/Enter/F9) or cancels (Cancel/Escape/deactivate).
5. Close: Accept() pushes to recent, fires ItemAccepted, hides. Cancel() cancels async load, fires Cancelled, hides. Auto-close on deactivate.

Architecture