# FTRCheckBox

## Customer Usage and Integration Guide

### 1. Overview

`FTRCheckBox` is a custom Windows Forms checkbox control provided by the FTR Controls library.

It extends the standard checkbox concept with additional visual styles, optional animations, three-state support, validation states, custom icons, keyboard interaction, grouping, theming, and optional sound feedback.

The control is designed to be used directly by application developers through the Visual Studio Toolbox or programmatically from C#.

**Namespace:** `FTRControls`

**Base Class:** `FTRControls.BaseClasses.FTRBaseControl`

**Default Event:** `CheckedChanged`

---

# 2. Requirements

The application must reference the FTR Controls assembly containing `FTRCheckBox`.

The control is intended for Windows Forms applications.

The following namespace is required when creating the control programmatically:

```csharp
using FTRControls;
```

Some examples also require:

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

---

# 3. Adding FTRCheckBox to a Windows Forms Application

## 3.1 Using the Visual Studio Toolbox

If the FTR Controls assembly is registered with the Visual Studio Toolbox:

1. Open the Windows Forms project.
2. Open the Toolbox.
3. Locate the FTR Controls section.
4. Select `FTRCheckBox`.
5. Drag the control onto the form.
6. Configure its properties through the Properties window.

The most commonly used properties are available under categories such as:

* FTR Data
* FTR Behavior
* FTR Appearance
* FTR State
* FTR Disabled
* FTR Animation
* FTR Icons
* FTR Sound

---

## 3.2 Creating the Control Programmatically

A basic checkbox can be created as follows:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Enable feature",
    Checked = false
};

Controls.Add(checkBox);
```

The control can then be configured using its public properties.

---

# 4. Basic Checkbox Usage

For normal checkbox behavior, the following properties are usually sufficient:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "I agree to the terms",
    Checked = false,
    AutoCheck = true
};
```

With `AutoCheck = true`, clicking the control automatically changes its state.

The default state is:

```text
Unchecked
```

---

# 5. Checkbox State

The control provides three related ways to work with its state.

## 5.1 Checked

`Checked` is the simplest option when the application only needs a Boolean state.

```csharp
checkBox.Checked = true;
```

Read the value:

```csharp
bool isChecked = checkBox.Checked;
```

Possible values:

* `true` — checked
* `false` — unchecked

---

## 5.2 CheckState

`CheckState` provides access to all supported states:

```csharp
checkBox.CheckState = CheckState.Checked;
```

The available states are:

* `CheckState.Unchecked`
* `CheckState.Checked`
* `CheckState.Indeterminate`

Example:

```csharp
if (checkBox.CheckState == CheckState.Checked)
{
    // Enabled
}
```

---

## 5.3 CheckedState

`CheckedState` provides a nullable Boolean representation:

```csharp
checkBox.CheckedState = true;
checkBox.CheckedState = false;
checkBox.CheckedState = null;
```

The mapping is:

| CheckedState | CheckState    |
| ------------ | ------------- |
| `true`       | Checked       |
| `false`      | Unchecked     |
| `null`       | Indeterminate |

For `null` to be represented as an indeterminate state through `CheckedState`, `ThreeState` should be enabled.

---

# 6. Three-State Mode

Three-state behavior can be enabled with:

```csharp
checkBox.ThreeState = true;
```

When enabled, clicking the control cycles through:

```text
Unchecked
    ↓
Checked
    ↓
Indeterminate
    ↓
Unchecked
```

Example:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Select all",
    ThreeState = true
};
```

Three-state mode is useful for scenarios such as:

* Parent/child selections
* "Some items selected" states
* Configuration options with an undefined state
* Hierarchical selection controls

---

# 7. Automatic State Changes

`AutoCheck` controls whether user interaction automatically changes the checkbox state.

Default:

```text
AutoCheck = true
```

### Automatic behavior

```csharp
checkBox.AutoCheck = true;
```

The control changes its state when clicked or activated through supported keyboard interaction.

### Manual behavior

```csharp
checkBox.AutoCheck = false;
```

When `AutoCheck` is disabled, the control does not automatically change its state when clicked.

This is useful when the application wants to control state changes itself.

Example:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Confirm operation",
    AutoCheck = false
};

checkBox.Click += (sender, e) =>
{
    // Application-specific logic
    checkBox.Checked = true;
};
```

