# FTRDashboard

## Overview

`FTRDashboard` is a Windows Forms dashboard control for building multi-page application interfaces with:

* Sidebar navigation
* Multiple dashboard pages
* Active page management
* Page ordering
* Top and bottom sidebar navigation items
* Optional badges and icons
* Profile information
* Sidebar footer
* Light, Dark, Color, and Duotone themes
* Right-to-left (RTL) layout support
* Optional premium sidebar styling

The dashboard is designed to be used as a container for `FTRPage` controls.

Each `FTRPage` represents one page of the dashboard and automatically appears as a navigation item in the sidebar.

---

## Namespace and Base Type

**Namespace:** `FTRControls`

**Control:** `FTRDashboard`

**Base Type:** `FTRControls.BaseClasses.FTRBaseControl`

**Default Property:** `ActivePage`

The control is available in the Visual Studio Toolbox under the FTR Controls category.

---

# Getting Started

## 1. Add FTRDashboard to a Form

Add an `FTRDashboard` control to your Windows Forms form.

For example:

```csharp
var dashboard = new FTRDashboard
{
    Dock = DockStyle.Fill
};

form.Controls.Add(dashboard);
```

The dashboard can also be added directly from the Visual Studio Toolbox.

---

## 2. Add Dashboard Pages

Dashboard pages must be created using `FTRPage`.

Do not use a standard `Panel` when you want a page to appear in the dashboard sidebar.

Example:

```csharp
var reports = new FTRPage
{
    ItemText = "Reports",
    OrderIndex = 0
};

var settings = new FTRPage
{
    ItemText = "Settings",
    OrderIndex = 1
};

dashboard.Controls.Add(reports);
dashboard.Controls.Add(settings);
```

Each `FTRPage` can contain standard Windows Forms controls such as:

* `Label`
* `Button`
* `TextBox`
* `DataGridView`
* `Panel`
* `PictureBox`
* Other custom WinForms controls

For example:

```csharp
var reports = new FTRPage
{
    ItemText = "Reports",
    OrderIndex = 0
};

var title = new Label
{
    Text = "Reports",
    AutoSize = true,
    Location = new Point(30, 30)
};

reports.Controls.Add(title);
dashboard.Controls.Add(reports);
```

---

# FTRPage

`FTRPage` represents an individual page inside an `FTRDashboard`.

The page itself is a Windows Forms `Panel`, so it can contain any standard WinForms controls.

## FTRPage Properties

| Property       | Type     | Description                                          |
| -------------- | -------- | ---------------------------------------------------- |
| `ItemText`     | `string` | Text displayed in the sidebar                        |
| `ItemIcon`     | `Image`  | Optional icon displayed next to the sidebar item     |
| `BadgeText`    | `string` | Optional badge displayed on the sidebar item         |
| `OrderIndex`   | `int`    | Determines the page's position in the sidebar        |
| `IsBottomItem` | `bool`   | Places the page in the bottom section of the sidebar |

---

## ItemText

Defines the text displayed for the page in the sidebar.

```csharp
var page = new FTRPage
{
    ItemText = "Reports"
};
```

If `ItemText` is not changed, the default value is:

```text
New Page
```

Use short, descriptive names for navigation items.

Examples:

* Dashboard
* Reports
* Customers
* Orders
* Settings
* About

---

## ItemIcon

Defines an optional image displayed next to the page title.

```csharp
page.ItemIcon = Properties.Resources.ReportsIcon;
```

If no icon is provided, the navigation item is displayed without an icon.

The image should be suitable for use in a sidebar navigation item.

---

## BadgeText

Adds a small badge to the navigation item.

```csharp
page.BadgeText = "5";
```

This can be useful for displaying counts or status information, for example:

```text
Messages    5
Orders      12
Alerts      3
```

To remove the badge, set the property to an empty string:

```csharp
page.BadgeText = "";
```

---

## OrderIndex

Controls the display order of pages in the sidebar.

Lower values appear first.

Example:

```csharp
var dashboardPage = new FTRPage
{
    ItemText = "Dashboard",
    OrderIndex = 0
};

var reportsPage = new FTRPage
{
    ItemText = "Reports",
    OrderIndex = 1
};

var settingsPage = new FTRPage
{
    ItemText = "Settings",
    OrderIndex = 2
};
```

The resulting order is:

1. Dashboard
2. Reports
3. Settings

For predictable navigation, use unique sequential values such as `0`, `1`, `2`, `3`.

---

## IsBottomItem

When `IsBottomItem` is `true`, the page is displayed in the bottom section of the sidebar.

This is useful for pages such as:

* Settings
* Help
* About
* Logout-related navigation

Example:

```csharp
var settings = new FTRPage
{
    ItemText = "Settings",
    OrderIndex = 0,
    IsBottomItem = true
};
```

Bottom items are visually separated from the regular top navigation area.

---

# Active Page

Only one dashboard page is displayed as the active page at a time.

The active page can be selected through the `ActivePage` property.

```csharp
dashboard.ActivePage = reports;
```

The same operation can be performed using:

```csharp
dashboard.SetActivePage(reports);
```

The selected page becomes visible and the other dashboard pages are hidden.

---

## Select a Page by Text

A page can be activated using its sidebar text:

```csharp
dashboard.SetActivePageByText("Reports");
```

The text must match the page's `ItemText`.

For example:

```csharp
var reports = new FTRPage
{
    ItemText = "Reports"
};

dashboard.Controls.Add(reports);

dashboard.SetActivePageByText("Reports");
```

---

## Select a Page by Order

A page can also be activated using its `OrderIndex`:

```csharp
dashboard.SetActivePageByOrder(2);
```

This activates the page whose `OrderIndex` is `2`.

---

## Get the Current Active Page

Use `GetActivePage()` to retrieve the currently active page:

```csharp
FTRPage activePage = dashboard.GetActivePage();
```

If no page is active, the method returns `null`.

---

## Get All Pages

Use `GetAllPages()` to retrieve all dashboard pages.

The pages are returned in `OrderIndex` order.

```csharp
FTRPage[] pages = dashboard.GetAllPages();
```

Example:

```csharp
foreach (FTRPage page in dashboard.GetAllPages())
{
    Console.WriteLine(page.ItemText);
}
```

---

# Sidebar Layout

## SidebarWidth

Controls the width of the dashboard sidebar.

```csharp
dashboard.SidebarWidth = 250;
```

The supported range is:

```text
Minimum: 150
Maximum: 400
```

Values outside this range are automatically limited to the supported range.

The default width is:

```text
250
```

---

## ItemHeight

Controls the height of each sidebar navigation item.

```csharp
dashboard.ItemHeight = 45;
```

The supported range is:

```text
Minimum: 30
Maximum: 80
```

The default value is:

```text
45
```

---

# Profile Section

The dashboard can display profile information at the top of the sidebar.

## ProfileName

Sets the profile name.

```csharp
dashboard.ProfileName = "John Smith";
```

Default:

```text
Admin User
```

---

## ProfileRole

Sets the profile role or description.

```csharp
dashboard.ProfileRole = "Administrator";
```

Default:

```text
Administrator
```

---

## ProfileAvatar

Sets the profile image.

```csharp
dashboard.ProfileAvatar = Properties.Resources.UserAvatar;
```

`ProfileAvatar` is a **Premium feature**.

A valid FTR Controls license is required to assign a non-null avatar.

If the feature is not licensed, the control will request activation instead of applying the Premium setting.

---

# Footer

## FooterText

Defines the text displayed at the bottom of the sidebar.

```csharp
dashboard.FooterText = "© 2026 My Company";
```

The default value is:

```text
© 2026 FTR Studio
```

This property can be used for:

* Company name
* Copyright information
* Product name
* Application version text

Example:

```csharp
dashboard.FooterText = "© 2026 My Company";
```

---

# Themes

`FTRDashboard` supports the global FTR Controls theme system.

Available theme modes include:

* Light
* Dark
* Color
* Duotone

The dashboard applies the selected theme to its sidebar and dashboard background.

## Set the Theme

Example:

```csharp
dashboard.Theme = ThemeManager.ThemeMode.Dark;
```

Alternatively, the global theme can be changed through `ThemeManager`:

```csharp
ThemeManager.CurrentTheme = ThemeManager.ThemeMode.Dark;
```

After changing the theme, the dashboard updates its appearance accordingly.

### Available Theme Modes

```csharp
ThemeManager.ThemeMode.Light
ThemeManager.ThemeMode.Dark
ThemeManager.ThemeMode.Color
ThemeManager.ThemeMode.Duotone
```

Example:

```csharp
ThemeManager.CurrentTheme = ThemeManager.ThemeMode.Light;
```

The dashboard does not require manually setting its `BackColor` to match the selected theme.

---

# Premium Features

Some dashboard appearance features require a valid FTR Controls Premium license.

## SidebarGradientColor

`SidebarGradientColor` defines the second color used by the sidebar gradient.

Example:

```csharp
dashboard.SidebarGradientColor = Color.DarkBlue;
```

This property requires a valid Premium license.

If the dashboard is not licensed, attempting to assign a Premium value will trigger the FTR Controls activation flow and the value will not be applied.

The default value is `Color.Empty`, which means that the sidebar uses its normal theme-based solid background.

---

## Premium Feature Summary

| Feature                | Premium |
| ---------------------- | ------: |
| `SidebarGradientColor` |     Yes |
| `ProfileAvatar`        |     Yes |
| `ProfileName`          |      No |
| `ProfileRole`          |      No |
| `FooterText`           |      No |
| `SidebarWidth`         |      No |
| `ItemHeight`           |      No |
| Page management        |      No |
| Theme selection        |      No |

---

# Designer Usage

`FTRDashboard` is designed to work with the Visual Studio Windows Forms Designer.

A typical Designer workflow is:

1. Add `FTRDashboard` to the form.
2. Add one or more `FTRPage` controls to the dashboard.
3. Configure each page's sidebar properties.
4. Select the desired active page.
5. Add normal WinForms controls to each page.
6. Run the application.

The `ActivePage` property is available in the Properties window and can be used to select the page displayed by the dashboard.

---

# Designer Actions

The dashboard provides two actions intended for use in the Visual Studio Designer.

## ActionAddNewPage

`ActionAddNewPage` creates a new `FTRPage` while working in the Windows Forms Designer.

This is a **design-time action**.

It is not intended to be used as a runtime command for creating application pages.

---

## ActionRemovePage

`ActionRemovePage` removes the currently active page while working in the Windows Forms Designer.

This is also a **design-time action**.

For runtime applications, page management should normally be performed through normal application code.

---

# Runtime Navigation Example

The following example demonstrates a typical dashboard application:

```csharp
public partial class MainForm : Form
{
    private FTRDashboard dashboard;
    private FTRPage dashboardPage;
    private FTRPage reportsPage;
    private FTRPage settingsPage;

    public MainForm()
    {
        InitializeComponent();

        dashboard = new FTRDashboard
        {
            Dock = DockStyle.Fill
        };

        dashboardPage = new FTRPage
        {
            ItemText = "Dashboard",
            OrderIndex = 0
        };

        reportsPage = new FTRPage
        {
            ItemText = "Reports",
            OrderIndex = 1,
            BadgeText = "5"
        };

        settingsPage = new FTRPage
        {
            ItemText = "Settings",
            OrderIndex = 2,
            IsBottomItem = true
        };

        dashboard.Controls.Add(dashboardPage);
        dashboard.Controls.Add(reportsPage);
        dashboard.Controls.Add(settingsPage);

        dashboard.SetActivePage(dashboardPage);

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

This creates a dashboard with:

* Dashboard
* Reports with a badge
* Settings in the bottom section

The Dashboard page is displayed initially.

---

# Complete Configuration Example

The following example demonstrates the main customer-facing features together:

```csharp
var dashboard = new FTRDashboard
{
    Dock = DockStyle.Fill,
    SidebarWidth = 250,
    ItemHeight = 45,
    ProfileName = "John Smith",
    ProfileRole = "Administrator",
    FooterText = "© 2026 My Company",
    Theme = ThemeManager.ThemeMode.Dark
};

