# FTRBadgeLabel

## Overview

`FTRBadgeLabel` is a Windows Forms custom control designed for displaying status badges, counters, tags, labels, and other compact visual indicators.

The control provides automatic sizing, pill-shaped or rounded-rectangle rendering, customizable colors, optional borders, configurable text alignment, padding, and right-to-left text support.

**Namespace:** `FTRControls`
**Base Class:** `System.Windows.Forms.Control`
**Toolbox Item:** Yes
**Default Property:** `Text`
**Default Event:** `Click`

---

# Features

* Pill-shaped badge rendering
* Rounded-rectangle rendering
* Automatic sizing based on text and font
* `GrowAndShrink` and `GrowOnly` sizing modes
* Custom background color
* Custom text color
* Optional border
* Custom border thickness
* Custom corner radius
* Configurable text alignment
* Right-to-left text support
* Transparent background support
* Smooth anti-aliased rendering
* Double-buffered display
* Standard Windows Forms events
* Integrated FTR Controls licensing support

---

# Installation

Add the FTR Controls assembly to your Windows Forms application.

Once the assembly is referenced, the control can be used directly in code:

```csharp
using FTRControls;
```

If the control is available in the Visual Studio Toolbox, it can also be added directly to a Windows Forms designer surface.

---

# Basic Usage

The following example creates a basic badge:

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Active"
};

Controls.Add(badge);
```

By default, the control automatically sizes itself according to its content.

---

# Properties

## Text

**Type:** `string`
**Default:** Empty

Specifies the text displayed inside the badge.

```csharp
badge.Text = "Active";
```

The control automatically recalculates its preferred size when the text changes while `AutoSize` is enabled.

---

## Font

**Type:** `Font`
**Default:** Segoe UI, 9 pt, Bold

Specifies the font used to display the badge text.

```csharp
badge.Font = new Font("Segoe UI", 10F, FontStyle.Bold);
```

Changing the font also updates the preferred size when automatic sizing is enabled.

---

## ForeColor

**Type:** `Color`
**Default:** White

Specifies the color of the badge text.

```csharp
badge.ForeColor = Color.White;
```

This property is inherited from the standard Windows Forms `Control` class.

---

## BadgeBackColor

**Type:** `Color`
**Default:** `Color.FromArgb(0, 122, 204)`
**License:** Premium

Specifies the background color of the badge.

```csharp
badge.BadgeBackColor = Color.FromArgb(40, 167, 69);
```

The property supports alpha values, allowing partially transparent backgrounds.

```csharp
badge.BadgeBackColor = Color.FromArgb(120, 0, 122, 204);
```

Set the property to `Color.Transparent` to disable the badge background fill.

> **Premium Feature:** An activated FTR Controls license is required to change this property.

---

## IsPillShape

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

Determines whether the badge is displayed as a pill-shaped capsule.

```csharp
badge.IsPillShape = true;
```

When `IsPillShape` is `true`, the control automatically uses a capsule-shaped outline based on its height.

To use a standard rounded rectangle instead:

```csharp
badge.IsPillShape = false;
```

When pill mode is disabled, the `BorderRadius` property controls the corner radius.

> **Premium Feature:** An activated FTR Controls license is required to enable this property.

---

## BorderRadius

**Type:** `int`
**Default:** `12`
**License:** Premium

Specifies the corner radius used when `IsPillShape` is disabled.

```csharp
badge.IsPillShape = false;
badge.BorderRadius = 8;
```

A value of `0` produces a rectangular shape without rounded corners.

```csharp
badge.BorderRadius = 0;
```

The control automatically limits the radius to a valid value based on its dimensions.

> **Note:** `BorderRadius` has no visible effect while `IsPillShape` is enabled.

> **Premium Feature:** An activated FTR Controls license is required to change this property.

---

## BorderColor

**Type:** `Color`
**Default:** `Color.Transparent`
**License:** Premium

Specifies the color of the badge border.

```csharp
badge.BorderColor = Color.White;
```

The border is visible only when:

* `BorderThickness` is greater than `0`, and
* `BorderColor` has a visible alpha value.

Example:

```csharp
badge.BorderColor = Color.White;
badge.BorderThickness = 1;
```

> **Premium Feature:** An activated FTR Controls license is required to change this property.

---

## BorderThickness

**Type:** `int`
**Default:** `0`
**License:** Premium

Specifies the width of the badge border in pixels.

```csharp
badge.BorderThickness = 1;
```

A value of `0` disables the border.

Negative values are automatically converted to `0`.

The border thickness is included in the preferred-size calculation when automatic sizing is enabled.

> **Premium Feature:** An activated FTR Controls license is required to change this property.

---

## TextAlign

**Type:** `ContentAlignment`
**Default:** `ContentAlignment.MiddleCenter`

Specifies the position of the text inside the badge.

Supported values include:

* `TopLeft`
* `TopCenter`
* `TopRight`
* `MiddleLeft`
* `MiddleCenter`
* `MiddleRight`
* `BottomLeft`
* `BottomCenter`
* `BottomRight`

Example:

```csharp
badge.TextAlign = ContentAlignment.MiddleCenter;
```

For most badge scenarios, `MiddleCenter` is recommended.

---

## AutoSize

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

Determines whether the control automatically adjusts its size according to its content.

```csharp
badge.AutoSize = true;
```

When enabled, the control calculates its preferred size using:

* Text
* Font
* Padding
* Border thickness
* Minimum size
* Maximum size

To manually control the control's dimensions:

```csharp
badge.AutoSize = false;
```

---

## AutoSizeMode

**Type:** `AutoSizeMode`
**Default:** `AutoSizeMode.GrowAndShrink`

Determines how the control behaves when automatic sizing is enabled.

### GrowAndShrink

The control continuously adjusts its size to match its preferred size.

```csharp
badge.AutoSize = true;
badge.AutoSizeMode = AutoSizeMode.GrowAndShrink;
```

This is the recommended mode for most badges and status indicators.

### GrowOnly

The control grows when more space is required but does not automatically shrink below its current size.

```csharp
badge.AutoSize = true;
badge.AutoSizeMode = AutoSizeMode.GrowOnly;
```

This mode is useful when a badge should be allowed to expand for longer text while preserving its existing size.

---

## Padding

**Type:** `Padding`
**Default:** `6, 4, 6, 4`

Specifies the space between the text and the edges of the badge.

The default padding is:

```text
Left:   6
Top:    4
Right:  6
Bottom: 4
```

Example:

```csharp
badge.Padding = new Padding(8, 4, 8, 4);
```

For compact badges or counters:

```csharp
badge.Padding = new Padding(8, 2, 8, 2);
```

Padding is included in the automatic size calculation.

---

## RightToLeft

**Type:** `RightToLeft`

`FTRBadgeLabel` supports the standard Windows Forms `RightToLeft` property.

Example:

```csharp
badge.RightToLeft = RightToLeft.Yes;
```

This can be used for right-to-left languages such as Arabic and Hebrew.

Text alignment can still be configured independently using `TextAlign`.

---

## BackColor

**Type:** `Color`

The control supports transparent backgrounds.

The default value is:

```csharp
Color.Transparent
```

`BackColor` controls the control's Windows Forms background, while `BadgeBackColor` controls the visible badge background.

For example:

```csharp
badge.BackColor = Color.Transparent;
```

---

# Automatic Sizing

Automatic sizing is enabled by default.

The control calculates its preferred size from the displayed text, font, padding, border thickness, minimum size, and maximum size.

Example:

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Processing",
    AutoSize = true,
    AutoSizeMode = AutoSizeMode.GrowAndShrink,
    Padding = new Padding(8, 4, 8, 4)
};
```