---

# 8. Responding to State Changes

The control provides two events that are raised after a successful state change.

## 8.1 CheckedChanged

Use `CheckedChanged` when the application is primarily interested in the checked state.

```csharp
checkBox.CheckedChanged += (sender, e) =>
{
    if (checkBox.Checked)
    {
        // Checkbox is checked
    }
    else
    {
        // Checkbox is not checked
    }
};
```

---

## 8.2 CheckStateChanged

Use `CheckStateChanged` when the application needs to distinguish between:

* Unchecked
* Checked
* Indeterminate

Example:

```csharp
checkBox.CheckStateChanged += (sender, e) =>
{
    switch (checkBox.CheckState)
    {
        case CheckState.Checked:
            // Checked
            break;

        case CheckState.Unchecked:
            // Unchecked
            break;

        case CheckState.Indeterminate:
            // Indeterminate
            break;
    }
};
```

---

# 9. Cancelling a State Change

`BeforeCheckChanged` is raised before the state is changed.

The event allows the application to prevent a state change by setting:

```csharp
e.Cancel = true;
```

Example:

```csharp
checkBox.BeforeCheckChanged += (sender, e) =>
{
    if (!IsOperationAllowed())
    {
        e.Cancel = true;
    }
};
```

The event arguments provide both states:

```csharp
e.OldState
e.NewState
```

Example:

```csharp
checkBox.BeforeCheckChanged += (sender, e) =>
{
    if (e.NewState == CheckState.Checked)
    {
        // Validate before allowing the checkbox to become checked.
    }
};
```

This is useful for:

* Validation
* Permission checks
* Business rules
* Preventing invalid selections
* Confirming application conditions before changing state

---

# 10. Visual Styles

`FTRCheckBox` provides four visual styles:

```text
Standard
Rounded
ToggleSwitch
CustomIcon
```

The style is selected using:

```csharp
checkBox.Style = FTRCheckBox.FTRCheckStyle.Rounded;
```

---

## 10.1 Standard

Standard checkbox appearance:

```csharp
checkBox.Style = FTRCheckBox.FTRCheckStyle.Standard;
```

This is the default style.

It is recommended for conventional checkbox scenarios.

---

## 10.2 Rounded

Rounded checkbox appearance:

```csharp
checkBox.Style = FTRCheckBox.FTRCheckStyle.Rounded;
```

This style provides a more rounded visual appearance.

The exact radius can also be controlled with:

```csharp
checkBox.CornerRadius = 6;
```

---

## 10.3 ToggleSwitch

The control can also be displayed as a switch:

```csharp
checkBox.Style = FTRCheckBox.FTRCheckStyle.ToggleSwitch;
```

Example:

```csharp
var toggle = new FTRCheckBox
{
    Text = "Dark mode",
    Style = FTRCheckBox.FTRCheckStyle.ToggleSwitch,
    Checked = true
};
```

### License requirement

`ToggleSwitch` is a licensed/premium style.

If the required license is not available, the control does not apply the premium style and falls back to `Standard`.

---

## 10.4 CustomIcon

The control can use different images for checked and unchecked states:

```csharp
checkBox.Style = FTRCheckBox.FTRCheckStyle.CustomIcon;
checkBox.CheckedIcon = checkedImage;
checkBox.UncheckedIcon = uncheckedImage;
```

### License requirement

`CustomIcon` is a licensed/premium style.

Without the required license, the control falls back to `Standard`.

---

# 11. Text Position

The checkbox and its text can be positioned using:

```csharp
checkBox.TextPosition =
    FTRCheckBox.FTRTextPosition.Right;
```

Available values:

```text
Right
Left
```

