# FTRMessageBox

## Overview

`FTRMessageBox` is a Windows Forms message box component for displaying modern, themed dialogs with standard buttons, custom buttons, optional user input, optional checkboxes, animations, automatic timeout, and asynchronous display.

It provides two usage styles:

1. **Simple API** for standard message boxes.
2. **Fluent Builder API** for advanced scenarios.

The component automatically follows the active FTR Controls theme.

**Namespace:** `FTRControls`

**Main Type:** `FTRMessageBox`

**Type:** Static class

**Toolbox:** Not required

---

# Basic Usage

## Simple Message Box

For a standard message box, use the static `Show()` method.

```csharp
using System.Windows.Forms;
using FTRControls;

DialogResult result = FTRMessageBox.Show(
    "The record was saved successfully.",
    "Success",
    MessageBoxButtons.OK,
    MessageBoxIcon.Information);
```

The method returns a standard WinForms `DialogResult`.

---

# Show Method

The available method is:

```csharp
public static DialogResult Show(
    string text,
    string title = "",
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None);
```

### Parameters

| Parameter | Type                | Description                          |
| --------- | ------------------- | ------------------------------------ |
| `text`    | `string`            | Message displayed in the dialog      |
| `title`   | `string`            | Dialog title                         |
| `buttons` | `MessageBoxButtons` | Standard button combination          |
| `icon`    | `MessageBoxIcon`    | Optional standard Windows Forms icon |

### Example

```csharp
DialogResult result = FTRMessageBox.Show(
    "Do you want to delete this record?",
    "Delete",
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Warning);

if (result == DialogResult.Yes)
{
    DeleteRecord();
}
```

---

# Standard Buttons

`FTRMessageBox` supports the standard `MessageBoxButtons` combinations used by Windows Forms.

| MessageBoxButtons  | Buttons              |
| ------------------ | -------------------- |
| `OK`               | OK                   |
| `OKCancel`         | OK, Cancel           |
| `YesNo`            | Yes, No              |
| `YesNoCancel`      | Yes, No, Cancel      |
| `RetryCancel`      | Retry, Cancel        |
| `AbortRetryIgnore` | Abort, Retry, Ignore |

The returned `DialogResult` corresponds to the button selected by the user.

For example:

```csharp
DialogResult result = FTRMessageBox.Show(
    "Do you want to continue?",
    "Confirmation",
    MessageBoxButtons.YesNo);

if (result == DialogResult.Yes)
{
    // Continue
}
else if (result == DialogResult.No)
{
    // Do not continue
}
```

---

# Standard Icons

The `icon` parameter accepts the standard Windows Forms `MessageBoxIcon` values.

Common examples include:

```csharp
MessageBoxIcon.Information
MessageBoxIcon.Warning
MessageBoxIcon.Error
MessageBoxIcon.Question
MessageBoxIcon.None
```

Example:

```csharp
FTRMessageBox.Show(
    "The operation could not be completed.",
    "Error",
    MessageBoxButtons.OK,
    MessageBoxIcon.Error);
```

---

# Fluent Builder API

Use `FTRMessageBox.Create()` when you need additional configuration.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Delete Record")
    .WithText("Are you sure you want to delete this record?")
    .WithButtons(MessageBoxButtons.YesNo)
    .WithIcon(MessageBoxIcon.Warning)
    .Show();

if (result.DialogResult == DialogResult.Yes)
{
    DeleteRecord();
}
```

The builder allows multiple configuration methods to be chained together.

---

# FTRMessageBoxBuilder

The following public builder methods are available:

| Method                | Premium | Description                        |
| --------------------- | :-----: | ---------------------------------- |
| `WithText()`          |    No   | Sets the message text              |
| `WithTitle()`         |    No   | Sets the dialog title              |
| `WithButtons()`       |    No   | Configures standard buttons        |
| `WithIcon()`          |    No   | Sets the standard message icon     |
| `WithCustomButtons()` |    No   | Creates custom action buttons      |
| `WithInput()`         |    No   | Adds a single-line text input      |
| `WithCheckbox()`      |    No   | Adds a checkbox                    |
| `WithCornerRadius()`  |   Yes   | Sets the dialog corner radius      |
| `WithButtonRadius()`  |   Yes   | Sets the button corner radius      |
| `WithAnimation()`     |   Yes   | Enables open/close animation       |
| `WithTimeout()`       |   Yes   | Automatically closes the dialog    |
| `Show()`              |    No   | Displays the dialog synchronously  |
| `ShowAsync()`         |    No   | Displays the dialog asynchronously |

---

# WithText

Sets the main message displayed in the dialog.

```csharp
var result = FTRMessageBox.Create()
    .WithText("The operation completed successfully.")
    .Show();
