# FTRButton User Guide

## Overview

`FTRButton` is a customizable Windows Forms button designed for modern desktop applications.

It supports:

* Modern button styles
* Custom colors
* Rounded corners
* Icons and images
* Icon-only buttons
* Badges
* Tooltips
* Toggle buttons
* Animations
* Gradients
* Themes
* Dialog buttons
* Right-to-left layouts

---

# Installation

After adding the FTR Controls library to your project, open the Windows Forms Designer.

From the Visual Studio Toolbox:

**FTR Controls → FTRButton**

Drag `FTRButton` onto your form.

You can also create the control programmatically:

```csharp
var button = new FTRButton();

button.Text = "Save";
button.Size = new Size(120, 40);

this.Controls.Add(button);
```

---

# Basic Usage

The simplest configuration is:

```csharp
var button = new FTRButton
{
    Text = "Save"
};
```

The button can then be handled through the standard WinForms `Click` event:

```csharp
button.Click += Button_Click;

private void Button_Click(object sender, EventArgs e)
{
    MessageBox.Show("Saved!");
}
```

You can also use the Visual Studio Properties window to configure the control.

---

# Main Properties

## Text

Defines the text displayed on the button.

```csharp
button.Text = "Save";
```

Example:

```csharp
var button = new FTRButton
{
    Text = "Save"
};
```

---

## ButtonText

`ButtonText` is an alternative name for `Text`.

These two are equivalent:

```csharp
button.Text = "Save";
```

```csharp
button.ButtonText = "Save";
```

If you prefer, you can use `ButtonText` when working with the FTRButton-specific properties.

---

# Button Styles

Use the `Style` property to select a predefined appearance.

Available styles:

* `Flat`
* `Material`
* `Neumorphism`
* `Glass`
* `Gradient`
* `Custom`

Example:

```csharp
button.Style = FTRButton.ButtonStyle.Material;
```

### Flat

Standard FTRButton appearance.

```csharp
button.Style = FTRButton.ButtonStyle.Flat;
```

### Material

Material-style appearance.

```csharp
button.Style = FTRButton.ButtonStyle.Material;
```

### Neumorphism

Soft, raised-style appearance.

```csharp
button.Style = FTRButton.ButtonStyle.Neumorphism;
```

### Glass

Glass-style appearance.

```csharp
button.Style = FTRButton.ButtonStyle.Glass;
```

### Gradient

Gradient background.

```csharp
button.Style = FTRButton.ButtonStyle.Gradient;
```

### Custom

Use `Custom` when you want to define the button colors yourself.

```csharp
button.Style = FTRButton.ButtonStyle.Custom;
```

---

# Licensing

Some visual features require an activated FTR Controls license.

Premium features include:

* Advanced button styles
* Rounded corners
* Advanced animations
* Gradient configuration
* 3D effect
* SVG icon support

If a Premium property is used without an active license, FTRButton displays the license activation prompt and does not apply the requested setting.

---

# Colors

FTRButton provides four main color properties.

## ButtonBackColor

Normal button background.

```csharp
button.ButtonBackColor = Color.DodgerBlue;
```

## HoverBackColor

Background displayed when the mouse is over the button.

```csharp
button.HoverBackColor = Color.RoyalBlue;
```

## PressedBackColor

Background displayed while the button is pressed.

It is also used when a checkable button is in the checked state.

```csharp
button.PressedBackColor = Color.MidnightBlue;
```

## ButtonForeColor

Text color.

```csharp
button.ButtonForeColor = Color.White;
```

### Custom Color Example

```csharp
var button = new FTRButton
{
    Text = "Delete",
    ButtonBackColor = Color.Firebrick,
    HoverBackColor = Color.Red,
    PressedBackColor = Color.DarkRed,
    ButtonForeColor = Color.White
};
```

When you manually change these color properties, the button automatically switches to `Custom` style.

---

# Rounded Corners

Use `BorderRadius` to create rounded corners.

```csharp
button.BorderRadius = 10;
```

Example:

```csharp
var button = new FTRButton
{
    Text = "Save",
    BorderRadius = 10
};
```