Example:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Enable notifications",
    TextPosition = FTRCheckBox.FTRTextPosition.Left
};
```

The effective position is automatically mirrored when right-to-left layout is enabled.

---

# 12. Text and Secondary Text

The main caption is provided through the standard Windows Forms `Text` property.

A secondary caption can be displayed using:

```csharp
checkBox.SubText = "Additional information";
```

Example:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Automatic updates",
    SubText = "Recommended for most users"
};
```

The secondary text color can be configured using:

```csharp
checkBox.SubTextColor = Color.Gray;
```

A custom font can be assigned using:

```csharp
checkBox.SubTextFont = new Font(
    "Segoe UI",
    8F
);
```

---

# 13. Icons

The control supports three icon properties.

## CheckedIcon

Displayed when the control is checked in `CustomIcon` mode.

```csharp
checkBox.CheckedIcon = checkedImage;
```

## UncheckedIcon

Displayed when the control is unchecked in `CustomIcon` mode.

```csharp
checkBox.UncheckedIcon = uncheckedImage;
```

## TextSideIcon

Displays an additional icon next to the text.

```csharp
checkBox.TextSideIcon = informationIcon;
```

---

## Icon Size

The icon size can be controlled using:

```csharp
checkBox.IconSize = 18;
```

If `IconSize` is not explicitly specified, the control calculates an appropriate size based on the available area.

---

## Icon Padding

Use `IconPadding` to control the space around the custom icon:

```csharp
checkBox.IconPadding = 4;
```

---

# 14. Colors and Appearance

The following properties allow the checkbox appearance to be customized.

### CheckedColor

Color used for the checked state.

```csharp
checkBox.CheckedColor = Color.DodgerBlue;
```

### UncheckedColor

Color used for the unchecked state.

```csharp
checkBox.UncheckedColor = Color.Gray;
```

### CheckMarkColor

Color of the check mark.

```csharp
checkBox.CheckMarkColor = Color.White;
```

### HoverColor

Color used for the hover effect.

```csharp
checkBox.HoverColor = Color.LightGray;
```

### RippleColor

Color used by the ripple animation.

```csharp
checkBox.RippleColor = Color.LightBlue;
```

### FocusBorderColor

Color of the focus indicator.

```csharp
checkBox.FocusBorderColor = Color.DodgerBlue;
```

---

# 15. Border and Shadow

## BorderThickness

Controls the border width.

```csharp
checkBox.BorderThickness = 2f;
```

Default value:

```text
2
```

## CornerRadius

Controls the corner radius.

```csharp
checkBox.CornerRadius = 6;
```

A value of `0` uses the style-dependent default radius.

## EnableShadow

Controls the shadow beneath the checkbox.

```csharp
checkBox.EnableShadow = true;
```

Default:

```text
true
```

## OpaqueBackground

Controls whether the background is explicitly painted.

```csharp
checkBox.OpaqueBackground = true;
```

Default:

```text
false
```

---

# 16. Animation

The control supports animated state transitions.

## AnimationEnabled

Controls whether animations are enabled.

Default:

```text
true
```

Example:

```csharp
checkBox.AnimationEnabled = false;
```

Disabling animation can be useful when:

* The application requires a simpler UI.
* Many controls are displayed simultaneously.
* Animation is not appropriate for the application design.

---

## AnimationSpeed

Controls the state animation speed.

```csharp
checkBox.AnimationSpeed = 5;
```

The default value is `5`.

---

## AnimationType

Available animation types:

```text
Linear
EaseIn
EaseOut
Bounce
Elastic
```

Example:

```csharp
checkBox.AnimationType =
    FTRCheckBox.FTRAnimationType.EaseOut;
```

`Linear` is the default.

The non-linear animation types require the appropriate license. Without the required license, the requested premium animation type is not applied.

---

# 17. Ripple Effect

The ripple effect can be enabled using:

```csharp
checkBox.EnableRipple = true;
```

Important:

`EnableRipple` defaults to:

```text
false
```

The ripple feature is license-protected. If the required license is unavailable, attempting to enable it does not activate the feature.

---

## RippleSpeed

Controls the speed of the ripple animation.

```csharp
checkBox.RippleSpeed = 4;
```

Default:

```text
4
```

---

# 18. Validation and Visual States

The control supports four visual states:

```text
Normal
Error
Warning
Info
```

The state is configured using:

```csharp
checkBox.VisualState =
    FTRCheckBox.FTRVisualState.Error;
```

---

## Normal

```csharp
checkBox.VisualState =
    FTRCheckBox.FTRVisualState.Normal;
```

No validation indicator is displayed.

---

## Error

```csharp
checkBox.ErrorMessage = "This option is required.";
checkBox.VisualState =
    FTRCheckBox.FTRVisualState.Error;
```

The control displays the error visual state and, when animation is enabled, performs the error shake animation.

---

## Warning

```csharp
checkBox.WarningMessage = "This option is recommended.";
checkBox.VisualState =
    FTRCheckBox.FTRVisualState.Warning;
```

---

## Info

```csharp
checkBox.InfoMessage = "This option changes application behavior.";
checkBox.VisualState =
    FTRCheckBox.FTRVisualState.Info;
```

---

# 19. State Tooltips

State messages can be displayed as tooltips.

Enable or disable this behavior using:

```csharp
checkBox.ShowStateTooltip = true;
```

Default:

```text
true
```

The message shown depends on the current visual state:

| Visual State | Message Property |
| ------------ | ---------------- |
| Normal       | None             |
| Error        | `ErrorMessage`   |
| Warning      | `WarningMessage` |
| Info         | `InfoMessage`    |

Example:

```csharp
checkBox.ErrorMessage = "Please select this option.";
checkBox.VisualState = FTRCheckBox.FTRVisualState.Error;
```

---

# 20. Keyboard Interaction

The control supports keyboard activation.

The following keys can activate the checkbox:

* Space
* Enter

Example:

```text
Focus the checkbox → Press Space → State changes
```

The control also supports Windows Forms mnemonic processing.

For example, text containing an ampersand can be used for mnemonic activation:

```csharp
checkBox.Text = "&Enable feature";
```

---

# 21. Custom Shortcut Key

A custom shortcut can be assigned using:

```csharp
checkBox.ShortcutKey = Keys.F5;
```

When the specified key is pressed while the control receives the keyboard event, the control performs its click behavior.

The default value is:

```text
Keys.None
```

---

# 22. Grouping Multiple Checkboxes

`FTRCheckBoxGroup` can be used when multiple `FTRCheckBox` controls need coordinated selection behavior.

The group supports:

* Radio-style mutual exclusion
* Maximum number of checked items

Example:

```csharp
var group = new FTRCheckBoxGroup();

group.Members.Add(option1);
group.Members.Add(option2);
group.Members.Add(option3);
```

---

# 23. Radio Mode

Enable radio behavior with:

```csharp
group.RadioMode = true;
```

When one member becomes checked, the other checked members are automatically unchecked.

Example:

```csharp
var group = new FTRCheckBoxGroup
{
    RadioMode = true
};

group.Members.Add(option1);
group.Members.Add(option2);
group.Members.Add(option3);
```

The intended result is:

```text
Option 1  ✓
Option 2  -
Option 3  -
```

If another option is selected:

```text
Option 1  -
Option 2  ✓
Option 3  -
```

The group implementation automatically unchecks other members when a member is checked.

---

# 24. Maximum Number of Checked Items

Use `MaxChecked` to limit the number of simultaneously checked members.

Example:

```csharp
var group = new FTRCheckBoxGroup
{
    MaxChecked = 2
};

group.Members.Add(option1);
group.Members.Add(option2);
group.Members.Add(option3);
group.Members.Add(option4);
```

With this configuration, at most two members can be checked.

If the maximum has already been reached, another attempt to check a member is cancelled.

A value of:

```text
-1
```

means that no maximum limit is applied.

---

# 25. Radio Mode vs. MaxChecked

These two features should be selected according to the required behavior.

### Use RadioMode

When exactly one option should normally be selected at a time.

```csharp
group.RadioMode = true;
```

### Use MaxChecked

When multiple options are allowed, but there is a maximum limit.

