Beep Tooltip System

Overview

The Beep Tooltip System is a layered, singleton-managed framework. The simplified architecture is:

• ToolTipManager — singleton façade; create, attach, update, and dismiss tooltips with one call.
• ToolTipConfig / PopoverConfig — immutable (or mutable) configuration objects passed to the manager.
• ToolTipInstance — the runtime wrapper that owns the CustomToolTip window, show/hide animation, and lifetime.
• CustomToolTip — the WinForms Form subclass rendered on screen. Delegates all drawing to an IToolTipPainter.
• IToolTipPainter / ToolTipPainterFactory — strategy pattern; chooses the correct painter per ToolTipLayoutVariant.
• BeepPopover / BeepPinnedTooltip — persistent non-auto-dismiss windows; extend CustomToolTip.
• BeepTourManager / BeepTourBuilder — guided-tour engine built on top of the tooltip stack.
• ToolTipExtensions / ToolTipBuilder — extension methods and fluent builder for attaching tooltips to any Control.

Enumerations

ToolTipType — Semantic type (20 values)

ToolTipPlacement — 13 positions

ToolTipAnimation — 8 values

ToolTipLayoutVariant — 7 values

ToolTipTriggerMode

EasingFunction

ToolTipArrowStyle

ToolTipConfig — Complete Reference

Identity & Content

Positioning

Timing

Appearance — Theme & Style

Appearance — Colors

Typography, Layout & Visual Elements

Icons & Images

Animation

Trigger & Interaction

Preview Layout

Shortcut Badges

// ShortcutKeyItem
new ShortcutKeyItem { Modifiers = Keys.Control, Key = Keys.S },
new ShortcutKeyItem { Modifiers = Keys.Control | Keys.Shift, Key = Keys.P, DisplayText = "Cmd Palette" }

Step / Tour Layout

Accessibility

Lifecycle Callbacks

ToolTipManager (Singleton Entry Point)

Access via ToolTipManager.Instance. Thread-safe via ConcurrentDictionary; auto-cleanup timer runs every 5 s.

Global Default Properties

Show Methods

Hide & Update Methods

Control Attachment

Query Methods

Extension Methods & Fluent Builder

ToolTipExtensions (Control extension methods)

ToolTipBuilder — Fluent API

// Attach to a control
ToolTipBuilder.Create()
    .WithTitle("Save File")
    .WithText("Saves the current document to disk.")
    .WithTheme(ToolTipType.Info)
    .WithPlacement(ToolTipPlacement.Top)
    .WithAnimation(ToolTipAnimation.Slide)
    .WithArrow(true)
    .WithShadow(true)
    .Closable(false)
    .AttachTo(btnSave);

// Show at a point
await ToolTipBuilder.Create()
    .WithText("Processing…")
    .WithTheme(ToolTipType.Notification)
    .WithDuration(2000)
    .ShowAsync(cursorPosition);

All builder methods return this for chaining. Available builder methods:

BeepPopover — Persistent Popup

A persistent window that stays open until explicitly dismissed. Extends CustomToolTip. Configured via PopoverConfig (extends ToolTipConfig).

PopoverConfig Properties

BeepPopover Public API

// Confirmation popover
await ToolTipManager.Instance.ShowPopoverAsync(btnDelete, new PopoverConfig
{
    Title               = "Delete item?",
    Text                = "This action cannot be undone.",
    Type                = ToolTipType.Error,
    PrimaryButtonText   = "Delete",
    PrimaryButtonType   = ToolTipType.Error,
    SecondaryButtonText = "Cancel",
    TriggerMode         = ToolTipTriggerMode.Click,
    Placement           = ToolTipPlacement.Top,
    OnPrimaryClick      = key => DeleteItem(),
    OnSecondaryClick    = key => { /* do nothing */ }
});

BeepPinnedTooltip — Draggable Pinned Window

Extends BeepPopover. When pinned, the window stays on screen and can be dragged anywhere. A pin button appears in the top-right corner.

// Enable pinnable tooltip via ToolTipConfig
btnHelp.SetTooltip(new ToolTipConfig
{
    Title     = "Detailed Help",
    Text      = "This panel controls the …",
    Pinnable  = true,
    Closable  = true,
    Duration  = 0,          // no auto-dismiss
    Placement = ToolTipPlacement.Right
});

Guided Tour — BeepTourManager & BeepTourBuilder

A lightweight guided-tour / onboarding engine built on the tooltip stack. All tooltips are ToolTipLayoutVariant.Tour with step indicators and Prev/Next navigation.

BeepTourStep Properties

BeepTourManager API

BeepTourBuilder Fluent API

// ── Fluent builder ──────────────────────────────────────────────
BeepTourManager.Instance
    .CreateTour()
    .AddStep(btnNew,     "Create New",  "Click here to create a new record")
    .AddStep(btnSave,    "Save",        "Saves all pending changes")
        .WithCallbacks(onEnter: () => btnSave.Focus())
    .AddStep(tbxSearch,  "Search",      "Type to filter the grid rows")
        .WithImage(@"Assets\tour-search.png")
    .AddStep(btnExport,  "Export",      "Export results to Excel or CSV",
                         ToolTipPlacement.Left)
    .Build()
    .Start();

// ── Events ──────────────────────────────────────────────────────
BeepTourManager.Instance.TourCompleted += (s, e) =>
    Properties.Settings.Default.TourSeen = true;

BeepTourManager.Instance.StepChanged += (s, args) =>
    lblStep.Text = $"Step {args.current} of {args.total}";

Painter Pipeline

All rendering is delegated through IToolTipPainter. ToolTipPainterFactory selects the correct painter based on ToolTipLayoutVariant.

