# FTR Controls - Documentation

> Modern Windows Forms controls with built-in licensing for .NET Framework 4.7.2 and .NET 6+ Windows.

---

## Table of Contents

1. [Overview](#overview)
2. [Why FTR Controls](#why-ftr-controls)
3. [Quick Start](#quick-start)
4. [Requirements](#requirements)
5. [Installation](#installation)
6. [Architecture & Namespaces](#architecture--namespaces)
7. [Components](#components)
8. [Design-Time Experience & Licensing](#design-time-experience--licensing)
9. [License & Activation](#license--activation)
10. [Unlicensed behavior](#unlicensed-behavior)
11. [Deployment & Redistribution](#deployment--redistribution)
12. [Support](#support)
13. [Developer FAQ](#developer-faq)

---

## Overview

FTR Controls helps Windows Forms developers build modern, professional desktop applications faster by providing high-performance UI components with an integrated licensing system.

**Per-control reference:** [controls/README.md](controls/README.md) — properties, events, examples, and premium features for each control.

The package includes 30+ controls. Highlights:

- **FTRTextBox** – Modern rounded text box with placeholder, icon, and validation
- **FTRRichTextEditor** – Rich text editor with toolbar, printing, and themes
- **FTRButton** – Owner-drawn button with Material, gradient, ripple, and badge styles
- **FTRDropDown** – Searchable dropdown with single/multi-select
- **FTRGridView** / **FTRGridViewPro** – Data grids with search, editing, and export
- **FTRChart** – Multi-series charts (line, bar, area, pie)
- **FTRDashboard** / **FTRSidebar** / **FTRTabControl** – Application shell and navigation
- **FTRRibbon** – Office-style ribbon toolbar
- **FTRCalendarPlannerControl** – Gregorian/Persian calendar with daily notes
- **FTRTokenEdit** – Tag/token input with removable chips
- **FTRMessageBox** / **ToastNotificationManager** – Styled dialogs and toast notifications
- **ThemeManager** – Global Light / Dark / Color / Duotone themes

Full index: [controls/README.md](controls/README.md)

---

## Why FTR Controls

| Problem | Solution | Result |
|--------|----------|--------|
| Default Windows Forms controls look dated | Modern rounded design, theming, and animations | Professional, polished UIs in less time |
| Building custom controls takes weeks | Ready-to-use components with full Designer support | Faster development, fewer bugs |
| License management is complex | Built-in free base and premium activation | Focus on your app, not on licensing logic |

---

## Quick Start

Get a modern text box on your form in under a minute:

```csharp
using FTRControls;

public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();

        var txt = new FTRTextBox();
        txt.Placeholder = "Enter your text...";
        txt.Dock = DockStyle.Top;
        txt.Height = 40;

        Controls.Add(txt);
    }
}
```

Or add a control from the Toolbox: drag **FTRTextBox** onto your form, set the `Placeholder` property, and run.

---

## Requirements

- **.NET Framework 4.7.2** or **.NET 6.0 Windows** (or later)
- **Windows Forms** application
- **Visual Studio 2019+** (for design-time support)

---

## Installation

### Option 1: NuGet (recommended)

1. In Visual Studio, right-click your project and select **Manage NuGet Packages**.
2. Search for **FTR.UI.WinForms**.
3. Click **Install**.
4. Controls appear in the Toolbox under the **FTR Controls** category.
5. Drag controls onto your form and configure as needed.

### Option 2: Manual reference

1. Right-click your project in Solution Explorer.
2. Select **Add** → **Reference**.
3. Click **Browse** and locate **FTR.UI.WinForms.dll** (or the appropriate assembly).
4. Add the reference and rebuild the project.
5. Open a form in Designer; controls should appear in the Toolbox. If not, right-click the Toolbox → **Choose Items** → browse to the DLL and add the controls.

---

## Architecture & Namespaces

FTR Controls ships as a Windows Forms control library focused on .NET Framework 4.7.2 and .NET 6+ Windows.

### Assemblies

- **`FTR.UI.WinForms.dll`** – main UI controls and licensing logic  
  Contains:
  - Core base classes (`FTRControls`, `FTRControls.BaseClasses`)
  - Licensing (`FTRControls.LicenseManager`)
  - Theme system (`FTRThemes.Themes`, `FTRControls.Theming`)
  - All toolbox controls, grids, charts, ribbon, dashboard, calendar, and dialogs

> Note: The NuGet package id and assembly name are **`FTR.UI.WinForms`**. XML documentation ships as **`FTR.UI.WinForms.xml`**.

### Key namespaces and controls

- `FTRControls` – most public controls (`FTRTextBox`, `FTRButton`, `FTRChart`, …)
- `FTRControls.BaseClasses` – `FTRBaseControl`
- `FTRControls.BaseClasses` – `FTRBaseUserControl`
- `FTRControls.FTRGridView` – `FTRGridViewPro`, grid columns/rows/cells
- `FTRThemes.Themes` – `ThemeManager`, `IThemeableControl`
- `FTRControls.Theming` – `FTRThemeColors`
- `FTRControls.LicenseManager` – `LicenseService`, activation dialog
- `FTRCalendarPlanner` – `NoteCardControl` (internal to calendar planner)
- `FTRDropDown` – `FTRDropDown`, `DropDownItem`
- `FTRichTextControls` – `FTRRichTextEditor`

Legacy sources such as `FTRGridView.cs` (namespace `CustomGridExample`) are **not** included in the NuGet package; use **`FTRGridViewPro`** instead.

When in doubt, let Visual Studio resolve namespaces via **Ctrl+.** (Quick Actions) after adding a control from the Toolbox.

---

## Components

### FTRTextBox

Modern text box with rounded corners, placeholder, optional icon, undo/redo, and clipboard support.

**Main Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Text` | string | Text content |
| `Placeholder` | string | Hint when empty |
| `BorderRadius` | int | Corner radius (premium) |
| `BorderColor` | Color | Border color (unfocused) |
| `FocusedBorderColor` | Color | Border color when focused (premium) |
| `BorderWidth` | float | Border thickness |
| `Icon` | Image | Optional icon (premium) |
| `IconOnLeft` | bool | Icon position (premium) |
| `PasswordChar` | char | Password mask (premium) |
| `MaxLength` | int | Maximum characters |
| `ReadOnly` | bool | Read-only mode |

**Events:** `TextChanged`, `KeyPress`, `KeyDown`, etc.

**Basic usage (Designer):**

- Drag **FTRTextBox** from the *FTR Controls* category in the Toolbox onto your form.
- In the Properties window, set `Placeholder`, `BorderRadius`, `BorderColor`, etc.
- Run the application and type into the control.

**Basic usage (Code):**

```csharp
using FTRControls;

var txt = new FTRTextBox
{
    Placeholder = "Search...",
    BorderRadius = 8,
    Dock = DockStyle.Top
};

// Optional: handle changes
txt.TextChanged += (_, _) =>
{
    // React to user input here
};

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

---

### FTRRichTextEditor

Rich text editor with formatting, links, and print support.

- Text formatting (bold, italic, color, font)
- Link support
- Printing
- Integrated with FTR license system

**Basic usage:**

- Designer: drag **FTRRichTextEditor** onto your form and set `Dock = Fill` for a full-screen editor.
- Code:

```csharp
using FTRichTextControls;

var editor = new FTRRichTextEditor
{
    Dock = DockStyle.Fill
};

this.Controls.Add(editor);

// Optional: set initial text
editor.Text = "Welcome to FTRControls...";
```

---

### FTRButton

Customizable button with themes, icons, gradients, and optional animations.

**Themes:** Flat, Material, Neumorphism, Glass, Gradient, Outline, Custom

**Main Properties:** `ButtonText`, `ButtonImage`, `BorderRadius`, `ImagePosition`, `ButtonTheme`

---

### FTRDropDown

Searchable dropdown with custom items, multi-select option, and styling.

**Basic usage (Designer):**

- Drag **FTRDropDown** from the Toolbox onto your form.
- Set the `Items` collection (or bind it in code).
- Optionally enable `MultiSelect` and configure search box properties.

**Basic usage (Code):**

```csharp
using FTRDropDown;

var dd = new FTRDropDown
{
    Dock = DockStyle.Top,
    MultiSelect = false
};

dd.Items = new List<string> { "Open", "In Progress", "Closed" };
dd.SelectedIndexChanged += (_, _) =>
{
    var value = dd.SelectedItem;
    // Handle selection
};

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

---

### FTRGridViewPro

Data grid with columns, in-cell editing, column filters (licensed), pagination, and export (licensed).

**Basic usage:**

```csharp
using FTRControls.FTRGridView;

var grid = new FTRGridViewPro
{
    Dock = DockStyle.Fill
};

grid.Columns.Add(new GridColumn { Header = "Id", Width = 60 });
grid.Columns.Add(new GridColumn { Header = "Title", Width = 200 });

var row = new GridRow();
row.Cells.Add("1");
row.Cells.Add("First item");
grid.Rows.Add(row);

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

The grid supports:

- Sorting by clicking column headers
- Searching via search row (if enabled)
- Custom drawing and styling via exposed properties

---

### FTRCalendarPlanner

Calendar control with day cells, month navigation, and optional notes.

**Basic usage:**

```csharp
using FTRCalendarPlanner;

var calendar = new CalendarPlannerControl
{
    Dock = DockStyle.Fill,
    DarkMode = false
};

// Optional: provide a note provider for persistence
calendar._NoteProvider = new MyNoteProvider();

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

Implement `ICalendarNoteProvider` to load and save notes for specific dates.

---

### NoteCardControl

Note card UI with text input and color picker, used with `FTRCalendarPlanner`.

---

### VerticalTabControl

Sidebar-style tab control with vertical tab buttons and content panels.

---

## Design-Time Experience & Licensing

FTR Controls integrates with the Windows Forms Designer for premium property editing.

- **Premium properties:** Properties in category **Premium Features** (or marked with `[PremiumFeature]`) are guarded at runtime and in the designer.
- **Activation prompts:** Changing a premium property without a license may open the activation dialog.
- **Runtime behavior:** Without a license, controls remain fully usable for basic features with default settings; premium customization is simply blocked until activation.

See [LICENSE-GUIDE.md](../LICENSE-GUIDE.md) and [GETTING-STARTED.md](GETTING-STARTED.md).

---

## License & Activation

There is **no time-limited trial mode** in the library. The core controls are **free forever**. Premium features require activation.

### Activation

- One license per customer (or per machine, if machine-locked)
- License keys are issued by the vendor
- License information is securely stored on the local machine

### Public API

Use `LicenseService`:

| Member | Description |
|--------|-------------|
| `IsLicensed` | `true` when a valid key is active on this machine |
| `EnsureLicensed()` | Shows the activation dialog if needed, then returns license state |
| `Activate(string key)` | Stores and validates a license key |
| `Deactivate()` | Removes the stored license |

### Premium features

Premium properties are listed per control under `Docs/controls/{ControlName}.md`. Example (`FTRTextBox`):

| Property | Description |
|----------|-------------|
| `BorderRadius` | Rounded corner radius |
| `FocusedBorderColor` | Border color when focused |
| `Icon` | Optional icon inside the control |
| `IconOnLeft` | Icon position (left/right) |
| `PasswordChar` | Password masking character |

Without a license, setters ignore new values and may show the activation dialog.

### Activation steps

1. Run your application (or set a premium property in the designer).
2. When the **Activate FTR Controls License** dialog appears:
   - Enter your license key and click **Activate License**, or
   - Use **Purchase now** to open the vendor purchase page.
3. After successful activation, premium properties apply normally.

You can also call `LicenseService.Activate(key)` from your own startup code.

### How to get a license key

1. Visit the vendor’s website.
2. Request a license with your contact details and Machine ID (shown in the activation dialog).
3. Enter the key in the activation form.

---

## Unlicensed behavior

- The base product is entirely free to use without a license.
- Controls keep working for basic scenarios (default property values).
- Premium property changes are blocked until activation.
- No watermark is drawn on controls at any time.

For licensing terms and pricing of premium features, contact the vendor.

---

## Deployment & Redistribution

This section summarizes how to ship applications that use FTR Controls.

- **Client deployment:**
  - Include the required FTR assemblies (e.g. `FTR.UI.WinForms.dll`) alongside your application binaries.
  - No additional Windows services or background processes are required.
- **Activation on end-user machines:**
  - License checks run on each machine where the application runs if premium features are utilized.
  - If no valid license is found, premium features stay restricted; your app can call `LicenseService.EnsureLicensed()` at startup.
- **What you must NOT deploy:**
  - Do **not** include the `FTRLicenseGenerator` tool with your product.
  - Do **not** expose internal licensing secrets or keys in your application configuration.

For complex deployment scenarios (MSI, ClickOnce, CI/CD), treat FTR assemblies like any other third‑party WinForms control library.

---

## XML Documentation & IntelliSense

Every public control in the library includes an English `/// <summary>` in source. When you build the project (or consume the NuGet package), **`FTR.UI.WinForms.xml`** is generated alongside the DLL and powers IntelliSense tooltips in Visual Studio.

**Project settings:**

- `GenerateDocumentationFile` = `true`
- Warning CS1591 (missing member comments) is suppressed so class-level summaries are sufficient; add `///` on public members as needed.

**Viewing docs:**

- Hover over a type name in code
- Use **Object Browser** (View → Object Browser)
- Open `FTR.UI.WinForms.xml` in the package or `bin` output folder

### Control reference (summary)

| Control | Summary |
|---------|---------|
| `FTRBaseControl` | Abstract base for FTR controls; theming, premium enforcement, double-buffering |
| `FTRBaseUserControl` | Base UserControl for composite controls with theme and license support |
| `FTRTextBox` | Rounded text box with placeholder, icon, validation, themes |
| `FTRRichTextEditor` | Rich text editor with toolbar, printing, themes |
| `FTRButton` | Modern button with animations, styles, SVG/gradient |
| `FTRCheckBox` | Checkbox/toggle with animations and grouping |
| `FTRRadioButton` | Radio button with ripple and themes |
| `FTRDropDown` | Searchable dropdown, single/multi-select |
| `FTRSlider` | Single-value slider |
| `FTRRangeSlider` | Dual-thumb range slider |
| `FTRNumericUpDown` | Numeric up/down input |
| `FTRRating` | Star rating control |
| `FTRProgressBar` | Linear progress bar (file: `FTRProgressBar.cs`) |
| `FTRCircularProgressBar` | Circular progress indicator |
| `FTRCard` | Card with header, footer, actions |
| `FTRChart` | Multi-series charts |
| `FTRGridView` | Classic data grid |
| `FTRGridViewPro` | Advanced grid with editing and export |
| `FTRTreeList` | Multi-column tree/list |
| `FTRTabControl` | Tabs with badges, pin, close |
| `FTRSidebar` | Vertical icon sidebar |
| `FTRDashboard` | Dashboard with sidebar pages |
| `FTRAccordion` | Collapsible accordion panels |
| `FTRBadgeLabel` | Pill/rounded status badge label |
| `FTRRibbon` | Office-style ribbon |
| `FTRCalendarPlannerControl` | Persian/Gregorian calendar with notes |
| `NoteCardControl` | Note card used inside calendar planner |
| `FTRTokenEdit` | Tag/token input with chips (`FTRTagInput.cs`) |
| `FTRMessageBox` | Custom message box API |
| `FTRToastNotification` / `ToastNotificationManager` | Toast notifications |
| `ThemeManager` | Global Light/Dark/Color/Duotone themes |
| `FTRThemeColors` | Theme-derived color palette |
| `IThemeableControl` | `ApplyTheme()` contract |

---

## Support

For licensing, activation, or technical support, contact the vendor through the website or purchase page.

---

## Developer FAQ

**Q: Which .NET versions are officially supported?**  
A: .NET Framework 4.7.2 and .NET 6.0‑windows or later. Newer LTS versions (e.g. .NET 8) are typically compatible as long as they support Windows Forms on Windows.

**Q: Are the controls thread‑safe?**  
A: Like standard WinForms controls, FTR Controls must be used from the UI thread. Do not access control members from background threads without marshaling to the UI thread (e.g. using `Control.Invoke`).

**Q: Can I deploy applications using FTR Controls to many client machines?**  
A: Yes. The base framework is free. If using premium features, you need a valid commercial license. Each client machine may need activation unless your key uses a wildcard machine id.

**Q: How are licensing errors handled?**  
A: Without a license, premium property setters are ignored and the activation dialog may appear. Controls do not throw on license failure during normal UI use and the basic features continue to function seamlessly. Call `LicenseService.EnsureLicensed()` from your app if you want a startup activation flow.

**Q: Can I use FTR Controls in open‑source projects?**  
A: Yes, the basic components are free to use. Premium features require a license. Check the license agreement or contact the vendor for details.

---

*FTR Controls v1.0.001 — Documentation*