```csharp
group.MaxChecked = 2;
```

For example:

```text
Maximum 2 selections:

[✓] Option A
[✓] Option B
[ ] Option C
[ ] Option D
```

---

# 26. Themes

The control integrates with the FTR Controls theme system.

Calling:

```csharp
checkBox.ApplyTheme();
```

applies the current global FTR theme.

The control selects its checkbox theme according to the active global theme, including the supported Light, Dark, Color, and Duotone theme modes.

---

# 27. Applying a Custom Theme

A custom `FTRCheckBoxTheme` can be created and applied to the control.

Example:

```csharp
var theme = new FTRCheckBoxTheme
{
    CheckedColor = Color.DodgerBlue,
    UncheckedColor = Color.Gray,
    CheckMarkColor = Color.White,
    HoverColor = Color.LightGray,
    FocusBorderColor = Color.DodgerBlue
};

checkBox.ApplyTheme(theme);
```

The supplied theme is cloned by the control, so subsequent changes to the original theme object do not directly replace the control's internal theme object.

---

# 28. Built-in Theme Presets

Two theme presets are available from `FTRCheckBoxTheme`:

```csharp
FTRCheckBoxTheme.LightTheme()
```

and:

```csharp
FTRCheckBoxTheme.DarkTheme()
```

Example:

```csharp
checkBox.ApplyTheme(
    FTRCheckBoxTheme.DarkTheme()
);
```

These presets provide predefined colors for the control.

---

# 29. Theme Color Properties

`FTRCheckBoxTheme` contains the following color settings:

* `CheckedColor`
* `UncheckedColor`
* `CheckMarkColor`
* `HoverColor`
* `RippleColor`
* `ForeColor`
* `SubTextColor`
* `FocusBorderColor`
* `ErrorColor`
* `WarningColor`
* `DisabledForeColor`
* `DisabledBoxColor`
* `DisabledCheckColor`

This allows applications to create a consistent visual configuration for multiple controls.

---

# 30. Disabled Appearance

The control provides dedicated colors for the disabled state.

### DisabledForeColor

```csharp
checkBox.DisabledForeColor = Color.Gray;
```

### DisabledBoxColor

```csharp
checkBox.DisabledBoxColor = Color.LightGray;
```

### DisabledCheckColor

```csharp
checkBox.DisabledCheckColor = Color.DarkGray;
```

The control can be disabled using the standard Windows Forms property:

```csharp
checkBox.Enabled = false;
```

When disabled, the control also changes the mouse cursor to the default cursor.

---

# 31. Sound Feedback

Optional sound feedback is available for checked and unchecked states.

Enable it using:

```csharp
checkBox.EnableSound = true;
```

Sound files are specified using:

```csharp
checkBox.CheckedSoundPath = @"C:\Sounds\checked.wav";
checkBox.UncheckedSoundPath = @"C:\Sounds\unchecked.wav";
```

Only WAV files supported by the underlying `SoundPlayer` mechanism should be used.

Example:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Enable sound",
    EnableSound = true,
    CheckedSoundPath = @"Sounds\checked.wav",
    UncheckedSoundPath = @"Sounds\unchecked.wav"
};
```

### License requirement

Sound feedback is license-protected. Without the required license, setting `EnableSound` to `true` does not enable the feature.

If a configured sound file does not exist, no sound is played.

---

# 32. Right-to-Left Layout

The control supports right-to-left layout.

Use:

```csharp
checkBox.RightToLeftLayout = true;
```

The control also considers the standard Windows Forms `RightToLeft` property when determining the effective position of the checkbox and text.

This allows the control to be used in applications that require right-to-left user interfaces.

---

# 33. Recommended Basic Configuration

For a normal customer application, the following configuration is recommended:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Enable feature",
    Checked = false,
    AutoCheck = true,
    AnimationEnabled = true,
    Style = FTRCheckBox.FTRCheckStyle.Standard
};
```

This configuration does not require any premium visual feature.

---

# 34. Example: Terms and Conditions

