# FTRTextBox

## Overview

`FTRTextBox` is a modern, customizable single-line text input control for Windows Forms applications.

It provides a rounded visual style, placeholder text, optional icons, password masking, text selection, undo/redo, clipboard operations, keyboard shortcuts, read-only mode, maximum text length, and integration with the FTR Controls theme system.

The control is designed to be used as a drop-in text input component in applications built with the FTR Controls library.

---

## Adding FTRTextBox to Your Application

After adding the FTR Controls assembly to your Windows Forms project, `FTRTextBox` can be added in either of the following ways:

### From the Visual Studio Toolbox

1. Open your Windows Forms project in Visual Studio.
2. Add the FTR Controls assembly to the project.
3. Make sure the FTR Controls components are available in the Toolbox.
4. Locate **FTRTextBox** under the **FTR Controls** category.
5. Drag the control onto your form.
6. Configure its properties using the Properties window.

### Programmatically

```csharp
var searchBox = new FTRTextBox
{
    Placeholder = "Search...",
    Width = 250,
    Height = 34
};

Controls.Add(searchBox);
```

---

## Basic Usage

A simple text box can be created without any additional configuration:

```csharp
var textBox = new FTRTextBox
{
    Width = 250
};

Controls.Add(textBox);
```

You can read or change the entered text through the `Text` property:

```csharp
textBox.Text = "Hello";

string value = textBox.Text;
```

---

# Properties

## Text

**Type:** `string`

Gets or sets the text contained in the control.

```csharp
textBox.Text = "John Smith";

string name = textBox.Text;
```

The `Text` property is bindable and is the default property of the control.

---

## Placeholder

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

Displays hint text when the control does not contain any text.

```csharp
textBox.Placeholder = "Enter your name";
```

The placeholder disappears automatically when the user enters text.

### Example

```csharp
var nameBox = new FTRTextBox
{
    Placeholder = "Full name",
    Width = 250
};
```

---

## MaxLength

**Type:** `int`
**Default:** `32767`

Specifies the maximum number of characters that can be entered.

```csharp
textBox.MaxLength = 100;
```

If the assigned text is longer than the configured maximum length, it is automatically limited to `MaxLength`.

Use `0` if you want to prevent text from being entered.

---

## ReadOnly

**Type:** `bool`
**Default:** `false`

Determines whether the user can modify the text.

```csharp
textBox.ReadOnly = true;
```

When `ReadOnly` is enabled, the user can still focus and view the control, but editing operations are disabled.

---

# Appearance

## BorderColor

**Type:** `Color`
**Default:** `LightGray`

Sets the border color when the control does not have focus.

```csharp
textBox.BorderColor = Color.Gray;
```

---

## FocusedBorderColor

**Type:** `Color`
**Premium:** Yes

Sets the border color when the control has focus.

```csharp
textBox.FocusedBorderColor = Color.DodgerBlue;
```

This property requires an active license for the corresponding premium functionality.

---

## BorderWidth

**Type:** `float`
**Default:** `1`

Sets the thickness of the control border.

```csharp
textBox.BorderWidth = 1.5f;
```

---

## BorderRadius

**Type:** `int`
**Default:** `6`
**Premium:** Yes

Controls the roundness of the control's corners.

```csharp
textBox.BorderRadius = 10;
```

Higher values produce more rounded corners.

This property requires an active license for the corresponding premium functionality.

---

## SearchBoxBackColor

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

Sets the background color of the text input area.

```csharp
textBox.SearchBoxBackColor = Color.WhiteSmoke;
```

> Use `SearchBoxBackColor` to customize the visible background of the text box. `BackColor` is not intended for this purpose.

---

## ForeColor

**Type:** `Color`

Sets the color of the entered text.

```csharp
textBox.ForeColor = Color.DarkSlateGray;
```

---

## SelectionBackColor

**Type:** `Color`

Sets the background color used for selected text.

```csharp
textBox.SelectionBackColor = Color.LightBlue;
```

---

## SelectionColor

**Type:** `Color`

Sets the text color of selected text.

```csharp
textBox.SelectionColor = Color.Black;
```

---

## Padding

**Type:** `Padding`

Controls the internal spacing between the border and the text/icon area.

```csharp
textBox.Padding = new Padding(12, 0, 12, 0);
```

The default padding is:

```text
Left:   10
Top:     0
Right:  10
Bottom:  0
```

---

# Icons

## Icon

**Type:** `Image`
**Premium:** Yes

Displays an optional icon inside the text box.

