# Custom Tabs and Commands

> Add RibbonTab, RibbonGroup and RibbonButton controls in Windows Forms, use ResourceProvider icons, fill the application menu and the Quick Access Toolbar.

- **Product:** TX Text Control .NET for Windows Forms
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for Windows Forms > Document Editor > Ribbon and UI > Custom Tabs and Commands
- **3842 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/custom-tabs/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/custom-tabs/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/custom-tabs/llms-full.txt

---

Your application's own commands, such as saving to a document management system or starting an approval, belong in the same ribbon as the formatting commands of TX Text Control. The classes the predefined tabs are built from are public, so you add tabs, groups and buttons of your own in the designer or in code, and give them the icons and tool tips of the built-in items with the `ResourceProvider`.

How the predefined tabs are organized, and how to change or remove their items, is described in [Built-in Ribbon Tabs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/ribbon/llms-full.txt).

### The Building Blocks

All classes are in the namespace `TXTextControl.Windows.Forms.Ribbon`. A [RibbonTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontab/llms-full.txt) holds groups in its [RibbonGroups](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontab/ribbongroups-property/llms-full.txt) collection, and a group holds items in its [RibbonItems](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbongroup/ribbonitems-property/llms-full.txt) collection:

| Class | What it is |
|---|---|
| [RibbonGroup](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbongroup/llms-full.txt) | A group that arranges its items in columns, with a title and an optional dialog box launcher |
| [HorizontalRibbonGroup](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/horizontalribbongroup/llms-full.txt) | A group that arranges its items in rows, like the Font group of the Home tab |
| [RibbonButton](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonbutton/llms-full.txt) | A button with a large or small icon and a text |
| [RibbonToggleButton](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontogglebutton/llms-full.txt) | A button that stays checked, with [Checked](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontogglebutton/checked-property/llms-full.txt) and a `CheckedChanged` event |
| [RibbonMenuButton](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonmenubutton/llms-full.txt) | A button that opens a drop-down menu of the items in [DropDownItems](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonmenubutton/dropdownitems-property/llms-full.txt) |
| [RibbonSplitButton](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonsplitbutton/llms-full.txt) | A button with a primary part that runs a command and a part that opens a drop-down menu |
| [RibbonComboBox](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribboncombobox/llms-full.txt), [RibbonTextBox](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontextbox/llms-full.txt), [RibbonLabel](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonlabel/llms-full.txt) | A combo box, a text box with optional up and down buttons, and a label |
| [RibbonListView](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonlistview/llms-full.txt) | A gallery of items, like the style gallery of the Home tab |
| [RibbonSeperator](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonseperator/llms-full.txt) | A separator in a `HorizontalRibbonGroup`, the application menu or a drop-down menu; a `RibbonGroup` does not accept it |

All of them are Windows Forms controls, so they have the usual `Name`, `Visible`, `Enabled` and `Click` members. The diagram shows the classes with their properties and how they are nested; the version in parentheses is the one each member was introduced in:

![The class diagram of the TXTextControl.Windows.Forms.Ribbon namespace: RibbonForm, Ribbon, the contextual tab groups, RibbonTab and the predefined tabs, RibbonGroup, and the button, list view, text box, label, combo box and separator classes.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/ribbon-class-diagram.cda545e9.webp)

### Add a Tab in the Designer

1. Select the ribbon by clicking its **File** tab title, open the smart tag and click **Add a RibbonTab**.
2. Set the tab's `Text` property, which is the tab title, in the **Properties** window.
3. Find **RibbonGroups** in the **Properties** window of the tab and click its ellipsis button. Add a group in the collection editor and set its `Text`.
4. In the properties of the group, click the ellipsis button of **RibbonItems** and add buttons and other items.
5. Handle the `Click` event of each button in the code of the form.

### Add a Tab in Code

Code is the better choice when the commands depend on the user or on settings. The following code, in the constructor of the form after `InitializeComponent`, adds a **Review** tab with an **Output** group, a print button with the built-in print icon, a toggle button that makes the document read-only and a drop-down menu that exports a PDF file:

```csharp
using TXTextControl;
using TXTextControl.Windows.Forms;
using TXTextControl.Windows.Forms.Ribbon;

// Create the tab and a group without a dialog box launcher
RibbonTab reviewTab = new RibbonTab() { Text = "Review" };
RibbonGroup outputGroup = new RibbonGroup() { Text = "Output" };
outputGroup.DialogBoxLauncher.Visible = false;
reviewTab.RibbonGroups.Add(outputGroup);

// A print button that looks like the built-in one
string print = ResourceProvider.FileMenuItem.TXITEM_Print.ToString();
RibbonButton printButton = new RibbonButton()
{
    Text = ResourceProvider.GetText(print),
    LargeIcon = ResourceProvider.GetLargeIcon(print, this),
    SmallIcon = ResourceProvider.GetSmallIcon(print, this),
    DisplayMode = IconTextRelation.LargeIconLabeled,
    KeyTip = "P",
    IsAddToQuickAccessToolbarEnabled = true
};
printButton.ToolTip.Title = ResourceProvider.GetToolTipTitle(print);
printButton.ToolTip.Description = ResourceProvider.GetToolTipDescription(print);
printButton.Click += (sender, e) => textControl1.Print("My Document");
outputGroup.RibbonItems.Add(printButton);

// A toggle button that switches the document to read-only
RibbonToggleButton readOnlyButton = new RibbonToggleButton()
{
    Text = "Read Only",
    DisplayMode = IconTextRelation.SmallIconLabeled
};
readOnlyButton.CheckedChanged += (sender, e) => textControl1.EditMode =
    readOnlyButton.Checked ? EditMode.ReadAndSelect : EditMode.Edit;
outputGroup.RibbonItems.Add(readOnlyButton);

// A menu button with one entry
RibbonMenuButton exportButton = new RibbonMenuButton() { Text = "Export" };
RibbonButton pdfItem = new RibbonButton() { Text = "PDF" };
pdfItem.Click += (sender, e) => textControl1.Save("document.pdf", StreamType.AdobePDF);
exportButton.DropDownItems.Add(pdfItem);
outputGroup.RibbonItems.Add(exportButton);

// Show the tab and select it
ribbon1.Controls.Add(reviewTab);
ribbon1.SelectedTab = reviewTab;
```

The code works as follows:

- [DialogBoxLauncher](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbongroup/dialogboxlauncher-property/llms-full.txt) is the small button in the footer of a group. Hide it when the group has no dialog to open, or handle its [Click](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/dialogboxlauncher/click-event/llms-full.txt) event to open one.
- [ResourceProvider](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms/resourceprovider/llms-full.txt) returns the text, the icons, the key tip and the tool tip of a built-in item for an identifier string. [ResourceProvider.FileMenuItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms/resourceprovider/filemenuitem-enumeration/llms-full.txt) lists items of the application menu such as print, open and save; the `RibbonItem` values of the predefined tabs work as well, for example `RibbonInsertTab.RibbonItem.TXITEM_InsertHyperlink.ToString()`. [GetLargeIcon](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms/resourceprovider/getlargeicon-method/llms-full.txt) and [GetSmallIcon](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms/resourceprovider/getsmallicon-method/llms-full.txt) take the form so that the icon is drawn for its resolution.
- [DisplayMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonbutton/displaymode-property/llms-full.txt) takes an [IconTextRelation](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/icontextrelation/enumeration/llms-full.txt) value: `LargeIconLabeled`, `SmallIconLabeled`, `SmallIconUnlabeled` or `NoIconLabeled`.
- [KeyTip](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonbutton/keytip-property/llms-full.txt) sets the keyboard shortcut of the button. [ToolTip](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonbutton/tooltip-property/llms-full.txt) is a [RibbonToolTip](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbontooltip/llms-full.txt) with a title and a description.
- [EditMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/editmode-property/llms-full.txt) and [Save](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/save-method/llms-full.txt) are members of the `TextControl` named `textControl1` on the form; any code of your application can go into the handlers.

### Add a Group to a Predefined Tab

A predefined tab is a `RibbonTab` too, so its `RibbonGroups` collection takes your groups. [Insert](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbongroupcollection/insert-method/llms-full.txt) places a group at a position, here before the **Clipboard** group of the Home tab:

```csharp
// Put a group of your own at the start of the Home tab
RibbonGroup companyGroup = new RibbonGroup() { Text = "Company" };
companyGroup.DialogBoxLauncher.Visible = false;
ribbonFormattingTab1.RibbonGroups.Insert(0, companyGroup);
```

In the same way, `FindItem` returns a predefined group, and its `RibbonItems` collection takes buttons of your own.

### Fill the Application Menu

The **File** tab is the application menu when [HasApplicationMenu](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbon/hasapplicationmenu-property/llms-full.txt) is `true`. Its commands are yours to add: the TX Words sample adds **New**, **Open**, **Save**, **Save As**, **Print**, **Document Settings**, **About** and **Exit** in the collection editor of [ApplicationMenuItems](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbon/applicationmenuitems-property/llms-full.txt):

![The Control Collection Editor of the ribbon's ApplicationMenuItems with the buttons m_rbtnNew to m_rbtnExit and a separator, and the properties of the New button.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/app-menu-items-editor.8803d0eb.webp)

In code, add buttons to the same collection:

```csharp
// An Open command in the application menu
string open = ResourceProvider.FileMenuItem.TXITEM_Open.ToString();
RibbonButton openButton = new RibbonButton()
{
    Text = ResourceProvider.GetText(open),
    LargeIcon = ResourceProvider.GetLargeIcon(open, this),
    DisplayMode = IconTextRelation.LargeIconLabeled
};
openButton.Click += (sender, e) => textControl1.Load();
ribbon1.ApplicationMenuItems.Add(openButton);
```

[Load](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/load-method/llms-full.txt) without parameters opens the built-in open dialog. The pane beside the commands, often a list of recent files, is filled through [ApplicationMenuHelpPaneItems](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbon/applicationmenuhelppaneitems-property/llms-full.txt). [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/load-save/llms-full.txt) covers the load and save methods behind such commands.

### Add Items to the Quick Access Toolbar

The Quick Access Toolbar, like the headers of contextual tab groups, is drawn in the window border of a form derived from [RibbonForm](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonform/llms-full.txt); **Convert to a RibbonForm** in the ribbon's smart tag changes the base class of your form.

![The Ribbon Tasks smart tag of a Windows Forms ribbon with Convert to a RibbonForm above the links that add the predefined tabs.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/ribbon-smart-tag-ribbonform.179bdcd2.webp)

- [HasQuickAccessToolbar](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonform/hasquickaccesstoolbar-property/llms-full.txt) shows the toolbar, and [QuickAccessToolbarPosition](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonform/quickaccesstoolbarposition-property/llms-full.txt) places it in the caption area, the default `AboveRibbon`, or `BelowRibbon`.
- [SetQuickAccessToolbarStandardItems](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonform/setquickaccesstoolbarstandarditems-method/llms-full.txt) sets the items it starts with, as an array of `ToolStripItem` objects.
- Users can add a ribbon button to the toolbar through its context menu when the button's [IsAddToQuickAccessToolbarEnabled](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonbutton/isaddtoquickaccesstoolbarenabled-property/llms-full.txt) is `true`, as for the print button above. [RibbonGroup](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbongroup/llms-full.txt) has the same property for whole groups.

The blog article [Customizing the Windows Forms Ribbon](https://www.textcontrol.com/blog/2018/09/17/customizing-the-windows-forms-ribbon/) shows further examples of changed and added ribbon items.

### Next Steps

- [Toolbars and Mini Toolbars](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/toolbars/llms-full.txt): add ribbon groups of your own to the mini toolbar.
- [Themes, Colors, and Icons](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/themes/llms-full.txt): colors of the ribbon and icons for other resolutions.
- [Localization and Resource Kit](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/localization/llms-full.txt): texts of the ribbon in other languages.
- [Built-in Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/dialog-boxes/llms-full.txt): dialogs your buttons can open.

---

## Nearby

- **Previous:** [Built-In Ribbon Tabs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/ribbon/llms-full.txt)
- **Next:** [Toolbars and Mini Toolbars](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/toolbars/llms-full.txt)