```

---

# WithTitle

Sets the dialog title.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Operation Complete")
    .WithText("The file was saved successfully.")
    .Show();
```

---

# WithButtons

Configures the standard WinForms button combination.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Confirmation")
    .WithText("Do you want to continue?")
    .WithButtons(MessageBoxButtons.YesNo)
    .Show();

if (result.DialogResult == DialogResult.Yes)
{
    ContinueOperation();
}
```

Supported combinations are:

* `OK`
* `OKCancel`
* `YesNo`
* `YesNoCancel`
* `RetryCancel`
* `AbortRetryIgnore`

---

# WithIcon

Sets the message box icon.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Warning")
    .WithText("This action cannot be undone.")
    .WithButtons(MessageBoxButtons.OKCancel)
    .WithIcon(MessageBoxIcon.Warning)
    .Show();
```

---

# Custom Buttons

Use `WithCustomButtons()` when standard `MessageBoxButtons` are not sufficient.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Choose an Action")
    .WithText("Select how you want to proceed.")
    .WithCustomButtons(
        "Save",
        "Save As",
        "Cancel")
    .Show();
```

The method accepts a variable number of button captions.

```csharp
.WithCustomButtons("Option 1", "Option 2", "Option 3")
```

## Important

Custom buttons do **not** receive standard `DialogResult` values such as `Yes`, `No`, or `OK`.

Their `DialogResult` is `DialogResult.None`.

For custom buttons, use `ClickedButtonText` to determine which button the user selected.

Example:

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Save Changes")
    .WithText("How would you like to save the document?")
    .WithCustomButtons(
        "Save",
        "Save As",
        "Discard")
    .Show();

switch (result.ClickedButtonText)
{
    case "Save":
        Save();
        break;

    case "Save As":
        SaveAs();
        break;

    case "Discard":
        DiscardChanges();
        break;
}
```

The first custom button is treated as the primary action.

---

# User Input

Use `WithInput()` to add a single-line text box to the dialog.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Rename")
    .WithText("Enter a new name:")
    .WithInput()
    .Show();

string newName = result.InputText;
```

### Important

`WithInput()` does not accept a label or default value.

The message text should be used to describe the requested input.

For example:

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Rename")
    .WithText("Enter the new name:")
    .WithInput()
    .Show();

if (result.DialogResult == DialogResult.OK)
{
    string newName = result.InputText;
}
```

`InputText` contains the text entered by the user when the dialog closes.

---

# Checkbox

Use `WithCheckbox()` to add an optional checkbox.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Preferences")
    .WithText("Would you like to remember this choice?")
    .WithCheckbox("Remember my choice")
    .Show();

bool rememberChoice = result.IsCheckboxChecked;
```

The checkbox caption is specified by the parameter:

```csharp
.WithCheckbox("Remember my choice")
```

The checked state is returned through:

```csharp
result.IsCheckboxChecked
```

---

# Input and Checkbox Together

Input and checkbox can be used in the same dialog.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("User Settings")
    .WithText("Enter your display name:")
    .WithInput()
    .WithCheckbox("Remember this setting")
    .WithButtons(MessageBoxButtons.OKCancel)
    .Show();

if (result.DialogResult == DialogResult.OK)
{
    string name = result.InputText;
    bool remember = result.IsCheckboxChecked;
}
```

---

# FTRMessageBoxResult

The fluent `Show()` and `ShowAsync()` methods return an `FTRMessageBoxResult`.

It contains the complete result of the interaction.

| Property            | Type           | Description                                  |
| ------------------- | -------------- | -------------------------------------------- |
| `DialogResult`      | `DialogResult` | Standard WinForms result                     |
| `ClickedButtonText` | `string`       | Caption of the button that closed the dialog |
| `InputText`         | `string`       | Text entered into the optional input box     |
| `IsCheckboxChecked` | `bool`         | Checkbox state when the dialog closed        |

---

# DialogResult

`DialogResult` contains the standard WinForms result.

For standard buttons:

```csharp
if (result.DialogResult == DialogResult.Yes)
{
    // User clicked Yes
}
```

Possible values depend on the configured standard buttons.

For custom buttons, `DialogResult` is `DialogResult.None`.

