# FTR Toast Notification

## Overview

`FTRToastNotification` is a Windows Forms toast notification component provided by the FTR Controls library.

It can be used to display short, non-blocking messages such as:

* Successful operations
* Warnings
* Errors
* Informational messages
* Background operation results

The component supports:

* Automatic dismissal after a configurable duration
* Manual dismissal
* Fade animation
* Slide-from-bottom animation
* Slide-from-right animation
* Custom background colors
* Gradient backgrounds
* Hatch/pattern backgrounds
* Custom border colors and thickness
* Rounded corners
* Optional close button
* Configurable close button position
* Optional custom icon
* Always-on-top behavior
* Theme integration
* DPI-aware sizing
* Notification queuing through `ToastNotificationManager`

**Namespace:** `FTRControls`

**Base class:** `System.Windows.Forms.Form`

---

# Recommended Usage

For most applications, use `ToastNotificationManager.Show(...)`.

The manager provides a notification queue and ensures that queued notifications are displayed one at a time.

```csharp
ToastNotificationManager.Show("File saved successfully.");
```

For example:

```csharp
ToastNotificationManager.Show(
    "The operation completed successfully.",
    5
);
```

The second argument specifies how many seconds the notification remains visible before it is automatically dismissed.

The manager is the recommended API when an application may display multiple notifications.

---

# ToastNotificationManager

## `Show`

```csharp
public static void Show(
    string message,
    int durationSeconds = 3,
    Action<FTRToastNotification> configure = null
)
```

Adds a notification to the queue.

### Parameters

| Parameter         | Type                           |  Default | Description                                                                    |
| ----------------- | ------------------------------ | -------: | ------------------------------------------------------------------------------ |
| `message`         | `string`                       | Required | Text displayed in the notification.                                            |
| `durationSeconds` | `int`                          |      `3` | Number of seconds the notification remains visible before automatic dismissal. |
| `configure`       | `Action<FTRToastNotification>` |   `null` | Optional callback used to customize the notification before it is displayed.   |

### Basic Example

```csharp
ToastNotificationManager.Show("File saved.");
```

### Custom Duration

```csharp
ToastNotificationManager.Show(
    "The file was uploaded successfully.",
    5
);
```

### Configure the Toast

The optional configuration callback allows the appearance and behavior of an individual notification to be customized.

```csharp
ToastNotificationManager.Show(
    "Download completed.",
    5,
    toast =>
    {
        toast.ShowCloseButton = true;
        toast.AlwaysOnTop = true;
    }
);
```

---

# Notification Queue

`ToastNotificationManager` maintains an internal notification queue.

Only one toast is displayed at a time.

If multiple notifications are submitted:

```csharp
ToastNotificationManager.Show("First notification.");
ToastNotificationManager.Show("Second notification.");
ToastNotificationManager.Show("Third notification.");
```

they are displayed sequentially:

1. First notification
2. Second notification
3. Third notification

A new notification does not replace the currently displayed notification.

The next notification is displayed after the current toast has been dismissed.

This behavior makes `ToastNotificationManager` suitable for applications that may generate several notifications in a short period.

---

# Threading

The toast component is intended to be used from the Windows Forms UI thread.

When an application is already running with a Windows Forms UI, the manager attempts to marshal `Show(...)` to the UI thread when necessary.

For best results, applications should normally trigger notifications from the application's UI thread.

For example:

```csharp
private void SaveButton_Click(object sender, EventArgs e)
{
    // Save operation...

    ToastNotificationManager.Show("Changes saved.");
}
```

When integrating the component with background operations, ensure that notification calls are made in a way that is compatible with the application's Windows Forms UI lifecycle.

---

# FTRToastNotification

`FTRToastNotification` can also be used directly when the application needs more control over an individual toast.

## Constructor

```csharp
public FTRToastNotification(
    string message,
    int durationSeconds = 3
)
```

### Parameters

