# FTRSlider

`FTRSlider` is a Windows Forms slider control provided by the FTR Controls library.

It allows users to select a single numeric value within a configurable range. The control supports horizontal and vertical layouts, mouse and keyboard interaction, optional tick marks, value tooltips, smooth value transitions, RTL layouts, and optional premium display features.

## Overview

The slider can be used for scenarios such as:

* Volume or audio level selection
* Brightness adjustment
* Progress or percentage selection
* Numeric settings
* User-configurable ranges
* Any UI where the user needs to select one numeric value

The control inherits from `FTRBaseControl` and is available in the `FTRControls` namespace.

**Namespace:** `FTRControls`
**Base class:** `FTRControls.BaseClasses.FTRBaseControl`
**Control type:** Windows Forms Control
**Default event:** `ValueChanged`

---

## Basic Usage

The simplest way to create and configure an `FTRSlider` is:

```csharp
using FTRControls;

var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Step = 5
};

slider.ValueChanged += (_, _) =>
{
    SetVolume(slider.Value);
};
```

The `Value` property contains the currently selected value.

For example, with:

```csharp
Minimum = 0
Maximum = 100
Step = 5
```

the slider is intended to work in increments of 5.

---

# Properties

## Value Range

### `Minimum`

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

Defines the minimum value that can be selected.

`Minimum` must always be less than `Maximum`.

```csharp
slider.Minimum = 0;
```

If an invalid value is assigned, the control throws `ArgumentOutOfRangeException`.

> **Important:** When changing both `Minimum` and `Maximum` at runtime, make sure the temporary values remain valid. `Minimum` cannot be greater than or equal to `Maximum`.

---

### `Maximum`

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

Defines the maximum value that can be selected.

`Maximum` must always be greater than `Minimum`.

```csharp
slider.Maximum = 1000;
```

If an invalid value is assigned, the control throws `ArgumentOutOfRangeException`.

---

### `Value`

**Type:** `int`
**Default:** `50`

Gets or sets the current slider value.

The value is automatically constrained to the range between `Minimum` and `Maximum`.

```csharp
slider.Value = 75;
```

For example, if:

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

then:

```csharp
slider.Value = 150;
```

results in a value of `100`.

Similarly:

```csharp
slider.Value = -10;
```

results in a value of `0`.

When the value changes, the `ValueChanged` event is raised.

---

### `Step`

**Type:** `int`
**Default:** `1`

Defines the increment used when the slider value is changed through user interaction.

The minimum supported value is `1`.

```csharp
slider.Step = 5;
```

With a range of `0` to `100` and a step of `5`, the slider uses values such as:

```text
0, 5, 10, 15, ... 95, 100
```

Changing `Step` also re-snaps the current value to the nearest step.

---

### `LargeChange`

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

Defines the amount added or subtracted when the user presses `Page Up` or `Page Down`.

```csharp
slider.LargeChange = 20;
```

For example:

* `Page Up` increases the value by `LargeChange`.
* `Page Down` decreases the value by `LargeChange`.

The minimum supported value is `1`.

---

# Orientation

### `Orientation`

**Type:** `FTRSliderOrientation`
**Default:** `Horizontal`

Controls whether the slider is displayed horizontally or vertically.

Available values:

```csharp
FTRSliderOrientation.Horizontal
FTRSliderOrientation.Vertical
```

### Horizontal

```csharp
slider.Orientation = FTRSliderOrientation.Horizontal;
```

The minimum value is displayed on the left and the maximum value on the right.

When `RightToLeft` is enabled, the horizontal direction is reversed.

### Vertical

```csharp
slider.Orientation = FTRSliderOrientation.Vertical;
```

The minimum value is at the bottom and the maximum value is at the top.

For vertical sliders, RTL does not change the value direction.

---

# Appearance

## `TrackColor`

**Type:** `Color`

Defines the color of the unselected portion of the slider track.

```csharp
slider.TrackColor = Color.Gray;
```

---

## `SliderColor`

**Type:** `Color`

Defines the color of the selected/filled portion of the track.

```csharp
slider.SliderColor = Color.DodgerBlue;
```

This color is also used for the hover and drag glow effects.

---

## `ThumbColor`

**Type:** `Color`

Defines the fill color of the slider thumb.

```csharp
slider.ThumbColor = Color.White;
```

---

## `ThumbBorderColor`

**Type:** `Color`

Defines the border color of the slider thumb.

```csharp
slider.ThumbBorderColor = Color.Gray;
```

---

## `TickColor`

**Type:** `Color`

Defines the color of tick marks when ticks are enabled.

```csharp
slider.TickColor = Color.Gray;
```

---

## `TrackHeight`

**Type:** `int`
**Default:** `6`

Defines the thickness of the slider track in pixels.

```csharp
slider.TrackHeight = 8;
```

