# FTRCircularProgressBar

## Overview

`FTRCircularProgressBar` is a Windows Forms circular progress control designed to display progress or completion status in a compact circular format.

The control supports:

* Circular progress visualization
* Smooth progress animation
* Gradient progress colors
* Customizable track and progress thickness
* Center percentage text
* Custom text formatting
* Value tooltip
* Indeterminate (Marquee) mode
* Application theme integration
* Right-to-left progress direction
* `ValueChanged` event notification

The control can be added to a Windows Forms application through the FTR Controls assembly and used either from the Visual Studio Toolbox or programmatically.

---

## Basic Usage

The following example creates a circular progress bar and displays 65% progress:

```csharp
var progressBar = new FTRCircularProgressBar
{
    Minimum = 0,
    Maximum = 100,
    Value = 65,
    ShowValueAsText = true,
    ProgressThickness = 12
};
```

The control automatically animates the visual progress when the `Value` changes at runtime.

For example:

```csharp
progressBar.Value = 80;
```

The displayed progress smoothly transitions from the previous value to the new value.

---

# Properties

## Behavior Properties

### Minimum

**Type:** `int`
**Default:** `0`

Defines the minimum value of the progress range.

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

If `Minimum` is changed and the current `Value` is below the new minimum, the `Value` is automatically adjusted to the minimum.

---

### Maximum

**Type:** `int`
**Default:** `100`

Defines the maximum value of the progress range.

```csharp
progressBar.Maximum = 100;
```

If `Maximum` is lower than the current `Value`, the `Value` is automatically adjusted to the new maximum.

If a value lower than `Minimum` is assigned to `Maximum`, the control uses `Minimum` as the effective maximum.

---

### Value

**Type:** `int`
**Default:** `0`

Gets or sets the current progress value.

```csharp
progressBar.Value = 65;
```

The value is automatically restricted to the configured `Minimum` and `Maximum` range.

For example:

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

progressBar.Value = 150;
```

The effective value will be `100`.

Similarly:

```csharp
progressBar.Value = -20;
```

will result in an effective value of `0`.

### Percentage Calculation

The visual progress and the displayed percentage are calculated relative to the configured range.

For example:

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

represents:

```text
50%
```

Therefore, `Value` is not required to be a percentage. It can represent any numeric range.

---

## Appearance Properties

### ProgressColor1

**Type:** `Color`
**Default:** `RoyalBlue`

Defines the starting color of the progress arc gradient.

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

---

### ProgressColor2

**Type:** `Color`
**Default:** `Cyan`

Defines the ending color of the progress arc gradient.

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

Together, `ProgressColor1` and `ProgressColor2` define the gradient used by the progress arc.

Example:

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

---

### ProgressThickness

**Type:** `int`
**Default:** `10`

Defines the thickness of the circular progress arc and background track.

```csharp
progressBar.ProgressThickness = 12;
```

Values below `1` are automatically adjusted to `1`.

---

### TrackColor

**Type:** `Color`
**Default:** `Gainsboro`

Defines the color of the background circular track.

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

---

### ShowValueAsText

**Type:** `bool`
**Default:** `true`

Determines whether the current percentage is displayed in the center of the control.

```csharp
progressBar.ShowValueAsText = true;
```

To hide the center text:

```csharp
progressBar.ShowValueAsText = false;
```

---

### TextFormat

**Type:** `string`
**Default:** `"{0}%"`

Defines the format used for the percentage displayed in the center of the control.

The `{0}` placeholder is replaced with the calculated percentage.

Default:

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

Example:

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

This produces text such as:

```text
Progress: 65%
```

Another example:

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

produces:

```text
65 percent
```

If an empty or whitespace-only format is assigned, the control uses the default format:

```text
{0}%
```

If the specified format is invalid, the control falls back to the standard percentage representation.

---

### ShowValueAsToolTip

**Type:** `bool`
**Default:** `true`

Determines whether the formatted percentage is displayed as a tooltip when the user hovers over the control.

```csharp
progressBar.ShowValueAsToolTip = true;
```

To disable the tooltip:

```csharp
progressBar.ShowValueAsToolTip = false;
```

The tooltip uses the same `TextFormat` configured for the center text.

For example:

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

The tooltip will display:

```text
Completed: 65%
```

---

# Premium Features

The following features require an activated FTR Controls license:

* `Marquee`
* `MarqueeAnimationSpeed`
* `MarqueeArcSize`

When a Premium property is used without an active license, the control requests activation instead of applying the Premium setting.

---

## Marquee

**Type:** `bool`
**Default:** `false`
**License:** Premium

Enables indeterminate progress mode.

Marquee mode is useful when the exact progress value is not known and the application needs to indicate that an operation is currently running.

```csharp
progressBar.Marquee = true;
```

When Marquee mode is enabled, the control displays a continuously rotating arc instead of representing the `Value` as a fixed percentage.

To return to normal progress mode:

```csharp
progressBar.Marquee = false;
```

When Marquee mode is disabled, the control returns to displaying the configured `Value`.

### Example

```csharp
progressBar.Marquee = true;

