# FTRRibbon

## Overview

`FTRRibbon` is a Windows Forms Ribbon control designed to provide an Office-style application toolbar with tabs, groups, command buttons, application-level actions, and tab-specific content areas.

The control supports:

* Ribbon tabs
* Ribbon groups
* Large and small command buttons
* Button icons
* Drop-down menus
* Application button
* Application button click handling
* Optional Backstage View integration
* Ribbon minimization
* Right-to-left (RTL) layouts
* DPI-aware sizing
* Theme integration
* Windows Forms Designer support
* Tab-specific content panels
* Premium features controlled by the FTR Controls license

**Namespace:** `FTRControls`

**Base type:** `FTRBasePanel` → `Panel`

---

# 1. Ribbon Structure

A typical FTR Ribbon is composed of the following elements:

```text
FTRRibbon
│
├── FTRRibbonTab
│   │
│   ├── FTRRibbonGroup
│   │   ├── FTRRibbonButton
│   │   ├── FTRRibbonButton
│   │   └── Other Windows Forms controls
│   │
│   └── FTRContentPanel
│
├── FTRRibbonTab
│   │
│   ├── FTRRibbonGroup
│   │   └── FTRRibbonButton
│   │
│   └── FTRContentPanel
│
└── ...
```

The main Ribbon is `FTRRibbon`.

Each `FTRRibbonTab` represents one Ribbon page.

Each tab can contain one or more `FTRRibbonGroup` objects.

Each group can contain command buttons and other supported Windows Forms controls.

Each tab can have an associated `FTRContentPanel` that displays the content belonging to that tab.

---

# 2. Adding FTRRibbon to a Windows Forms Application

After adding the FTR Controls assembly to your Windows Forms project:

1. Add a reference to the FTR Controls assembly.
2. Build the project.
3. Open the Windows Forms Designer.
4. Locate **FTR Controls** in the Toolbox.
5. Add `FTRRibbon` to the form.
6. Configure the Ribbon through the Properties window.

`FTRRibbon` is the primary Ribbon component exposed in the Toolbox. The child Ribbon components are intended to be composed inside the Ribbon rather than added independently from the Toolbox.

The Ribbon automatically uses:

```csharp
Dock = DockStyle.Top;
```

when it is created.

---

# 3. Creating a Ribbon Programmatically

A basic Ribbon can be created as follows:

```csharp
var ribbon = new FTRRibbon
{
    Dock = DockStyle.Top
};

var homeTab = new FTRRibbonTab
{
    TabText = "Home"
};

var clipboardGroup = new FTRRibbonGroup
{
    Title = "Clipboard"
};

var pasteButton = new FTRRibbonButton
{
    Text = "Paste",
    ItemSize = FTRRibbonButton.RibbonItemSize.Large
};

pasteButton.Click += (_, _) =>
{
    // Execute the Paste command
};

clipboardGroup.Controls.Add(pasteButton);
homeTab.Controls.Add(clipboardGroup);
ribbon.Controls.Add(homeTab);

Controls.Add(ribbon);
```

When a tab is added to the Ribbon, the control automatically manages its associated content panel.

---

# 4. FTRRibbon Properties

## Theme

**Type:** `ThemeManager.ThemeMode`

Controls the global FTR Controls theme.

The theme is shared through the FTR Controls theme manager.

Supported theme modes include:

* Light
* Dark
* Duotone
* Color

Example:

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

Theme changes are automatically propagated to FTR Controls that participate in the theme system.

---

## IsMinimized

**Type:** `bool`

**Default:** `false`

**License:** Premium

Controls whether the Ribbon is collapsed.

When minimized, the Ribbon displays only its header/tab area rather than the full group content.

```csharp
ribbon.IsMinimized = true;
```

To restore the full Ribbon:

```csharp
ribbon.IsMinimized = false;
```

## Selecting a tab while the Ribbon is minimized automatically expands the Ribbon.

## ShowApplicationButton

**Type:** `bool`

**Default:** `true`

Determines whether the Application Button is displayed.