Values smaller than `1` are automatically changed to `1`.

---

## `ThumbSize`

**Type:** `int`
**Default:** `16`

Defines the diameter of the slider thumb in pixels.

```csharp
slider.ThumbSize = 20;
```

The minimum supported value is `8` pixels.

---

# Tick Marks

### `ShowTicks`

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

Enables or disables tick marks.

```csharp
slider.ShowTicks = true;
```

A valid FTR Controls license is required to enable this premium feature.

If the feature is not licensed, the control displays the activation prompt and does not enable the requested setting.

---

### `TickFrequency`

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

Defines the numeric interval between tick marks.

```csharp
slider.TickFrequency = 10;
```

For example, with:

```csharp
Minimum = 0;
Maximum = 100;
TickFrequency = 20;
```

ticks are generated at values corresponding to:

```text
0, 20, 40, 60, 80, 100
```

The minimum supported value is `1`.

---

### `TickStyle`

**Type:** `FTRSliderTickStyle`
**Default:** `Bottom`
**Premium:** Yes

Controls where tick marks are displayed relative to the slider track.

Available values:

```csharp
FTRSliderTickStyle.None
FTRSliderTickStyle.Top
FTRSliderTickStyle.Bottom
FTRSliderTickStyle.Both
```

For a horizontal slider:

* `Top` — ticks are displayed above the track.
* `Bottom` — ticks are displayed below the track.
* `Both` — ticks are displayed above and below the track.
* `None` — no tick marks are displayed.

For a vertical slider:

* `Top` corresponds to the left side.
* `Bottom` corresponds to the right side.
* `Both` displays ticks on both sides.
* `None` disables tick marks.

A valid FTR Controls license is required to enable this premium feature.

> `TickStyle` controls tick placement. `ShowTicks` controls whether tick marks are enabled.

---

# Value Display and Tooltip

## `ShowValueTooltip`

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

Controls whether a tooltip showing the current value is displayed while the user interacts with the slider.

```csharp
slider.ShowValueTooltip = true;
```

The tooltip is displayed while the user is dragging the slider and is hidden when the interaction ends or the mouse leaves the control.

---

## `ValueSuffix`

**Type:** `string`
**Default:** `""`

Adds text after the numeric value displayed in the tooltip and, when enabled, the value label.

```csharp
slider.ValueSuffix = "%";
```

For example, if the current value is `75`, the displayed value becomes:

```text
75%
```

This can be useful for units such as:

```csharp
slider.ValueSuffix = "%";
slider.ValueSuffix = " dB";
slider.ValueSuffix = "°C";
```

---

## `ShowValue`

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

Displays the current slider value as text next to the slider thumb.

```csharp
slider.ShowValue = true;
```

`ValueSuffix` is also applied to this displayed value.

For example:

```csharp
slider.ShowValue = true;
slider.ValueSuffix = "%";
```

may display:

```text
75%
```

next to the thumb.

A valid FTR Controls license is required to enable this premium feature.

---

# Animation

## `SmoothScrolling`

**Type:** `bool`
**Default:** `true`
**Premium:** Yes

Controls whether programmatic value changes are visually animated.

```csharp
slider.SmoothScrolling = true;
```

When enabled, changing `Value` programmatically can produce a smooth transition of the thumb instead of immediately moving it to the new position.

When disabled, the visual position is updated immediately.

A valid FTR Controls license is required to enable this premium feature.

---

# User Interaction

The control supports mouse, keyboard, and mouse-wheel interaction.

## Mouse

The user can:

* Click the slider.
* Drag the thumb.
* Move the value by clicking/dragging along the track.

During mouse interaction, the value is converted to the configured numeric range and snapped according to `Step`.

---

## Keyboard

The slider is focusable and supports keyboard navigation.

### Horizontal slider

* `Left Arrow` — decrease value.
* `Right Arrow` — increase value.
* `Page Down` — decrease by `LargeChange`.
* `Page Up` — increase by `LargeChange`.

### Vertical slider

* `Down Arrow` — decrease value.
* `Up Arrow` — increase value.
* `Page Down` — decrease by `LargeChange`.
* `Page Up` — increase by `LargeChange`.

The control is RTL-aware for horizontal sliders.

When `RightToLeft = RightToLeft.Yes`, the horizontal left/right behavior is reversed so that keyboard interaction remains consistent with the visual direction of the control.

---

## Mouse Wheel

The mouse wheel can also change the slider value when the control has focus.

* Wheel up — increases the value by `Step`.
* Wheel down — decreases the value by `Step`.

The `Scroll` event is raised when the wheel changes the value.

---

# Events

## `ValueChanged`

Raised whenever the `Value` property changes.

```csharp
slider.ValueChanged += Slider_ValueChanged;

private void Slider_ValueChanged(object sender, EventArgs e)
{
    var slider = (FTRSlider)sender;

    Console.WriteLine(slider.Value);
}
```

