Skip to main content

RibbonBar

RibbonBar is an Office-style command bar. It organizes an application's commands into tabs across the top of a page or window and replaces the traditional menu bar and toolbars. Commands are arranged in a three-level hierarchy:

  • pages, shown as tabs;
  • groups, the titled panels inside a page;
  • items, the commands inside a group: buttons, split buttons, check boxes, radio buttons, text boxes, combo boxes, separators, or any Wisej.NET control.

Every item's events are also raised on the RibbonBar itself, so a whole ribbon can be handled in a single event handler.

A RibbonBar with File, Home, Options and Edit tabs. The Home page shows a Clipboard group with Pin, Copy, Paste, Cut, Copy special and Paste special, and a New group with File, Folder, Overwrite and Save to cloud

A RibbonBar with an application button (File), three pages and two groups.

Installation​

Add the Wisej-4-RibbonBar package to your Wisej.NET project:

dotnet add package Wisej-4-RibbonBar

The package targets .NET Framework 4.8 and .NET 8 or later (including the -windows, Android, iOS and Mac Catalyst targets). After a rebuild, RibbonBar shows up in the Visual Studio toolbox. A new RibbonBar docks to the top (DockStyle.Top) and sizes its height to its content (AutoSize = true).

Structure​

LevelTypeCollectionNotes
Application buttonRibbonBarAppButtonRibbonBar.AppButtonAn optional tab before the first page. Hidden until you set Visible = true.
PageRibbonBarPageRibbonBar.PagesOne tab.
GroupRibbonBarGroupRibbonBarPage.GroupsA titled panel of items, with an optional button next to the title.
ItemRibbonBarItem subclassesRibbonBarGroup.ItemsLaid out in columns, see Columns and orientation.

The AppButton tab followed by three page tabs: Page1, Page2 and Page3

A page with three empty groups side by side: Group1, Group2 and Group3

Top: the application button and three pages. Bottom: a page with three groups.

All three collections can be indexed by position or by Name, e.g. ribbonBar1.Pages["home"].Groups["clipboard"].Items["paste"].

Getting started​

This example builds a Home page with a Clipboard group: one large Paste button and two small buttons stacked beside it. A single ItemClick handler on the RibbonBar handles all three.

using Wisej.Web.Ext.RibbonBar;

var ribbonBar = new RibbonBar();

var home = new RibbonBarPage { Name = "home", Text = "&Home" };
var clipboard = new RibbonBarGroup { Name = "clipboard", Text = "Clipboard" };
clipboard.Items.Add(new RibbonBarItemButton { Name = "paste", Text = "Paste", ImageSource = "icon-paste" });
clipboard.Items.Add(new RibbonBarItemButton { Name = "cut", Text = "Cut", Orientation = Orientation.Horizontal });
clipboard.Items.Add(new RibbonBarItemButton { Name = "copy", Text = "Copy", Orientation = Orientation.Horizontal });
home.Groups.Add(clipboard);
ribbonBar.Pages.Add(home);

ribbonBar.ItemClick += (s, e) =>
{
    switch (e.Item.Name)
    {
        case "paste": Paste(); break;
        case "cut": Cut(); break;
        case "copy": Copy(); break;
    }
};

this.Controls.Add(ribbonBar);

The & in "&Home" makes H the page's mnemonic key. Set UseMnemonic to false to show the ampersand as text instead.

Design it in Visual Studio

The RibbonBar is fully editable in the designer. Click any page, group or item on the design surface to select it and edit its properties in the Properties window. Use the collection editors of Pages, Groups and Items to add, remove and reorder elements.

Items​

A group containing a Button, a CheckBox, a SplitButton, a separator, a ComboBox, a RadioButton and a TextBox

From left to right: a button; a check box above a split button; a separator; then a combo box, a radio button and a text box.
ItemWhat it isSpecific members
RibbonBarItemButtonA push button, optionally with a drop-down menu.Orientation, Pushed, MenuItems; events PushedChanged, ItemClicked
RibbonBarItemSplitButtonA button with a separate arrow that opens its MenuItems.Everything RibbonBarItemButton has
RibbonBarItemButtonGroupA horizontal row of buttons treated as one item.Buttons
RibbonBarItemCheckBoxA check box.Checked, CheckedChanged
RibbonBarItemRadioButtonA radio button.Checked, CheckedChanged
RibbonBarItemTextBoxA label followed by a text field.Value, FieldWidth (120), ValueChanged
RibbonBarItemComboBoxA label followed by a drop-down list.Items (string[]), Value, Editable (false), FieldWidth (120), ValueChanged
RibbonBarItemSeparatorA vertical line between items.—
RibbonBarItemControlHosts any Wisej.NET Control.Control, Orientation