```csharp
ribbon.ShowApplicationButton = true;
```

To hide it:

```csharp
ribbon.ShowApplicationButton = false;
```

When the Application Button is hidden, any currently displayed Backstage View is also closed.

---

## ApplicationButtonText

**Type:** `string`

**Default:** `"File"`

Specifies the text displayed inside the Application Button.

Example:

```csharp
ribbon.ApplicationButtonText = "File";
```

You can customize this according to the application, for example:

```csharp
ribbon.ApplicationButtonText = "Menu";
```

---

## ApplicationButtonColor

**Type:** `Color`

Specifies the background color of the Application Button.

Example:

```csharp
ribbon.ApplicationButtonColor = Color.DarkBlue;
```

---

## BackstageView

Associates an Office-style Backstage View with the Application Button.

When the Application Button is clicked, the Ribbon displays the configured `BackstageView` if one is available.

Example:

```csharp
ribbon.BackstageView = myBackstageView;
```

If no Backstage View is configured but an application menu is available, the Ribbon can display the application menu instead.

---

# 5. Application Button

The Application Button can be used for application-level commands such as:

* New
* Open
* Save
* Save As
* Print
* Settings
* Exit

The button is enabled by default.

Example:

```csharp
ribbon.ShowApplicationButton = true;
ribbon.ApplicationButtonText = "File";
ribbon.ApplicationButtonColor = Color.DarkBlue;
```

---

## ApplicationButtonClick

Raised when the user clicks the Application Button.

Example:

```csharp
ribbon.ApplicationButtonClick += (_, _) =>
{
    // Handle application-level action
};
```

The event is raised before the configured Backstage View or application menu is displayed.

---

# 6. FTRRibbonTab

`FTRRibbonTab` represents one page of the Ribbon.

## TabText

**Type:** `string`

Specifies the text displayed in the Ribbon tab header.

Example:

```csharp
var homeTab = new FTRRibbonTab
{
    TabText = "Home"
};
```

Another example:

```csharp
var reportsTab = new FTRRibbonTab
{
    TabText = "Reports"
};
```

---

## ContentPanel

**Type:** `FTRContentPanel`

Specifies the content area associated with the tab.

Example:

```csharp
homeTab.ContentPanel = homeContentPanel;
```

The content panel is automatically synchronized with the active Ribbon tab. When the user switches tabs, the corresponding content panel becomes visible.

---

# 7. Working with Content Panels

`FTRContentPanel` is the main content area associated with a Ribbon tab.

It is designed to host the application's actual page or document controls.

For example:

```text
Home Tab
    └── Home Content Panel
        ├── Dashboard
        ├── Recent Files
        └── Quick Actions

Reports Tab
    └── Reports Content Panel
        ├── Report List
        ├── Filters
        └── Report Viewer
```

`FTRContentPanel` uses:

```csharp
Dock = DockStyle.Fill;
```

by default.

Example:

```csharp
var contentPanel = new FTRContentPanel();

var homeTab = new FTRRibbonTab
{
    TabText = "Home",
    ContentPanel = contentPanel
};
```

The Ribbon manages visibility so that the content belonging to the active tab is shown while the other tab content panels are hidden.

---

# 8. FTRRibbonGroup

`FTRRibbonGroup` visually groups related commands.

Example:

```csharp
var clipboardGroup = new FTRRibbonGroup
{
    Title = "Clipboard"
};
```

A group can contain buttons and other controls.

```csharp
clipboardGroup.Controls.Add(pasteButton);
clipboardGroup.Controls.Add(copyButton);
```

Groups are arranged horizontally inside a Ribbon tab in left-to-right layouts and are automatically arranged for RTL layouts.

---

## Title

**Type:** `string`

Specifies the group caption.

Example:

```csharp
group.Title = "Editing";
```

---

## ItemsPerRow

**Type:** `int`

**Default:** `3`

**License:** Premium

Controls how many items are arranged per row inside the group.

Example:

```csharp
group.ItemsPerRow = 2;
```

The value is automatically limited to a minimum of `1`.

---