This is the recommended event when the application needs to react to a changed slider value.

Typical uses include:

* Updating another control.
* Changing application settings.
* Updating volume or brightness.
* Refreshing a preview.
* Saving user preferences.

---

## `Scroll`

Raised when the user changes the slider during interaction.

It can be raised during:

* Mouse dragging
* Keyboard interaction
* Mouse-wheel interaction

```csharp
slider.Scroll += Slider_Scroll;

private void Slider_Scroll(object sender, EventArgs e)
{
    var slider = (FTRSlider)sender;

    UpdatePreview(slider.Value);
}
```

If the application only needs to know that the value has changed, `ValueChanged` is generally the more appropriate event.

---

# Themes

`FTRSlider` supports the FTR Controls theme system.

The control applies the current theme when it is initialized and exposes:

```csharp
ApplyTheme()
```

to reapply the current theme colors.

Theme-dependent colors include:

* Track color
* Slider/fill color
* Thumb color
* Thumb border color
* Tick color

If the application changes its FTR Controls theme at runtime, `ApplyTheme()` can be used to refresh the slider appearance.

Example:

```csharp
slider.ApplyTheme();
```

Custom colors can also be assigned directly through the color properties if the application requires a custom appearance.

---

# Right-to-Left Support

Horizontal sliders support RTL layouts through the standard Windows Forms `RightToLeft` property.

```csharp
slider.RightToLeft = RightToLeft.Yes;
```

In RTL mode:

* The visual direction of a horizontal slider is reversed.
* Mouse interaction follows the reversed direction.
* Left/right keyboard behavior is reversed accordingly.

Vertical sliders are not affected by RTL for their value direction.

---

# Premium Features and Licensing

The following features are premium:

* `SmoothScrolling`
* `ShowTicks`
* `ShowValue`
* `TickStyle`

A valid FTR Controls license is required to enable these features.

If a premium property is enabled without a valid license, the control requests activation through the FTR Controls licensing system and does not apply the requested setting until the feature is properly licensed.

Applications using only the non-premium functionality can continue to use the standard slider features without enabling these premium options.

---

# Recommended Configuration Examples

## Basic Slider

```csharp
var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Step = 1
};
```

---

## Percentage Slider

```csharp
var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Step = 5,
    ValueSuffix = "%",
    ShowValueTooltip = true
};
```

---

## Slider with Tick Marks

Requires the appropriate premium license.

```csharp
var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Step = 10,
    ShowTicks = true,
    TickFrequency = 10,
    TickStyle = FTRSliderTickStyle.Bottom
};
```

---

## Vertical Slider

```csharp
var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Orientation = FTRSliderOrientation.Vertical
};
```

---

## Keyboard-Friendly Slider

```csharp
var slider = new FTRSlider
{
    Minimum = 0,
    Maximum = 100,
    Value = 50,
    Step = 5,
    LargeChange = 20,
    TabStop = true
};
```

The control is focusable by default and supports arrow and Page Up/Page Down keyboard navigation.

---

# Important Behavior

## Range Validation

`Minimum` must always be less than `Maximum`.

Valid:

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

Invalid:

```csharp
slider.Minimum = 100;
slider.Maximum = 100;
```

The invalid assignment causes `ArgumentOutOfRangeException`.

When changing an existing range, change the properties in an order that keeps the range valid.

For example, to change:

```text
0..100
```

to:

```text
0..1000
```

you can safely increase `Maximum` first:

```csharp
slider.Maximum = 1000;
slider.Minimum = 0;
```

---

## Value Clamping

The control automatically keeps `Value` within the configured range.

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

slider.Value = 150;
```

The resulting value is:

```text
100
```

---

## Step and Range

`Step` defines the snapping interval relative to `Minimum`.

For example:

```csharp
Minimum = 10;
Maximum = 100;
Step = 10;
```

produces values based on offsets from the minimum:

```text
10, 20, 30, 40, ... 100
```

When configuring a slider, it is recommended to choose a `Step` that makes sense for the selected range.

---

# Complete Example

The following example creates a percentage slider with keyboard support, a value tooltip, and a `ValueChanged` handler.

```csharp
using System;
using FTRControls;

public class VolumeController
{
    private readonly FTRSlider _slider;

    public VolumeController()
    {
        _slider = new FTRSlider
        {
            Minimum = 0,
            Maximum = 100,
            Value = 50,
            Step = 5,
            LargeChange = 20,
            ValueSuffix = "%",
            ShowValueTooltip = true,
            Orientation = FTRSliderOrientation.Horizontal
        };

        _slider.ValueChanged += Slider_ValueChanged;
    }

    private void Slider_ValueChanged(object sender, EventArgs e)
    {
        int volume = _slider.Value;

        SetVolume(volume);
    }