// Perform an operation...

progressBar.Marquee = false;
progressBar.Value = 100;
```

---

## MarqueeAnimationSpeed

**Type:** `int`
**Default:** `50` milliseconds
**License:** Premium

Defines the animation interval used by Marquee mode.

The value is specified in milliseconds.

```csharp
progressBar.MarqueeAnimationSpeed = 50;
```

Smaller values generally result in a faster animation.

For example:

```csharp
progressBar.MarqueeAnimationSpeed = 25;
```

creates a faster update interval than:

```csharp
progressBar.MarqueeAnimationSpeed = 100;
```

Values below `1` are automatically adjusted to `1`.

---

## MarqueeArcSize

**Type:** `int`
**Default:** `90` degrees
**Allowed range:** `10`–`350` degrees
**License:** Premium

Defines the angular size of the rotating Marquee arc.

```csharp
progressBar.MarqueeArcSize = 90;
```

Examples:

```csharp
progressBar.MarqueeArcSize = 45;
```

creates a shorter rotating arc.

```csharp
progressBar.MarqueeArcSize = 180;
```

creates a larger rotating arc.

The value is automatically restricted to the range:

```text
10° to 350°
```

---

# Events

## ValueChanged

Occurs when the `Value` property changes.

```csharp
progressBar.ValueChanged += ProgressBar_ValueChanged;
```

Example:

```csharp
private void ProgressBar_ValueChanged(object sender, EventArgs e)
{
    // Respond to the progress value changing.
}
```

The event is raised when the target `Value` changes, not for every animation frame while the control is visually transitioning toward the new value.

---

# Methods

## Increment

```csharp
Increment(int delta = 1)
```

Increases the current `Value` by the specified amount.

Example:

```csharp
progressBar.Increment();
```

This increases the value by `1`.

A custom increment can also be specified:

```csharp
progressBar.Increment(5);
```

For example, if the current value is `60`, the resulting value is `65`.

The resulting value is still restricted by `Minimum` and `Maximum`.

For example:

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

progressBar.Increment(20);
```

The effective value becomes `100`.

---

# Theme Support

The control supports the application's FTR theme system.

Use:

```csharp
progressBar.ApplyTheme();
```

to apply the currently selected application theme.

The theme can determine:

* Progress gradient colors
* Track color
* Foreground/text color

When using the control together with the FTR Controls theme system, theme-specific colors can therefore be applied automatically.

If custom colors are required, the appearance properties can be explicitly configured after the theme has been applied.

Example:

```csharp
progressBar.ApplyTheme();

progressBar.ProgressColor1 = Color.DodgerBlue;
progressBar.ProgressColor2 = Color.Cyan;
progressBar.TrackColor = Color.LightGray;
```

---

# Complete Example

The following example demonstrates a typical determinate progress configuration:

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

    ProgressColor1 = Color.DodgerBlue,
    ProgressColor2 = Color.Cyan,
    TrackColor = Color.LightGray,
    ProgressThickness = 12,

    ShowValueAsText = true,
    TextFormat = "{0}%",
    ShowValueAsToolTip = true
};

progressBar.ValueChanged += (sender, e) =>
{
    // Handle progress changes here.
};
```

The control will display approximately:

```text
65%
```

in the center and will show the same formatted value in the tooltip when the user hovers over the control.

---

# Example: Updating Progress

A common usage pattern is to update the value as an operation progresses:

```csharp
progressBar.Value = 0;

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

The control provides a smooth visual transition between values when running at runtime.

Alternatively, use `Increment()`:

```csharp
progressBar.Value = 0;

progressBar.Increment(10);
progressBar.Increment(10);
progressBar.Increment(10);
```

---

# Example: Indeterminate Operation

When the application cannot determine the exact completion percentage, Marquee mode can be used:

```csharp
progressBar.MarqueeAnimationSpeed = 50;
progressBar.MarqueeArcSize = 90;
progressBar.Marquee = true;
```

When the operation is complete:

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

`Marquee`, `MarqueeAnimationSpeed`, and `MarqueeArcSize` are Premium features and require an active FTR Controls license.

---

# Example: Custom Center Text

The center text can be customized using `TextFormat`.

For example:

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

The control may then display:

```text
Loading 65%
```

