Enterprise Architect User Guide Series Enterprise Architect Add-In Model Author: Sparx Systems Date: 30/06/2017 Version: 1.0 CREATED WITH Table of Contents Enterprise Architect Add-In Model 5 The Add-In Manager 6 Add-In Tasks 7 Create Add-Ins 8 Define Menu Items 9 Deploy Add-Ins 11 Tricks and Traps 13 Add-In Search 15 XML Format (Search Data) 16 Add-In Events 18 EA_Connect 19 EA_Disconnect 20 EA_GetMenuItems 21 EA_GetMenuState 22 EA_GetRibbonCategory 24 EA_MenuClick 25 EA_OnOutputItemClicked 27 EA_OnOutputItemDoubleClicked 28 EA_ShowHelp 29 Broadcast Events 30 Schema Composer Broadcasts 32 EA_GenerateFromSchema 33 EA_GetProfileInfo 34 EA_IsSchemaExporter 35 Add-In License Management Events 36 EA_AddinLicenseValidate 37 EA_AddinLicenseGetDescription 38 EA_GetSharedAddinName 39 Compartment Events 41 EA_QueryAvailableCompartments 42 EA_GetCompartmentData 44 Context Item Events 47 EA_OnContextItemChanged 48 EA_OnContextItemDoubleClicked 49 EA_OnNotifyContextItemModified 50 EA_FileClose 51 EA_FileNew 52 EA_FileOpen 53 EA_OnPostCloseDiagram 54 EA_OnPostInitialized 55 EA_OnPostOpenDiagram 56 EA_OnPostTransform 57 EA_OnPreExitInstance 58 EA_OnRetrieveModelTemplate 59 EA_OnTabChanged 61 Model Validation Broadcasts 62 EA_OnInitializeUserRules 63 EA_OnStartValidation 64 EA_OnEndValidation 65 EA_OnRunElementRule 66 EA_OnRunPackageRule 67 EA_OnRunDiagramRule 68 EA_OnRunConnectorRule 69 EA_OnRunAttributeRule 70 EA_OnRunMethodRule 71 EA_OnRunParameterRule 72 Model Validation Example 73 Post-New Events 79 EA_OnPostNewElement 80 EA_OnPostNewConnector 81 EA_OnPostNewDiagram 82 EA_OnPostNewDiagramObject 83 EA_OnPostNewAttribute 84 EA_OnPostNewMethod 85 EA_OnPostNewPackage 86 EA_OnPostNewGlossaryTerm 87 Pre-Deletion Events 88 EA_OnPreDeleteElement 89 EA_OnPreDeleteAttribute 90 EA_OnPreDeleteMethod 91 EA_OnPreDeleteConnector 92 EA_OnPreDeleteDiagram 93 EA_OnPreDeleteDiagramObject 94 EA_OnPreDeletePackage 95 EA_OnPreDeleteGlossaryTerm 96 Pre New-Object Events 97 EA_OnPreNewElement 98 EA_OnPreNewConnector 99 EA_OnPreNewDiagram 100 EA_OnPreNewDiagramObject 101 EA_OnPreDropFromTree 102 EA_OnPreNewAttribute 103 EA_OnPreNewMethod 104 EA_OnPreNewPackage 105 EA_OnPreNewGlossaryTerm 106 Tagged Value Broadcasts 107 EA_OnAttributeTagEdit 108 EA_OnConnectorTagEdit 109 EA_OnElementTagEdit 110 EA_OnMethodTagEdit 111 Technology Events 112 EA_OnInitializeTechnologies 113 EA_OnPreActivateTechnology 114 EA_OnPostActivateTechnology 115 EA_OnPreDeleteTechnology 116 EA_OnDeleteTechnology 117 EA_OnImportTechnology 118 Custom Views 119 Create a Custom View 120 Add a Portal 121 Custom Docked Window 122 MDG Add-Ins 123 MDG Events 124 MDG_Build Project 125 MDG_Connect 126 MDG_Disconnect 127 MDG_GetConnectedPackages 128 MDG_GetProperty 129 MDG_Merge 130 MDG_NewClass 133 MDG_PostGenerate 134 MDG_PostMerge 135 MDG_PreGenerate 136 MDG_PreMerge 137 MDG_PreReverse 138 MDG_RunExe 139 MDG_View 140 User Guide - Enterprise Architect Add-In Model 30 June, 2017 Enterprise Architect Add-In Model The Add-In facility provides a means of extending Enterprise Architect, allowing the programmer to enhance the user interface by adding new menus, sub menus, windows and other controls to perform a variety of functions. An Add-In is an ActiveX COM object that is notified of events in the user interface, such as mouse clicks and element selections, and has access to the repository content through the Object Model. Add-Ins can also be integrated with the license management system. Using this powerful facility, you can extend Enterprise Architect to create new features not available in the core product, and these can be compiled and easily distributed to a community of users within an organization, or more broadly to an entire industry. Using the Add-In facility it is even possible to create support for modeling languages and frameworks not supported in the core product. Add-Ins have several advantages over stand-alone automation clients: · Add-Ins can (and should) be written as in-process (DLL) components; this provides lower call overhead and better integration into the Enterprise Architect environment · Because a current version of Enterprise Architect is already running there is no requirement to start a second copy of Enterprise Architect via the automation interface · Because the Add-In receives object handles associated with the currently running copy of Enterprise Architect, more information is available about the current user's activity; for example, which diagram objects are selected · You are not required to do anything other than to install the Add-In to make it usable; that is, you do not have to configure Add-Ins to run on your systems · Because Enterprise Architect is constantly evolving in response to customer requests, the Add-In interface is flexible · The Add-In interface does not have its own version, rather it is identified by the version of Enterprise Architect it first appeared in; for example, the current version of the Enterprise Architect Add-In interface is version 2.1 · When creating your Add-In, you do not have to subscribe to a type-library (Add-Ins created before 2004 are no longer supported - if an Add-In subscribes to the Addn_Tmpl.tlb interface (2003 style), it fails on load; in this event, contact the vendor or author of the Add-In and request an upgrade) · Add-Ins do not have to implement methods that they never use · Add-Ins prompt users via context menus in the tree view and the diagram · Menu check and disable states can be controlled by the Add-In Add-Ins enhance the existing functionality of Enterprise Architect through a variety of mechanisms, such as Scripts, UML Profiles and the Automation Interface. Once an Add-In is registered, it can be managed using the Add-In Manager. (c) Sparx Systems 2015 - 2017 Page 5 of 141 Created with Enterprise Architect User Guide - Enterprise Architect Add-In Model 30 June, 2017 The Add-In Manager If you want to check what Add-Ins are available on your system, and enable or disable them for use, you can review the 'Add-In Manager' dialog. This dialog lists the Add-Ins that have been registered on your system, and their current status (Enabled or Disabled). Access Ribbon Extend > Configure > Manage Add-Ins Enable/disable Add-Ins Action Detail Enable an Add-In To enable an Add-In so that it is available for use, select the 'Load on Startup' check box corresponding to the name. Click on the OK button. · Any Add-In specific features, facilities and Help are made available through the 'Extensions | <add-in name>' context menu option · Any defined Add-In windows are populated with information; select 'Extend > Configure > Add-In Windows' Disable an Add-In To disable an Add-In so that it is not available for use, clear the 'Load on Startup' check box corresponding to the name. Click on the OK button. All menu options, features and facilities specific to the Add-In are hidden and made inactive. Notes · When you enable or disable an Add-In, you must re-start Enterprise Architect to action the change (c) Sparx Systems 2015 - 2017 Page 6 of 141 Created with Enterprise Architect User Guide - Enterprise Architect Add-In Model 30 June, 2017 Add-In Tasks This topic provides instructions on how to create, test, deploy and manage Add-Ins. Create an Add-In Task Create an Add-In. Define Menu Items. Respond to Menu Events. Handle Add-In Events. Deploy your Add-In Task Potential Pitfalls. Manage Add-Ins Task Register an Add-In (developed in-house or brought-in). The Add-In Manager. (c) Sparx Systems 2015 - 2017 Page 7 of 141 Created with Enterprise Architect User Guide - Enterprise Architect Add-In Model 30 June, 2017 Create Add-Ins Before you start you must have an application development tool that is capable of creating ActiveX COM objects supporting the IDispatch interface, such as: · Borland Delphi · Microsoft Visual Basic · Microsoft Visual Studio .NET You should consider how to define menu items. To help with this, you could review some examples of Automation Interfaces - examples of code used to create Add-Ins for Enterprise Architect - on the Sparx Systems web page. Create an Enterprise Architect Add-In Step Action 1 Use a development tool to create an ActiveX COM DLL project. Visual Basic users, for example, choose File-Create New Project-ActiveX DLL. 2 Connect to the interface using the syntax appropriate to the language. 3 Create a COM Class and implement each of the general Add-In Events applicable to your Add-In. You only have to define methods for events to respond to. 4 Add a registry key that identifies your Add-In to Enterprise Architect, as described in the Deploy Add-Ins topic. (c) Sparx Systems 2015 - 2017 Page 8 of 141 Created with Enterprise Architect User Guide - Enterprise Architect Add-In Model 30 June, 2017 Define Menu Items Tasks Task Detail Define Menu Items Menu items are defined by responding to the GetMenuItems event. The first time this event is called, MenuName is an empty string, representing the top-level menu. For a simple Add-In with just a single menu option you can return a string. Function EA_GetMenuItems(Repository as EA.Repository, MenuLocation As String, MenuName As String) As Variant EA_GetMenuItems = "&Joe's Add-In" End Function Define Sub-Menus To define sub-menus, prefix a parent menu with a dash. Parent and sub-items are defined like this: Function EA_GetMenuItems(Repository as EA.Repository, MenuLocation As String, MenuName As String) As Variant Select Case MenuName Case "" 'Parent Menu Item EA_GetMenuItems = "-&Joe's Add-In" Case "-&Joe's Add-In" 'Define Sub-Menu Items using the Array notation. 'In this example, "Diagram" and "Treeview" compose the "Joe's Add-In" sub-menu. EA_GetMenuItems = Array("&Diagram", "&Treeview") Case Else MsgBox "Invalid Menu", vbCritical End Select End Function Define Further Sub-Menus Similarly, you can define further sub-items: Function EA_GetMenuItems(Repository as EA.Repository, MenuLocation As String, MenuName As String) As Variant Select Case MenuName Case "" EA_GetMenuItems = "-Joe's Add-In" Case "-Joe's Add-In" EA_GetMenuItems = Array("-&Diagram", "&TreeView") Case "-&Diagram" EA_GetMenuItems = "&Properties" Case Else MsgBox "Invalid Menu", vbCritical End Select (c) Sparx Systems 2015 - 2017 Page 9 of 141 Created with Enterprise Architect User Guide - Enterprise Architect Add-In Model 30 June, 2017 End Function Enable/Disable menu To enable or disable menu options by default, you can use this method to show options particular items to the user: Sub EA_GetMenuState(Repository As EA.Repository, Location As String, MenuName As String, ItemName As String, IsEnabled As Boolean, IsChecked As Boolean) Select Case Location Case "TreeView" 'Always enable Case "Diagram" 'Always enable Case "MainMenu" Select Case ItemName Case "&Translate", "Save &Project" If GetIsProjectSelected() Then IsEnabled = False End If End Select End Select IsChecked = GetIsCurrentSelection() End Sub (c) Sparx Systems 2015 - 2017 Page 10 of 141 Created with Enterprise Architect