All items share the members of RibbonBarItem: Text, ToolTipText, Enabled, Visible, Tag, ColumnBreak, the Click event, and the image properties Image, ImageSource, ImageIndex and ImageKey. ImageSource takes a URL, a relative path or a theme icon name. ImageIndex and ImageKey pick an image from the RibbonBar's ImageList.

tip

The RibbonBar's theme mixin ships a set of ready-made icons you can use in ImageSource: ribbon-paste, ribbon-copy, ribbon-cut, ribbon-save, ribbon-save-as, ribbon-save-all, ribbon-print, ribbon-open, ribbon-folder, ribbon-add-file, ribbon-add-folder, ribbon-delete, ribbon-settings, ribbon-about and more.

Any RibbonBarItemButton can carry a drop-down menu in MenuItems, a collection of standard Wisej.NET MenuItem objects. On a plain button the whole button opens the menu. On a RibbonBarItemSplitButton, the button fires Click and only the arrow opens the menu.

var paste = new RibbonBarItemSplitButton { Name = "paste", Text = "Paste", ImageSource = "ribbon-paste" };
paste.MenuItems.Add(new MenuItem("Keep source formatting") { Name = "pasteSource" });
paste.MenuItems.Add(new MenuItem("Keep text only") { Name = "pasteText" });

// The button itself...
paste.Click += (s, e) => Paste();

// ...and a menu item, handled on the RibbonBar.
this.ribbonBar1.MenuButtonItemClick += (s, e) =>
{
    AlertBox.Show($"{e.Item.Name}: {e.MenuItem.Name}");
};

A menu click fires ItemClicked on the button and MenuButtonItemClick on the RibbonBar. Both take a RibbonBarMenuItemEventArgs, whose Item is the button and MenuItem the menu entry.

Toggle buttons​

Set Pushed to show a button in its pressed state, for commands that switch something on and off, like Bold. The button doesn't toggle itself: set Pushed in the Click handler. Each change fires PushedChanged.

private void buttonBold_Click(object sender, EventArgs e)
{
    this.buttonBold.Pushed = !this.buttonBold.Pushed;
}

Button groups​

A RibbonBarItemButtonGroup lays out its Buttons side by side, like the alignment buttons in a word processor. It takes regular buttons and split buttons.

A group with two buttons and a split button side by side in a single row

A RibbonBarItemButtonGroup with two buttons and a split button.

Hosting other controls​

When the built-in items aren't enough, RibbonBarItemControl hosts any Wisej.NET control, such as a date picker, a numeric editor or a color picker, inside a group.

var dateItem = new RibbonBarItemControl { Text = "Due date" };
this.ribbonBarGroupSchedule.Items.Add(dateItem);

// Assign the control after the item is in a group that belongs to a RibbonBar.
dateItem.Control = new DateTimePicker { Format = DateTimePickerFormat.Short, Width = 120 };
Order matters

Assign Control after adding the item to a group that is already part of a RibbonBar. The hosted control is moved into the RibbonBar, and if the item isn't attached yet, the control ends up with no parent. The control's AutoSize is set to false and its size follows the item. Disposing the item disposes the hosted control too.

Columns and orientation​

A group stacks its items vertically in columns. A new column starts after any item whose ColumnBreak is true. Large buttons (Orientation.Vertical, the default: icon above the text), vertical hosted controls and separators always take a column of their own. Small buttons (Orientation.Horizontal: icon beside the text), check boxes, radio buttons, text boxes and combo boxes stack in the current column.

var font = new RibbonBarGroup { Text = "Font" };
font.Items.Add(new RibbonBarItemButton { Text = "Bold", Orientation = Orientation.Horizontal });
font.Items.Add(new RibbonBarItemButton { Text = "Italic", Orientation = Orientation.Horizontal });
font.Items.Add(new RibbonBarItemButton { Text = "Underline", Orientation = Orientation.Horizontal, ColumnBreak = true });
font.Items.Add(new RibbonBarItemCheckBox { Text = "Superscript" });
font.Items.Add(new RibbonBarItemCheckBox { Text = "Subscript" });

This gives two columns: Bold, Italic and Underline in the first, the two check boxes in the second.

Groups​

