# FTRProgressBar – Customer Usage Guide

## Overview

`FTRProgressBar` is a Windows Forms progress indicator for displaying the progress of an operation.

It supports:

* Horizontal and vertical progress display
* Solid color progress
* Gradient progress
* Animated striped progress
* Indeterminate marquee animation
* Optional progress text
* Custom progress text formats
* Configurable text position
* Configurable colors
* Smooth value transitions
* Automatic color changes based on progress percentage
* Rounded corners
* Light, Dark, Color, and Duotone theme support

The control is available from the **FTR Controls** toolbox.

---

# Adding the Control to a Windows Forms Application

After adding the FTR Controls assembly to your Windows Forms project, add `FTRProgressBar` to the form from the Visual Studio toolbox.

The control can also be created programmatically.

### Basic Example

```csharp
var progressBar = new FTRProgressBar
{
    Maximum = 100,
    Value = 75
};

Controls.Add(progressBar);
```

The default progress range is:

```text
Minimum = 0
Maximum = 100
Value = 0
```

The default visual style is `Gradient`.

---

# Basic Progress Configuration

## Value

`Value` represents the current progress.

```csharp
progressBar.Value = 50;
```

The value is automatically kept within the configured `Minimum` and `Maximum` range.

For example:

```csharp
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 75;
```

displays 75% progress.

If a value below `Minimum` is assigned, it is adjusted to `Minimum`.

If a value above `Maximum` is assigned, it is adjusted to `Maximum`.

---

## Minimum

Defines the lowest value in the progress range.

Default:

```text
0
```

Example:

```csharp
progressBar.Minimum = 0;
```

The percentage displayed by the control is calculated relative to the configured minimum and maximum values.

For example:

```csharp
progressBar.Minimum = 20;
progressBar.Maximum = 120;
progressBar.Value = 70;
```

represents 50% progress through the configured range.

---

## Maximum

Defines the highest value in the progress range.

Default:

```text
100
```

Example:

```csharp
progressBar.Maximum = 500;
```

The control requires `Maximum` to remain greater than `Minimum`.

If a value that would make the range invalid is assigned, the control automatically adjusts it so that the range remains valid.

---

# Animation

## Animated

Controls whether changes in `Value` are displayed using a smooth transition.

Default:

```text
true
```

Example:

```csharp
progressBar.Animated = true;
progressBar.Value = 75;
```

When animation is enabled, the visual progress moves gradually toward the new value.

When animation is disabled:

```csharp
progressBar.Animated = false;
progressBar.Value = 75;
```

the displayed progress changes immediately to the new value.

### When to use it

Use `Animated = true` when the progress indicator should provide a smooth visual transition.

Use `Animated = false` when the progress needs to update immediately without visual interpolation.

---

# Progress Styles

The control supports four visual styles.

## Solid

Displays the progress using a single solid color.

```csharp
progressBar.Style = FTRProgressStyle.Solid;
```

`Solid` is available without a Premium license.

---

## Gradient

Displays the progress using a gradient between `ProgressColor1` and `ProgressColor2`.

```csharp
progressBar.Style = FTRProgressStyle.Gradient;
```

This is the default style.

`Gradient` is available without a Premium license.

---

## Striped — Premium

Displays the progress with animated diagonal stripes.

```csharp
progressBar.Style = FTRProgressStyle.Striped;
```

`Striped` requires a Premium license.

The stripe appearance can be customized using:

* `StripeColor`
* `StripeWidth`
* `StripeSpacing`

---

## Marquee — Premium

Displays an animated moving progress indicator rather than a fixed percentage-based fill.

```csharp
progressBar.Style = FTRProgressStyle.Marquee;
```

`Marquee` requires a Premium license.

Marquee mode is useful when the application knows that an operation is in progress but does not know how much work remains.

### Important

Progress text is not displayed while `Style` is set to `Marquee`.

```text
Marquee → animated indicator
         → no progress text
```

---

# Orientation

## Horizontal

Displays progress from left to right.

```csharp
progressBar.Orientation = FTRProgressOrientation.Horizontal;
```

This is the default orientation.

---

## Vertical

Displays progress from bottom to top.

```csharp
progressBar.Orientation = FTRProgressOrientation.Vertical;
```

Example:

```csharp
var progressBar = new FTRProgressBar
{
    Orientation = FTRProgressOrientation.Vertical,
    Minimum = 0,
    Maximum = 100,
    Value = 65
};
```

In vertical mode, the progress fill grows upward from the bottom of the control.

---

# Text Display

## ShowText

Controls whether progress text is displayed.

Default:

```text
true
```

Example:

```csharp
progressBar.ShowText = true;
```

To hide the progress text:

```csharp
progressBar.ShowText = false;
```

### Important

Text is not displayed in `Marquee` mode, even if:

```csharp
progressBar.ShowText = true;
```

---

# Text Format

## TextFormat

Defines the text displayed over the progress bar.

The default format is:

```text
{0}%
```

Example:

```csharp
progressBar.TextFormat = "{0}%";
```

This produces text such as:

```text
75%
```

The control supports three placeholders.

| Placeholder | Meaning                     |
| ----------- | --------------------------- |
| `{0}`       | Current progress percentage |
| `{1}`       | Maximum value               |
| `{2}`       | Current animated value      |

---

## Text Format Examples

### Percentage

```csharp
progressBar.TextFormat = "{0}%";
```

Result:

```text
75%
```

### Current Value and Maximum

```csharp
progressBar.TextFormat = "{2} / {1}";
```

Result:

```text
75 / 100
```

### Percentage with Maximum

```csharp
progressBar.TextFormat = "{0}% of {1}";
```

Result:

```text
75% of 100
```

### Custom Message

```csharp
progressBar.TextFormat = "Completed: {0}%";
```

Result:

```text
Completed: 75%
```

If the specified format is invalid, the control falls back to the default percentage display.

---

# Text Position

## Center

Centers the progress text.

```csharp
progressBar.TextPosition = FTRTextPosition.Center;
```

This is the default position.

---

## Left

Places the progress text toward the left side.

```csharp
progressBar.TextPosition = FTRTextPosition.Left;
```

---

## Right

Places the progress text toward the right side.

```csharp
progressBar.TextPosition = FTRTextPosition.Right;
```

Example:

```csharp
var progressBar = new FTRProgressBar
{
    ShowText = true,
    TextFormat = "{0}%",
    TextPosition = FTRTextPosition.Right
};
```

---

# Colors

## ChannelColor

Controls the color of the unfilled portion of the progress bar.

Example:

```csharp
progressBar.ChannelColor = Color.LightGray;
```

---

## ProgressColor1

Controls the primary progress color.

In `Solid` mode, this is the progress color.

In `Gradient` mode, it is the first color of the gradient.

Example:

```csharp
progressBar.ProgressColor1 = Color.DodgerBlue;
```

---

## ProgressColor2

Controls the second color of the gradient.

Example:

```csharp
progressBar.ProgressColor2 = Color.MediumPurple;
```

This property is primarily visible when using:

```csharp
progressBar.Style = FTRProgressStyle.Gradient;
```

---

## StripeColor

Controls the color of the animated stripes.

Example:

```csharp
progressBar.StripeColor = Color.White;
```

This setting is relevant when:

```csharp
progressBar.Style = FTRProgressStyle.Striped;
```

---

## AlternateForeColor

Controls the text color used when progress text is drawn over the filled portion of the progress bar.

This helps maintain text readability when the progress fill uses a dark or saturated color.

Example:

```csharp
progressBar.AlternateForeColor = Color.White;
```

This property is available without a Premium license.

---

# Striped Style Customization

The following properties control the appearance of animated stripes.

## StripeWidth — Premium

Defines the width of the stripes in pixels.

Example:

```csharp
progressBar.StripeWidth = 10;
```

The control does not allow a value below `1`.

This property requires a Premium license.

---

## StripeSpacing — Premium

Defines the spacing between adjacent stripes.

Example:

```csharp
progressBar.StripeSpacing = 20;
```

The control does not allow a value below `1`.

This property requires a Premium license.

---

## Stripe Configuration Example

```csharp
var progressBar = new FTRProgressBar
{
    Style = FTRProgressStyle.Striped,
    Value = 60,
    Maximum = 100,
    StripeWidth = 8,
    StripeSpacing = 18,
    StripeColor = Color.White
};
```

`Style`, `StripeWidth`, and `StripeSpacing` require an appropriate Premium license.

---

# Dynamic Colors — Premium

Dynamic colors allow the progress color to change automatically according to the current progress percentage.

This feature is controlled by:

```csharp
UseDynamicColors
WarningThreshold
SuccessThreshold
```

All three properties require a Premium license.

---

## UseDynamicColors

Enables or disables automatic progress colors.

Default:

```text
false
```

Example:

```csharp
progressBar.UseDynamicColors = true;
```

When enabled, the control chooses a color according to the current percentage.

The default thresholds are:

```text
WarningThreshold = 40
SuccessThreshold = 80
```

The default color levels are:

* Below the warning threshold → low color
* From the warning threshold up to the success threshold → medium color
* At or above the success threshold → high color

---

## WarningThreshold — Premium

Defines the percentage below which the low-level color is used.

Default:

```text
40
```

Example:

```csharp
progressBar.WarningThreshold = 30;
```

Valid values are automatically limited to the range:

```text
0–100
```

---

## SuccessThreshold — Premium

Defines the percentage at which the high-level color starts being used.

