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

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

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

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

Prior to version 2027, custom commands could be created with either a small icon or no icon. Starting with version 2027, it is also possible to create custom commands with large icons. 

Additionally, version 2027 offers dropdown button functionality: You can now create dropdown commands that open a dropdown list of subcommands when you click the small arrow. You can specify whether the dropdown root command itself should act as a button and execute an action, or whether it should simply open the dropdown list:

For more details on the large icon buttons and the dropdown buttons, please refer to the corresponding sections below.

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 keep it in mind that some tabs are context sensitive, i.e they are open only when the editor is visible.

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

In the API, commands can be created in the following places:

• Extensions > API command group
• A custom command group that is placed in a persistent tab or a custom tab

Menu and toolbar migration

The classes corresponding to the old GUI items i.e.  Toolbar  and  Menu  are removed in version 2026, so it is essential to migrate relevant code.

The following table shows how to create new ribbon items and provides example code:

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

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

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

Ribbon icons

Ribbon command actions can now be 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 a 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 a 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 a command action using the path to the 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 icons to a RibbonBar using the path to the file
RibbonIcon ribbonIcon = ribbonBar.AddIcon("D:\\CarIco.svg");
commandGroup = tab.AddCommandGroup("AddIcon using path");
commandGroup.AddCommand("Button10", "action10", ribbonIcon);

// Adding new custom icons to a RibbonBar using the 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);

The above examples result in this RibbonBar:

Creating large icon commands

Ribbon icons are small by default, but you can also create a command with a large icon by setting the  RibbonIcon.IsLarge  property. Since its default value is "FALSE", you only have to set this property, if you want a large icon command. Of course it is also possible to create a command without any icon:

var customTab = new RibbonBar().AddTab("New API tab");
var customCommandGroup1 = customTab.AddCommandGroup("New API command group 1");
var customCommandGroup2 = customTab.AddCommandGroup("New API command group 2");

// Create a large icon command
var commandInfo1 = new RibbonCommandInfo("Large icon button", "action1");
var ribbonIcon1 = new RibbonIcon(CommandIcon.Eplan);
ribbonIcon1.IsLarge = true;
commandInfo1.Icon = ribbonIcon1;
var command1 = customCommandGroup1.AddCommand(commandInfo1);

// Create a small icon command
var commandInfo2 = new RibbonCommandInfo("Small icon button", "action2");
var ribbonIcon2 = new RibbonIcon(CommandIcon.Eplan);
commandInfo2.Icon = ribbonIcon2;
var command2 = customCommandGroup2.AddCommand(commandInfo2);

// Create a command without icon
var commandInfo3 = new RibbonCommandInfo("No icon button", "action3");
var command3 = customCommandGroup2.AddCommand(commandInfo3);

RibbonCommandInfo

Ribbon command actions can now be created using a  RibbonCommandInfo  object. This object contains all required and optional properties.

The mandatory properties are:

•   ActionCommandLine – This property value must be unique.
•   ButtonText

The optional properties are:

•   Description
•   Tooltip
•   Icon
•   IndexButtonPosition
•   MultiLangButtonText
•   MultiLangDescription
•   MultiLangTooltip

The  IndexButtonPosition  is used to specify the position in a  RibbonCommandGroup.

If they are not left empty, the multilingual properties are used over the corresponding non-multilingual properties in the GUI. If you want know more about how to use multilingual ribbon items, please refer to the "Adding multilingual ribbon items" chapter.

// Adding new commands using the RibbonCommandInfo
commandGroup = tab.AddCommandGroup("commands with RibbonCommandInfo");
RibbonCommandInfo ribbonCommandInfo = new RibbonCommandInfo("buttonText", "actionCommandLine");
commandGroup.AddCommand(ribbonCommandInfo);

Add existing Eplan actions to a custom CommandGroup

It is possible to add existing Eplan ribbon command actions to a custom  CommandGroup  via their  Command.ID.

The corresponding internal icon is automatically added to the action.

// Adding an existing Eplan command action by its ID
const int commandId = 35089;
var tab = ribbonBar.AddTab("CustomTab");
var commandGroup = tab.AddCommandGroup("Group1");
var commandAction = commandGroup.AddCommandWithId(commandId);

To find the correct  Command.ID  value for the command, you can check the description log in the Eplan Diagnostics dialog after calling this action from the ribbon (to show the Diagnostics Dialog press [Ctrl] + [VK_OEM_5]. [VK_OEM_5] corresponds to the [^] key on a German keyboard or to the [\] on a United States 101 keyboard.):