| Parameter         | Type     |  Default | Description                          |
| ----------------- | -------- | -------: | ------------------------------------ |
| `message`         | `string` | Required | Text displayed in the notification.  |
| `durationSeconds` | `int`    |      `3` | Duration before automatic dismissal. |

### Example

```csharp
var toast = new FTRToastNotification(
    "File saved successfully.",
    4
);

toast.ShowToast();
```

For most applications, however, `ToastNotificationManager.Show(...)` is preferred because it handles notification queuing automatically.

---

# Animations

The component supports three animation modes.

## `AnimationType.Fade`

The notification fades into view and fades out when dismissed.

This is the default animation.

```csharp
toast.Animation =
    FTRToastNotification.AnimationType.Fade;
```

No premium license is required for the Fade animation.

---

## `AnimationType.SlideFromBottom`

The notification slides upward from the bottom of the screen.

```csharp
toast.Animation =
    FTRToastNotification.AnimationType.SlideFromBottom;
```

A valid FTR Controls license is required.

---

## `AnimationType.SlideFromRight`

The notification slides into view from the right side of the screen.

```csharp
toast.Animation =
    FTRToastNotification.AnimationType.SlideFromRight;
```

A valid FTR Controls license is required.

---

# Close Button

The close button is enabled by default.

```csharp
toast.ShowCloseButton = true;
```

To hide it:

```csharp
toast.ShowCloseButton = false;
```

The close button can be displayed on either side of the notification.

## Right Side

```csharp
toast.ButtonPosition =
    FTRToastNotification.CloseButtonPosition.Right;
```

This is the default.

## Left Side

```csharp
toast.ButtonPosition =
    FTRToastNotification.CloseButtonPosition.Left;
```

Clicking the close button starts the toast's close process.

---

# Manual Dismissal

A toast can be closed programmatically by calling:

```csharp
toast.CloseToast();
```

Example:

```csharp
var toast = new FTRToastNotification(
    "Processing...",
    10
);

toast.ShowToast();

// Later, when the operation is complete:
toast.CloseToast();
```

---

# Automatic Dismissal

The duration is specified in seconds.

```csharp
var toast = new FTRToastNotification(
    "This message will close automatically.",
    5
);
```

The default duration is 3 seconds.

The duration can also be changed through the `DurationSeconds` property:

```csharp
toast.DurationSeconds = 5;
```

If the notification is already displayed, changing this property updates the internal lifetime timer.

---

# Message Text

The notification message can be specified through the constructor:

```csharp
var toast = new FTRToastNotification("File saved.");
```

It can also be changed through `MessageText`:

```csharp
toast.MessageText = "File uploaded successfully.";
```

Example:

```csharp
var toast = new FTRToastNotification("Initial message");

toast.MessageText = "Updated message";
toast.ShowToast();
```

---

# Appearance

## Background Color

Use `ToastBackColor` to specify the toast background color.

```csharp
toast.ToastBackColor = Color.DarkSlateGray;
```

## Text Color

Use `ToastForeColor` to specify the message text color.

```csharp
toast.ToastForeColor = Color.White;
```

## Border Color

```csharp
toast.ToastBorderColor = Color.Gray;
```

## Border Thickness

```csharp
toast.ToastBorderThickness = 2f;
```

---

# Gradient Background

The component supports a linear gradient background.

```csharp
toast.ToastColor1 = Color.DarkBlue;
toast.ToastColor2 = Color.MediumBlue;
toast.GradientMode =
    System.Drawing.Drawing2D.LinearGradientMode.Horizontal;
```

Supported `GradientMode` values are provided by:

```csharp
System.Drawing.Drawing2D.LinearGradientMode
```

For example:

```csharp
toast.GradientMode =
    LinearGradientMode.Vertical;
```

The gradient is used when `ToastColor1` and `ToastColor2` are different colors.

If both colors are equal, the toast falls back to the configured background color.

