# FTRChart
## Customer User Guide

**Product:** FTR Controls  
**Control:** `FTRChart`  
**Namespace:** `FTRControls`  
**Platform:** Windows Forms

---

## 1. Overview

`FTRChart` is a multi-series Windows Forms chart control for displaying numeric and date-based data in several chart formats.

The control supports:

- Bar
- Horizontal Bar
- Line
- Spline
- Area
- Spline Area
- Pie
- Doughnut
- Radar
- Solid Gauge

It also provides chart title, grid, legend, animation, mouse interaction, optional premium features, data-point click events, and image export.

`FTRChart` is a Windows Forms control and can be placed on a form from the **FTR Controls** Toolbox category or created programmatically.

---

## 2. Basic Usage

A chart is built from three main objects:

```text
FTRChart
   └── FTRSeries
          └── FTRDataPoint
```

- **FTRChart** is the visual chart control.
- **FTRSeries** represents one data series.
- **FTRDataPoint** represents one value within a series.

A chart can contain multiple series.

### Minimal example

```csharp
var chart = new FTRChart
{
    Title = "Revenue",
    ShowLegend = true
};

var series = new FTRSeries
{
    Name = "2026",
    Type = FTRSeriesType.SplineArea,
    Color = Color.SteelBlue
};

series.Points.Add(new FTRDataPoint(1, 120));
series.Points.Add(new FTRDataPoint(2, 180));

chart.Series.Add(series);
chart.Animate();
```

---

# 3. Adding FTRChart to a Windows Forms Application

## 3.1 Using the Toolbox

When the FTR Controls assembly is available to the project and the control is registered in the Visual Studio Toolbox:

1. Open the Windows Forms designer.
2. Locate **FTR Controls** in the Toolbox.
3. Select `FTRChart`.
4. Drag the control onto the form.
5. Configure its properties in the Properties window.

The control is a standard Windows Forms control and can also be configured entirely through code.

## 3.2 Creating the control in code

```csharp
var chart = new FTRChart();

chart.Title = "Sales";
chart.Dock = DockStyle.Fill;

Controls.Add(chart);
```

The control is initialized with a default size of **600 × 400 pixels**.

---

# 4. Working with Data

## 4.1 Creating a Series

```csharp
var series = new FTRSeries
{
    Name = "Revenue",
    Type = FTRSeriesType.Line,
    Color = Color.SteelBlue
};
```

### FTRSeries properties

| Property | Description |
|---|---|
| `Name` | Name of the series. It is displayed in the legend and used by the tooltip. |
| `Type` | Chart type used to render the series. |
| `Color` | Primary display color of the series. |
| `Points` | Collection of `FTRDataPoint` objects. |
| `Visible` | Controls whether the series is rendered. |
| `GaugeMaxValue` | Optional maximum value used by `SolidGauge`. |

A newly created series uses `Line` as its default chart type and is visible by default.

---

## 4.2 Adding Numeric Data Points

A data point can be created with an X value, Y value, optional label, and optional point color.

```csharp
series.Points.Add(
    new FTRDataPoint(1, 120, "January")
);

series.Points.Add(
    new FTRDataPoint(2, 180, "February")
);

series.Points.Add(
    new FTRDataPoint(3, 150, "March")
);
```

The values represent:

- `X` — horizontal position/category value.
- `Y` — numeric value.
- `Label` — optional display label.
- `OverrideColor` — optional color for the individual point.

---

## 4.3 Using DateTime Data

`FTRDataPoint` provides a constructor that accepts a `DateTime`.

```csharp
series.Points.Add(
    new FTRDataPoint(
        new DateTime(2026, 1, 1),
        120,
        "January"
    )
);
```

The date is internally stored using `DateTime.ToOADate()`.

When the chart detects an OLE Automation Date range on the X axis, the X-axis labels are rendered as dates.

---

## 4.4 Point-Specific Colors

A point can override its series color:

```csharp
series.Points.Add(
    new FTRDataPoint(
        1,
        120,
        "January",
        Color.Red
    )
);
```

The color is stored in `OverrideColor`.

For Pie and Doughnut charts, this value is used as the color of the corresponding slice.

---

# 5. Chart Types

`FTRSeriesType` provides the following chart types:

```text
Bar
HorizontalBar
Line
Spline
Area
SplineArea
Pie
Doughnut
Radar
SolidGauge
```