Default:

```text
80
```

Example:

```csharp
progressBar.SuccessThreshold = 90;
```

Valid values are automatically limited to:

```text
0–100
```

---

## Dynamic Color Example

```csharp
var progressBar = new FTRProgressBar
{
    Minimum = 0,
    Maximum = 100,
    Value = 65,

    UseDynamicColors = true,
    WarningThreshold = 40,
    SuccessThreshold = 80
};
```

With this configuration:

| Progress | Color level |
| -------: | ----------- |
|    0–39% | Low         |
|   40–79% | Medium      |
|  80–100% | High        |

The exact colors are determined by the active FTR theme unless the control's color configuration provides the corresponding values.

---

# Rounded Corners

## BorderRadius — Premium

Controls the roundness of the progress bar corners.

Default:

```text
15 pixels
```

Example:

```csharp
progressBar.BorderRadius = 10;
```

The value cannot be negative. Negative values are automatically treated as `0`.

This property requires a Premium license.

The control automatically adjusts the rendered radius so that it remains compatible with the current control size.

---

# Themes

`FTRProgressBar` integrates with the FTR Controls theme system.

The control supports:

* Light
* Dark
* Color
* Duotone

When the FTR theme changes, the progress bar updates its theme-dependent colors.

Theme-dependent visual settings include:

* Channel color
* Progress colors
* Stripe color
* Foreground color
* Dynamic color presets

The application normally does not need to manually configure these colors when using the FTR theme system.

---

# ProgressCompleted Event

The `ProgressCompleted` event is raised when the displayed progress reaches the configured `Maximum`.

Example:

```csharp
progressBar.ProgressCompleted += ProgressBar_ProgressCompleted;

private void ProgressBar_ProgressCompleted(
    object sender,
    EventArgs e)
{
    MessageBox.Show("Operation completed.");
}
```

### Important behavior

When `Animated` is enabled, `Value` may reach `Maximum` before the visual animation has finished.

`ProgressCompleted` is raised after the animated display reaches the maximum.

Therefore:

```text
Value reaches Maximum
        ↓
Animation completes
        ↓
ProgressCompleted
```

When `Animated` is disabled, the displayed value is updated immediately, so the completion event can occur immediately when the value reaches the maximum.

---

## Completion Event Frequency

The control prevents the completion event from being raised repeatedly while the progress remains at the maximum.

After the value changes, the completion state is reset.

For example:

```csharp
progressBar.Value = 100;
```

can raise `ProgressCompleted`.

If the value subsequently changes:

```csharp
progressBar.Value = 50;
progressBar.Value = 100;
```

the completion event can be raised again when the progress reaches the maximum.

---

# Recommended Usage Patterns

## Standard Determinate Progress

Use this configuration when the application knows the current progress.

```csharp
var progressBar = new FTRProgressBar
{
    Minimum = 0,
    Maximum = 100,
    Value = 0,
    Style = FTRProgressStyle.Gradient,
    Animated = true,
    ShowText = true,
    TextFormat = "{0}%"
};
```

Update the progress as the operation advances:

```csharp
progressBar.Value = 25;
progressBar.Value = 50;
progressBar.Value = 75;
progressBar.Value = 100;
```

---

## Immediate Progress Updates

For applications where the visual value should update immediately:

```csharp
var progressBar = new FTRProgressBar
{
    Animated = false
};
```

Then:

```csharp
progressBar.Value = 75;
```

updates the displayed progress immediately.

---

## Vertical Progress

```csharp
var progressBar = new FTRProgressBar
{
    Orientation = FTRProgressOrientation.Vertical,
    Minimum = 0,
    Maximum = 100,
    Value = 60,
    ShowText = true,
    TextFormat = "{0}%"
};
```

---

## Indeterminate Operation

Use `Marquee` when the application cannot determine the exact percentage of completion.

```csharp
var progressBar = new FTRProgressBar
{
    Style = FTRProgressStyle.Marquee
};
```

The marquee animation continuously moves across the control.

No percentage text is displayed in this mode.

`Marquee` requires a Premium license.

---

# Complete Configuration Example

The following example demonstrates several common features:

```csharp
var progressBar = new FTRProgressBar
{
    Minimum = 0,
    Maximum = 100,
    Value = 65,

    Style = FTRProgressStyle.Gradient,
    Orientation = FTRProgressOrientation.Horizontal,
    Animated = true,

    ShowText = true,
    TextFormat = "{0}%",
    TextPosition = FTRTextPosition.Center,

    ChannelColor = Color.LightGray,
    ProgressColor1 = Color.DodgerBlue,
    ProgressColor2 = Color.MediumPurple,
    AlternateForeColor = Color.White,

    BorderRadius = 15
};

progressBar.ProgressCompleted += (sender, e) =>
{
    MessageBox.Show("The operation has completed.");
};
```