Dropdown buttons with subbuttons

You can now add dropdown buttons that, when clicked, open a list of subbuttons.  For this, the  RibbonCommandInfo  object now provides the new  IsDropdownRoot  and  IsSplitButton  properties.

In order to create a dropdown button, you first need to create the so-called root command—that is, the part of the dropdown button that remains visible when the dropdown is closed. To do this, use the  IsDropdownRoot  property. The default value of the  IsDropdownRoot  property is "FALSE". Therefore, this property must be set to "TRUE" only for the root command. The  subbuttons are created in the same way as normal buttons. Then, they are added to the root command using the  RibbonCommand.AddSubCommand  method. This step identifies them as subbuttons in a dropdown list. Please see the following example:

var customTab = new RibbonBar().AddTab("New API tab");
var customCommandGroup = customTab.AddCommandGroup("New API command group");

// Create the root button
var rootCommandInfo = new RibbonCommandInfo("Dropdown root button", "action0");
rootCommandInfo.IsDropdownRoot = true; // Set this command as the root command of the dropdown
rootCommandInfo.IsSplitButton = true; // The root button is a split button
var ribbonIcon = new RibbonIcon(CommandIcon.Eplan);
ribbonIcon.IsLarge = true;
rootCommandInfo.Icon = ribbonIcon;

// Create the subbuttons
// Subbutton 1
var subCommandInfo1 = new RibbonCommandInfo("Dropdown subbutton 1", "action1");
var ribbonIconSub1 = new RibbonIcon(CommandIcon.Circle_1);
subCommandInfo1.Icon = ribbonIconSub1;

// Subbutton 2
var subCommandInfo2 = new RibbonCommandInfo("Dropdown subbutton 2", "action2");
var ribbonIconSub2 = new RibbonIcon(CommandIcon.Circle_2);
subCommandInfo2.Icon = ribbonIconSub2;

// Subbutton 3
var subCommandInfo3 = new RibbonCommandInfo("Dropdown subbutton 3", "action3");
var ribbonIconSub3 = new RibbonIcon(CommandIcon.Circle_3);
subCommandInfo3.Icon = ribbonIconSub3;

// Put dropdown list together
var rootCommand = customCommandGroup.AddCommand(rootCommandInfo);
var subCommand1 = rootCommand.AddSubCommand(subCommandInfo1); // Assigning subbutton 1 to the dropdown root button
var subCommand2 = rootCommand.AddSubCommand(subCommandInfo2); // Assigning subbutton 2 to the dropdown root button
var subCommand3 = rootCommand.AddSubCommand(subCommandInfo3); // Assigning subbutton 3 to the dropdown root button

The root button of the dropdown list can be a button whose sole purpose is to open the dropdown list. Hovering over such a standard dropdown root button (without clicking) will look like this:

However, the root botton of a dropdown list can also be a split button. A split button combines two functions: The split button’s surface is divided into two sections. While clicking the part of the split button with the small arrow opens the dropdown list, clicking the other section performs an action and thus functions as a regular button itself. When you hover over a split button with the mouse, its two sections are displayed:

To turn a root button into a split button, the  IsSplitButton  property must be set to "TRUE", as shown in the code example above. By default, it is set to "FALSE", resulting in a standard dropdown root button. Consequently, the  RibbonCommandInfo.ActionCommandLine  property is not considered for a standard dropdown root button. Therefore, the property value can be set to an empty string and does not have to be unique in this special case.

Like any other button, a dropdown root button can be created with a small icon, a large icon, or no icon at all. The subbuttons can only be created with small icons or without any icons.

SVG Icons limitations

Our UI libraries provide  SVG  support with the following limitations:

   • Scripts, interactions and external objects are not implemented for security reasons.

   • Animations, videos, sounds and internal images are not implemented.

   • Since  SVG  icons should be small and fast to render, we disabled the following  SVG  elements that can significantly affect drawing performance:

       -  <pattern>

       -  <color-profile>

       -  <hkern>

       -  <hatch>

       -  <hatchpath>

       -  all effects, blend mode and filters

       -  compressed  SVG  files (SVGz)

It is strongly recommended to use only simplified ("optimized")  SVG: All elements such as text or shapes should be converted to paths and all paths should be combined.
The simplified  SVG  is small and fast-drawing. In addition, it will be very difficult to "reverse engineer" your media in this case.