Ribbon bar

In This Topic

Migration from menu and toobar
RibbonIcons
See Also

Since 2022 version, Eplan GUI items are accessible by means of a ribbon. In API this control is represented by following classes :

Eplan.EplApi.Gui.RibbonBar
Eplan.EplApi.Gui.RibbonTab
Eplan.EplApi.Gui.RibbonCommandGroup
Eplan.EplApi.Gui.RibbonCommand

The ribbon is divided on tabs and these on command groups and commands.

All ribbon related classes are stored in Eplan.EplApi.Gui namespace. They correspond with types of ribbon items from GUI :

Here is an example of listing ribbon items (tabs, command groups and commands):

RibbonBar ribbonBar = new RibbonBar();
foreach (RibbonTab tab in ribbonBar.Tabs)
{
    Debug.WriteLine($"\tTab Name:{tab.Name}------------");
    foreach (var commandGroup in tab.CommandGroups)
    {
        Debug.WriteLine($"\t\tCommand group:{commandGroup.Name}------");
        foreach (var command in commandGroup.Commands)
        {
            RibbonCommand ribbonCommand = command.Value;
            uint commandId          = ribbonCommand.ID;
            string strText          = ribbonCommand.Text;
            string strDescription   = ribbonCommand.Description;
            string strTooltipText   = ribbonCommand.TooltipText;
            string strActionCommandLine = ribbonCommand.ActionCommandLine;
            Debug.WriteLine($"\t\t\tCommand Id:{commandId}---.Text:{strText}---.ActionCommandLine:{strActionCommandLine}---.TooltipText:{strTooltipText}---.Description:{strDescription}");
        }
        Debug.WriteLine($"\t\t-----------------------");
    }
    Debug.WriteLine($"\t-----------------------------");
}

Please mind that some tabs are context sensitive, i.e they are open only when editor is visible.

Old menu and toolbars are no longer accessible. The equivalent of old menu point/toolbar button is now ribbon command :

In API, commands can be created in following places:

"Extensions"->"API" command group
A custom command group that is placed in a persistient or custom tab

Migration from menu and toobar

The classes corresponding to old GUI items i.e. Toolbar and Menu are currently deprecated, so it is highly recommended to migrate relevant code.

Following table shows how to create new ribbon items together with example code:

Old GUI item	Old API method	New GUI equivalent	New API method	Example old code	Example new code
Main menu	Menu.AddMainMenu	RibbonTab	RibbonBar.AddTab	menu.AddMainMenu("API Tests A-N", Menu.MainMenuName.eMainMenuHelp,"AddingMessageAction", "AddingMessageAction", "First menu element", 1);	var ribbonTab = ribbonBar.AddTab("API Tests A-N");
Popup menu	Menu.AddPopupMenuItem	RibbonCommandGroup	RibbonTab.AddCommandGroup	menu.AddPopupMenuItem("ActionExample - test2","ActionExample - test2 submenupoint1", "ActionExample", "status text", mainID, 0, false, false);	var commandGroup = ribbonTab.AddCommandGroup("ActionExample - test2");
Toolbar	toolbar.CreateCustomToolbar	RibbonCommandGroup	RibbonTab.AddCommandGroup	toolbar.CreateCustomToolbar("SelectionSet", Toolbar.ToolBarDockPos.eToolbarLeft, 4, 1, true);	var commandGroup = ribbonTab.AddCommandGroup("SelectionSet");
Menu item	menu.AddMenuItem(	RibbonCommand	RibbonBar.AddCommand , RibbonCommandGroup.AddCommand	menu.AddMenuItem("UndoAction", "UndoAction"); menu.AddMenuItem("SelectionRecursive", "SelectionRecursiveAction", "", selectionSetID, 1,false, false);	ribbonBar.AddCommand("UndoAction", "UndoAction"); commandGroup.AddCommand("SelectionRecursive", "SelectionRecursiveAction");
Toolbar button	toolbar.AddButton(	RibbonCommand	RibbonCommandGroup.AddCommand(…,index)	toolbar.AddButton("SelectionSet", Int32.MaxValue, "SelectionOneItemAction","C:\\myicons\\0.ico", "SelectionOneItemAction");	commandGroup.AddCommand("SelectionOneItemAction", "SelectionOneItemAction", 0);

Here is also a list of other old methods and their new conterparts :

Old method	New method

Toolbar.ExistsToolbar	RibbonBar.Tabs.Any(by LINQ) RibbonBar.GetTab RibbonBar.GetDefaultTab
Toolbar.GetButtonAction	RibbonCommand.ActionCommandLine
Toolbar.GetButtonToolTip	RibbonCommand.TooltipText
Toolbar.GetCountOfButtons	RibbonCommandGroup.Commands.Count
Toolbar.GetPersistentButtonId Menu.GetCustomMenuId GetPersistentMenuId	RibbonCommand.ID
Toolbar.RemoveButton	RibbonCommand.Remove
Toolbar.RemoveCustomToolbar	RibbonCommandGroup.Remove
Menu.IsActionChecked	RibbonCommand.IsChecked
Menu.IsActionEnabled	RibbonCommand.IsEnabled
Menu.RemoveMenuItem	RibbonTab.Remove RibbonCommandGroup.Remove RibbonCommand.Remove

ContextMenu class is not affected by this change, i.e everything should work as before 2022 version.

For more information, please refer to chapter "The New Ribbon" of Eplan Help.

RibbonIcons

Ribbon command actions can be now created with .svg icons. There is a list of standard CommandIcons accessible by name or index number.
Furthermore, below examples present also how to use custom icons, which can be added by specifying path to .svg file or providing icon content in string format.

Adding standard icons

var ribbonBar = new RibbonBar();
var tab = ribbonBar.AddTab("RibbonIcons");


//Adding standard icons to command action using enum names
var commandGroup = tab.AddCommandGroup("enum names");
commandGroup.AddCommand("Button1", "action1", new RibbonIcon(CommandIcon.Generator));
commandGroup.AddCommand("Button2", "action2", new RibbonIcon(CommandIcon.Amplifier));
commandGroup.AddCommand("Button3", "action3", new RibbonIcon(CommandIcon.Octagon_3));


//Adding standard icons to command action using index numbers
commandGroup = tab.AddCommandGroup("index numbers");
commandGroup.AddCommand("Button4", "action4", new RibbonIcon(75));
commandGroup.AddCommand("Button5", "action5", new RibbonIcon(123));
commandGroup.AddCommand("Button6", "action6", new RibbonIcon(181));

Adding custom icons

//Adding new custom icons to command action using path to file
commandGroup = tab.AddCommandGroup("custom icons path to file");
commandGroup.AddCommand("Button7", "action7", new RibbonIcon("D:\\Icon2.svg"));
commandGroup.AddCommand("Button8", "action8", new RibbonIcon("D:\\Icon3.svg"));

//Adding new custom icon to RibbonBar using path to file
RibbonIcon ribbonIcon = ribbonBar.AddIcon("D:\\CarIco.svg");
commandGroup = tab.AddCommandGroup("AddIcon using path");
commandGroup.AddCommand("Button10", "action10", ribbonIcon);

//Adding new custom icon to RibbonBar using string source
var svgContent = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\">" +
 "<title>Clock_1</title>" +
 "<g id=\"GUIicons\">" +
 "<g id=\"Clock\">" +
 "<g>" +
   "<circle cx=\"8\" cy=\"8\" r=\"7.5\" style=\"fill: #fff\"/>" +
   "<path d=\"M8,1A7,7,0,1,1,1,8,7,7,0,0,1,8,1M8,0a8,8,0,1,0,8,8A8,8,0,0,0,8,0Z\" style=\"fill: #4a7db1\"/>" +
 "<g>" +
   "<path d=\"M12,8.5H8v-1h4ZM7.5,4V7h1V4Z\" style=\"fill:#9e0b0f\"/>" +
 "<g>" +
   "<rect x=\"13.5\" y=\"7\" width=\"1\" height=\"2\"transform=\"translate(22 -6) rotate(90)\" style=\"fill: #505050\"/>" +
   "<rect x=\"7.5\" y=\"13\" width=\"1\" height=\"2\"transform=\"translate(16 28) rotate(-180)\" style=\"fill: #505050\"/>" +
   "<rect x=\"1.5\" y=\"7\" width=\"1\" height=\"2\"transform=\"translate(-6 10) rotate(-90)\" style=\"fill: #505050\"/>" +
   "<rect x=\"7.5\" y=\"1\" width=\"1\" height=\"2\"style=\"fill: #505050\"/>" +
 "</g>" +
   "<circle cx=\"8\" cy=\"8\" r=\"1\" style=\"fill:#4a7db1;stroke: #9e0b0f;stroke-miterlimit: 10;stroke-width: 0.5px\"/>" +
 "</g>" +
 "</g>" +
 "</svg>";

commandGroup = tab.AddCommandGroup("AddIcon using source");
ribbonIcon = ribbonBar.AddIcon(svgContent);
commandGroup.AddCommand("Button13", "action13", ribbonIcon);

Above examples results in RibbonBar

Scripts

Adding ribbon items by a script

Addins

Adding ribbon commands

Send Feedback