Therefore, custom buttons should be handled through `ClickedButtonText`.

---

# ClickedButtonText

`ClickedButtonText` contains the actual caption of the button that closed the dialog.

Example:

```csharp
var result = FTRMessageBox.Create()
    .WithText("Choose an action.")
    .WithCustomButtons("Open", "Edit", "Delete")
    .Show();

string selectedButton = result.ClickedButtonText;
```

This is particularly useful with custom buttons.

---

# InputText

`InputText` contains the text entered by the user when `WithInput()` is used.

Example:

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Search")
    .WithText("Enter a search term:")
    .WithInput()
    .Show();

string searchTerm = result.InputText;
```

If no input control was added, `InputText` remains an empty string.

---

# IsCheckboxChecked

`IsCheckboxChecked` contains the state of the optional checkbox.

Example:

```csharp
var result = FTRMessageBox.Create()
    .WithText("Configure application settings.")
    .WithCheckbox("Enable automatic updates")
    .Show();

if (result.IsCheckboxChecked)
{
    EnableAutomaticUpdates();
}
```

If no checkbox was added, the value remains `false`.

---

# Asynchronous Display

Use `ShowAsync()` when you want to await the dialog result.

```csharp
var result = await FTRMessageBox.Create()
    .WithTitle("Confirmation")
    .WithText("Continue with this operation?")
    .WithButtons(MessageBoxButtons.YesNo)
    .WithIcon(MessageBoxIcon.Question)
    .ShowAsync();

if (result.DialogResult == DialogResult.Yes)
{
    await ContinueOperationAsync();
}
```

`ShowAsync()` returns:

```csharp
Task<FTRMessageBoxResult>
```

---

# ShowAsync Owner

You can optionally specify an owner window.

```csharp
var result = await FTRMessageBox.Create()
    .WithTitle("Confirmation")
    .WithText("Do you want to continue?")
    .WithButtons(MessageBoxButtons.YesNo)
    .ShowAsync(this);
```

If no owner is supplied, the component attempts to use the active visible Windows Forms window.

---

# Important ShowAsync Requirement

`ShowAsync()` must be called from a Windows Forms UI thread.

Calling it from a context without a UI `SynchronizationContext` causes an `InvalidOperationException`.

Recommended usage:

```csharp
private async void btnSave_Click(object sender, EventArgs e)
{
    var result = await FTRMessageBox.Create()
        .WithTitle("Save")
        .WithText("Save the current document?")
        .WithButtons(MessageBoxButtons.YesNo)
        .ShowAsync(this);

    if (result.DialogResult == DialogResult.Yes)
    {
        SaveDocument();
    }
}
```

---

# Dialog Corner Radius

`WithCornerRadius()` controls the corner radius of the message box.

```csharp
var result = FTRMessageBox.Create()
    .WithText("Rounded dialog")
    .WithCornerRadius(16)
    .Show();
```

> **Premium Feature**

A valid FTR Controls license is required.

When the feature is used without a valid license, the FTR Controls activation prompt is displayed and the requested premium setting is not applied.

---

# Button Corner Radius

`WithButtonRadius()` controls the corner radius of the action buttons.

```csharp
var result = FTRMessageBox.Create()
    .WithText("Custom button appearance")
    .WithButtonRadius(8)
    .Show();
```

> **Premium Feature**

A valid FTR Controls license is required.

---

# Animation

Use `WithAnimation()` to enable the message box open/close animation.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Animated Dialog")
    .WithText("This dialog uses the FTR animation effect.")
    .WithAnimation()
    .Show();
```

> **Premium Feature**

A valid FTR Controls license is required.

Animation is disabled by default.

---

# Automatic Timeout

Use `WithTimeout()` to automatically close the message box after a specified number of milliseconds.

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Automatic Close")
    .WithText("This dialog will close automatically.")
    .WithTimeout(5000)
    .Show();