When the text changes, the control automatically recalculates its size:

```csharp
badge.Text = "Completed";
```

---

# Minimum and Maximum Size

The control has a default minimum size of:

```text
20 x 20 pixels
```

The preferred size cannot be smaller than the configured `MinimumSize`.

Example:

```csharp
badge.MinimumSize = new Size(40, 24);
```

If `MaximumSize` is configured, the preferred size is also limited by the specified maximum dimensions.

Example:

```csharp
badge.MaximumSize = new Size(150, 40);
```

---

# Licensing

Several appearance-related properties are premium features.

The following properties require an activated FTR Controls license:

* `IsPillShape`
* `BadgeBackColor`
* `BorderColor`
* `BorderThickness`
* `BorderRadius`

When a premium property is changed without an active license, the FTR Controls activation mechanism is invoked and the requested value is not applied.

The following properties are available without premium licensing:

* `Text`
* `Font`
* `ForeColor`
* `TextAlign`
* `AutoSize`
* `AutoSizeMode`
* `Padding`
* Standard inherited Windows Forms properties and events

> **Important:** Activate the FTR Controls license before configuring premium appearance properties.

For information about license activation, refer to the licensing documentation supplied with the FTR Controls product.

---

# Common Usage Examples

## Status Badge

```csharp
var status = new FTRBadgeLabel
{
    Text = "Active",
    BadgeBackColor = Color.FromArgb(40, 167, 69),
    IsPillShape = true,
    ForeColor = Color.White,
    Padding = new Padding(8, 4, 8, 4)
};

Controls.Add(status);
```

---

## Error Badge

```csharp
var error = new FTRBadgeLabel
{
    Text = "Error",
    BadgeBackColor = Color.FromArgb(220, 53, 69),
    IsPillShape = true
};

Controls.Add(error);
```