```csharp
textBox.Icon = Properties.Resources.SearchIcon;
```

Icons can be used for search boxes, usernames, passwords, email fields, and similar input scenarios.

This property requires an active license for the corresponding premium functionality.

---

## IconOnLeft

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

Determines whether the icon is displayed on the left or right side of the text area.

```csharp
textBox.IconOnLeft = true;
```

For example:

```csharp
var searchBox = new FTRTextBox
{
    Placeholder = "Search...",
    Icon = Properties.Resources.SearchIcon,
    IconOnLeft = true
};
```

When right-to-left layout is enabled, the control automatically takes the RTL layout into account when positioning the icon.

---

# Password Input

## PasswordChar

**Type:** `char`
**Default:** `\0`
**Premium:** Yes

Specifies the character used to mask entered text.

```csharp
passwordBox.PasswordChar = '●';
```

Example:

```csharp
var passwordBox = new FTRTextBox
{
    Placeholder = "Password",
    PasswordChar = '●',
    Width = 250
};
```

To disable password masking:

```csharp
passwordBox.PasswordChar = '\0';
```

This property requires an active license for the corresponding premium functionality.

---

# Text Editing

`FTRTextBox` supports common text-editing operations expected from a standard text input control.

Supported operations include:

* Text selection
* Select All
* Copy
* Cut
* Paste
* Delete
* Undo
* Redo
* Backspace
* Home
* End
* Left/Right cursor movement
* Ctrl + Left/Right word navigation
* Shift-based text selection

---

# Keyboard Shortcuts

The following keyboard shortcuts are supported:

| Shortcut       | Action                         |
| -------------- | ------------------------------ |
| `Ctrl + A`     | Select all text                |
| `Ctrl + C`     | Copy selected text             |
| `Ctrl + V`     | Paste text                     |
| `Ctrl + X`     | Cut selected text              |
| `Ctrl + Z`     | Undo                           |
| `Ctrl + Y`     | Redo                           |
| `Left Arrow`   | Move cursor left               |
| `Right Arrow`  | Move cursor right              |
| `Ctrl + Left`  | Move to previous word          |
| `Ctrl + Right` | Move to next word              |
| `Home`         | Move to beginning              |
| `End`          | Move to end                    |
| `Backspace`    | Delete character before cursor |
| `Delete`       | Delete character after cursor  |

---

# Context Menu

Right-clicking the control provides access to common text-editing operations.

The context menu includes:

* Undo
* Redo
* Cut
* Copy
* Paste
* Delete
* Select All

Operations that are not currently available are automatically disabled.

For example, Cut and Delete are disabled when the control is read-only or when there is no selected text.

---

# Undo and Redo

The control provides built-in undo and redo functionality.

```csharp
var textBox = new FTRTextBox();

textBox.Text = "First";
textBox.Text = "Second";
```

The user can then use:

```text
Ctrl + Z
```

to undo changes, and:

```text
Ctrl + Y
```

to redo them.

The control maintains a limited undo history.

---

# Events

## TextChanged

`TextChanged` is the default event of `FTRTextBox`.

It is raised whenever the text content changes.

Example:

```csharp
var searchBox = new FTRTextBox
{
    Placeholder = "Search..."
};

searchBox.TextChanged += (sender, e) =>
{
    string searchText = searchBox.Text;

    // Update your search results here.
};
```

### Search Example

```csharp
var searchBox = new FTRTextBox
{
    Placeholder = "Search...",
    Width = 300
};

searchBox.TextChanged += (_, _) =>
{
    FilterResults(searchBox.Text);
};

Controls.Add(searchBox);
```

---

# Standard Control Events

Because `FTRTextBox` is a Windows Forms control, it can also be used with standard control events such as:

* `KeyDown`
* `KeyPress`
* `GotFocus`
* `LostFocus`
* `MouseDown`
* `MouseMove`
* `MouseUp`
* `TextChanged`

---

# Theme Support

`FTRTextBox` integrates with the FTR Controls theme system.

The control supports the available FTR theme modes and automatically maps its background, border, focused-border, text, and selection colors to the active theme.

The theme can be applied through:

```csharp
textBox.ApplyTheme();
```

For applications that already use the FTR Controls theme system, the control can therefore be used without manually configuring every visual property.

---

# Common Examples

## Search Box

```csharp
var searchBox = new FTRTextBox
{
    Placeholder = "Search...",
    Width = 300,
    Height = 34,
    BorderRadius = 8
};

searchBox.TextChanged += (_, _) =>
{
    FilterResults(searchBox.Text);
};

Controls.Add(searchBox);
```

