Build a ribbon with tabs, groups and commands

MxRibbon is a ribbon in the style of Office. It holds tabs. Each tab holds groups, and each group holds commands. All ribbon types are in the Mordex.Windows.Ribbon namespace.

The Home tab with large and small buttons

Add a ribbon to a form

Create the ribbon, dock it at the top and add it to the form. ApplicationName is the name shown in the title.

using System.Windows.Forms;
using Mordex.Windows.Ribbon;

MxRibbon ribbon = new MxRibbon
{
    ApplicationName = "Orders",
    Dock = DockStyle.Top
};
Controls.Add(ribbon);

By default the ribbon draws inside the title bar of the form. Set HandlesTitleBar to false to keep the normal Windows title bar. ShowCaptionBar adds a bar at the top of the ribbon for contextual tabs. Set it to false when you do not use them.

In Visual Studio you can also drop MxRibbon on a form. Use the New Tab verb to add a tab, and the MxRibbon Designer dialog to edit the rest.

Add a tab and a group

A RibbonTab takes its text in the constructor. A RibbonGroup takes a key and a text. Add groups to RibbonTab.Groups and tabs to MxRibbon.Tabs. SelectedTab sets the tab that is open.

RibbonTab home = new RibbonTab("Home");
RibbonGroup clipboard = new RibbonGroup("clipboard", "Clipboard");
home.Groups.Add(clipboard);

ribbon.Tabs.Add(home);
ribbon.Tabs.Add(new RibbonTab("Insert"));
ribbon.SelectedTab = home;

The SelectedTabChanged event tells you when the user opens another tab. In ChangingSelectedTab you can set Cancel to true to keep the current tab.

Add large and small buttons

A ButtonCommand is a button. Give it a key and a text. SizeStyle sets the size:

• CommandSizeStyle.Large shows a tall button with a large image and the text under it.
• CommandSizeStyle.Small shows a short button with a small image and the text beside it.

A large button uses LargeImage. A small button uses Image. Set both when a button can change size.

using System.Drawing;

ButtonCommand paste = new ButtonCommand("paste", "Paste")
{
    LargeImage = pasteImage32,
    Image = pasteImage16,
    SizeStyle = CommandSizeStyle.Large
};
ButtonCommand cut = new ButtonCommand("cut", "Cut")
{
    Image = cutImage16,
    SizeStyle = CommandSizeStyle.Small
};

clipboard.Commands.Add(paste);
clipboard.Commands.Add(cut);

Small buttons stack in a column. ItemRows sets how many small buttons fit in one column. The default is 3.

To take images from image lists, set MxRibbon.ImageList and MxRibbon.LargeImageList. Then set ImageIndex and LargeImageIndex on each button.

Run code when a button is clicked

Handle Click on the button. The event gives you the command in e.Command.

paste.Click += (sender, e) => PasteFromClipboard();

To handle all buttons in one place, use MxRibbon.CommandClick and check e.Command.Key.

ribbon.CommandClick += (sender, e) =>
{
    if (e.Command.Key == "cut")
    {
        CutSelection();
    }
};

Make a toggle button

Set CheckOnClick to true. Each click then changes Checked, and CheckedChanged runs.

ButtonCommand showPanel = new ButtonCommand("navigation", "Navigation")
{
    CheckOnClick = true,
    Checked = true,
    SizeStyle = CommandSizeStyle.Large
};
showPanel.CheckedChanged += (sender, e) => sidePanel.Visible = showPanel.Checked;

Set ActAsOptionButton to true on several buttons in one group to make them work like option buttons. When the user picks one, the others are unchecked.

Use other kinds of commands

A group can hold more than buttons.

Set DropDownStyle to DropDownButtonStyle.SplitButton to make a button with a separate arrow. A click on the main part runs the button. A click on the arrow opens the list.

DropDownCommand pasteMenu = new DropDownCommand("pastemenu", "Paste")
{
    DropDownStyle = DropDownButtonStyle.SplitButton,
    LargeImage = pasteImage32,
    SizeStyle = CommandSizeStyle.Large
};
pasteMenu.Commands.Add(new ButtonCommand("pastetext", "Paste text only"));
pasteMenu.Commands.Add(new ButtonCommand("pastespecial", "Paste special"));
clipboard.Commands.Add(pasteMenu);

Add a dialog launcher to a group

A dialog launcher is the small button in the corner of a group. Set DialogButtonVisible to true and handle DialogButtonClick.

clipboard.DialogButtonVisible = true;
clipboard.DialogButtonClick += (sender, e) => ShowClipboardOptions();

Show super tips

A super tip is a large tooltip with a header, a body and a footer. Fill SuperTipSettings on a button. A button with empty settings shows no tip.

paste.SuperTipSettings.HeaderText = "Paste";
paste.SuperTipSettings.Text = "Add the content of the clipboard to the document.";
paste.SuperTipSettings.FooterText = "Press F1 for more help";

