Skip to main content

Implement the ribbon element

Overview​

ExtensionPoints allows you to dynamically generate ribbons in code. Ribbon extension points can be created in code by accessing the Ribbon of the ExtensionPoints property within the OnActivate method of the extension. You can add tabs, groups, and buttons to the ribbon and implement processing logic by assigning commands to the buttons. A command can implement command execution processing by associating a derived class of CommandHandlerBase.

public class SampleExtensionEntryPoint : ExtensionBase
{
    protected override void OnActivate()
    {
        //ribbon
        var tab = ExtensionPoints.Ribbon.AddTab("SampleExPoint");
        var group = tab.AddGroup("Test1");
        group.AddLargeButton<HelloCommand>("Hello");
    }
}

The above code can be succinctly written in method chaining as follows:

ExtensionPoints.Ribbon.AddTab("SampleExPoint").AddGroup("Test1").AddLargeButton<HelloCommand>("Hello world");<br/>

For more information about the relationships and details of each user interface element of the ribbon, such as tabs and groups, see Ribbon in Manifest.

Implementing the ribbon element​

Tabs​

The Ribbon (RibbonTab) is made up of tabs. You can add new tabs and add elements such as buttons, or you can add elements such as buttons to the system standard tabs.

Add Tab
To add a tab, call the Ribbon.AddTab method on the Ribbon property.
Below is an example of adding a new tab.

//add a tab named "custom tabs"
var customTabId = "MySampleExtension.CustomTab";
var tab = ExtensionPoints.Ribbon.AddTab("custom tab",customTabId);

AddTab allows you to set a unique Id if you want to be able to retrieve the tab object later. However, in most cases it is recommended to use it by assigning it to a variable like var tab = ExtensionPoints.Ribbon.AddTab(. ..). However, if you want to add groups and buttons to the same tab in common with multiple extensions, please specify the Id.

Use RibbonTab.SetOrderBefore or RibbonTab.SetOrderAfter for the tab insertion position.

//add tabs after home tab
var tab = ExtensionPoints.Ribbon.AddTab("custom tab").SetOrderAfter(RibbonTabs.Home);

Get tab
To get the tab, call the Ribbon.GetTab method on the Ribbon property.
Below is an example of getting an existing tab.

//Get the tab added by the extension by Id
var tab = ExtensionPoints.Ribbon.GetTab("MySampleExtension.CustomTab");

To get system tabs such as Home and add groups, buttons, etc., call them using the RibbonTabs enumeration as follows.

//get home tab
var homeTab = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home);

Tab display control
You can also hide tabs. It is also possible to hide system tabs as well as added tabs.

//hide home tab
var homeTab = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home);
homeTab.Visible = false;

Groups​

A group (RibbonGroup) is a user interface element that organizes controls such as buttons on a ribbon tab. A group is always required to create a control.

Add Group
To add a new group to a tab, call the RibbonTab.AddGroup method on the RibbonTab property. Below is an example of adding a new group.

//Add a group named "Sample Group" to the "Home" tab
var group = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).AddGroup("Sample Group");
group.AddLargeButton<HelloCommand>("Hello world");

As with tabs, groups can also be added by specifying an Id.

var group = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).AddGroup("Sample Group","MySampleExtension.SampleGroup");
group.AddLargeButton<HelloCommand>("Hello world");

Use RibbonGroup.SetOrderBefore or RibbonGroup.SetOrderAfter for the group insertion position. Defines groups that can be inserted into the RibbonGroups enumeration.

//Set behind the "Models" group in the "Home" tab
group.SetOrderAfter(RibbonGroups.Home_Model);

Get Groups
To get an existing group of tabs, call the RibbonTab.GetGroup method on the RibbonTab property. Below is an example of getting an existing group.

var modelGroup = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).GetGroup(RibbonGroups.Home_Model);

Group display control
You can also hide groups. It is possible to hide system groups as well as added groups.

//Hide the "Models" group in the "Home" tab
var modelGroup = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).GetGroup(RibbonGroups.Home_Model);
modelGroup.Visible =false;

button​

A button (RibbonButton) is a button object that can be executed on the Ribbon. It can be added as a child element of groups, stack panels, menus, etc.

Add button
To add a button, call the AddLargeButton method or the AddSmallButton method.

//add a large button named "Button 1" to the "MyCoustomGroup" group
var group = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).AddGroup("MyCoustomGroup");
group.AddLargeButton<MyCommand1>("Button 1");