```csharp
var terms = new FTRCheckBox
{
    Text = "I agree to the terms and conditions",
    Style = FTRCheckBox.FTRCheckStyle.Rounded
};

terms.BeforeCheckChanged += (sender, e) =>
{
    if (e.NewState == CheckState.Checked && !TermsLoaded())
    {
        e.Cancel = true;
    }
};

terms.CheckedChanged += (sender, e) =>
{
    continueButton.Enabled = terms.Checked;
};
```

This example demonstrates:

* Standard state management
* Rounded appearance
* Validation before checking
* Responding to the final state

---

# 35. Example: Toggle Setting

If the application license supports the premium ToggleSwitch style:

```csharp
var darkMode = new FTRCheckBox
{
    Text = "Dark mode",
    Style = FTRCheckBox.FTRCheckStyle.ToggleSwitch,
    Checked = true
};

darkMode.CheckedChanged += (sender, e) =>
{
    SetDarkMode(darkMode.Checked);
};
```

---

# 36. Example: Validation State

```csharp
var requiredOption = new FTRCheckBox
{
    Text = "I accept the required option"
};

requiredOption.CheckedChanged += (sender, e) =>
{
    if (!requiredOption.Checked)
    {
        requiredOption.ErrorMessage =
            "This option must be selected.";

        requiredOption.VisualState =
            FTRCheckBox.FTRVisualState.Error;
    }
    else
    {
        requiredOption.VisualState =
            FTRCheckBox.FTRVisualState.Normal;
    }
};
```

---

# 37. Example: Multiple Selection Limit

```csharp
var group = new FTRCheckBoxGroup
{
    MaxChecked = 2
};

group.Members.Add(optionA);
group.Members.Add(optionB);
group.Members.Add(optionC);
group.Members.Add(optionD);
```

This allows the user to select up to two options.

---

# 38. Example: Single Selection Group

```csharp
var group = new FTRCheckBoxGroup
{
    RadioMode = true
};

group.Members.Add(optionA);
group.Members.Add(optionB);
group.Members.Add(optionC);
```

Selecting one option automatically unchecks the other checked members.

---

# 39. Premium Features

The following features are protected by the FTR Controls licensing system:

| Feature                   | License Required |
| ------------------------- | ---------------- |
| `Style = ToggleSwitch`    | Yes              |
| `Style = CustomIcon`      | Yes              |
| `EnableRipple = true`     | Yes              |
| `AnimationType != Linear` | Yes              |
| `EnableSound = true`      | Yes              |

The standard checkbox functionality does not require these premium features.

If a protected feature is requested without a valid license, the control prevents the premium setting from being applied or falls back to the standard behavior, depending on the feature.

---

# 40. Recommended Customer Usage

For maximum compatibility, use the standard features unless a licensed feature is specifically required.

Recommended standard configuration:

```csharp
var checkBox = new FTRCheckBox
{
    Text = "Enable option",
    Style = FTRCheckBox.FTRCheckStyle.Standard,
    AutoCheck = true,
    AnimationEnabled = true,
    EnableRipple = false
};
```

Use premium functionality only when the corresponding FTR Controls license has been activated.

---

# 41. Property Reference

## Data

| Property             | Type         |     Default | Purpose                                                      |
| -------------------- | ------------ | ----------: | ------------------------------------------------------------ |
| `Checked`            | `bool`       |     `false` | Gets or sets the checked state.                              |
| `CheckState`         | `CheckState` | `Unchecked` | Gets or sets the full checkbox state.                        |
| `CheckedState`       | `bool?`      |     `false` | Nullable Boolean representation of the state.                |
| `AllowIndeterminate` | `bool`       |           — | Alias for `ThreeState`; primarily exposed for compatibility. |

## Behavior

| Property           | Type   | Default | Purpose                                    |
| ------------------ | ------ | ------: | ------------------------------------------ |
| `ThreeState`       | `bool` | `false` | Enables three-state user interaction.      |
| `AutoCheck`        | `bool` |  `true` | Automatically changes state on activation. |
| `AnimationEnabled` | `bool` |  `true` | Enables visual animations.                 |
| `EnableRipple`     | `bool` | `false` | Enables ripple effect; licensed feature.   |
| `ShortcutKey`      | `Keys` |  `None` | Optional keyboard shortcut.                |