```

The value is specified in milliseconds.

For example:

```csharp
.WithTimeout(5000)
```

means approximately 5 seconds.

## Timeout Result

When the timeout closes the dialog:

```csharp
result.DialogResult == DialogResult.Cancel
```

and:

```csharp
result.ClickedButtonText
```

is an empty string.

If an input box or checkbox is present, their current values are still copied into the result.

> **Premium Feature**

A valid FTR Controls license is required.

---

# Global Configuration

`FTRMessageBoxConfig` provides application-wide defaults.

These settings affect newly created message boxes.

```csharp
FTRMessageBoxConfig.DefaultCornerRadius = 12;
FTRMessageBoxConfig.DefaultButtonCornerRadius = 8;
FTRMessageBoxConfig.DefaultUseAnimation = true;
```

## Available Settings

| Property                    | Type   | Default | Description                       |
| --------------------------- | ------ | ------: | --------------------------------- |
| `DefaultCornerRadius`       | `int`  |    `10` | Default message box corner radius |
| `DefaultButtonCornerRadius` | `int`  |    `10` | Default button corner radius      |
| `DefaultUseAnimation`       | `bool` | `false` | Enables animation by default      |

A typical application-wide configuration can be placed during application startup:

```csharp
FTRMessageBoxConfig.DefaultCornerRadius = 12;
FTRMessageBoxConfig.DefaultButtonCornerRadius = 8;
FTRMessageBoxConfig.DefaultUseAnimation = false;
```

Individual dialogs can override the defaults through the builder.

---

# Button Text Localization

Standard button captions can be customized through `FTRMessageBoxButtonTexts`.

Available properties are:

```csharp
FTRMessageBoxButtonTexts.OK
FTRMessageBoxButtonTexts.Cancel
FTRMessageBoxButtonTexts.Yes
FTRMessageBoxButtonTexts.No
FTRMessageBoxButtonTexts.Retry
FTRMessageBoxButtonTexts.Abort
FTRMessageBoxButtonTexts.Ignore
```

For example, an application can change the standard captions before displaying dialogs:

```csharp
FTRMessageBoxButtonTexts.OK = "OK";
FTRMessageBoxButtonTexts.Cancel = "Cancel";
FTRMessageBoxButtonTexts.Yes = "Yes";
FTRMessageBoxButtonTexts.No = "No";
```

This is useful for applications that need localized button captions.

For example:

```csharp
FTRMessageBoxButtonTexts.OK = "Confirm";
FTRMessageBoxButtonTexts.Cancel = "Close";
FTRMessageBoxButtonTexts.Yes = "Continue";
FTRMessageBoxButtonTexts.No = "Stop";
```

These values are application-wide settings.

---

# Themes

`FTRMessageBox` automatically uses the active FTR Controls theme.

The dialog applies the current theme when it is created and responds to runtime theme changes.

Applications do not need to manually assign the MessageBox background, panel, text, and primary colors for normal FTR theme usage.

This allows MessageBox dialogs to remain visually consistent with the rest of an FTR Controls application.

---

# Right-to-Left Applications

The MessageBox is a Windows Forms dialog and can be used in applications configured for right-to-left layouts.

When integrating it into an RTL application, configure the application's or owning form's RTL settings according to the application's requirements.

---

# Recommended Usage Patterns

## Simple Information Message

```csharp
FTRMessageBox.Show(
    "The operation completed successfully.",
    "Success",
    MessageBoxButtons.OK,
    MessageBoxIcon.Information);
```

---

## Confirmation

```csharp
DialogResult result = FTRMessageBox.Show(
    "Are you sure you want to delete this record?",
    "Delete",
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Warning);

if (result == DialogResult.Yes)
{
    DeleteRecord();
}
```

---

## Input Dialog

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Rename")
    .WithText("Enter the new name:")
    .WithInput()
    .WithButtons(MessageBoxButtons.OKCancel)
    .Show();

if (result.DialogResult == DialogResult.OK)
{
    string newName = result.InputText;
}
```

---

## Input + Checkbox

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("Application Settings")
    .WithText("Configure your preference:")
    .WithInput()
    .WithCheckbox("Remember this setting")
    .WithButtons(MessageBoxButtons.OKCancel)
    .Show();

if (result.DialogResult == DialogResult.OK)
{
    string value = result.InputText;
    bool remember = result.IsCheckboxChecked;
}
```

---

## Custom Actions

```csharp
var result = FTRMessageBox.Create()
    .WithTitle("File Exists")
    .WithText("A file with this name already exists.")
    .WithCustomButtons(
        "Replace",
        "Keep Both",
        "Cancel")
    .Show();

switch (result.ClickedButtonText)
{
    case "Replace":
        ReplaceFile();
        break;

    case "Keep Both":
        KeepBothFiles();
        break;

    case "Cancel":
        break;
}
```

---

## Async Confirmation

```csharp
var result = await FTRMessageBox.Create()
    .WithTitle("Confirmation")
    .WithText("Do you want to continue?")
    .WithButtons(MessageBoxButtons.YesNo)
    .WithIcon(MessageBoxIcon.Question)
    .ShowAsync(this);

