MACRO ENGINE USER GUIDE version 17.0 No Magic, Inc. 2011 All material contained herein is considered proprietary information owned by No Magic, Inc. and is not to be shared, copied, or reproduced by any means. All information copyright 2009-2011 by No Magic, Inc. CONTENTS MACRO ENGINE 2 1. Introduction 2 2. Working with Macro Engine 2 2.1 Selecting a Default Macro Language 2 2.2 Creating a Macro 4 2.3 Adding a Macro, Entering and Editing Macro Information 5 2.3.1 Opening Macro Information Dialog 5 2.3.2 Adding a Macro and Its Information 7 2.3.3 Editing Macro Information 11 2.3.4 Macro Information Dialog Mnemonic Keys 12 2.4 Deleting and Executing Macros 12 2.4.1 Deleting a Macro 12 2.4.2 Executing a Macro 13 2.4.3 Organize Macros Dialog Mnemonic Keys 15 2.5 Macro Keyboard Shortcuts 17 2.5.1 Assigning a Keyboard Shortcut to a Macro 19 2.5.2 Removing a Keyboard Shortcut from a Macro 19 2.6 Opaque Objects 20 2.6.1 Getting an Opaque Object 20 2.6.2 Getting Element Property Values 21 2.6.3 Setting Element Property Values 22 2.6.4 Getting the Child of an Element 25 2.6.5 Getting the Owner of an Element 26 2.6.6 Creating a New Element 26 2.6.7 Creating a Relationship Between Elements 26 2.6.8 Removing an Element 26 2.6.9 Adding a Stereotype to an Element 27 2.6.10 Removing a Stereotype from an Element 27 2.6.11 Printing Element Details 27 2.7 Recording Macros 28 3. Appendix 30 3.1 Using Code Completion to Develop BeanShell Scripts 30 3.2 Using NetBeans IDE to Develop Groovy Scripts 31 3.3 Using Eclipse to Develop Groovy Scripts 33 3.4 Installing Gems for JRuby 33 3.5 Adding a Scripting Language to MagicDraw 35 3.5.1 Script Filename Extension Filter 35 1 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE 1. Introduction Macro Engine (previously called Script Engine) in MagicDraw allows you to create your own macro (script) by using BeanShell, Groovy, JRuby, JavaScript, or Jython. With Macro Engine, you can control everything that is allowed in Open API, for example, transforming and manipulating models. You can find MagicDraw Open API in MagicDraw OpenAPI UserGuide.pdf in the manual directory and sample macros in <MagicDraw>/ samples/product features/macros. Macro Engine comes with Professional, Architect, and Enterprise Editions starting from MagicDraw version 16.6 and greater. Macro Engine for MagicDraw works with Java 6.0. 2. Working with Macro Engine 2.1 Selecting a Default Macro Language Use the Environment Options dialog to select a default macro language. To select a default macro language: 1. Click Options > Environment on the MagicDraw main menu (Figure 1). The Environment Options dialog will open (Figure 2). Figure 1 -- Environment Options Dialog Menu 2. Select the Macros node (Figure 2). 2 Copyright © 2009-2011 No Magic, Inc. MACRO ENGINE Working with Macro Engine Figure 2 -- Environment Options Dialog 3. Click the box next to the Default Macro Language box to see a list of supported programming languages (Figure 3). 3 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine Figure 3 -- Selecting a Macro Language 4. Select Jython, BeanShell, Groovy, JRuby, or JavaScript. 5. Click OK to save the selected language as the default macro language. NOTE: • JavaScript is the default macro language. • Macro Engine currently supports BeanShell, Groovy, JRuby, JavaScript, and Jython only. 2.2 Creating a Macro Once you have selected a default macro language, you can create a new macro by using the Create Macro dialog (Figure 4). The dialog allows you to specify a macro language, enter source code, and save it. To create a new macro: 1. Click Tools > Macros > Create Macro... on the MagicDraw main menu. The Create Macro dialog will open (Figure 4). 4 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine Figure 4 -- Create Macro Dialog 2. Select a macro language. 3. Enter source code in the text box. 4. Click Run to test and make sure that the source code works properly. 5. Click Save to open the Macro Information dialog (Figure 7) and follow the steps described in section 2.3.2 Adding a Macro and Its Information. 6. After clicking OK in the Macro Information dialog (Figure 7), the new macro will be saved in the location you have specified in the text box after File. 2.3 Adding a Macro, Entering and Editing Macro Information You can add a macro and enter all necessary information about your new macro to MagicDraw by following the steps described in sections 2.3.1 Opening Macro Information Dialog and 2.3.2 Adding a Macro and Its Information. 2.3.1 Opening Macro Information Dialog You can add or modify macro information, such the macro name and description, in the Macro Information dialog. To open the Macro Information dialog, you need to open the Organize Macros dialog first. To open the Organize Macros dialog: 1. Click Tools > Macros > Organize Macros... on the MagicDraw main menu (Figure 5). The Organize Macros dialog will open (Figure 6). 5 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine Figure 5 -- Organize Macros Dialog Menu Figure 6 -- Organize Macros Dialog To open the Macro Information dialog: 1. Click Tools > Macros > Organize Macros... on the MagicDraw main menu to open the Organize Macros dialog. 6 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine 2. Click Add (Figure 6). The Macro Information dialog will open. 2.3.2 Adding a Macro and Its Information Use the Add or Edit button in the Organize Macros dialog to add or edit a macro and its information in the Macro Information dialog. You can also press the mnemonic keys to add or edit a macro (see 2.4.3 Organize Macros Dialog Mnemonic Keys). To add a macro and enter macro information in the Macro Information dialog: 1. Click Tools > Macros > Organize Macros... on the MagicDraw main menu to open the Organize Macros dialog. 2. Click Add. The Macro Information dialog will open (Figure 7). NOTE: The Edit, Delete, Edit Code, and Run buttons in the Organize Macros dialog will be disabled if there is no macro in the table or if you do not select any macro from the table. 7 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine Figure 7 -- Macro Information Dialog 3. Type the macro name. 4. The default macro language you have previously selected (see 2.1 Selecting a Default Macro Language) will appear in the Macro Language box (Figure 7). 5. Click the ... button to locate a macro file. The Open file dialog will open (Figure 8). 6. Select the file and its type (there are 5 types of file filter: *.bsh, *.groovy, *.rb, *.js, or *.py) (Figure 9). If you do not select the Use path variables check box (Figure 8), the full pathname will be saved. 8 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine NOTE: If you have specified the file or network path in the Environment Options dialog by clicking Options > Environment > Path Variables and selected the Use path variables check box in Open dialog, the <Path Variable name> will show in front of the file pathname. This field is the [Required] field, for example, <mypath>/ <macro_name>.js. Figure 8 -- Use Path Variables Check Box 7. Click Open (Figure 9). The selected pathname will appear in the File box in the Macro Information dialog (Figure 10). Figure 9 -- Types of File Filter 9 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine Figure 10 -- Macro Information Dialog 8. Type the macro description in the Description box (Figure 10). NOTE: A macro name must be unique and cannot be duplicated. 9. Click Add to specify the arguments of the macro. The argument that is specified in the Arguments table will be the global variable of a specific macro. The Name is the name of a parameter, the Type is the type of the parameter, and the Array check box is to identify if the parameter is an array. NOTE: The parameter type can be String, Integer, Long, Double, Date, or ElementPath. 10. Type a keyboard shortcut that will be used to run the macro in the Press new shortcut key box and click Assign. The newly assigned keyboard shortcut will appear in the Current keys box. 1 0 Copyright © 2009-2011 No Magic, Inc.. MACRO ENGINE Working with Macro Engine 11. Click OK. The Organize Macros dialog will open, showing the newly added macro name, description, and keyboard shortcut. 12. Click Close to close the Organize Macros dialog. NOTE: • The macro name, filename, and language are required. • The macro description and keyboard shortcut are optional. • If any of the required fields are not filled in, a message will open: Please input all the required fields. • If a duplicate macro name is entered, an error message will open: The macro name has already been used, please input another name. 2.3.3 Editing Macro Information You can see macro information such as the macro name and description, as well as the keyboard shortcut for the macro in the Organize Macros dialog. To edit macro information: 1. Click Tools > Macros > Organize Macros... The Organize Macros dialog will open (Figure 11). Figure 11 -- Editing a Macro 2. Select a macro from the table and either click Edit or press Alt + E.