---

# Background Pattern

A hatch pattern can be displayed over the toast background.

Enable it with:

```csharp
toast.UseBackgroundPattern = true;
```

The pattern style can be selected using `PatternStyle`:

```csharp
toast.PatternStyle =
    HatchStyle.Percent10;
```

The pattern foreground color can be configured with:

```csharp
toast.PatternColor = Color.FromArgb(
    60,
    255,
    255,
    255
);
```

Example:

```csharp
toast.UseBackgroundPattern = true;
toast.PatternStyle = HatchStyle.DiagonalBrick;
toast.PatternColor = Color.FromArgb(
    50,
    Color.White
);
```

`PatternStyle` uses the standard .NET `System.Drawing.Drawing2D.HatchStyle` enumeration.

---

# Rounded Corners

The `BorderRadius` property controls the radius of the toast corners.

```csharp
toast.BorderRadius = 16;
```

The value is measured in pixels.

A valid FTR Controls license is required to change this property.

Without a valid license, attempting to set a different value does not apply the requested change and may display the library's activation prompt.

---

# Custom Icon

An optional image can be displayed on the left side of the message.

```csharp
toast.IconImage = myImage;
```

The icon size can be configured using `IconSize`:

```csharp
toast.IconSize = 32;
```

Example:

```csharp
toast.IconImage = Image.FromFile("success.png");
toast.IconSize = 24;
```

A valid FTR Controls license is required to assign a non-null custom icon.

---

# Always On Top

By default, the toast is not configured as a topmost window.

To keep the notification above other top-level windows:

```csharp
toast.AlwaysOnTop = true;
```

Example:

```csharp
ToastNotificationManager.Show(
    "Important notification.",
    5,
    toast =>
    {
        toast.AlwaysOnTop = true;
    }
);
```

---

# NotificationClosed Event

`NotificationClosed` is raised after the toast has completed its close process.

```csharp
toast.NotificationClosed +=
    Toast_NotificationClosed;
```

Example:

```csharp
private void Toast_NotificationClosed(
    object sender,
    EventArgs e)
{
    // Notification has been closed.
}
```

A complete example:

```csharp
var toast = new FTRToastNotification(
    "Operation completed.",
    5
);

toast.NotificationClosed +=
    (sender, e) =>
    {
        Console.WriteLine("Toast closed.");
    };

toast.ShowToast();
```

When using `ToastNotificationManager`, the manager internally uses this event to determine when the next queued notification can be displayed.

---

# Theme Integration

The toast automatically uses the current FTR Controls theme when it is created.

The component supports the themes provided by the FTR Controls theme system, including:

* Light
* Dark
* Duotone
* Color theme

When the FTR Controls theme changes, an active toast updates its theme-related colors automatically.

Applications do not normally need to manually configure the basic toast colors when they want to follow the application theme.

Custom colors can still be assigned when a notification requires a specific appearance.

---

# DPI Awareness

The component performs DPI-aware sizing.

The default toast dimensions are scaled according to the display DPI.

The default base dimensions are approximately:

* Width: 340 pixels
* Height: 80 pixels
* Default icon size: 24 pixels

Applications do not normally need to perform their own DPI scaling for the toast.

---

# Screen Position

The toast is displayed near the bottom-right corner of the primary screen's working area.

A margin is applied between the toast and the edge of the working area.

The component currently positions the notification relative to the **primary screen**.

Applications that require custom multi-monitor positioning should not assume that the toast automatically appears on the monitor containing the active application window.

---

# Complete Manager Example

The following example demonstrates the recommended approach for a normal application:

```csharp
using FTRControls;

public void ShowSuccessNotification()
{
    ToastNotificationManager.Show(
        "Your changes have been saved successfully.",
        4,
        toast =>
        {
            toast.ShowCloseButton = true;
            toast.AlwaysOnTop = false;
        }
    );
}
```

---

# Complete Customized Example