    private void SetVolume(int value)
    {
        // Apply the selected value to the application.
    }
}
```

---

# API Summary

| Property / Event   | Type                   |      Default | Premium | Purpose                                 |
| ------------------ | ---------------------- | -----------: | :-----: | --------------------------------------- |
| `Minimum`          | `int`                  |          `0` |    No   | Minimum allowed value                   |
| `Maximum`          | `int`                  |        `100` |    No   | Maximum allowed value                   |
| `Value`            | `int`                  |         `50` |    No   | Current selected value                  |
| `Step`             | `int`                  |          `1` |    No   | Value snapping increment                |
| `LargeChange`      | `int`                  |         `10` |    No   | Page Up/Page Down increment             |
| `Orientation`      | `FTRSliderOrientation` | `Horizontal` |    No   | Horizontal or vertical layout           |
| `TrackColor`       | `Color`                |        Theme |    No   | Track color                             |
| `SliderColor`      | `Color`                |        Theme |    No   | Filled track color                      |
| `ThumbColor`       | `Color`                |        Theme |    No   | Thumb color                             |
| `ThumbBorderColor` | `Color`                |        Theme |    No   | Thumb border color                      |
| `TickColor`        | `Color`                |        Theme |    No   | Tick color                              |
| `TrackHeight`      | `int`                  |          `6` |    No   | Track thickness                         |
| `ThumbSize`        | `int`                  |         `16` |    No   | Thumb diameter                          |
| `ShowValueTooltip` | `bool`                 |       `true` |    No   | Show value tooltip during interaction   |
| `ValueSuffix`      | `string`               |         `""` |    No   | Text appended to displayed value        |
| `SmoothScrolling`  | `bool`                 |       `true` |   Yes   | Smooth value animation                  |
| `ShowTicks`        | `bool`                 |      `false` |   Yes   | Enable tick marks                       |
| `TickFrequency`    | `int`                  |         `10` |    No   | Tick interval                           |
| `ShowValue`        | `bool`                 |      `false` |   Yes   | Display value beside thumb              |
| `TickStyle`        | `FTRSliderTickStyle`   |     `Bottom` |   Yes   | Tick mark placement                     |
| `ValueChanged`     | Event                  |            — |    No   | Raised when value changes               |
| `Scroll`           | Event                  |            — |    No   | Raised during user-driven value changes |
| `ApplyTheme()`     | Method                 |            — |    No   | Reapply current theme colors            |

---

# Enumerations

## `FTRSliderOrientation`

Defines the slider orientation.

```csharp
FTRSliderOrientation.Horizontal
FTRSliderOrientation.Vertical
```

---

## `FTRSliderTickStyle`

Defines the placement of tick marks.

```csharp
FTRSliderTickStyle.None
FTRSliderTickStyle.Top
FTRSliderTickStyle.Bottom
FTRSliderTickStyle.Both
```

For horizontal sliders, `Top` and `Bottom` refer to the upper and lower sides of the track.

For vertical sliders, they correspond to the left and right sides respectively.

---

# Customer Integration Checklist

Before shipping an application using `FTRSlider`, verify:

1. The FTR Controls assembly is referenced by the application.
2. The application targets a compatible Windows Forms environment.
3. `Minimum` is less than `Maximum`.
4. `Value` is configured within the intended range.
5. `Step` matches the desired user interaction.
6. `LargeChange` is configured if Page Up/Page Down behavior is important.
7. `Orientation` is configured correctly for the intended UI.
8. `ShowTicks`, `ShowValue`, `SmoothScrolling`, and `TickStyle` are only enabled when the required premium license is available.
9. `ValueChanged` is used when the application needs to react to value changes.
10. `Scroll` is used when the application specifically needs to respond to user-driven scrolling/interaction.
11. The control's theme or custom colors are configured according to the application's UI.
12. RTL behavior is tested if the application supports right-to-left layouts.

---

# Summary

`FTRSlider` provides a configurable single-value slider for Windows Forms applications.

The main configuration points are:

* **Range:** `Minimum`, `Maximum`
* **Current value:** `Value`
* **Increment:** `Step`
* **Keyboard page increment:** `LargeChange`
* **Orientation:** `Orientation`
* **Appearance:** color and size properties
* **Ticks:** `ShowTicks`, `TickFrequency`, `TickStyle`
* **Value display:** `ShowValueTooltip`, `ShowValue`, `ValueSuffix`
* **Animation:** `SmoothScrolling`
* **Interaction events:** `ValueChanged`, `Scroll`
* **Themes:** `ApplyTheme()`
* **RTL:** standard Windows Forms `RightToLeft` support

For most applications, a basic configuration using `Minimum`, `Maximum`, `Value`, and `Step` is sufficient. Additional properties can be enabled as required by the application's UI and licensing configuration.