Eplan Platform API
EPLAN API / User Guide / API Framework / Scripts / Adding ribbon items by a script
In This Topic
    Adding ribbon items by a script
    In This Topic

    A script can add one or items to the EPLAN ribbon. The convenient place to add these items is a function with [DeclareRegister] attribute, then the items are registered until the script is unloaded:

    public class RegisterRibbonItems
    {   
        string m_newTabName         = "New API tab";
        string m_commandGroupName     = "New API command group";
        string m_commandName         = "New API command";
               
        [DeclareRegister]
        public void registerRibbonItems()
        {               
            cleanItems();
            var newTab = new Eplan.EplApi.Gui.RibbonBar().AddTab(m_newTabName);
            var commandGroup = newTab.AddCommandGroup(m_commandGroupName);                              
            var command = commandGroup.AddCommand(m_commandName, "XPartsManagementStart");
        }
           
        [DeclareUnregister]
        public void unRegisterRibbonItems()
        {   
            cleanItems();
        }
       
        void cleanItems()
        {
            var newTab = new Eplan.EplApi.Gui.RibbonBar().Tabs.FirstOrDefault(item => item.Name == m_newTabName);
             if(newTab != null)
             {
                 var commandGroup = newTab.CommandGroups.FirstOrDefault(item => item.Name == m_commandGroupName);
                 if(commandGroup != null)
                 {
                     var command = commandGroup.Commands.Values.FirstOrDefault(item => item.Text == m_commandName);
                     if(command != null)   
                       
                    commandGroup.Remove();
                 }                         
                newTab.Remove();
             }
        }   
    }
    

    A ribbon command is always connected with an action, which is called, when the command is clicked. This means the script either additionally registers an action, or the command is assigned to an already existing action.

    Remarks

    Please mind, that users may start EPLAN in QUIET mode using W3u.exe /Quiet or the API could be initialized by an offline program. Because of this, it is not recommended to show .NET dialogs in the method marked by [DeclareRegister]. Please use Eplan.EplApi.Base.Decider class instead. If you encounter some problem during registering or initializing an script, just create and throw a BaseException or use BaseException.FixMessage(...) to add the message to the system messages list.

                
    The following example shows a script, which registers an action and a ribbon command. 
    public class ButtonWithAction
    {
        [DeclareAction("HelloWorldAction")]
        public void MyFunctionAsAction()
        {
           new Decider().Decide(EnumDecisionType.eOkDecision, "Hello World!", "HelloWorldAction title", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK);
           return;
        }
    
        [DeclareRegister]
        public void registerButtonWithAction()
        {
            var ribbonBar= new Eplan.EplApi.Gui.RibbonBar();
            ribbonBar.AddCommand("MyMenuText", "HelloWorldAction", 2);
        }
    
        [DeclareUnregister]
        public void unRegisterButtonWithAction()
        {
            var ribbonBar= new Eplan.EplApi.Gui.RibbonBar();
            ribbonBar.RemoveCommand("HelloWorldAction");
        }
    
    }
    
    Public Class ButtonWithAction
    
       <DeclareAction("HelloWorldAction")>  _
       Public Sub MyFunctionAsAction()
          Dim dec As Decider = New Decider
          dec.Decide(EnumDecisionType.eOkDecision, "Hello World!", "HelloWorldAction title", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK)
          Return
       End Sub 'MyFunctionAsAction
    
       <DeclareRegister()>  _
       Public Sub registerButtonWithAction()
          Dim ribbonBar As New Eplan.EplApi.Gui.RibbonBar()
          ribbonBar.AddCommand("MyMenuText", "HelloWorldAction", 2)
       End Sub 'registerButtonWithAction
    
       <DeclareUnregister()>  _
       Public Sub unRegisterButtonWithAction()
          Dim ribbonBar As New Eplan.EplApi.Gui.RibbonBar()
          ribbonBar.RemoveCommand("HelloWorldAction")
       End Sub 'unRegisterButtonWithAction
    
    
    End Class 'ButtonWithAction
    

     

    By the [DeclareRegister] attribute the function buttonWithAction() will be called during loading the script. The function creates a new ribbon command "MyMenuText" and binds it the action "HelloWorldAction". 

    See Also

    Addins

    API Miscellaneous