# 9. FTRRibbonButton

`FTRRibbonButton` is the primary command control used inside a Ribbon group.

It supports:

* Text
* Icons
* Large and small layouts
* Drop-down menus
* Normal, hover, and pressed visual states
* Standard Windows Forms `Click` event

The control is intended to be placed inside an `FTRRibbonGroup`.

---

## Text

Uses the standard Windows Forms `Text` property.

Example:

```csharp
var saveButton = new FTRRibbonButton
{
    Text = "Save"
};
```

---

## Icon

Specifies the image displayed by the button.

Example:

```csharp
var saveButton = new FTRRibbonButton
{
    Text = "Save",
    Icon = saveIcon
};
```

---

## ItemSize

**Type:** `FTRRibbonButton.RibbonItemSize`

Supported values:

```text
Large
Small
```

### Large

Large buttons display the icon above the text.

```csharp
button.ItemSize = FTRRibbonButton.RibbonItemSize.Large;
```

### Small

Small buttons use a more compact horizontal layout.

```csharp
button.ItemSize = FTRRibbonButton.RibbonItemSize.Small;
```

The button automatically calculates an appropriate size based on its text, icon, icon size, and whether a drop-down menu is assigned.

---

## IconSize

**Type:** `Size`

Controls the displayed icon dimensions.

Example:

```csharp
button.IconSize = new Size(32, 32);
```

The default icon size is DPI-scaled from a base size of approximately `32 × 32` pixels.

---

## DropDownMenu

Associates a context menu with the Ribbon button.

Example:

```csharp
var menu = new ContextMenuStrip();

menu.Items.Add("Option 1");
menu.Items.Add("Option 2");

var button = new FTRRibbonButton
{
    Text = "Options",
    DropDownMenu = menu
};
```

When a drop-down menu is assigned, the button reserves space for and displays a drop-down indicator.

---

## Click

`FTRRibbonButton` uses the standard Windows Forms `Click` event.

Example:

```csharp
saveButton.Click += (_, _) =>
{
    SaveDocument();
};
```

This is the recommended way to connect a Ribbon button to application functionality.

---

## ItemSizeChanged

Raised when the button's `ItemSize` changes.

Example:

```csharp
button.ItemSizeChanged += (_, _) =>
{
    // React to button layout changes
};
```

---

# 10. Adding Common Commands

A typical Ribbon group might look like this:

```csharp
var fileGroup = new FTRRibbonGroup
{
    Title = "File"
};

var newButton = new FTRRibbonButton
{
    Text = "New",
    ItemSize = FTRRibbonButton.RibbonItemSize.Large
};

var openButton = new FTRRibbonButton
{
    Text = "Open",
    ItemSize = FTRRibbonButton.RibbonItemSize.Large
};

var saveButton = new FTRRibbonButton
{
    Text = "Save",
    ItemSize = FTRRibbonButton.RibbonItemSize.Large
};

newButton.Click += (_, _) => CreateNewDocument();
openButton.Click += (_, _) => OpenDocument();
saveButton.Click += (_, _) => SaveDocument();

fileGroup.Controls.Add(newButton);
fileGroup.Controls.Add(openButton);
fileGroup.Controls.Add(saveButton);
```

---

# 11. Selecting Tabs Programmatically

The Ribbon provides a `SelectTab()` method for selecting a tab from application code.

Example:

```csharp
ribbon.SelectTab(reportsTab);
```

This makes the specified tab active and updates the associated content panel.

A common use case is navigating to a specific section after an application action:

```csharp
private void OpenReports()
{
    ribbon.SelectTab(reportsTab);
}
```

---

# 12. Right-to-Left (RTL) Support

The Ribbon supports Windows Forms RTL layouts.

Example:

```csharp
ribbon.RightToLeft = RightToLeft.Yes;
```

RTL mode affects:

* Application Button placement
* Tab ordering
* Group positioning
* Ribbon layout direction
* Content layout behavior

The Ribbon automatically recalculates its layout when the `RightToLeft` property changes.

