Script functions, attributes and objects - diagram toolbar button script for adding links
In addition to the standard Modeler automation interface functions, objects and attributes, there are special functions, objects and attributes you can use in the scripts of Stereotypes and Script items. For general information about extensibility scripts, including information about the Modeler, Projects, ActiveProject and Dictionary objects that are available in most script functions, see
Script functions, attributes and objects - overview.
To write scripts you require a good working knowledge of the VBScript language, the Modeler Meta Model and the ModelerAutomation Interface.
If you run a script that has errors, those errors can cause Modeler to crash and corrupt Modeler model data.
The Diagram Toolbar Button script functions you use depend on whether the toolbar button is adding a node or link.
For Adding Links
A Diagram Toolbar Button script can include the following functions for adding links to a diagram. All script must be within one or more of the following functions.
• For validating the source item, use the ValidOrigin function.
• For validating the destination item, use the ValidDestination function.
• For selecting an Association or Dependency to add to the diagram through the script rather than the default context menu, use the SelectObject function.
• For modifying the link or its item after adding the link to the diagram, use the OnFinished function.
Make all updates to the model through the OnFinished function. If any of the other functions make changes to the model, those changes will not be seen in Modeler until a refresh is performed, and the changes cannot be undone through an Edit Undo operation.
These functions are case sensitive, are called in the order listed, and cannot be used in any other scripts.
• ValidOrigin Script function - after clicking the toolbar button, this function is called when the user clicks the diagram background or the source diagram item. Example code:
Function ValidOrigin() set HitSymbol = Script.HitSymbol strType = HitSymbol("Type") If strType = "Class" Then ValidOrigin = true Else ValidOrigin = False End If End Function
Use this function to validate the source item a user has clicked. This function can use the following objects:
◦ Diagram object - is the diagram that is active when clicking the toolbar button.
◦ Script.Flags Script attribute - the bit values of this attribute are set according to which mouse button was clicked and whether the Shift or Control keys were pressed while that mouse button was clicked.
Left mouse button sets 0x0001
Right mouse button sets 0x0002
Shift key sets 0x0004
Control key sets 0x0008
Middle mouse button sets 0x0010
◦ Script.HitSymbol Script object - is the source symbol that is clicked on the diagram after clicking the toolbar button. If the diagram background is clicked, HitSymbol is set to nothing. Example code:
Function ValidOrigin() Set HitSymbol = Script.HitSymbol strType = HitSymbol("Type") If strType = "Class" Then ValidOrigin = true Else ValidOrigin = False End If End Function
◦ Script.PasteAtX script attribute - this script attribute is the cursor's absolute x-position at which the mouse button was clicked.
◦ Script.PasteAtY script attribute - this script attribute is the cursor's absolute y-position at which the mouse button was clicked.
If the ValidOrigin function returns FALSE, the toolbar operation is abandoned.
• ValidDestination Script function - after clicking the toolbar button and then clicking the source item, this function is called when the user clicks the diagram background or the destination diagram item. The ValidOrigin function is called before calling this function. Example code:
Function ValidDestination() Set HitSymbol = Script.HitSymbol strType = HitSymbol("Type") If strType = "Class" Then ValidDestination = true Else ValidDestination = False End If End Function
Use this function to validate the destination item a user has clicked. This function can use the following objects:
◦ Diagram object - is the diagram that is active when clicking the toolbar button.
◦ Script.Flags Script attribute - the bit values of this attribute are set according to which mouse button was clicked and whether the Shift or Control keys were pressed while that mouse button was clicked.
Left mouse button sets 0x0001
Right mouse button sets 0x0002
Shift key sets 0x0004
Control key sets 0x0008
Middle mouse button sets 0x0010
The following script demonstrates how you can determine whether the left mouse button or right mouse buttons has been pressed:
If ((Script.Flags AND 2) = 0) Then Msgbox "Left" Else Msgbox "Right" End If
◦ Script.HitSymbol Script object - is the destination symbol that is clicked on the diagram after clicking the toolbar button and clicking a source item. If the diagram background is clicked, HitSymbol is set to nothing. Example code:
Function ValidDestination() Set HitSymbol = Script.HitSymbol strType = HitSymbol("Type") If strType = "Class" Then ValidDestination = true Else ValidDestination = False End If End Function
◦ Script.OriginSymbol Script object - is the source symbol that is clicked on the diagram after clicking the toolbar button. If the diagram background was clicked, OriginSymbol is set to nothing.
◦ Script.PasteAtX script attribute - this script attribute is the cursor's absolute x-position at which the mouse button was clicked.
◦ Script.PasteAtY script attribute - this script attribute is the cursor's absolute y-position at which the mouse button was clicked.
If the ValidDestination function returns FALSE, the toolbar operation is abandoned.
• SelectObject script function - this function is called after the ValidOrigin and ValidDestination script functions have been called.
This function applies only to Associations and Dependencies.
When you add an Association or Dependency between two symbols, Modeler checks to see if there are any Associations or Dependencies that exist between those two symbols:
◦ If no Associations or Dependencies exist between the two symbols, Modeler creates a new Association or Dependency.
◦ If Associations or Dependencies exist between the two symbols and all those Associations or Dependencies are shown on the diagram, Modeler creates a new Association or Dependency.
◦ If Associations or Dependencies exist between the two symbols and not all those Associations or Dependencies are shown on the diagram, Modeler opens a popup menu so that you can choose an unshown Association or Dependency to add to diagram. The popup menu has a New command, so that you can create a new Association or Dependency on the diagram.
If you are working with stereotyped Associations or Dependencies and want only appropriately stereotyped Associations or Dependencies to be made available for selection, you can use the SelectObject script function to control the selection of an Association or Dependency, rather than the default popup menu.
When adding an Association or Dependency between two symbols, the SelectObject script function is called when the following conditions are true: Associations or Dependencies exist between the two symbols and not all those Associations or Dependencies are shown on the diagram and there is a SelectObject script function defined. When the SelectObject script function is called, Modeler does not display the popup menu.
In the SelectObject script function, you can open a dialog to select an Association or Dependency through the SelectObjectOfStereotype and SelectObjectOfType automation interface functions.
• If you want to create a new Association or Dependency through the SelectObject script function, you must set a name: Modeler will then ignore the name you set and create a new Association or Dependency using a default name.
• If the SelectObject script function does not set a result object or new object name, the toolbar operation is abandoned.
This function can use the following objects and script attributes:
◦ Diagram object - is the diagram that is active when clicking the toolbar button.
◦ Script.AddResultObject script attribute - returns the Association or Dependency that was specified through the SelectObject script function.
◦ Script.NewItemName object - specifies a name for a new link created through the Select Object dialog.
◦ Script.HitSymbol Script object - is the destination item that is clicked on the diagram.
◦ Script.OriginSymbol Script object - is the source item for a link that is being added to a diagram.
• OnFinished Script function - this function is called after the preceding functions have been called, after adding a node or link to the diagram. Example code:
In this example, ClassST is a model object reference.
Function OnFinished() set NewClass = NewSymbol.Item("Dict Item") call NewClass.Add("Stereotype", ClassST) OnFinished = True End Function
Use this function to modify the symbol or its item, after adding the symbol to the diagram. For example, you may want to conditionally change a property of an item or apply a Stereotype to the item.
This function is run as a transaction, so any changes made by the script are immediately seen in Modeler, and the changes can be undone.
Do not use the OnFinished function to interact with users (for example, displaying messages), because items in the model will be locked and unavailable to other users while that interaction takes place.
This function can use the following objects:
◦ Script.DestinationSymbol Script object - is the destination item for a link that is being added to a diagram. Note that you cannot use the Script.DestinationSymbol script object for Provided Interface or Required Interface links, instead use the script.HitSymbol script object.
◦ Diagram object - is the diagram that is active when clicking the toolbar button.
◦ Script.HitSymbol Script object - is the destination item that is clicked on the diagram. If the diagram background is clicked, HitSymbol is set to nothing.
◦ NewSymbol object- is the symbol that is being added to the diagram. Example code:
In this example, ClassST is a model object reference.
Function OnFinished() set NewClass = NewSymbol.Item("Dict Item") call NewClass.Add("Stereotype", ClassST) OnFinished = True End Function
Note that the NewSymbol object is not used by Custom Link toolbar button scripts.
◦ Script.OriginSymbol Script object - is the source item for a link that is being added to a diagram.
◦ DictItem object - is the dictionary item that is being added to a diagram.
Note that the DictItem object is not used by Custom Link toolbar button scripts.
◦ Script.AddedSymbol script object - this script attribute applies only to Custom Node and Custom Link toolbar button scripts. This script object specifies the node symbol that is created by the OnFinished function. When adding links, the AddedSymbol must be a link symbol.
This script object specifies the new symbol that that was created by the script in the OnFinished function. When adding links, the AddedSymbol must be a link symbol, such as CD::Dependency.
It is the script's responsibility to create the link symbol, link it to its dictionary item (if required) and set the AddedSymbol script object to that new symbol. Failure to do this will result in script errors.
Note that you can only create link symbols that can normally be created on that particular diagram. For example, you cannot create a CD::Association between a CD::Package and a CD::Class on a Class Diagram.
◦ Script.SelectedDictionaryItem script object - this script attribute applies only to Custom Node and Custom Link toolbar button scripts. This script object is the item that has been set through the AddResultObject script attribute in the SelectObject function.
Note that the script must create the dictionary item and set the SelectedDictionaryItem script object script object to that dictionary item.
◦ Script.ReverseWaypoints script attribute - this script attribute applies only to Custom Link toolbar button scripts. This Boolean script attribute is used to ensure waypoints are created correctly when the direction of a link is reversed, that is, the first item clicked becomes the target for the link.
The Dictionary object is not available within an OnFinished function.
If the OnFinished function returns FALSE, the toolbar operation is abandoned.