Larger values create more rounded corners.

---

# Images and Icons

FTRButton supports images through the `ButtonImage` property.

```csharp
button.ButtonImage = Properties.Resources.Save;
```

Example:

```csharp
var button = new FTRButton
{
    Text = "Save",
    ButtonImage = Properties.Resources.Save
};
```

---

# Image Size

Use `ImageSize` to control the displayed image size.

```csharp
button.ImageSize = 24;
```

Example:

```csharp
var button = new FTRButton
{
    Text = "Settings",
    ButtonImage = Properties.Resources.Settings,
    ImageSize = 24
};
```

---

# Image Position

Use `ImagePosition` to control where the image appears.

Available positions:

```text
TopLeft
TopCenter
TopRight

MiddleLeft
MiddleCenter
MiddleRight

BottomLeft
BottomCenter
BottomRight
```

Example:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.MiddleLeft;
```

### Common configurations

Image on the left:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.MiddleLeft;
```

Image on the right:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.MiddleRight;
```

Image above the text:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.TopCenter;
```

Image below the text:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.BottomCenter;
```

Centered icon:

```csharp
button.ImagePosition =
    FTRButton.ImagePositionEnum.MiddleCenter;
```

---

# Icon-Only Buttons

Use `IconOnly` when the button should display only an icon.

```csharp
var button = new FTRButton
{
    IconOnly = true,
    ButtonImage = Properties.Resources.Settings,
    Size = new Size(48, 48)
};
```

This is useful for:

* Toolbar buttons
* Dashboard buttons
* Navigation buttons
* Settings buttons
* Action icons

---

# Image and Text Spacing

Use `ImageTextSpacing` to control the distance between the image and text.

```csharp
button.ImageTextSpacing = 8;
```

Example:

```csharp
var button = new FTRButton
{
    Text = "Settings",
    ButtonImage = Properties.Resources.Settings,
    ImageTextSpacing = 8
};
```

---

# Text Alignment

Use `TextAlignment` to control the horizontal alignment of the button text.

Available values:

* `Left`
* `Center`
* `Right`

Example:

```csharp
button.TextAlignment =
    FTRButton.FTRTextAlignment.Center;
```

---

# Tooltips

Use `TooltipText` to display a tooltip when the user moves the mouse over the button.

```csharp
button.TooltipText = "Save the current document";
```

Example:

```csharp
var saveButton = new FTRButton
{
    Text = "Save",
    TooltipText = "Save the current document"
};
```

---

# Notification Badge

Use `BadgeValue` to display a notification counter.

```csharp
button.BadgeValue = 5;
```

Example:

```csharp
var notificationButton = new FTRButton
{
    IconOnly = true,
    ButtonImage = Properties.Resources.Notification,
    BadgeValue = 5,
    Size = new Size(48, 48)
};
```

### Hide the Badge

Set the value to `0`.

```csharp
button.BadgeValue = 0;
```

### Large Values

Values greater than `99` are displayed as:

```text
99+
```

For example:

```csharp
button.BadgeValue = 150;
```

displays:

```text
99+
```

---

# Checkable / Toggle Buttons

FTRButton can work as a toggle button.

Set:

```csharp
button.Checkable = true;
```

Then the button automatically changes its `Checked` state when clicked.

Example:

```csharp
var toggle = new FTRButton
{
    Text = "Enable",
    Checkable = true
};
```

---

# Checked

Use `Checked` to read or set the current toggle state.

```csharp
toggle.Checked = true;
```

Read the state:

```csharp
if (toggle.Checked)
{
    // Button is enabled
}
```

---

# CheckedChanged Event

Use `CheckedChanged` when your application needs to react to changes in the toggle state.

```csharp
toggle.CheckedChanged += Toggle_CheckedChanged;

private void Toggle_CheckedChanged(object sender, EventArgs e)
{
    if (toggle.Checked)
    {
        // Enabled
    }
    else
    {
        // Disabled
    }
}
```

---

# Animations

FTRButton supports several click animations.

Available options:

* `None`
* `Ripple`
* `SlideIn`
* `DropIn`

Example:

```csharp
button.AnimationType =
    FTRButton.AnimationTypeEnum.Ripple;