> **Licensing:** The source code checks the FTR Controls license when a series type other than `Line` is selected. If the required license is not active, the control invokes the license activation prompt and does not change the series type.

---

## 5.1 Line

A Line series connects data points with straight line segments.

```csharp
var series = new FTRSeries
{
    Name = "Sales",
    Type = FTRSeriesType.Line,
    Color = Color.SteelBlue
};
```

Use Line charts when the relationship between sequential values is important.

---

## 5.2 Spline

Spline uses a smooth curve between data points.

```csharp
series.Type = FTRSeriesType.Spline;
```

---

## 5.3 Area

Area uses line-based data with a filled region below the series.

```csharp
series.Type = FTRSeriesType.Area;
```

---

## 5.4 Spline Area

Spline Area combines a smooth curve with a filled area.

```csharp
series.Type = FTRSeriesType.SplineArea;
```

---

## 5.5 Bar

Bar displays values as vertical bars.

```csharp
series.Type = FTRSeriesType.Bar;
```

The chart calculates the bar position from the X and Y values.

---

## 5.6 Horizontal Bar

Horizontal Bar displays values horizontally.

```csharp
series.Type = FTRSeriesType.HorizontalBar;
```

Multiple visible Horizontal Bar series are arranged within each category.

---

## 5.7 Pie

Pie represents the values in a series as slices of a circle.

```csharp
var series = new FTRSeries
{
    Name = "Market Share",
    Type = FTRSeriesType.Pie
};

series.Points.Add(new FTRDataPoint(1, 30, "Product A", Color.SteelBlue));
series.Points.Add(new FTRDataPoint(2, 45, "Product B", Color.Green));
series.Points.Add(new FTRDataPoint(3, 25, "Product C", Color.Orange));
```

The slice size is calculated from each point's `Y` value relative to the sum of all `Y` values.

If the total of all point values is zero, nothing is rendered.

---

## 5.8 Doughnut

Doughnut works like Pie but displays a hole in the center.

```csharp
series.Type = FTRSeriesType.Doughnut;
```

Point-specific colors can be used to control individual slices.

---

## 5.9 Radar

Radar displays multiple values around a circular set of axes.

```csharp
var series = new FTRSeries
{
    Name = "Performance",
    Type = FTRSeriesType.Radar,
    Color = Color.SteelBlue
};

series.Points.Add(new FTRDataPoint(1, 80, "Quality"));
series.Points.Add(new FTRDataPoint(2, 65, "Speed"));
series.Points.Add(new FTRDataPoint(3, 90, "Reliability"));
series.Points.Add(new FTRDataPoint(4, 75, "Support"));
```

Radar rendering requires at least **3 points**.

When multiple visible series are used in a Radar chart, the series must contain the same number of points as the largest visible series. Otherwise, that series is not rendered by the Radar renderer.

---

## 5.10 Solid Gauge

Solid Gauge displays one or more values as circular progress rings.

```csharp
var series = new FTRSeries
{
    Name = "CPU",
    Type = FTRSeriesType.SolidGauge,
    Color = Color.Green,
    GaugeMaxValue = 100
};

series.Points.Add(
    new FTRDataPoint(1, 65, "CPU")
);
```

### Gauge maximum

The maximum value is selected in this order:

1. `GaugeMaxValue`, if specified.
2. `CustomMaxY`, if custom Y-axis mode is enabled.
3. The maximum Y value in the series.

If the resulting maximum is not positive, the control uses `100`.

Each point is displayed as a separate ring.

---

# 6. Multiple Series

A single `FTRChart` can contain multiple visible series.

```csharp
var sales = new FTRSeries
{
    Name = "Sales",
    Type = FTRSeriesType.Line,
    Color = Color.SteelBlue
};

sales.Points.Add(new FTRDataPoint(1, 4500, "Jan"));
sales.Points.Add(new FTRDataPoint(2, 8200, "Feb"));
sales.Points.Add(new FTRDataPoint(3, 6500, "Mar"));

var profit = new FTRSeries
{
    Name = "Profit",
    Type = FTRSeriesType.Spline,
    Color = Color.MediumSeaGreen
};

profit.Points.Add(new FTRDataPoint(1, 2000, "Jan"));
profit.Points.Add(new FTRDataPoint(2, 4000, "Feb"));
profit.Points.Add(new FTRDataPoint(3, 3500, "Mar"));

chart.Series.Add(sales);
chart.Series.Add(profit);
```

