# FTR Controls — License Guide

This guide is for **customers and developers** who use FTR Controls in desktop applications. For internal key generation, see `Docs/VENDOR_GUIDE.md` (vendor-only).

## License states

| State | Description |
|-------|-------------|
| **Licensed** | Valid key activated on the machine; premium features unlocked |
| **Unlicensed** | No valid license; controls remain functional with premium property restrictions |

## Activating a license

1. Run your application that references FTR Controls.
2. When prompted, open the **license activation** dialog (or call `LicenseService.Activate` from your app).
3. Enter the license key provided by your vendor.

License keys use the pipe format:

```
FTR|LicensedTo|MachineId|Signature
```

- **LicensedTo** — customer identifier  
- **MachineId** — `*` for any machine, or an 8-character machine fingerprint for locked licenses  
- **Signature** — cryptographic signature (do not modify)

## Public API

Use only `LicenseService`:

- `IsLicensed` — true when a valid license is active
- `EnsureLicensed()` — returns true when licensed; otherwise shows the activation dialog once per session
- `Activate(string key)` — activate on this machine
- `Deactivate()` — remove stored license

## Runtime behavior

- Premium properties marked with `[PremiumFeature]` or category **Premium Features** are blocked or reset when unlicensed.
- Changing a premium property without a license may open the activation dialog.
- Controls remain functional without a license; only premium customization is restricted.

## Deployment

- Ship **`FTR.UI.WinForms.dll`** (and dependencies) with your application.
- Do **not** redistribute `FTRLicenseGenerator` or private signing keys.
- Each end-user machine may need its own activation unless the key uses `*` for MachineId.

## Troubleshooting

| Issue | Action |
|-------|--------|
| Premium property does not change | Activate with a valid license key |
| Activation dialog does not appear | Call `LicenseService.EnsureLicensed()` from your app |
| Activation fails | Verify key format and machine fingerprint |

## Legal

Use of FTR Controls is subject to your purchase agreement with the vendor. Unauthorized redistribution of the assembly or license generator is prohibited.