```

## Ripple

Recommended default animation.

```csharp
button.AnimationType =
    FTRButton.AnimationTypeEnum.Ripple;
```

## SlideIn

```csharp
button.AnimationType =
    FTRButton.AnimationTypeEnum.SlideIn;
```

## DropIn

```csharp
button.AnimationType =
    FTRButton.AnimationTypeEnum.DropIn;
```

## Disable Animation

```csharp
button.AnimationType =
    FTRButton.AnimationTypeEnum.None;
```

Advanced animation types require an activated Premium license.

---

# Animation Speed

Use `AnimationSpeed` to control the animation duration.

```csharp
button.AnimationSpeed = 300;
```

The value is specified in milliseconds.

Examples:

```csharp
button.AnimationSpeed = 200;
```

Fast animation.

```csharp
button.AnimationSpeed = 500;
```

Normal animation.

```csharp
button.AnimationSpeed = 800;
```

Slower animation.

---

# Gradient Buttons

Enable gradient rendering with:

```csharp
button.GradientEnabled = true;
```

Then configure the colors:

```csharp
button.GradientStart = Color.DodgerBlue;
button.GradientEnd = Color.MediumPurple;
```

Configure the direction:

```csharp
button.GradientDirection =
    FTRButton.GradientDir.Horizontal;