The following example demonstrates several available customization options:

```csharp
using System.Drawing;
using System.Drawing.Drawing2D;
using FTRControls;

ToastNotificationManager.Show(
    "Download completed successfully.",
    6,
    toast =>
    {
        toast.Animation =
            FTRToastNotification.AnimationType.SlideFromRight;

        toast.ShowCloseButton = true;

        toast.ButtonPosition =
            FTRToastNotification.CloseButtonPosition.Right;

        toast.ToastForeColor = Color.White;

        toast.ToastColor1 = Color.DarkBlue;
        toast.ToastColor2 = Color.MediumBlue;

        toast.GradientMode =
            LinearGradientMode.Horizontal;

        toast.ToastBorderColor = Color.LightBlue;
        toast.ToastBorderThickness = 1.5f;

        toast.BorderRadius = 14;

        toast.AlwaysOnTop = true;
    }
);
```

The Slide animation and custom border radius require a valid FTR Controls license.

---

# Direct Toast Example

Applications that need direct control over an individual toast can use the class directly:

```csharp
using System.Drawing;
using FTRControls;

var toast = new FTRToastNotification(
    "The operation is in progress.",
    10
);

toast.ShowCloseButton = true;
toast.ToastBackColor = Color.DarkSlateGray;
toast.ToastForeColor = Color.White;

toast.ShowToast();
```

The toast can later be dismissed manually:

```csharp
toast.CloseToast();
```

---

# API Reference

## `FTRToastNotification`

### Constructor

```csharp
FTRToastNotification(
    string message,
    int durationSeconds = 3
)
```

### Properties

| Property               | Type                  |  Premium | Description                                                |
| ---------------------- | --------------------- | :------: | ---------------------------------------------------------- |
| `MessageText`          | `string`              |    No    | Notification message.                                      |
| `DurationSeconds`      | `int`                 |    No    | Automatic dismissal duration in seconds.                   |
| `ShowCloseButton`      | `bool`                |    No    | Shows or hides the close button.                           |
| `ButtonPosition`       | `CloseButtonPosition` |    No    | Positions the close button on the left or right.           |
| `ToastBackColor`       | `Color`               |    No    | Background color used when a solid background is rendered. |
| `ToastForeColor`       | `Color`               |    No    | Notification text color.                                   |
| `ToastBorderColor`     | `Color`               |    No    | Border color.                                              |
| `ToastBorderThickness` | `float`               |    No    | Border thickness in pixels.                                |
| `UseBackgroundPattern` | `bool`                |    No    | Enables the hatch background pattern.                      |
| `PatternStyle`         | `HatchStyle`          |    No    | Hatch pattern style.                                       |
| `PatternColor`         | `Color`               |    No    | Hatch pattern foreground color.                            |
| `ToastColor1`          | `Color`               |    No    | First gradient color.                                      |
| `ToastColor2`          | `Color`               |    No    | Second gradient color.                                     |
| `GradientMode`         | `LinearGradientMode`  |    No    | Gradient direction.                                        |
| `BorderRadius`         | `int`                 |  **Yes** | Rounded corner radius.                                     |
| `Animation`            | `AnimationType`       | **Yes*** | Toast entrance/exit animation.                             |
| `IconImage`            | `Image`               |  **Yes** | Optional custom icon.                                      |
| `IconSize`             | `int`                 |   No**   | Icon rendering size in pixels.                             |
| `AlwaysOnTop`          | `bool`                |    No    | Keeps the toast above other top-level windows.             |

* `Fade` does not require a license. `SlideFromBottom` and `SlideFromRight` require a valid license.

** The `IconImage` property requires a valid license when assigning a non-null image. `IconSize` itself is not license-gated by the implementation.

---

# Enumerations

## `AnimationType`

```csharp
FTRToastNotification.AnimationType.Fade
FTRToastNotification.AnimationType.SlideFromBottom
FTRToastNotification.AnimationType.SlideFromRight
```