var homePage = new FTRPage
{
    ItemText = "Dashboard",
    OrderIndex = 0
};

var reportsPage = new FTRPage
{
    ItemText = "Reports",
    OrderIndex = 1,
    BadgeText = "5"
};

var settingsPage = new FTRPage
{
    ItemText = "Settings",
    OrderIndex = 2,
    IsBottomItem = true
};

dashboard.Controls.Add(homePage);
dashboard.Controls.Add(reportsPage);
dashboard.Controls.Add(settingsPage);

dashboard.SetActivePage(homePage);

form.Controls.Add(dashboard);
```

---

# Right-to-Left (RTL) Support

`FTRDashboard` supports right-to-left layouts.

Set the dashboard's `RightToLeft` property to `RightToLeft.Yes` when the application requires RTL navigation.

Example:

```csharp
dashboard.RightToLeft = RightToLeft.Yes;
```

In RTL mode:

* The sidebar is displayed on the right side.
* Sidebar text is aligned appropriately.
* Icons and badges are positioned according to the RTL layout.
* Dashboard pages inherit the RTL direction.

Example:

```csharp
var dashboard = new FTRDashboard
{
    Dock = DockStyle.Fill,
    RightToLeft = RightToLeft.Yes
};
```

For applications using inherited RTL settings, the dashboard also supports the normal WinForms `RightToLeft.Inherit` behavior.

---

# Adding Controls to a Page

Because `FTRPage` is a Windows Forms `Panel`, controls can be added directly to it.

Example:

```csharp
var reportsPage = new FTRPage
{
    ItemText = "Reports"
};

var reportsGrid = new DataGridView
{
    Dock = DockStyle.Fill
};

reportsPage.Controls.Add(reportsGrid);
dashboard.Controls.Add(reportsPage);
```

This allows each dashboard page to contain its own independent UI.

---

# Navigation Recommendations

For a consistent user experience:

* Use short and descriptive `ItemText` values.
* Use unique `OrderIndex` values.
* Use `IsBottomItem = true` for secondary navigation such as Settings or Help.
* Use `BadgeText` for counts or status indicators.
* Use icons consistently across navigation items.
* Keep the sidebar width large enough for the longest navigation label.
* Use `ActivePage` or one of the page selection methods to control navigation from application code.

---

# Important Behavior

## Pages Must Be FTRPage Controls

Only `FTRPage` controls are treated as dashboard pages.

Use:

```csharp
dashboard.Controls.Add(new FTRPage());
```

rather than:

```csharp
dashboard.Controls.Add(new Panel());
```

A normal `Panel` will not appear as a dashboard navigation item.

---

## Only One Page Is Active

When a page is activated, the dashboard makes that page visible and hides the other `FTRPage` controls.

For example:

```csharp
dashboard.SetActivePage(reportsPage);
```

After this operation, `reportsPage` is the active visible page.

---

## Theme Controls the Dashboard Background

The dashboard manages its background appearance through the selected theme.

The dashboard's `BackColor` is not intended to be manually configured through the Visual Studio Properties window.

Use the theme system instead:

```csharp
dashboard.Theme = ThemeManager.ThemeMode.Dark;
```

---

# Public API Reference

## Properties

| Property               | Type                     | Description                            | Premium |
| ---------------------- | ------------------------ | -------------------------------------- | ------: |
| `ActivePage`           | `FTRPage`                | Gets or sets the active dashboard page |      No |
| `SidebarWidth`         | `int`                    | Controls sidebar width; 150–400        |      No |
| `ItemHeight`           | `int`                    | Controls navigation item height; 30–80 |      No |
| `ProfileAvatar`        | `Image`                  | Profile image                          | **Yes** |
| `ProfileName`          | `string`                 | Profile name                           |      No |
| `ProfileRole`          | `string`                 | Profile role                           |      No |
| `FooterText`           | `string`                 | Sidebar footer text                    |      No |
| `SidebarGradientColor` | `Color`                  | Premium sidebar gradient color         | **Yes** |
| `Theme`                | `ThemeManager.ThemeMode` | Dashboard theme                        |      No |

## FTRPage Properties

| Property       | Type     | Description                                      |
| -------------- | -------- | ------------------------------------------------ |
| `ItemText`     | `string` | Sidebar navigation text                          |
| `ItemIcon`     | `Image`  | Optional sidebar icon                            |
| `BadgeText`    | `string` | Optional sidebar badge                           |
| `OrderIndex`   | `int`    | Sidebar ordering                                 |
| `IsBottomItem` | `bool`   | Places the item in the bottom navigation section |

## Methods

| Method                        | Description                                  |
| ----------------------------- | -------------------------------------------- |
| `SetActivePage(FTRPage)`      | Activates the specified page                 |
| `SetActivePageByText(string)` | Activates a page using its `ItemText`        |
| `SetActivePageByOrder(int)`   | Activates a page using its `OrderIndex`      |
| `GetActivePage()`             | Returns the currently active page            |
| `GetAllPages()`               | Returns all dashboard pages in order         |
| `ApplyTheme()`                | Applies the currently selected theme         |
| `RefreshActivePageProperty()` | Refreshes the Designer's ActivePage property |

---

# Troubleshooting

## A Page Does Not Appear in the Sidebar

Make sure the page is an `FTRPage`:

```csharp
var page = new FTRPage
{
    ItemText = "Reports"
};