```

Available directions:

* `Vertical`
* `Horizontal`
* `ForwardDiagonal`
* `BackwardDiagonal`

Example:

```csharp
var button = new FTRButton
{
    Text = "Continue",
    GradientEnabled = true,
    GradientStart = Color.DodgerBlue,
    GradientEnd = Color.MediumPurple,
    GradientDirection =
        FTRButton.GradientDir.ForwardDiagonal
};
```

Gradient configuration requires an activated Premium license.

---

# 3D Effect

Use `Is3D` to enable the 3D highlight/shadow effect.

```csharp
button.Is3D = true;
```

For the best visual result, combine it with a rounded button:

```csharp
var button = new FTRButton
{
    Text = "3D Button",
    BorderRadius = 10,
    Is3D = true
};
```

This feature requires an activated Premium license.

---

# Dialog Buttons

FTRButton supports the WinForms `DialogResult` concept.

For an OK button:

```csharp
var okButton = new FTRButton
{
    Text = "OK",
    DialogResult = DialogResult.OK
};
```

For a Cancel button:

```csharp
var cancelButton = new FTRButton
{
    Text = "Cancel",
    DialogResult = DialogResult.Cancel
};
```

When the button is clicked inside a modal form, the parent form receives the specified `DialogResult`.

---

# Programmatically Clicking the Button

Use `PerformClick()` when you want to trigger the button from code.

```csharp
button.PerformClick();
```

For example:

```csharp
private void ExecuteAction()
{
    saveButton.PerformClick();
}
```

The click animation is also started when `PerformClick()` is called.

---

# Keyboard Support

FTRButton supports keyboard activation when it has focus.

### Space

Pressing `Space` activates the button.

### Enter

Pressing `Enter` activates the button.

This allows FTRButton to be used naturally with keyboard-based navigation.

---

# Themes

FTRButton integrates with the FTR Controls theme system.

When the active application theme changes, FTRButton automatically updates its colors as long as it is not using `Custom` style.

Supported themes in the current implementation include:

* Dark
* Light
* Color
* Duotone

### Important

If you manually customize the button colors, the control switches to:

```csharp
FTRButton.ButtonStyle.Custom
```

Custom buttons do not automatically receive the predefined theme colors.

---

# Right-to-Left Applications

FTRButton supports RTL layouts.

For Persian or Arabic applications, set:

```csharp
button.RightToLeft = RightToLeft.Yes;
```

The control automatically adjusts:

* Image positions
* Text direction
* Badge position

Example:

```csharp
var button = new FTRButton
{
    Text = "ذخیره",
    RightToLeft = RightToLeft.Yes
};
```

---

# Disabled Buttons

Use the standard WinForms `Enabled` property.

```csharp
button.Enabled = false;
```

Example:

```csharp
var saveButton = new FTRButton
{
    Text = "Save",
    Enabled = false
};
```

The control automatically displays a disabled appearance and prevents user interaction.

---

# Recommended Configurations

## Standard Action Button

```csharp
var button = new FTRButton
{
    Text = "Save",
    Size = new Size(120, 40)
};
```

---

## Modern Rounded Button

```csharp
var button = new FTRButton
{
    Text = "Save",
    BorderRadius = 8,
    AnimationType =
        FTRButton.AnimationTypeEnum.Ripple
};
```

---

## Icon Button

```csharp
var button = new FTRButton
{
    IconOnly = true,
    ButtonImage = Properties.Resources.Settings,
    Size = new Size(48, 48)
};
```

---

## Notification Button

```csharp
var button = new FTRButton
{
    IconOnly = true,
    ButtonImage = Properties.Resources.Notification,
    BadgeValue = 5,
    Size = new Size(48, 48)
};
```

---

## Toggle Button

```csharp
var button = new FTRButton
{
    Text = "Dark Mode",
    Checkable = true
};
```

---

## Dialog OK Button

```csharp
var button = new FTRButton
{
    Text = "OK",
    DialogResult = DialogResult.OK
};
```

---

# Property Reference

| Property            | Description                |
| ------------------- | -------------------------- |
| `Text`              | Button caption             |
| `ButtonText`        | Alias for `Text`           |
| `Style`             | Predefined visual style    |
| `BorderRadius`      | Corner radius              |
| `ButtonImage`       | Button image               |
| `SvgIconPath`       | Icon file path             |
| `IconOnly`          | Displays only the icon     |
| `ImagePosition`     | Image placement            |
| `ImageSize`         | Image size                 |
| `ImageTextSpacing`  | Image/text spacing         |
| `TextAlignment`     | Text alignment             |
| `TooltipText`       | Tooltip text               |
| `BadgeValue`        | Notification badge value   |
| `Checkable`         | Enables toggle behavior    |
| `Checked`           | Current toggle state       |
| `AnimationType`     | Click animation            |
| `AnimationSpeed`    | Animation duration         |
| `GradientEnabled`   | Enables gradient           |
| `GradientDirection` | Gradient direction         |
| `GradientStart`     | Gradient start color       |
| `GradientEnd`       | Gradient end color         |
| `Is3D`              | Enables 3D effect          |
| `ButtonBackColor`   | Normal background          |
| `HoverBackColor`    | Hover background           |
| `PressedBackColor`  | Pressed/checked background |
| `ButtonForeColor`   | Text color                 |
| `DialogResult`      | Modal dialog result        |

---

# Events

| Event            | Description                          |
| ---------------- | ------------------------------------ |
| `Click`          | Raised when the button is activated  |
| `CheckedChanged` | Raised when the toggle state changes |

---

# Quick Start

The following example demonstrates a typical FTRButton configuration:

```csharp
var saveButton = new FTRButton
{
    Text = "Save",
    Style = FTRButton.ButtonStyle.Material,
    BorderRadius = 8,
    ButtonImage = Properties.Resources.Save,
    ImagePosition =
        FTRButton.ImagePositionEnum.MiddleLeft,
    ImageSize = 20,
    ImageTextSpacing = 8,
    TooltipText = "Save the current document",
    AnimationType =
        FTRButton.AnimationTypeEnum.Ripple,
    Size = new Size(140, 42)
};

saveButton.Click += (sender, e) =>
{
    SaveData();
};
```

This creates a modern Material-style button with:

* Rounded corners
* Save icon
* Icon/text spacing
* Tooltip
* Ripple animation
* Click event

---

# Notes

* Changing custom color properties automatically switches the button to `Custom` style.
* `BadgeValue = 0` hides the badge.
* Badge values greater than `99` are displayed as `99+`.
* `Checkable` must be enabled for the button to behave as a toggle.
* `CheckedChanged` is raised whenever `Checked` changes.
* `RightToLeft.Yes` automatically adjusts image and badge positions.
* Premium features require an activated FTR Controls license.