Eplan Platform API
EPLAN API / User Guide / API Miscellaneous / Ribbon bar
In This Topic
    Ribbon bar
    In This Topic

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

    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:

    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 following places:

    Menu and toolbar migration

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

    The following table shows how to create new ribbon items and provides 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 counterparts:

    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

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

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

     

    RibbonIcons

    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=\"BCGSoft_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:

     

     

    RibbonCommandInfo

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

    The optional properties are  Description,  Tooltip,  Icon,  IndexButtonPosition,  MultiLangButtonText,  MultiLangDescription  and  MultiLangTooltip.

    The multilanguage properties are used over the non-multilanguage properties if they are not empty.

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

    // 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.):

     

     

    SVG Icons limitations

    BCGSoft 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.

     

     

    See Also

    Scripts

    Adding ribbon items by a script

    Addins

    Adding ribbon commands

     

     

    EPLAN API , 27.08.2024, © by EPLAN GmbH & Co. KG. All rights reserved.

    Use the Eplan Global Support Portal for feedback and support