//add a small button named "Button2" to the "MyCoustomGroup" group
var stackPanel = ExtensionPoints.Ribbon.GetTab(RibbonTabs.Home).GetGroup("MyCoustomGroup").AddStackPanel();
stackPanel.AddSmallButton<HelloCommand>("Button 2");

You can specify an icon for the button by giving an additional argument when adding the button. 

//assign an icon to the big button
group.AddLargeButton<MyCommand1>("Button 1","resource/MyIcon.png");

//assign an icon to the small button
stackPanel.AddSmallButton<HelloCommand>("Button2","resource/MySmallIcon.png");

You can also specify an icon for the button.
Specify Large Button Icon

group.AddLargeButton<MyCommand1>("Button 1","resource/MyIcon.png");

Specify small button icon

stackPanel.AddSmallButton<HelloCommand>("Hello world","resource/MySmallIcon.png");

Command Assignment
By passing the command handler class to the button parameter, the command handler will be executed.
Below is an example of assigning the MyCommand command to a button.

stackPanel.AddSmallButton<MyCommand>("Hello world");

When you press the Hello world button added above, the OnExecute method of the MyCommand class will be executed.
For the command handler implementation, see here.

CheckBox​

A checkbox (RibbonCheckBox) is a control that has a checked state. To add a checkbox, add a stack panel or button group to the group and make it a child element.

Add checkbox
To add a checkbox, call the AddCheckBox method. At this time, specify the property name to get the checked state of the checkbox in the handler.

var stackPanel = tab.AddGroup("Group1").AddStackPanel();
stackPanel.AddCheckBox<SomeCommand>("CheckBox1","MyProperty1");

You can also specify the initial value of the checked state.

stackPanel.AddCheckBox<SomeCommand>("CheckBox1","MyProperty1",true);

Get check status
To get the check state, call the Context.GetProperty method inside the handler.

public class MyCommand : CommandHandlerBase
{
    protected override void OnExecute(ICommandContext c, ICommandParams p)
    {
        //To get the checked state, use the `GetProperty` method to get the property.
        var isChecked = Context.GetProperty<bool>("MyProperty1");

        UI.ShowMessageBox( $"Checked {isChecked}", ExtensionName);
    }
}

Update Check Status
To update the check state, call the Context.SetProperty method inside the handler.

//To change the checked state, change the property using the `SetProperty` method.
Context.SetProperty("MyProperty1", true);

Separator​

A separator (RibbonSeparator) can separate small image buttons such as menus and groups. Available for groups, button groups and menus.

Add Separator
To add a separator call the AddSeparator method.

var menu = tab.AddMenu("Sample Menu");
menu.AddSmallButton<MyCommand1>("Menu 1");
menu.AddSeparator(); //add a separator between menu items
menu.AddSmallButton<MyCommand2>("Menu2");

Button Group​

Button Group (RibbonButtonGroup) A container that displays multiple small image buttons side by side like a toolbar.

Add Button Group
Call the AddButtonGroup method to add a button group.

var buttonGroup = tab.AddGroup("Group1").AddButtonGroup();
buttonGroup.AddSmallButton<MyCommand1>("Command1","images/command1-small.png");
buttonGroup.AddSmallButton<MyCommand2>("Command2","images/command1-small.png");

Stack Panel​

A stack panel (RibbonStackPanel) is a container that arranges checkboxes and small image buttons vertically in a group.

Add Stack Panel
Call the AddStackPanel method to add a stack panel.

var stackPanel = tab.AddGroup("Group1").AddStackPanel();
stackPanel.AddSmallButton<MyCommand1>("Command1","resource/MyIcon1.png");
stackPanel.AddSmallButton<MyCommand2>("Command2","resource/MyIcon2.png");

A menu (RibbonMenu) is a container that displays multiple buttons in a pull-down menu format.

Add Menu
To add a menu, call the AddMenu method.

var menu = tab.AddGroup("Sample Group").AddMenu("Sample Menu");
menu.AddSmallButton<MyCommand1>("Menu 1");
menu.AddSmallButton<MyCommand2>("Menu2");

Split button​

A split button (RibbonSplitButton) is a container that has the function of a button that can be pressed to execute a command, and also displays other buttons in a pull-down menu format.

Add Split Buttons
To add a split button, call the AddSplitButton method.

var splitButton = tab.AddGroup("Sample Group").AddSplitButton<HelloCommand>("Split Button Example");
var menu = splitButton.AddMenu();
menu.AddSmallButton<MyCommand1>("Menu 1");
menu.AddSmallButton<MyCommand2>("Menu2");
Last updated on