A RibbonBarGroup shows its Text as a title under its items. Set ShowButton to true to add the small corner button next to the title, the one visible in the New group at the top of this page. It usually opens a dialog with more options. A click fires the group's Click event and GroupClick on the RibbonBar.

this.ribbonBarGroupFont.ShowButton = true;
this.ribbonBarGroupFont.Click += (s, e) => new FontOptionsDialog().ShowDialog();

Setting Enabled = false on a group, or on a page, disables all the items inside it at once.

Pages and selection​

SelectedPage returns or sets the active page. Until a page is selected, it returns the first visible page. Changing it, from code or when the user clicks a tab, fires SelectedPageChanged. Setting RibbonBarPage.Selected to true does the same from the page's side.

Hiding a page and showing it on demand is how you build contextual tabs, such as Picture Tools that only appear while a picture is selected:

private void pictureBox1_Click(object sender, EventArgs e)
{
    var page = this.ribbonBar1.Pages["pictureTools"];
    page.Visible = true;
    this.ribbonBar1.SelectedPage = page;
}

private void ribbonBar1_SelectedPageChanged(object sender, EventArgs e)
{
    this.labelStatus.Text = "Page: " + this.ribbonBar1.SelectedPage?.Text;
}

Use TabBackColor and TabForeColor to make a contextual tab stand out, like the green Edit tab in the screenshot at the top of this page.

warning

SelectedPage only accepts a page from this RibbonBar's Pages collection, and it can't be set to null. Either mistake throws an exception.

Application button​

The AppButton is the colored tab before the first page (File in the screenshot at the top). It isn't a page: clicking it fires AppButtonClick, which is where you open a backstage view, a side panel or a menu. It's hidden by default.

this.ribbonBar1.AppButton.Visible = true;
this.ribbonBar1.AppButton.Text = "File";
this.ribbonBar1.AppButton.BackColor = Color.FromArgb(0x2B, 0x57, 0x9A);
this.ribbonBar1.AppButton.ForeColor = Color.White;

this.ribbonBar1.AppButtonClick += (s, e) => this.fileMenuPanel.Visible = true;

Compact view​

With CompactView set to true, only the tab strip is visible and no page is shown as selected, which frees up vertical space. When the user clicks a tab, its page opens temporarily over the content below the ribbon, and it closes again at the next click outside the ribbon. Clicks inside the ribbon's own drop-down menus and popups don't close it. On the server, SelectedPage keeps the last page the user chose. Each switch fires CompactViewChanged.

private void buttonCollapse_Click(object sender, EventArgs e)
{
    this.ribbonBar1.CompactView = !this.ribbonBar1.CompactView;
}

Tools​

Tools is a standard ComponentToolCollection. Its tools appear at the right end of the tab strip, like the help and settings icons in the screenshot at the top. A click fires ToolClick. See Embedded Tools in the user guide.

Validation​

CausesValidation is false by default. With the default, clicking a ribbon command doesn't validate the control that currently has focus. Set it to true when commands such as Save must first run the active editor's Validating handler. See Validation.

Events​

EventRaised onWhen
ItemClickRibbonBarAny item is clicked. e.Item is the item.
ItemValueChangedRibbonBarThe user changes an item's value: a check box, radio button, text box or combo box.
MenuButtonItemClickRibbonBarA drop-down menu item of a button or split button is clicked.
GroupClickRibbonBarA group's title button is clicked.
SelectedPageChangedRibbonBarThe active page changes.
AppButtonClickRibbonBarThe application button is clicked.
CompactViewChangedRibbonBarCompactView changes.
ToolClickRibbonBarA tool in Tools is clicked.
ClickEach item and groupThe same click, raised on the element itself.
CheckedChanged / ValueChanged / PushedChangedThe specific item typeThe item's value changes.

Styling​

RibbonBar.mixin.theme is embedded in the extension and loaded automatically. It defines the ribbonbar, ribbonbar-group and ribbonbar-item appearances, the icon set listed above, and five colors you can override in a mixin of your own:

ColorDefaultUsed for
ribbonBar#f5f6f7Ribbon background
ribbonPage#f5f6f7Page background
ribbonBarText#3F3F3FTab text
ribbonGroupText#5F5F5FGroup titles
ribbonItemText#2B2B2BItem text
Themes/MyApp.mixin.theme
{
  "name": "MyApp.mixin",
  "colors": {
    "ribbonBar": "#FFFFFF",
    "ribbonPage": "#FFFFFF",
    "ribbonGroupText": "#6B7280"
  }
}

See Theming and editing a mixin in the Theme Builder.

API reference​