Macros and User Forms INTRODUCTION Toad Data Modeler supports macros. You can create a macro in Package Explorer or Script Explorer and modify its properties to display the macro either in main menu or pop-up menu (of particular object or on the Workspace etc.). Older Toad Data Modeler versions allowed you to define such macros via a script written in Script Editor. To execute the script directly, you simply selected the macro in the particular menu. Current BETA version is bringing some improvements for using macros - visual components for macros (User Forms). So, now when you select a macro, a user form can display. Examples of User Forms: Right-click the Workspace displays the Macros item. Two user macros are available there: Copyright: 2009 Quest Software, Inc. 1/12
Mark Procedures as Generate macro opens the following user form: Select the procedures for which you want to clear the Generate box. Click Close to execute the macro. Add Prefix macro opens the following user form: Define a prefix for attributes. Click Execute to execute the macro. These have just been examples of user forms that you can create on your own. User Forms - Brief Information: You can create and use user forms to interact with Toad Data Modeler during script and macro execution. You can enter input parameters or see some output information. Function Main only creates and displays the user form. Other functionalities must be implemented/added via form events or its controls. So, a form is not a dialog. Copyright: 2009 Quest Software, Inc. 2/12
MACRO Create Macro Use Case: You want to create a macro that will add a particular prefix to all attributes in your model. Solution: You will create a macro Add Prefix. The macro will be available via right-click menu on the Workspace. You want to create a user form where you will define the prefix and decide if you want to apply the change in Caption of attributes too. 1. Open Script Explorer. 2. Right-click the Macros item and select Add New Macro. 3. Right-click the new item and select Properties. 4. On tab General, define properties of the macro. Copyright: 2009 Quest Software, Inc. 3/12
Important! Name of macro mustn t contain spaces and other forbidden characters. The name must start with a character (not number). Then you can use characters, numbers or possibly _. The rules don t refer to caption. Caption can be any title you want. 5. On tab Visibility, select where you want to apply the macro Physical Model. 6. On tab Menu, define whether you want to display the macro in: - Macro menu, - pop-up menu, - both places. Parameter Path specifies position in main menu or pop-up menu. Feel free to define e.g. Test\My Items. In this example, you decide to display it only in pop-up menu. Path box is empty as Macros item is set as default. Copyright: 2009 Quest Software, Inc. 4/12
7. On tab Object Types, select in which object pop-up menu you want to display it. Select Workspace. 8. Confirm OK. Copyright: 2009 Quest Software, Inc. 5/12
9. Double-click the macro to open Script Editor. Modify the default code. function Main() var App = System.GetInterface("Application"); var Model = App.ActiveModel; var WS = App.ActiveWorkSpace; var Log = System.CreateObject("Log"); var form, lb, ed, chb; //Create form form = System.CreateForm('Form','Add Prefix to Attributes',200, 170); //Add script that should be executed after you click the Execute button form.executescriptname = 'AddPrefix'; form.executemethodname = 'Execute'; form.closeafterexecute = true; //Add component Label on the form lb = form.addcontrol('label', 5); lb.caption = 'Prefix:'; //Add component Edit on the form ed = form.addcontrol('edprefix', 1); ed.width = 160; //Add component Checkbox on the form chb = form.addcontrol('chbonlyname', 2); chb.caption = 'Modify Caption'; chb.checked = true; Copyright: 2009 Quest Software, Inc. 6/12
//Macro can be executed for Attributes, Model or Workspace //If macro is executed only for attributes, it relates only to selected attributes. var OnlyAttributes = true; var i, SelectObject; for(i=0; i<this.count;i++) SelectObject = This.GetObject(i); if (SelectObject.ObjectType!=2003) //2003 = Attribute OnlyAttributes = false; //Variable will be accessible also in event via calling Instance.VariableName (Instance.OnlyAttributes) form.adduservariable('onlyattributes',onlyattributes); //Registered objects will be accessible in events. form.registerobject(this, 'SelectedObjects'); form.registerobject(model,'model'); form.registerobject(log,'log'); form.showmodal(); function RenameAttribute(Attribute) Log.Information('Attribute has been renamed from "'+Attribute.Name+'" to "'+EdPrefix.Text+Attribute.Name+'"'); if (ChbOnlyName.Checked) Attribute.Caption = EdPrefix.Text+Attribute.Caption; else Attribute.Name = EdPrefix.Text+Attribute.Name; function Execute() var i, j, SelectObject, Ent; if (Instance.OnlyAttributes) for(i=0; i<selectedobjects.count;i++) SelectObject = SelectedObjects.GetObject(i); RenameAttribute(SelectObject); Copyright: 2009 Quest Software, Inc. 7/12
else for(i=0; i<model.entities.count; i++) Ent = Model.Entities.GetObject(i); for(j=0; j<ent.attributes.count; j++) SelectObject = Ent.Attributes.GetObject(j); RenameAttribute(SelectObject); Model.RefreshModel(); 10. Click Commit and Save. Result: Right-click the Workspace Macros Add Prefix to open the user form. Copyright: 2009 Quest Software, Inc. 8/12
FORM Create a Form To create a form, use the object System that is registered in every script. The method you need is called CreateForm and has four optional parameters: Example: var form = System.CreateForm( FormName, Form Caption, 200, 150); 1. First Parameter Name of form (it mustn t contain spaces and other invalid/not permitted characters). 2. Second Parameter Caption that will be displayed in the heading of the form. 3. Third Parameter Width of the form. 4. Fourth Parameter Height of the form. Functions of Form AddControl(ControlName: widestring, ControlType: Integer): IDispatch; - ControlName Name under which the control is accessible. - ControlType Number of control type that should be created. See the following table: - 1 - Edit Box - 2 - Check Box - 3 - Memo - 4 - Panel - 5 - Label - 6 - Group Box - 7 - Radio Button - 8 - Combo Box - 9 - List Box - 10 - Button This function adds control on the form. ShowModal() This function displays the form. Copyright: 2009 Quest Software, Inc. 9/12
Procedures of Form AddUserVariable(AName: widestring, DefaultValue) - AName Name under which a variable is accessible in events of forms. - DefaultValue Default value. It can be of types integer, widestring or boolean. This procedure adds a variable on the form. The variable is then accessible in events via calling the Instance.VariableName. The variable is accessible across events. If you change a content of the variable in one event, the changed status will be accessible in another event. RegisterObject(AName: widestring, AObject: IDispatch) - AName Name of object via which it will be accessible in events. - Aobject Object that is registered. Use this procedure to register objects in events. Properties of Form Caption Heading of the form. CloseAfterExecute True When you click Execute, the code will be executed and the form closed. False The form will not close after execution. False is set up by default. ExecuteMethodName Name of method that should be executed when you press the Execute button. ExecuteScriptName Name of script for calling out the method when you click the Execute button. Note: If you don t want to use the button Execute, do not set up the properties ExecuteMethodName and ExecuteScriptName. The button will not be visible on the form then. Copyright: 2009 Quest Software, Inc. 10/12
EVENTS To assign events, assign the component of particular event to properties of names NameEventScriptName, NameEventMethodName with reference to particular service method. Example: Button.OnClickScriptName = MyScript ; Button.OnClickMethodName = DoOnClick ; CONTROL Control is an ancestor from which all controls, including the form, inherit. Properties of Control Align Alignment of control. Possible values to use: 0 No alignment 1 Alignment - Top 2 Alignment - Bottom 3 Alignment - Left 4 Alignment - Right 5 Alignment Justify AnchorTop, AnchorBottom, AnchorLeft, AnchorRight Determines the position of control. Default place top left-hand corner. Parent Control on which a control is placed. Default position of all controls is on the form and this property is not set up. Note: Description of value Align 0..5: alnone - The control remains where it was placed. This is the default value. altop - The control moves to the top of its parent and resizes to fill the width of its parent. The height of the control is not affected. albottom - The control moves to the bottom of its parent and resizes to fill the width of its parent. The height of the control is not affected. alleft - The control moves to the left side of its parent and resizes to fill the height of its parent. The width of the control is not affected. alright - The control moves to the right side of its parent and resizes to fill the height of its parent. The width of the control is not affected. alclient - The control resizes to fill the client area of its parent. If another control already occupies part of the client area, the control resizes to fit within the remaining client area. Copyright: 2009 Quest Software, Inc. 11/12
BUTTON Event OnClick Occurs when you click the button. CHECKBOX Event OnClick Occurs when the check in checkbox is changed. COMBO-BOX Event OnSelect - Occurs when combo box is selected. EDIT Event OnChangeText Occurs when text in edit box is changed. MEMO Event OnChangeText Occurs when text in memo is changed. RADIO BUTTON Event OnClick Occurs when the button is selected. For more properties, please read the Reference Guide (Help menu Reference, Expert mode must be selected). See objects: UserButton, IUserCheckBox, IUserComboBox, UserControl, UserEdit, UserFormBasic, UserForm, UserGroupBox, IUserLabel, UserListBox, UserMemo, IUserPanel, UserRadioButton, UserStrings. Note: Reference Guide is not being updated for Beta versions. The document will be updated for next commercial release of Toad Data Modeler. Thank you. Copyright: 2009 Quest Software, Inc. 12/12