IToolTipPainter Interface

public interface IToolTipPainter
{
    void Paint(Graphics g, Rectangle bounds, ToolTipConfig config,
               ToolTipPlacement placement, IBeepTheme theme);
    void PaintBackground(Graphics g, Rectangle bounds, ToolTipConfig config, IBeepTheme theme);
    void PaintBorder    (Graphics g, Rectangle bounds, ToolTipConfig config, IBeepTheme theme);
    void PaintShadow    (Graphics g, Rectangle bounds, ToolTipConfig config);
    void PaintArrow     (Graphics g, Point position, ToolTipPlacement placement,
                         ToolTipConfig config, IBeepTheme theme);
    void PaintContent   (Graphics g, Rectangle bounds, ToolTipConfig config, IBeepTheme theme);
    Size CalculateSize  (Graphics g, ToolTipConfig config);
}

Registering a custom painter

// Implement the interface
public class MyCustomPainter : ToolTipPainterBase
{
    public override void PaintContent(Graphics g, Rectangle bounds,
                                      ToolTipConfig config, IBeepTheme theme)
    {
        // custom rendering
    }
}

// Use it via ToolTipLayoutVariant.Custom requires overriding GetPainter,
// or set directly on the CustomToolTip instance before Show().

Code Examples

Simple tooltip on any control

btnSave.SetTooltip("Save your changes (Ctrl+S)");

Rich titled tooltip

btnSave.SetRichTooltip(
    text:  "Saves all unsaved changes to the current document.",
    title: "Save File",
    type:  ToolTipType.Info
);

Shortcut badge tooltip

btnSave.SetTooltip(new ToolTipConfig
{
    Title         = "Save File",
    Text          = "Save the current document.",
    LayoutVariant = ToolTipLayoutVariant.Shortcut,
    Shortcuts     = new List<ShortcutKeyItem>
    {
        new ShortcutKeyItem { Modifiers = Keys.Control, Key = Keys.S }
    }
});

Preview hover card (lazy image)

thumbnailLabel.SetTooltip(new ToolTipConfig
{
    Title             = "Project Screenshot",
    Text              = "Last modified: today",
    LayoutVariant     = ToolTipLayoutVariant.Preview,
    PreviewSubtitle   = "screenshot.png · 2.4 MB",
    PreviewFooterText = "Click to open",
    LoadPreviewAsync  = async () => await LoadThumbnailAsync(projectId),
    Placement         = ToolTipPlacement.Right
});

Transient notification above a button

// After form validation
await txtEmail.ShowErrorAsync("Please enter a valid email address.");

// After a successful save
await btnSave.ShowSuccessAsync("Saved!", duration: 1500);

Glass-style tooltip

statusIcon.SetTooltip(new ToolTipConfig
{
    Title         = "System Status",
    Text          = "All services running normally.",
    Type          = ToolTipType.Success,
    LayoutVariant = ToolTipLayoutVariant.Glass,
    Animation     = ToolTipAnimation.Zoom,
    Placement     = ToolTipPlacement.BottomStart
});

Programmatic tooltip at cursor

private async void OnGridCellHover(object sender, CellHoverEventArgs e)
{
    var pos = grid.PointToScreen(e.CellBounds.Location);

    _hoverKey = await ToolTipManager.Instance.ShowTooltipAsync(new ToolTipConfig
    {
        Title     = e.ColumnHeader,
        Text      = e.CellValue?.ToString() ?? "(empty)",
        Type      = ToolTipType.Default,
        Duration  = 0,          // keep until cell leave
        Placement = ToolTipPlacement.Top,
        Position  = pos
    });
}

private async void OnGridCellLeave(object sender, EventArgs e)
{
    if (_hoverKey != null)
    {
        await ToolTipManager.Instance.HideTooltipAsync(_hoverKey);
        _hoverKey = null;
    }
}

Follow-cursor tooltip

ToolTipBuilder.Create()
    .WithText("Drag to resize")
    .WithTheme(ToolTipType.Hint)
    .WithAnimation(ToolTipAnimation.Fade)
    .FollowCursor(true)
    .WithArrow(false)
    .AttachTo(resizeHandle);

Best Practices

• Use extension methods for simple cases. control.SetTooltip("text") is always sufficient for plain hover tooltips — no manual ToolTipManager calls needed.
• Use ToolTipBuilder for one-off styled tooltips. The fluent API avoids repeatedly constructing ToolTipConfig objects.
• Use ToolTipType semantically. Choose Error for errors, Warning for cautions — the type drives accessible color selection including WCAG contrast enforcement (MinContrastRatio).
• Set Duration = 0 for popovers and pinnable tooltips. Never let an interactive or pinned tooltip auto-dismiss.
• Use PersistOnHover = true (default) for all rich tooltips. This satisfies WCAG 1.4.13 — users must be able to move the mouse over the tooltip.
• Wire TriggerMode = Click for destructive confirmation popovers. Hover-triggered confirmation dialogs are confusing; click-triggered ones are expected.
• Prefer LoadPreviewAsync for heavy images in Preview tooltips — the skeleton placeholder displays immediately while the image loads.
• Call HideAllTooltipsAsync() when opening a modal dialog to prevent orphaned tooltips underneath.
• Disable animations during tests: ToolTipManager.Instance.EnableAnimations = false;
• Always set TriggerMode = Manual when managing lifecycle yourself (grid cells, map pins, etc.) so the manager does not interfere with your MouseEnter/Leave logic.
• Tour: call Properties.Settings.Default.TourSeen after TourCompleted to avoid showing the tour to returning users.