| Value             | Description                             | License |
| ----------------- | --------------------------------------- | :-----: |
| `Fade`            | Fade in and fade out                    |    No   |
| `SlideFromBottom` | Slide from the bottom of the screen     |   Yes   |
| `SlideFromRight`  | Slide from the right side of the screen |   Yes   |

## `CloseButtonPosition`

```csharp
FTRToastNotification.CloseButtonPosition.Left
FTRToastNotification.CloseButtonPosition.Right
```

| Value   | Description                                  |
| ------- | -------------------------------------------- |
| `Left`  | Displays the close button on the left side.  |
| `Right` | Displays the close button on the right side. |

---

# Methods

## `ShowToast()`

```csharp
public void ShowToast()
```

Displays the toast and starts the configured entrance animation.

The notification is positioned near the bottom-right of the primary screen.

---

## `CloseToast()`

```csharp
public void CloseToast()
```

Starts the toast dismissal process.

For animated toasts, the configured exit animation is used.

---

# Events

## `NotificationClosed`

```csharp
public event EventHandler NotificationClosed;
```

Raised after the toast has completed its close animation and the toast close process has completed.

This event can be used when an application needs to perform an action after a notification has been dismissed.

---

# Licensing

Some visual features are protected by the FTR Controls licensing system.

The following features require a valid license:

* `BorderRadius` customization
* `SlideFromBottom` animation
* `SlideFromRight` animation
* Assigning a non-null `IconImage`

The standard Fade animation and the other basic notification customization features do not require a premium license.

If a license-required property or feature is selected without a valid license, the FTR Controls activation mechanism may be displayed and the requested premium setting will not be applied.

---

# Recommended Integration Pattern

For typical customer applications, the following pattern is recommended:

```csharp
ToastNotificationManager.Show(
    "Operation completed successfully."
);
```

Use the optional configuration callback when appearance or behavior needs to be customized:

```csharp
ToastNotificationManager.Show(
    "Operation completed successfully.",
    5,
    toast =>
    {
        toast.ShowCloseButton = true;
        toast.AlwaysOnTop = true;
    }
);
```

Use `FTRToastNotification` directly only when the application needs to maintain and control an individual toast instance itself.

---

# Quick Reference

### Show a basic notification

```csharp
ToastNotificationManager.Show("File saved.");
```

### Set duration

```csharp
ToastNotificationManager.Show(
    "File saved.",
    5
);
```

### Configure a notification

```csharp
ToastNotificationManager.Show(
    "File saved.",
    5,
    toast =>
    {
        toast.ShowCloseButton = true;
        toast.AlwaysOnTop = true;
    }
);
```

### Use a slide animation

```csharp
toast.Animation =
    FTRToastNotification.AnimationType.SlideFromRight;
```

### Hide the close button

```csharp
toast.ShowCloseButton = false;
```

### Change the close button position

```csharp
toast.ButtonPosition =
    FTRToastNotification.CloseButtonPosition.Left;
```

### Close a toast manually

```csharp
toast.CloseToast();
```

---

# Important Notes

* The recommended entry point for normal applications is `ToastNotificationManager.Show(...)`.
* Notifications submitted through the manager are queued and displayed sequentially.
* The toast is displayed near the bottom-right of the primary screen.
* The component automatically applies the current FTR Controls theme.
* Toast dimensions are DPI-aware.
* Fade animation is available without a premium license.
* Slide animations require a valid license.
* Custom icons require a valid license.
* Custom corner radius requires a valid license.
* The component is designed for Windows Forms applications.
* Applications should integrate notification calls with their Windows Forms UI thread/lifecycle.

---

# Version Compatibility

This document describes the public behavior and API of the `FTRToastNotification` and `ToastNotificationManager` implementations supplied with the FTR Controls assembly.

If a future assembly version changes the public API or behavior, this document should be updated together with that release.