This makes the control suitable for applications targeting languages such as Arabic and Hebrew.

---

# 13. DPI Awareness

The Ribbon automatically scales its internal dimensions according to the display DPI.

This includes:

* Ribbon header dimensions
* Button dimensions
* Icon sizes
* Spacing
* Minimum sizes
* Application Button dimensions

Applications do not normally need to perform manual scaling for the Ribbon.

---

# 14. Theme Support

FTRRibbon participates in the FTR Controls theme system.

When the global FTR theme changes, the Ribbon automatically refreshes its appearance.

The same theme system is used by the Ribbon's child components and content panels.

If required, the control also exposes:

```csharp
ribbon.ApplyTheme();
```

Use this when your application needs to explicitly refresh the Ribbon's theme-dependent appearance.

---

# 15. Visual Studio Designer Support

FTRRibbon is designed to work with the Windows Forms Designer.

The recommended workflow is:

1. Add `FTRRibbon` to the form.
2. Add Ribbon tabs.
3. Configure each tab's `TabText`.
4. Add groups to each tab.
5. Add buttons to each group.
6. Configure button text, icons, and sizes.
7. Configure the associated content panel.
8. Add application commands through button events.

The Ribbon also provides designer actions for common operations such as:

* Add New Tab
* Remove Current Tab
* Add New Group to Active Tab
* Switch to Next Tab

These actions are intended for Visual Studio Designer usage and are not application runtime commands.

---

# 16. Designer Actions

The following properties are available for designer convenience:

| Property            | Purpose                                             |
| ------------------- | --------------------------------------------------- |
| `ActionAddNewTab`   | Adds a new Ribbon tab in the Windows Forms Designer |
| `ActionRemoveTab`   | Removes the current tab in the Designer             |
| `ActionAddNewGroup` | Adds a group to the active tab                      |
| `ActionSwitchTab`   | Switches the active Designer tab                    |

These properties are intended for design-time use.

Applications should normally configure Ribbon structure directly through the Designer or normal application code rather than setting these action properties at runtime.

---

# 17. Licensing

FTRRibbon contains both standard and premium functionality.

## Standard functionality

The standard Ribbon functionality includes:

* Ribbon itself
* Tabs within the free limit
* Groups
* Buttons
* Application Button
* Themes
* RTL support
* DPI-aware layout
* Content panels

## Premium functionality

The following features require an active FTR Controls license:

* More than 3 Ribbon tabs
* Ribbon minimized mode (`IsMinimized`)
* Custom `ItemsPerRow` configuration

The source implementation allows up to **3 tabs without a license**. A licensed application is not subject to this tab-count restriction.

When a fourth tab is added without a valid license, the Ribbon prevents that tab from being added.

### Example

A non-licensed application can use:

```text
Tab 1
Tab 2
Tab 3
```

but cannot add:

```text
Tab 4
```

An active license removes this three-tab limitation.

---

# 18. Recommended Application Layout

For a typical business application, the following structure is recommended:

```text
Main Form
│
├── FTRRibbon
│   │
│   ├── Home
│   │   ├── Clipboard
│   │   ├── Editing
│   │   └── View
│   │
│   ├── Reports
│   │   ├── Reports
│   │   └── Export
│   │
│   └── Settings
│       ├── Preferences
│       └── Security
│
└── Active FTRContentPanel
```

Each Ribbon tab should represent a meaningful functional area of the application.

Groups should contain commands that are logically related.

---

# 19. Complete Example

The following example demonstrates a practical Ribbon configuration:

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

public partial class MainForm : Form
{
    private FTRRibbon ribbon;

    private FTRRibbonTab homeTab;
    private FTRRibbonTab reportsTab;

    public MainForm()
    {
        InitializeComponent();
        CreateRibbon();
    }