The same format is also used by the tooltip when `ShowValueAsToolTip` is enabled.

---

# Example: Custom Progress Range

The control does not have to use a `0–100` range.

For example:

```csharp
progressBar.Minimum = 0;
progressBar.Maximum = 500;
progressBar.Value = 250;
```

The visual progress represents `50%` because `250` is halfway between `0` and `500`.

The center text and tooltip will therefore display:

```text
50%
```

when using the default `TextFormat`.

---

# Right-to-Left Layout

The control supports right-to-left progress direction through the standard Windows Forms `RightToLeft` property.

Example:

```csharp
progressBar.RightToLeft = RightToLeft.Yes;
```

This reverses the direction of the progress arc.

---

# Recommended Configuration

For a standard progress indicator:

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

    ProgressThickness = 10,

    ShowValueAsText = true,
    TextFormat = "{0}%",
    ShowValueAsToolTip = true,

    Marquee = false
};
```

For an indeterminate loading indicator:

```csharp
var progressBar = new FTRCircularProgressBar
{
    ProgressThickness = 10,
    ShowValueAsText = false,
    ShowValueAsToolTip = false,

    MarqueeAnimationSpeed = 50,
    MarqueeArcSize = 90,
    Marquee = true
};
```

The second configuration requires a Premium license.

---

# Property Reference

| Property                | Type     |     Default | License     | Description                                |
| ----------------------- | -------- | ----------: | ----------- | ------------------------------------------ |
| `Minimum`               | `int`    |         `0` | Standard    | Minimum progress value                     |
| `Maximum`               | `int`    |       `100` | Standard    | Maximum progress value                     |
| `Value`                 | `int`    |         `0` | Standard    | Current progress value                     |
| `ProgressColor1`        | `Color`  | `RoyalBlue` | Standard    | First gradient color                       |
| `ProgressColor2`        | `Color`  |      `Cyan` | Standard    | Second gradient color                      |
| `ProgressThickness`     | `int`    |        `10` | Standard    | Progress/track thickness                   |
| `TrackColor`            | `Color`  | `Gainsboro` | Standard    | Background track color                     |
| `ShowValueAsText`       | `bool`   |      `true` | Standard    | Shows percentage in center                 |
| `TextFormat`            | `string` |    `"{0}%"` | Standard    | Center/tooltip text format                 |
| `ShowValueAsToolTip`    | `bool`   |      `true` | Standard    | Shows value on hover                       |
| `Marquee`               | `bool`   |     `false` | **Premium** | Enables indeterminate mode                 |
| `MarqueeAnimationSpeed` | `int`    |        `50` | **Premium** | Marquee animation interval in milliseconds |
| `MarqueeArcSize`        | `int`    |        `90` | **Premium** | Marquee arc size in degrees                |

---

# Event Reference

| Event          | Description                              |
| -------------- | ---------------------------------------- |
| `ValueChanged` | Occurs when the `Value` property changes |

---

# Method Reference

| Method                     | Description                                           |
| -------------------------- | ----------------------------------------------------- |
| `Increment(int delta = 1)` | Increases the current `Value` by the specified amount |
| `ApplyTheme()`             | Applies the currently selected FTR application theme  |

---

# Important Notes

1. `Value` is automatically constrained to the `Minimum`–`Maximum` range.
2. The displayed center value is a calculated percentage based on the configured range.
3. `TextFormat` uses `{0}` as the percentage placeholder.
4. `ShowValueAsToolTip` uses the same formatted value as the center text.
5. Progress changes are visually animated at runtime.
6. `Marquee` is intended for operations where the exact progress percentage is unknown.
7. `Marquee`, `MarqueeAnimationSpeed`, and `MarqueeArcSize` require an active Premium license.
8. `MarqueeArcSize` is limited to `10`–`350` degrees.
9. `ProgressThickness` cannot be less than `1`.
10. The control supports application theme integration through `ApplyTheme()`.
11. The control supports right-to-left progress direction through the standard Windows Forms `RightToLeft` property.

---

# Summary

`FTRCircularProgressBar` provides a configurable circular progress indicator for Windows Forms applications.

For normal progress reporting, configure `Minimum`, `Maximum`, and `Value`. Customize the visual appearance using the color and thickness properties, and optionally enable center text and tooltips.

For operations where the completion percentage is unknown, enable Premium Marquee mode.

A typical standard configuration is:

```csharp
var progressBar = new FTRCircularProgressBar
{
    Minimum = 0,
    Maximum = 100,
    Value = 65,
    ProgressThickness = 12,
    ShowValueAsText = true,
    ShowValueAsToolTip = true
};
```

This provides a standard 0–100 circular progress indicator with animated progress, center percentage text, and tooltip support.