dashboard.Controls.Add(page);
```

A standard `Panel` is not automatically treated as a dashboard page.

---

## A Page Is Not Displayed

Make sure the page has been added to the dashboard before activating it:

```csharp
dashboard.Controls.Add(reportsPage);
dashboard.SetActivePage(reportsPage);
```

---

## The Sidebar Width Does Not Match the Requested Value

`SidebarWidth` is limited to the range `150–400`.

Values outside this range are automatically constrained.

---

## The Item Height Does Not Match the Requested Value

`ItemHeight` is limited to the range `30–80`.

Values outside this range are automatically constrained.

---

## A Premium Property Is Not Applied

Check that a valid FTR Controls Premium license is active.

The following properties require Premium licensing:

* `ProfileAvatar`
* `SidebarGradientColor`

Without a valid license, Premium values will not be applied.

---

# Recommended Customer Workflow

For most applications, the recommended workflow is:

1. Add `FTRDashboard` to the main form.
2. Set the dashboard theme.
3. Configure the sidebar width and item height if necessary.
4. Configure the profile and footer.
5. Add `FTRPage` controls.
6. Set each page's `ItemText`.
7. Set `OrderIndex` values.
8. Add icons and badges where appropriate.
9. Mark secondary navigation items with `IsBottomItem`.
10. Add the page-specific WinForms controls.
11. Select the initial page using `ActivePage` or `SetActivePage`.
12. Use the page selection methods for runtime navigation.

---

# Minimal Example

For a simple dashboard, the following is sufficient:

```csharp
var dashboard = new FTRDashboard
{
    Dock = DockStyle.Fill
};

var home = new FTRPage
{
    ItemText = "Home",
    OrderIndex = 0
};

var settings = new FTRPage
{
    ItemText = "Settings",
    OrderIndex = 1,
    IsBottomItem = true
};

dashboard.Controls.Add(home);
dashboard.Controls.Add(settings);

dashboard.SetActivePage(home);

form.Controls.Add(dashboard);
```

This creates a basic dashboard with a Home page and a Settings page.

---

# Summary

`FTRDashboard` provides a complete navigation shell for Windows Forms applications.

Use `FTRDashboard` as the main container and `FTRPage` for individual application pages. Configure the sidebar through the page properties, use the theme system for appearance, and use the active-page methods for runtime navigation.

The main customer-facing components are:

* **FTRDashboard** — dashboard container and navigation shell
* **FTRPage** — individual dashboard page
* **ActivePage** — currently displayed page
* **Theme** — global dashboard appearance
* **Sidebar properties** — navigation layout customization
* **Profile properties** — sidebar profile information
* **FooterText** — sidebar footer
* **Premium properties** — optional advanced visual features