    private void CreateRibbon()
    {
        ribbon = new FTRRibbon
        {
            Dock = DockStyle.Top,
            ShowApplicationButton = true,
            ApplicationButtonText = "File",
            ApplicationButtonColor = Color.DarkBlue
        };

        // -------------------------
        // Home tab
        // -------------------------

        homeTab = new FTRRibbonTab
        {
            TabText = "Home"
        };

        var editingGroup = new FTRRibbonGroup
        {
            Title = "Editing"
        };

        var newButton = new FTRRibbonButton
        {
            Text = "New",
            ItemSize = FTRRibbonButton.RibbonItemSize.Large
        };

        var saveButton = new FTRRibbonButton
        {
            Text = "Save",
            ItemSize = FTRRibbonButton.RibbonItemSize.Large
        };

        newButton.Click += (_, _) =>
        {
            CreateNewDocument();
        };

        saveButton.Click += (_, _) =>
        {
            SaveDocument();
        };

        editingGroup.Controls.Add(newButton);
        editingGroup.Controls.Add(saveButton);

        homeTab.Controls.Add(editingGroup);

        // -------------------------
        // Reports tab
        // -------------------------

        reportsTab = new FTRRibbonTab
        {
            TabText = "Reports"
        };

        var reportsGroup = new FTRRibbonGroup
        {
            Title = "Reports"
        };

        var openReportButton = new FTRRibbonButton
        {
            Text = "Open Report",
            ItemSize = FTRRibbonButton.RibbonItemSize.Large
        };

        openReportButton.Click += (_, _) =>
        {
            OpenReport();
        };

        reportsGroup.Controls.Add(openReportButton);
        reportsTab.Controls.Add(reportsGroup);

        // Add tabs to Ribbon
        ribbon.Controls.Add(homeTab);
        ribbon.Controls.Add(reportsTab);

        // Add Ribbon to form
        Controls.Add(ribbon);
    }

    private void CreateNewDocument()
    {
        // Application-specific implementation
    }

    private void SaveDocument()
    {
        // Application-specific implementation
    }

    private void OpenReport()
    {
        ribbon.SelectTab(reportsTab);
    }
}
```

---

# 20. Using RTL

For an Arabic or Hebrew application:

```csharp
ribbon.RightToLeft = RightToLeft.Yes;
```

The Ribbon automatically adjusts its layout direction.

No separate Ribbon-specific layout code is required.

---

# 21. Using a Readable Application Button

A common configuration is:

```csharp
ribbon.ShowApplicationButton = true;
ribbon.ApplicationButtonText = "File";
ribbon.ApplicationButtonColor = Color.DarkBlue;