The Legend displays each visible series using its `Name` and `Color`.

---

# 7. Controlling Series Visibility

A series can be hidden without removing its data:

```csharp
series.Visible = false;
```

To display it again:

```csharp
series.Visible = true;
```

Hidden series are excluded from chart rendering and from the collection of visible data used for axis calculations.

---

# 8. Chart Appearance

## 8.1 Title

```csharp
chart.Title = "Monthly Revenue";
```

The title is displayed above the chart area.

The default title is:

```text
Advanced Multi-Series Chart
```

---

## 8.2 Grid

Grid lines are enabled by default.

```csharp
chart.ShowGrid = true;
```

Disable them with:

```csharp
chart.ShowGrid = false;
```

The grid color can be configured with:

```csharp
chart.GridColor = Color.LightGray;
```

The standard Cartesian grid is not drawn when a visible series uses Pie, Doughnut, Radar, or Solid Gauge rendering.

---

## 8.3 Legend

The Legend is enabled by default:

```csharp
chart.ShowLegend = true;
```

Disable it with:

```csharp
chart.ShowLegend = false;
```

Only visible series are included in the Legend.

---

## 8.4 Text Color

```csharp
chart.TextColor = Color.Black;
```

This affects chart labels and other chart text.

---

## 8.5 Line Thickness

```csharp
chart.LineThickness = 3;
```

The value is constrained to a minimum of `1`.

This setting affects line-based series.

---

# 9. Border

The chart border is enabled by default.

```csharp
chart.ShowBorder = true;
chart.BorderColor = Color.Gray;
chart.BorderThickness = 1;
```

To remove the border:

```csharp
chart.ShowBorder = false;
```

`BorderThickness` cannot be lower than `0`.

---

## 9.1 Border Radius

The rounded border radius can be configured with:

```csharp
chart.BorderRadius = 8;
```

`BorderRadius` is a Premium feature.

The value cannot be lower than `0`.

---

# 10. Animation

Animation is enabled by default.

```csharp
chart.AutoAnimate = true;
```

Disable automatic animation:

```csharp
chart.AutoAnimate = false;
```

Animation can be started manually:

```csharp
chart.Animate();
```

`Animate()` restarts the chart entrance animation.

---

# 11. Mouse Interaction

## 11.1 Zoom

Hold **Ctrl** and use the mouse wheel:

- **Ctrl + Mouse Wheel Up** — zoom in
- **Ctrl + Mouse Wheel Down** — zoom out

The internal zoom factor is limited to:

```text
0.5x – 20x
```

---

## 11.2 Pan

To pan the chart:

1. Press and hold the **right mouse button**.
2. Move the mouse.
3. Release the right mouse button.

The chart adjusts its internal offset according to the current zoom factor.

---

# 12. Tooltip

Tooltip display is controlled by:

```csharp
chart.ShowTooltip = true;
```

When the mouse is over a detected data point, the tooltip displays:

```text
Series Name | Point Label: Value
```

For example:

```text
Revenue | January: 120
```

If a point has no label, the tooltip uses its X value.

Tooltip is a **Premium Feature**. When enabling it without an active license, the control invokes the license activation prompt.

---

# 13. Crosshair

Crosshair lines can be enabled with:

```csharp
chart.ShowCrosshair = true;
```

The crosshair follows the mouse position while it is inside the chart area.

Crosshair is a **Premium Feature**.

---

# 14. Custom Y-Axis

The chart normally calculates its Y-axis range automatically.

Premium users can enable a custom range:

```csharp
chart.UseCustomYAxis = true;
chart.CustomMinY = 0;
chart.CustomMaxY = 1000;
```

When enabled, these values are used for the Y-axis range.

Both `CustomMinY` and `CustomMaxY` are Premium properties, and enabling custom Y-axis mode requires an active license.

---

# 15. Themes

The chart automatically applies the current FTR Controls theme when it is created.

The control supports the following theme modes exposed by the implementation:

- Light
- Dark
- Duotone
- Color Theme

The current theme controls chart background, grid color, text color, and border color.

The current theme can be reapplied with:

```csharp
chart.ApplyTheme();
```

---

# 16. Data Management

## 16.1 Clearing the Chart

Remove all series:

```csharp
chart.ClearData();
```

This clears the chart's series collection.

After clearing, new series can be added normally.

