BeepDialogBox

Overview

BeepDialogBox is a composable dialog panel that replaces standard MessageBox dialogs with a fully themed, customizable alternative. It renders inside any container — typically a BeepPopupForm or a borderless overlay panel — and surfaces up to three action buttons plus a close button.

Built on BeepPanel, the control owns an icon area, a message area, and a button row. Each button exposes its label and color as first-class properties, and the dialog fires dedicated events for every possible user action, from which the caller derives the BeepDialogResult.

Inheritance: Control → BaseControl → BeepPanel → BeepDialogBox
Typical host: BeepPopupForm or a dedicated overlay Panel
Namespace: TheTechIdea.Beep.Winform.Controls

Key Features

🎨 Three-Button Layout

Primary, secondary, and tertiary buttons with independent labels and colors. Show only the buttons you need.

🖼️ Icon Area

Built-in BeepImage area for info, warning, error, or custom icons to convey dialog type at a glance.

✖ Close Button

Dedicated close (×) button fires CloseButtonClicked — distinct from any destructive action button.

📣 Rich Events

Separate events for every button click make it trivial to wire different logic to each action.

🎯 DialogResult

Read the DialogResult property after the dialog closes instead of checking events.

🖌️ Full Theming

BeepPanel inheritance makes every color, border, font, and spacing theme-aware.

Visual Preview

Confirm Delete ✕

⚠️

Are you sure you want to permanently delete this record? This action cannot be undone.

Basic Usage

Simple Confirmation Dialog

var dlg = new BeepDialogBox
{
    ShowTitle            = true,
    Text                 = "Confirm Delete",
    PrimaryButtonText    = "Delete",
    PrimaryButtonColor   = Color.FromArgb(244, 67, 54),
    SecondaryButtonText  = "Cancel"
};

dlg.PrimaryButtonClicked   += (s, e) => DeleteRecord();
dlg.SecondaryButtonClicked += (s, e) => { /* dismiss */ };
dlg.CloseButtonClicked     += (s, e) => { /* dismiss */ };

popupHost.ShowDialog(dlg);

Reading DialogResult

dlg.PrimaryButtonClicked += (s, e) =>
{
    if (dlg.DialogResult == BeepDialogResult.Primary)
        ProcessResult();
};

Properties

Property	Type	Default	Description
`DialogResult`	BeepDialogResult	None	Which button was pressed. Values: None, Primary, Secondary, Third, Close.
`PrimaryButtonText`	string	"OK"	Label on the primary (right-most) action button.
`SecondaryButtonText`	string	"Cancel"	Label on the secondary button. Hidden when empty or null.
`PrimaryButtonColor`	Color	(theme primary)	Background fill color for the primary button.
`SecondaryButtonColor`	Color	(theme surface)	Background fill color for the secondary button.
`IconImagePath`	string	""	Path to an image shown in the left icon area (info, warning, error, or custom).

Inherits all BeepPanel and BaseControl properties including ShowTitle, BorderStyle, BorderThickness, and all theme properties.

Events

Event	Signature	Description
`PrimaryButtonClicked`	EventHandler	Fires when primary button is clicked. DialogResult set to Primary.
`SecondaryButtonClicked`	EventHandler	Fires when secondary button is clicked. DialogResult set to Secondary.
`ThirdButtonClicked`	EventHandler	Fires when the optional third button is clicked. DialogResult set to Third.
`CloseButtonClicked`	EventHandler	Fires when the ✕ header close icon is clicked. DialogResult set to Close.

Code Examples

Async Awaitable Confirmation

public static Task<BeepDialogResult> ShowConfirmAsync(
    Control host, string title, string message,
    string primaryLabel = "Confirm", string secondaryLabel = "Cancel",
    Color? primaryColor = null)
{
    var tcs = new TaskCompletionSource<BeepDialogResult>();
    var dlg = new BeepDialogBox
    {
        Text                = title,
        MessageText         = message,
        PrimaryButtonText   = primaryLabel,
        SecondaryButtonText = secondaryLabel,
        PrimaryButtonColor  = primaryColor ?? Color.FromArgb(25, 118, 210)
    };

    dlg.PrimaryButtonClicked   += (s, e) => tcs.TrySetResult(BeepDialogResult.Primary);
    dlg.SecondaryButtonClicked += (s, e) => tcs.TrySetResult(BeepDialogResult.Secondary);
    dlg.CloseButtonClicked     += (s, e) => tcs.TrySetResult(BeepDialogResult.Close);

    ShowOverlay(host, dlg, () => tcs.Task.IsCompleted);
    return tcs.Task;
}

// Usage:
var result = await ShowConfirmAsync(this, "Delete Item",
    "This cannot be undone.", "Delete",
    primaryColor: Color.FromArgb(244, 67, 54));
if (result == BeepDialogResult.Primary)
    DeleteItem();

Error Dialog

var errorDlg = new BeepDialogBox
{
    Text                = "Connection Failed",
    MessageText         = $"Could not connect:\n{ex.Message}",
    IconImagePath       = "icons/error.svg",
    PrimaryButtonText   = "Retry",
    SecondaryButtonText = "Cancel"
};
errorDlg.PrimaryButtonClicked   += (s, e) => RetryConnection();
errorDlg.SecondaryButtonClicked += (s, e) => NavigateHome();

Best Practices

Color destructive actions red — Set PrimaryButtonColor to a red/danger value for Delete, Remove, or irreversible action buttons.
Hide unused buttons — Set SecondaryButtonText = "" to hide it for simple OK-only confirmations.
Always handle CloseButtonClicked — Users must always be able to dismiss the dialog; never leave this event unhandled.
Use an icon — An info/warning/error icon set via IconImagePath dramatically improves comprehension.
Keep messages concise — One to three sentences maximum. Link to help pages for detailed explanations.
Prefer async wrappers — The TaskCompletionSource pattern avoids blocking the UI thread and integrates cleanly with async workflows.