if (result.DialogResult == DialogResult.Yes)
{
    await ProcessAsync();
}
```

---

# Keyboard Behavior

The message box supports common keyboard interaction.

### Enter

Activates the primary action button.

For standard buttons, this is normally the primary positive action such as `OK`, `Yes`, or `Retry`.

For custom buttons, the first custom button is treated as the primary action.

### Escape

If a Cancel button is available, pressing `Escape` activates the Cancel action.

If no Cancel action is available, Escape does not provide a standard Cancel result.

---

# Licensing

Some FTRMessageBox features are premium features.

The following builder methods require a valid FTR Controls license:

* `WithCornerRadius()`
* `WithButtonRadius()`
* `WithAnimation()`
* `WithTimeout()`

When a premium method is used without a valid license, the FTR Controls activation prompt is displayed and the premium setting is not applied.

The following features do not require a premium license:

* Standard `Show()`
* `Create()`
* `WithText()`
* `WithTitle()`
* `WithButtons()`
* `WithIcon()`
* `WithCustomButtons()`
* `WithInput()`
* `WithCheckbox()`
* `ShowAsync()`

---

# Public API Summary

## FTRMessageBox

```csharp
public static FTRMessageBoxBuilder Create();

public static DialogResult Show(
    string text,
    string title = "",
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None);
```

---

## FTRMessageBoxBuilder

```csharp
WithText(string text)
WithTitle(string title)
WithButtons(MessageBoxButtons buttons)
WithIcon(MessageBoxIcon icon)
WithCustomButtons(params string[] buttonTexts)

WithInput()
WithCheckbox(string text)

WithCornerRadius(int radius)
WithButtonRadius(int radius)
WithAnimation()
WithTimeout(int milliseconds)

Show()
ShowAsync(IWin32Window owner = null)
```

---

## FTRMessageBoxResult

```csharp
DialogResult DialogResult
string ClickedButtonText
string InputText
bool IsCheckboxChecked
```

---

## FTRMessageBoxConfig

```csharp
int DefaultCornerRadius
int DefaultButtonCornerRadius
bool DefaultUseAnimation
```

Default values:

```text
DefaultCornerRadius       = 10
DefaultButtonCornerRadius = 10
DefaultUseAnimation       = false
```

---

## FTRMessageBoxButtonTexts

```csharp
string OK
string Cancel
string Yes
string No
string Retry
string Abort
string Ignore
```

---

# Quick Reference

| Requirement                   | Recommended API                        |
| ----------------------------- | -------------------------------------- |
| Simple message                | `FTRMessageBox.Show()`                 |
| Standard confirmation         | `WithButtons(MessageBoxButtons.YesNo)` |
| Custom actions                | `WithCustomButtons()`                  |
| User text input               | `WithInput()`                          |
| Checkbox                      | `WithCheckbox()`                       |
| Read selected standard button | `DialogResult`                         |
| Read selected custom button   | `ClickedButtonText`                    |
| Read user input               | `InputText`                            |
| Read checkbox state           | `IsCheckboxChecked`                    |
| Async dialog                  | `ShowAsync()`                          |
| Rounded dialog                | `WithCornerRadius()`                   |
| Rounded buttons               | `WithButtonRadius()`                   |
| Animation                     | `WithAnimation()`                      |
| Auto-close                    | `WithTimeout()`                        |
| Global defaults               | `FTRMessageBoxConfig`                  |
| Localize standard buttons     | `FTRMessageBoxButtonTexts`             |
| Automatic FTR theme support   | Built in                               |

---

# Important Notes

* `FTRMessageBox` is a static API and does not need to be placed on a form or added to the Visual Studio Toolbox.
* Use the simple `Show()` method when you only need a standard message box.
* Use `Create()` when you need input, checkboxes, custom buttons, animation, timeout, or other advanced configuration.
* For standard buttons, use `DialogResult` to determine the user's choice.
* For custom buttons, use `ClickedButtonText` because custom buttons return `DialogResult.None`.
* `WithInput()` does not accept a default value or a separate input label.
* `WithCheckbox()` requires a checkbox caption.
* `ShowAsync()` must be called from a Windows Forms UI thread.
* Timeout closes the dialog with `DialogResult.Cancel`.
* Premium features require a valid FTR Controls license.
* Standard button captions can be customized globally through `FTRMessageBoxButtonTexts`.
* The MessageBox automatically follows the active FTR Controls theme.