---

## 16.2 Updating Data

A series exposes its point collection through:

```csharp
series.Points
```

For example:

```csharp
series.Points.Clear();

series.Points.Add(new FTRDataPoint(1, 100));
series.Points.Add(new FTRDataPoint(2, 150));
series.Points.Add(new FTRDataPoint(3, 125));

chart.Animate();
```

---

# 17. Point Click Event

`FTRChart` exposes the `PointClicked` event.

```csharp
chart.PointClicked += Chart_PointClicked;
```

Example:

```csharp
private void Chart_PointClicked(
    object sender,
    FTRChart.FTRPointClickedEventArgs e)
{
    string seriesName = e.Series.Name;
    double value = e.Point.Y;
    string label = e.Point.Label;

    MessageBox.Show(
        $"{seriesName}: {label} = {value}"
    );
}
```

The event arguments provide:

| Property | Description |
|---|---|
| `Series` | The series containing the clicked point. |
| `Point` | The clicked `FTRDataPoint`. |
| `SeriesIndex` | Zero-based index of the series. |
| `PointIndex` | Zero-based index of the point within the series. |

The event is raised when the user clicks an area recognized as a data-point hit area.

---

# 18. Exporting the Chart

The rendered chart can be exported as an image:

```csharp
chart.SaveAsImage(
    @"C:\Reports\revenue.png",
    System.Drawing.Imaging.ImageFormat.Png
);
```

The method accepts:

- `filePath` — destination file path.
- `format` — `System.Drawing.Imaging.ImageFormat`.

The chart is rendered into a bitmap using its current control dimensions and then saved to the specified path.

Make sure the destination directory exists and that the application has permission to write to it.

---

# 19. Default Behavior

The following defaults are defined by the control implementation:

| Setting | Default |
|---|---|
| Control size | `600 × 400` |
| Title | `Advanced Multi-Series Chart` |
| `ShowGrid` | `true` |
| `ShowLegend` | `true` |
| `LineThickness` | `3` |
| `AutoAnimate` | `true` |
| `EnableShadow` | `true` |
| `ShowTooltip` | `true` |
| `ShowCrosshair` | `true` |
| `ShowBorder` | `true` |
| `BorderThickness` | `1` |
| `BorderRadius` | `8` |
| `UseCustomYAxis` | `false` |
| `CustomMinY` | `0` |
| `CustomMaxY` | `1000` |
| Default series type | `Line` |
| Default series visibility | `true` |

Note that Premium properties may appear with these defaults in the control but cannot necessarily be enabled or modified without an active license.

---

# 20. Premium Features

The implementation identifies the following features as Premium:

| Feature | Property |
|---|---|
| Series types other than Line | `FTRSeries.Type` |
| Shadow | `EnableShadow` |
| Tooltip | `ShowTooltip` |
| Crosshair | `ShowCrosshair` |
| Rounded border radius | `BorderRadius` |
| Custom Y-axis | `UseCustomYAxis`, `CustomMinY`, `CustomMaxY` |

When a protected feature is enabled without a valid license, the control invokes its license activation prompt.

The exact license activation procedure is not defined in the supplied `FTRChart` source/documentation and should therefore be documented separately by the product owner if required for customer delivery.

---

# 21. Complete Example

The following example creates a chart with two series and enables common display options:

```csharp
using System.Drawing;
using FTRControls;

var chart = new FTRChart
{
    Title = "Sales and Profit",
    ShowGrid = true,
    ShowLegend = true,
    AutoAnimate = true,
    LineThickness = 3
};

var sales = new FTRSeries
{
    Name = "Sales",
    Type = FTRSeriesType.SplineArea,
    Color = Color.SteelBlue
};

sales.Points.Add(new FTRDataPoint(1, 4500, "Jan"));
sales.Points.Add(new FTRDataPoint(2, 8200, "Feb"));
sales.Points.Add(new FTRDataPoint(3, 6500, "Mar"));

var profit = new FTRSeries
{
    Name = "Profit",
    Type = FTRSeriesType.Spline,
    Color = Color.MediumSeaGreen
};

profit.Points.Add(new FTRDataPoint(1, 2000, "Jan"));
profit.Points.Add(new FTRDataPoint(2, 4000, "Feb"));
profit.Points.Add(new FTRDataPoint(3, 3500, "Mar"));

chart.Series.Add(sales);
chart.Series.Add(profit);

Controls.Add(chart);

chart.Animate();
```