RibbonGroup has its own SuperTipSettings too, and DialogButtonSuperTipSettings for the dialog launcher. On the ribbon, ShowToolTips turns tips on or off, SuperTipDelay sets how long a tip stays, and SuperTipWidth sets its width. When ShowShortcutInToolTips is on, the tip header shows the Shortcut of the button.

Fill the Quick Access toolbar

The Quick Access toolbar is a short row of buttons that stays visible on every tab. Add commands to QuickAccessCommands. You can add a button that is already in a group.

ribbon.QuickAccessCommands.Add(save);
ribbon.QuickAccessCommands.Add(undo);

These properties change the toolbar:

• QuickAccessPosition puts it above the ribbon (AboveRibbon, the default) or below it (BelowRibbon).
• ShowCustomizeButton shows the customize button on the toolbar.
• AllowAddToQuickAccessBar on a command lets the user add that command to the toolbar.

The QuickAccessCommandAdded and QuickAccessCommandRemoved events tell you when the user changes the toolbar.

Build the application menu

ControlBoxMode sets which main menu the ribbon shows. With the default value, the ribbon shows a backstage menu: a full page that opens from the first tab.

Add BackstageTab pages and ButtonCommand items to BackstageMenu.Commands. Each BackstageTab has a TabPage that holds your own controls.

ribbon.BackstageMenu.Text = "File";

BackstageTab info = new BackstageTab("info", "Info");
info.TabPage.Controls.Add(new Label { Text = "Document details", Dock = DockStyle.Top });
ribbon.BackstageMenu.Commands.Add(info);

ButtonCommand saveAs = new ButtonCommand("saveas", "Save as");
saveAs.Click += (sender, e) => SaveDocumentAs();
ribbon.BackstageMenu.Commands.Add(saveAs);

The ribbon raises BackstageOpening, BackstageOpened, BackstageClosing and BackstageClosed.

The other values of ControlBoxMode are:

• ControlBoxButton shows a button at the top of the ribbon that opens a drop-down menu.
• ControlBoxTab opens the same drop-down menu from the menu tab.
• None shows no main menu.

Fill the drop-down menu with ControlBoxMenu.LeftCommands, ControlBoxMenu.RightCommands and ControlBoxMenu.BottomCommands.

Show a contextual tab

A contextual tab appears only when it is needed, for example while a picture is selected. Create a RibbonContextualTab, add it to ContextualTabs and add tabs to it.

RibbonContextualTab pictureTools = new RibbonContextualTab("Picture tools")
{
    BackColor = Color.Orange
};
ribbon.ContextualTabs.Add(pictureTools);
pictureTools.Tabs.Add(new RibbonTab("Format"));

pictureTools.Controls.Add(pictureBox);

Controls in RibbonContextualTab.Controls show the tab when they have the focus. You can also show or hide it yourself with Active.

Let users minimize the ribbon

When AllowMinimize is true, the user can fold the ribbon so that only the tab names show. MinimizeOnDoubleClick folds it when the user double clicks a tab. Read or set Minimized in code, and handle MinimizedChanged to react.

Add a ribbon status bar

MxRibbonStatusBar is a status bar that matches the ribbon. It has two areas. Add commands to LeftPanelCommands and RightPanelCommands.

MxRibbonStatusBar statusBar = new MxRibbonStatusBar { Dock = DockStyle.Bottom };
statusBar.LeftPanelCommands.Add(new LabelCommand("ready", "Ready"));
statusBar.LeftPanelCommands.Add(new LabelCommand("words", "Words: 128"));

ButtonCommand view = new ButtonCommand("view", "Print layout");
view.Click += (sender, e) => SwitchToPrintLayout();
statusBar.RightPanelCommands.Add(view);

Controls.Add(statusBar);

ShowSizeGrip shows the grip in the corner. CommandClick runs for every command in the bar.

Show a ribbon context menu

MxRibbonContextMenu is a menu in the ribbon style. Fill Commands, then call Show with a control and a point.

MxRibbonContextMenu menu = new MxRibbonContextMenu();
menu.Commands.Add(new ButtonCommand("cut", "Cut"));
menu.Commands.Add(new ButtonCommand("copy", "Copy"));
menu.Commands.Add(new SeparatorCommand());
menu.Commands.Add(new ButtonCommand("properties", "Properties"));
menu.CommandClick += (sender, e) => RunCommand(e.Command.Key);

editor.MouseUp += (sender, e) =>
{
    if (e.Button == MouseButtons.Right)
    {
        menu.Show(editor, e.Location);
    }
};

Give other forms the ribbon title bar

A dialog without a ribbon can still match the main window. Add a MxRibbonFormAdorner and set its Form. It gives that form the ribbon title bar and frame. ApplicationName and DocumentName set the title text.

MxRibbonFormAdorner adorner = new MxRibbonFormAdorner
{
    Form = optionsDialog,
    ApplicationName = "Orders",
    DocumentName = "Options"
};

The ribbon follows the application theme. See Themes to pick one.