---

## Password Field

```csharp
var passwordBox = new FTRTextBox
{
    Placeholder = "Password",
    PasswordChar = '●',
    Width = 250
};

Controls.Add(passwordBox);
```

---

## Password Field with Icon

```csharp
var passwordBox = new FTRTextBox
{
    Placeholder = "Password",
    PasswordChar = '●',
    Icon = Properties.Resources.LockIcon,
    IconOnLeft = true,
    Width = 250
};

Controls.Add(passwordBox);
```

---

## Read-Only Field

```csharp
var accountId = new FTRTextBox
{
    Text = "ACC-10025",
    ReadOnly = true,
    Width = 200
};

Controls.Add(accountId);
```

---

## Custom Appearance

```csharp
var textBox = new FTRTextBox
{
    Placeholder = "Enter a value",
    Width = 300,
    Height = 36,
    BorderColor = Color.Gray,
    FocusedBorderColor = Color.DodgerBlue,
    BorderWidth = 1.5f,
    BorderRadius = 10,
    SearchBoxBackColor = Color.WhiteSmoke,
    ForeColor = Color.DarkSlateGray,
    Padding = new Padding(12, 0, 12, 0)
};

Controls.Add(textBox);
```

---

# Premium Features

The following properties are premium features:

| Property             | Premium |
| -------------------- | ------- |
| `BorderRadius`       | Yes     |
| `FocusedBorderColor` | Yes     |
| `Icon`               | Yes     |
| `IconOnLeft`         | Yes     |
| `PasswordChar`       | Yes     |

An active license is required to use the corresponding premium properties.

If a premium property is used without the required license, the control may display the license activation prompt and will not apply the requested value.

---

# Default Values

| Property             | Default Value  |
| -------------------- | -------------- |
| `Text`               | Empty          |
| `Placeholder`        | Empty          |
| `MaxLength`          | `32767`        |
| `ReadOnly`           | `false`        |
| `BorderColor`        | `LightGray`    |
| `BorderWidth`        | `1`            |
| `BorderRadius`       | `6`            |
| `SearchBoxBackColor` | `White`        |
| `ForeColor`          | `Black`        |
| `IconOnLeft`         | `true`         |
| `PasswordChar`       | `\0`           |
| `Height`             | `34`           |
| `Padding`            | `10, 0, 10, 0` |

---

# Important Notes

* `FTRTextBox` is a **single-line** text input control.
* Use `SearchBoxBackColor` when you want to change the visible background color.
* `BackColor` is not intended to be used for changing the control's background.
* `PasswordChar = '\0'` disables password masking.
* `ReadOnly = true` prevents editing operations while allowing the control to remain usable for displaying and selecting text.
* `MaxLength` limits the number of characters that can be entered or pasted.
* Premium properties require the appropriate license.
* The control automatically supports right-to-left layout when the Windows Forms `RightToLeft` property is configured.
* The control provides built-in clipboard, selection, undo/redo, and keyboard-editing functionality.

---

# API Summary

| Member               | Type      | Premium | Purpose                       |
| -------------------- | --------- | ------- | ----------------------------- |
| `Text`               | `string`  | No      | Gets or sets the text         |
| `Placeholder`        | `string`  | No      | Displays hint text when empty |
| `MaxLength`          | `int`     | No      | Limits text length            |
| `ReadOnly`           | `bool`    | No      | Prevents editing              |
| `BorderColor`        | `Color`   | No      | Unfocused border color        |
| `BorderWidth`        | `float`   | No      | Border thickness              |
| `SearchBoxBackColor` | `Color`   | No      | Text area background          |
| `ForeColor`          | `Color`   | No      | Text color                    |
| `SelectionBackColor` | `Color`   | No      | Selection background          |
| `SelectionColor`     | `Color`   | No      | Selected text color           |
| `Padding`            | `Padding` | No      | Internal spacing              |
| `BorderRadius`       | `int`     | Yes     | Corner radius                 |
| `FocusedBorderColor` | `Color`   | Yes     | Focused border color          |
| `Icon`               | `Image`   | Yes     | Optional icon                 |
| `IconOnLeft`         | `bool`    | Yes     | Icon position                 |
| `PasswordChar`       | `char`    | Yes     | Password masking character    |
| `ApplyTheme()`       | Method    | No      | Applies the current FTR theme |
| `TextChanged`        | Event     | No      | Raised when text changes      |

---

# See Also

* `FTRDropDown`
* `FTRTokenEdit`
* `FTRBaseControl`