---

# 22. Troubleshooting

## The chart is empty

Check that:

1. At least one series has been added to `chart.Series`.
2. The series contains at least one point.
3. The series `Visible` property is `true`.
4. The control has a non-zero size.
5. The selected chart type is available under the current license.

Example:

```csharp
chart.Series.Add(series);
```

---

## A series is not displayed

Check:

```csharp
series.Visible = true;
```

Also verify that the series contains data:

```csharp
series.Points.Count > 0
```

---

## The selected chart type does not change

Chart types other than `Line` are protected by the license check in `FTRSeries.Type`.

Verify that the required FTR Controls license is active.

---

## Tooltip does not activate

Check:

```csharp
chart.ShowTooltip = true;
```

Tooltip is a Premium feature and requires an active license.

Also make sure the mouse is positioned over a data-point hit area.

---

## Crosshair does not appear

Check:

```csharp
chart.ShowCrosshair = true;
```

Crosshair is a Premium feature.

The crosshair is drawn only while the mouse is inside the chart area.

---

## Custom Y-axis values are not applied

Check:

```csharp
chart.UseCustomYAxis = true;
chart.CustomMinY = 0;
chart.CustomMaxY = 1000;
```

Custom Y-axis functionality requires an active license.

---

## Radar does not render

Check that:

- The series has at least 3 points.
- The series has the same number of points as the largest visible series when multiple Radar series are used.
- The series is visible.

---

## Pie or Doughnut is empty

The renderer uses the sum of all point Y values.

If the total is zero, the chart does not render the Pie/Doughnut.

---

## Gauge does not use the expected maximum

Set the maximum explicitly:

```csharp
series.GaugeMaxValue = 100;
```

This takes precedence over the other maximum-selection rules.

---

# 23. Quick Reference

## Main Types

```text
FTRChart
FTRSeries
FTRDataPoint
FTRSeriesType
FTRChart.FTRPointClickedEventArgs
```

## Series Types

```text
Bar
HorizontalBar
Line
Spline
Area
SplineArea
Pie
Doughnut
Radar
SolidGauge
```

## FTRChart Properties

```text
Series
Title
GridColor
TextColor
ShowGrid
ShowLegend
LineThickness
AutoAnimate
EnableShadow
ShowTooltip
ShowCrosshair
ShowBorder
BorderColor
BorderThickness
BorderRadius
UseCustomYAxis
CustomMinY
CustomMaxY
```

## FTRSeries Properties

```text
Name
Type
Color
Points
Visible
GaugeMaxValue
```

## FTRDataPoint Properties

```text
X
Y
Label
OverrideColor
XDate
```

## Methods

```text
ApplyTheme()
ClearData()
Animate()
SaveAsImage(...)
```

## Event

```text
PointClicked
```

---

# 24. Customer Usage Pattern

For most applications, the recommended usage pattern is:

```text
Create FTRChart
      ↓
Create FTRSeries
      ↓
Select FTRSeriesType
      ↓
Add FTRDataPoint objects
      ↓
Add the series to chart.Series
      ↓
Configure appearance
      ↓
Display the control
      ↓
Optionally use interaction/export features
```

Minimal pattern:

```csharp
var chart = new FTRChart
{
    Title = "My Chart"
};

var series = new FTRSeries
{
    Name = "Data",
    Type = FTRSeriesType.Line,
    Color = Color.Blue
};

series.Points.Add(new FTRDataPoint(1, 10));
series.Points.Add(new FTRDataPoint(2, 20));
series.Points.Add(new FTRDataPoint(3, 15));

chart.Series.Add(series);
```

---

# 25. Scope and Source Notes

This guide is based specifically on the supplied `FTRChart.cs` implementation and the supplied `FTRChart.md` documentation.

Where the implementation provides concrete behavior, this guide documents that behavior. Where the supplied sources do not define a customer-facing procedure—such as the exact license activation workflow, package installation procedure, assembly version, or product release information—this guide does not invent those details.

The source documentation identifies `FTRChart` as a multi-series chart control, lists its related types, properties, event, methods, and a basic example. The implementation additionally defines the complete `FTRSeriesType` list, point constructors, licensing checks, mouse interaction, theme handling, chart rendering behavior, click-event data, and image export.

**FTR Controls — FTRChart Customer User Guide**