If the application uses Premium features, additional configuration can be applied:

```csharp
progressBar.Style = FTRProgressStyle.Striped;
progressBar.StripeWidth = 8;
progressBar.StripeSpacing = 20;

progressBar.UseDynamicColors = true;
progressBar.WarningThreshold = 40;
progressBar.SuccessThreshold = 80;
```

---

# Premium Features

The following features require an appropriate FTR Controls Premium license.

| Feature / Property | Purpose                                     |
| ------------------ | ------------------------------------------- |
| `Striped` style    | Animated diagonal stripes                   |
| `Marquee` style    | Indeterminate moving animation              |
| `BorderRadius`     | Rounded corner customization                |
| `StripeWidth`      | Stripe width                                |
| `StripeSpacing`    | Stripe spacing                              |
| `UseDynamicColors` | Automatic color selection based on progress |
| `WarningThreshold` | Low/medium color threshold                  |
| `SuccessThreshold` | Medium/high color threshold                 |

If a Premium feature is selected without the required license, the control displays the FTR Controls activation prompt and does not apply the requested Premium setting.

---

# Non-Premium Features

The following functionality is available without the Premium features listed above:

* `Value`
* `Minimum`
* `Maximum`
* `Animated`
* `Solid` style
* `Gradient` style
* `Horizontal` orientation
* `Vertical` orientation
* `ChannelColor`
* `ProgressColor1`
* `ProgressColor2`
* `StripeColor`
* `AlternateForeColor`
* `ShowText`
* `TextFormat`
* `TextPosition`
* `ProgressCompleted`

---

# Quick Reference

| Property / Event     | Type                     |                   Default |  Premium |
| -------------------- | ------------------------ | ------------------------: | :------: |
| `Value`              | `int`                    |                       `0` |    No    |
| `Minimum`            | `int`                    |                       `0` |    No    |
| `Maximum`            | `int`                    |                     `100` |    No    |
| `Animated`           | `bool`                   |                    `true` |    No    |
| `Style`              | `FTRProgressStyle`       |                `Gradient` | Partial* |
| `Orientation`        | `FTRProgressOrientation` |              `Horizontal` |    No    |
| `BorderRadius`       | `int`                    |                      `15` |    Yes   |
| `ChannelColor`       | `Color`                  | Theme-dependent / default |    No    |
| `ProgressColor1`     | `Color`                  | Theme-dependent / default |    No    |
| `ProgressColor2`     | `Color`                  | Theme-dependent / default |    No    |
| `StripeColor`        | `Color`                  | Theme-dependent / default |    No    |
| `AlternateForeColor` | `Color`                  |                   `White` |    No    |
| `StripeWidth`        | `int`                    |                      `10` |    Yes   |
| `StripeSpacing`      | `int`                    |                      `20` |    Yes   |
| `UseDynamicColors`   | `bool`                   |                   `false` |    Yes   |
| `WarningThreshold`   | `int`                    |                      `40` |    Yes   |
| `SuccessThreshold`   | `int`                    |                      `80` |    Yes   |
| `ShowText`           | `bool`                   |                    `true` |    No    |
| `TextFormat`         | `string`                 |                  `"{0}%"` |    No    |
| `TextPosition`       | `FTRTextPosition`        |                  `Center` |    No    |
| `ProgressCompleted`  | Event                    |                         — |    No    |

* `Solid` and `Gradient` are available without Premium. `Striped` and `Marquee` require Premium.

---

# Default Configuration

When the control is created, its main defaults are:

```text
Minimum            = 0
Maximum            = 100
Value              = 0
Animated           = true
Style              = Gradient
Orientation        = Horizontal
BorderRadius       = 15
ShowText           = true
TextFormat         = "{0}%"
TextPosition       = Center
StripeWidth        = 10
StripeSpacing      = 20
UseDynamicColors   = false
WarningThreshold   = 40
SuccessThreshold   = 80
```

The default colors are also automatically adjusted according to the active FTR theme.

---

# Customer Usage Checklist

For a normal determinate progress bar:

1. Set `Minimum` and `Maximum`.
2. Set `Value` as the operation progresses.
3. Choose `Solid` or `Gradient`.
4. Decide whether `Animated` should be enabled.
5. Decide whether progress text should be displayed.
6. Customize `TextFormat` if necessary.
7. Use `ProgressCompleted` if the application needs to react when the progress finishes.

For an indeterminate operation:

1. Set `Style` to `Marquee`.
2. Do not rely on the percentage text because Marquee mode does not display it.
3. Stop or replace the progress indicator when the operation has finished.

For Premium visual effects:

1. Make sure the required FTR Controls license is activated.
2. Enable the desired Premium style or feature.
3. Configure the related Premium properties.