## Appearance

| Property            | Type              |         Default | Purpose                              |
| ------------------- | ----------------- | --------------: | ------------------------------------ |
| `Style`             | `FTRCheckStyle`   |      `Standard` | Selects the visual style.            |
| `TextPosition`      | `FTRTextPosition` |         `Right` | Positions checkbox relative to text. |
| `CornerRadius`      | `int`             |             `0` | Controls corner radius.              |
| `BorderThickness`   | `float`           |             `2` | Controls border width.               |
| `EnableShadow`      | `bool`            |          `true` | Enables shadow.                      |
| `OpaqueBackground`  | `bool`            |         `false` | Controls background painting.        |
| `SubText`           | `string`          |           Empty | Secondary text.                      |
| `SubTextFont`       | `Font`            |    Segoe UI 8pt | Secondary text font.                 |
| `SubTextColor`      | `Color`           | Theme dependent | Secondary text color.                |
| `RightToLeftLayout` | `bool`            |         `false` | Mirrors the layout.                  |

## Colors

| Property           | Type    | Purpose                |
| ------------------ | ------- | ---------------------- |
| `CheckedColor`     | `Color` | Checked-state color.   |
| `UncheckedColor`   | `Color` | Unchecked-state color. |
| `CheckMarkColor`   | `Color` | Check-mark color.      |
| `HoverColor`       | `Color` | Hover effect color.    |
| `RippleColor`      | `Color` | Ripple effect color.   |
| `FocusBorderColor` | `Color` | Focus indicator color. |

## State and Validation

| Property           | Type             |  Default | Purpose                          |
| ------------------ | ---------------- | -------: | -------------------------------- |
| `VisualState`      | `FTRVisualState` | `Normal` | Current validation/visual state. |
| `ErrorMessage`     | `string`         |    Empty | Error tooltip message.           |
| `WarningMessage`   | `string`         |    Empty | Warning tooltip message.         |
| `InfoMessage`      | `string`         |    Empty | Information tooltip message.     |
| `ShowStateTooltip` | `bool`           |   `true` | Enables state tooltips.          |

## Disabled Appearance

| Property             | Type    | Purpose                      |
| -------------------- | ------- | ---------------------------- |
| `DisabledForeColor`  | `Color` | Disabled text color.         |
| `DisabledBoxColor`   | `Color` | Disabled checkbox color.     |
| `DisabledCheckColor` | `Color` | Disabled check/handle color. |

## Animation

| Property         | Type               |  Default | Purpose                            |
| ---------------- | ------------------ | -------: | ---------------------------------- |
| `AnimationSpeed` | `int`              |      `5` | Controls check animation speed.    |
| `RippleSpeed`    | `int`              |      `4` | Controls ripple animation speed.   |
| `AnimationType`  | `FTRAnimationType` | `Linear` | Selects the animation easing type. |

## Icons

| Property        | Type    | Default | Purpose                                |
| --------------- | ------- | ------: | -------------------------------------- |
| `CheckedIcon`   | `Image` |  `null` | Checked-state icon.                    |
| `UncheckedIcon` | `Image` |  `null` | Unchecked-state icon.                  |
| `TextSideIcon`  | `Image` |  `null` | Icon displayed beside text.            |
| `IconPadding`   | `int`   |     `4` | Icon padding.                          |
| `IconSize`      | `int`   |     `0` | Custom icon size; automatic when zero. |

## Sound

| Property             | Type     | Default | Purpose                                   |
| -------------------- | -------- | ------: | ----------------------------------------- |
| `EnableSound`        | `bool`   | `false` | Enables sound feedback; licensed feature. |
| `CheckedSoundPath`   | `string` |   Empty | WAV file for checked state.               |
| `UncheckedSoundPath` | `string` |   Empty | WAV file for unchecked state.             |

---

# 42. Event Reference