---

## Counter Badge

```csharp
var count = new FTRBadgeLabel
{
    Text = "99+",
    BadgeBackColor = Color.FromArgb(220, 53, 69),
    IsPillShape = true,
    Padding = new Padding(8, 2, 8, 2)
};

Controls.Add(count);
```

---

## Rounded Rectangle Badge

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Pending",
    IsPillShape = false,
    BorderRadius = 8,
    BadgeBackColor = Color.FromArgb(255, 193, 7),
    ForeColor = Color.Black
};

Controls.Add(badge);
```

---

## Badge with Border

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Verified",
    BadgeBackColor = Color.FromArgb(40, 167, 69),
    BorderColor = Color.White,
    BorderThickness = 1,
    IsPillShape = true
};

Controls.Add(badge);
```

---

## Left-Aligned Badge

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Processing",
    TextAlign = ContentAlignment.MiddleLeft,
    Padding = new Padding(10, 4, 10, 4)
};

Controls.Add(badge);
```

---

## Right-to-Left Badge

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Active",
    RightToLeft = RightToLeft.Yes,
    TextAlign = ContentAlignment.MiddleCenter
};

Controls.Add(badge);
```

---

# Using FTRBadgeLabel from the Visual Studio Toolbox

If `FTRBadgeLabel` is available in the Visual Studio Toolbox:

1. Open the Windows Forms Designer.
2. Locate `FTRBadgeLabel` in the FTR Controls section.
3. Drag the control onto the form.
4. Select the control.
5. Configure its properties in the Properties window.
6. Set the `Text` property.
7. Configure the desired appearance and sizing options.

Premium properties require an activated FTR Controls license.

---

# Events

`FTRBadgeLabel` inherits standard Windows Forms events from `Control`.

Common events include:

* `Click`
* `TextChanged`
* `Paint`

Example:

```csharp
badge.Click += (sender, e) =>
{
    MessageBox.Show("Badge clicked.");
};
```

The control uses the standard Windows Forms `Click` event and does not introduce a separate custom click event.

---

# Preferred Size

`FTRBadgeLabel` supports the standard Windows Forms `GetPreferredSize(Size)` method.

Applications can use this method to determine the size required by the badge.

Example:

```csharp
Size preferredSize = badge.GetPreferredSize(Size.Empty);
```

The preferred size takes the following into account:

* Text
* Font
* Padding
* Border thickness
* Minimum size
* Maximum size

---

# Recommended Configuration

For a typical status badge, the following configuration is recommended:

```csharp
var badge = new FTRBadgeLabel
{
    Text = "Active",
    IsPillShape = true,
    BadgeBackColor = Color.FromArgb(40, 167, 69),
    ForeColor = Color.White,
    TextAlign = ContentAlignment.MiddleCenter,
    AutoSize = true,
    AutoSizeMode = AutoSizeMode.GrowAndShrink,
    Padding = new Padding(8, 4, 8, 4)
};

Controls.Add(badge);
```

This configuration provides:

* A pill-shaped badge
* Automatic sizing
* Centered text
* Custom background color
* White text
* Balanced horizontal and vertical padding

---

# Property Reference

| Property          | Type               | Default               | License  |
| ----------------- | ------------------ | --------------------- | -------- |
| `Text`            | `string`           | Empty                 | Standard |
| `Font`            | `Font`             | Segoe UI 9 pt Bold    | Standard |
| `ForeColor`       | `Color`            | White                 | Standard |
| `BadgeBackColor`  | `Color`            | RGB(0, 122, 204)      | Premium  |
| `BorderColor`     | `Color`            | Transparent           | Premium  |
| `BorderThickness` | `int`              | 0                     | Premium  |
| `BorderRadius`    | `int`              | 12                    | Premium  |
| `IsPillShape`     | `bool`             | `true`                | Premium  |
| `TextAlign`       | `ContentAlignment` | MiddleCenter          | Standard |
| `AutoSize`        | `bool`             | `true`                | Standard |
| `AutoSizeMode`    | `AutoSizeMode`     | GrowAndShrink         | Standard |
| `Padding`         | `Padding`          | 6, 4, 6, 4            | Standard |
| `RightToLeft`     | `RightToLeft`      | Windows Forms default | Standard |

---

# Summary

`FTRBadgeLabel` is intended for compact visual elements such as:

* Status indicators
* Notification counters
* Category tags
* State labels
* Validation indicators
* Dashboard badges
* Short informational labels

For a typical implementation, configure:

* `Text` for the displayed content
* `BadgeBackColor` for the badge background
* `IsPillShape` for the overall shape
* `Padding` for internal spacing
* `TextAlign` for text positioning
* `AutoSize` and `AutoSizeMode` for sizing behavior

Premium appearance properties require an activated FTR Controls license.