ribbon.ApplicationButtonClick += (_, _) =>
{
    // Optional custom application-level behavior
};
```

If a Backstage View is assigned, it can be displayed automatically when the user clicks the Application Button.

---

# 22. Common Configuration Examples

## Standard Ribbon

```csharp
var ribbon = new FTRRibbon();
```

## Hidden Application Button

```csharp
ribbon.ShowApplicationButton = false;
```

## Minimized Ribbon

```csharp
ribbon.IsMinimized = true;
```

## Two-column group layout

```csharp
group.ItemsPerRow = 2;
```

## RTL Ribbon

```csharp
ribbon.RightToLeft = RightToLeft.Yes;
```

## Select a tab

```csharp
ribbon.SelectTab(reportsTab);
```

---

# 23. Property Summary

## FTRRibbon

| Property                 | Type               | Default / Behavior        | License                         |
| ------------------------ | ------------------ | ------------------------- | ------------------------------- |
| `Theme`                  | `ThemeMode`        | Global theme              | No                              |
| `IsMinimized`            | `bool`             | `false`                   | Premium                         |
| `ShowApplicationButton`  | `bool`             | `true`                    | No                              |
| `ApplicationButtonText`  | `string`           | `"File"`                  | No                              |
| `ApplicationButtonColor` | `Color`            | Theme/application default | No                              |
| `BackstageView`          | `FTRBackstageView` | `null`                    | Depends on associated component |
| `ActionAddNewTab`        | `bool`             | Design-time action        | No                              |
| `ActionRemoveTab`        | `bool`             | Design-time action        | No                              |
| `ActionAddNewGroup`      | `bool`             | Design-time action        | No                              |
| `ActionSwitchTab`        | `bool`             | Design-time action        | No                              |

## FTRRibbonTab

| Property       | Type              | Purpose                              |
| -------------- | ----------------- | ------------------------------------ |
| `TabText`      | `string`          | Tab header text                      |
| `ContentPanel` | `FTRContentPanel` | Content area associated with the tab |

## FTRRibbonGroup

| Property      | Type     |   Default | License |
| ------------- | -------- | --------: | ------- |
| `Title`       | `string` | `"Group"` | No      |
| `ItemsPerRow` | `int`    |       `3` | Premium |

## FTRRibbonButton

| Property / Event  | Type               | Purpose                              |
| ----------------- | ------------------ | ------------------------------------ |
| `Text`            | `string`           | Button caption                       |
| `Icon`            | `Image`            | Button image                         |
| `ItemSize`        | `RibbonItemSize`   | Large or Small layout                |
| `IconSize`        | `Size`             | Icon dimensions                      |
| `DropDownMenu`    | `ContextMenuStrip` | Optional drop-down menu              |
| `Click`           | Event              | Executes the button command          |
| `ItemSizeChanged` | Event              | Raised when button size mode changes |

## FTRContentPanel

| Property    | Type           | Purpose                                        |
| ----------- | -------------- | ---------------------------------------------- |
| `RibbonTab` | `FTRRibbonTab` | Associates the content panel with a Ribbon tab |
| `Theme`     | `ThemeMode`    | Uses the global FTR theme                      |

---

# 24. Events Summary

| Event                    | Component         | Description                                    |
| ------------------------ | ----------------- | ---------------------------------------------- |
| `ApplicationButtonClick` | `FTRRibbon`       | Raised when the Application Button is clicked  |
| `Click`                  | `FTRRibbonButton` | Raised when a Ribbon command button is clicked |
| `ItemSizeChanged`        | `FTRRibbonButton` | Raised when the button's size mode changes     |

---

# 25. Best Practices

### Keep tabs functional

Use tabs for major application areas such as:

* Home
* Reports
* Data
* Settings

### Keep groups focused

A group should contain related commands.

For example:

```text
Clipboard
    Copy
    Paste
    Cut
```

rather than mixing unrelated commands.

### Use Large buttons for primary commands

Large buttons work well for frequently used actions.

```csharp
button.ItemSize = FTRRibbonButton.RibbonItemSize.Large;
```

Use Small buttons when space is limited or when the command is secondary.

### Use icons consistently

Use icons with consistent dimensions and visual style.

### Use ContentPanel for tab-specific application content

Avoid placing unrelated page content directly inside the Ribbon. The Ribbon should provide commands, while the associated `FTRContentPanel` should host the application's main content.

### Avoid design-time action properties in application logic

Properties such as `ActionAddNewTab` and `ActionAddNewGroup` are intended to assist with Visual Studio Designer operations, not to implement application behavior.

---

# 26. Important Notes

* `FTRRibbon` is the main Toolbox control.
* `FTRRibbonTab`, `FTRRibbonGroup`, and `FTRRibbonButton` are intended to be composed inside the Ribbon rather than used as standalone Toolbox controls.
* Each Ribbon tab can have an associated `FTRContentPanel`.
* The Ribbon automatically manages which content panel is visible for the active tab.
* The default Ribbon height is approximately 150 DPI-scaled pixels when expanded and approximately 35 DPI-scaled pixels when minimized.
* A non-licensed application is limited to three Ribbon tabs.
* A licensed application can use more than three tabs.
* `IsMinimized` is a premium feature.
* `ItemsPerRow` is a premium feature.
* The Ribbon automatically supports RTL layout.
* The Ribbon automatically scales its UI according to display DPI.
* Theme changes are integrated with the FTR Controls theme system.
* `ApplicationButtonClick` can be used for application-level actions.
* `FTRRibbonButton.Click` should normally be used to connect Ribbon commands to application functionality.

---

# 27. See Also

* FTR Controls Theme Manager documentation
* FTR Backstage View documentation
* FTR Controls Licensing documentation