| Event                | When It Occurs           | Typical Use                           |
| -------------------- | ------------------------ | ------------------------------------- |
| `BeforeCheckChanged` | Before the state changes | Validation or cancellation            |
| `CheckStateChanged`  | After the state changes  | Respond to all three states           |
| `CheckedChanged`     | After the state changes  | Respond to checked/unchecked behavior |

Example:

```csharp
checkBox.BeforeCheckChanged += OnBeforeCheckChanged;
checkBox.CheckStateChanged += OnCheckStateChanged;
checkBox.CheckedChanged += OnCheckedChanged;
```

---

# 43. Important Behavior Notes

### State changes can be cancelled

If `BeforeCheckChanged` sets:

```csharp
e.Cancel = true;
```

the requested state change is not applied.

### Three-state cycling

When `ThreeState` is enabled, clicking cycles through:

```text
Unchecked → Checked → Indeterminate → Unchecked
```

### Animation does not change the logical state

Animation only affects the visual transition. The actual state is available immediately through:

```csharp
Checked
CheckState
CheckedState
```

### Premium features require licensing

Premium features should not be assumed to be available in every installation.

The application should be designed so that standard checkbox behavior remains functional if premium features are not licensed.

---

# 44. Troubleshooting

## The checkbox does not change state

Check:

```csharp
AutoCheck
```

If it is:

```csharp
AutoCheck = false;
```

the application is responsible for changing the state.

Also check whether `BeforeCheckChanged` is cancelling the operation.

---

## A premium style does not appear

Verify that the required FTR Controls license is active.

For example:

```csharp
Style = FTRCheckBox.FTRCheckStyle.ToggleSwitch
```

requires the corresponding license.

Without the license, the control falls back to the standard style.

---

## Ripple does not appear

Verify:

```csharp
EnableRipple = true;
```

Ripple is a licensed feature and defaults to `false`.

---

## Sound does not play

Check all of the following:

1. `EnableSound` is enabled.
2. The required license is active.
3. The configured WAV file exists.
4. The file path is correct.

Example:

```csharp
checkBox.CheckedSoundPath =
    @"C:\Application\Sounds\checked.wav";
```

---

## The validation tooltip is not displayed

Verify:

```csharp
ShowStateTooltip = true;
```

and configure the appropriate message:

```csharp
ErrorMessage = "Please select this option.";
VisualState = FTRCheckBox.FTRVisualState.Error;
```

---

# 45. Recommended Integration Pattern

For most applications, the recommended integration pattern is:

1. Create the `FTRCheckBox`.
2. Set the display text.
3. Select the required standard or licensed style.
4. Set the initial state.
5. Subscribe to `CheckedChanged` or `CheckStateChanged`.
6. Use `BeforeCheckChanged` when state changes require validation.
7. Use `FTRCheckBoxGroup` when multiple controls require coordinated selection.
8. Apply the application's FTR theme where appropriate.

Example:

```csharp
var option = new FTRCheckBox
{
    Text = "Enable automatic processing",
    Style = FTRCheckBox.FTRCheckStyle.Standard,
    Checked = false,
    AutoCheck = true
};

option.BeforeCheckChanged += (sender, e) =>
{
    if (e.NewState == CheckState.Checked &&
        !CanEnableAutomaticProcessing())
    {
        e.Cancel = true;
    }
};

option.CheckedChanged += (sender, e) =>
{
    UpdateAutomaticProcessing(option.Checked);
};

Controls.Add(option);
```

---

# 46. Summary

`FTRCheckBox` can be used as a standard checkbox without requiring advanced configuration.

For common scenarios, the following properties are the most important:

```text
Text
Checked
CheckState
ThreeState
AutoCheck
Style
TextPosition
VisualState
BeforeCheckChanged
CheckedChanged
CheckStateChanged
```

Advanced functionality is available for applications that require:

* Toggle-switch presentation
* Custom icons
* Ripple effects
* Advanced animation
* Sound feedback
* Validation states
* Grouped selection
* Custom themes
* Right-to-left layouts

Premium functionality is controlled by the FTR Controls licensing system and should only be enabled when the required license is available.