Script functions, attributes and objects - diagram toolbar button script for adding nodes

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 Modeler Automation 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.

A Diagram Toolbar Button script can include the following functions for adding items to a diagram. All script must be within one or more of the following functions.

• For validating the item that is clicked on the diagram, use the ValidInsertionPoint function.

• For creating an item that requires a linked item on creation, use the SelectType function.

• For modifying the symbol or its item after adding the symbol to the diagram, use the OnFinished function.

To open a topic that has a script template for diagram toolbar scripts for nodes, see Script template for diagram toolbar button scripts for nodes. The script template includes the preceding functions (empty).

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 shown, and cannot be used in any other scripts.

• ValidInsertionPoint Script function - after clicking the toolbar button, this function is called when the user clicks the diagram background or a diagram item. Example code:

Function ValidInsertionPoint()
set HitSymbol = Script.HitSymbol
If Not HitSymbol Is Nothing Then
ValidInsertionPoint = true
Else
ValidInsertionPoint = False
End If
End Function

Use this function to validate the item a user has clicked. This function can use the following objects and scripts attributes:

◦ 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.

The following script demonstrates how you can determine whether the left mouse button or right mouse buttons has been pressed:

◦ Script.HitSymbol Script object - is the item 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 ValidInsertionPoint()
set HitSymbol = Script.HitSymbol
If Not HitSymbol Is Nothing Then
ValidInsertionPoint = true
Else
ValidInsertionPoint = False
End If
End Function

◦ Script.AdditionalInfo Script attribute - this script attribute applies only when adding an Activity Partition to an Activity Diagram. This script attribute indicates how the Activity Partition is being added to the diagram:

1 - Means the Activity Partition is being added to the diagram background (Activity frame)

◦ 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.

• SelectObject Script function - after clicking the toolbar button, this function is called when the user right-clicks the diagram background or a diagram item. The ValidInsertionPoint function is called before calling this function. Example code:

Function SelectObject()
strId = Studio.SelectObjectOfStereotype (USECASEST("id"), true)
If strId = "" Then
SelectObject = False
Else
set Existing = ActiveProject.FindObject(strId)
If Existing Is Nothing Then
Script.NewItemName = strId
Else
Script.AddResultObject(Existing)
End If
End If

SelectObject = True
End Function

Use this function to specify an existing item to add to the diagram. You can open the Select Object dialog through the SelectObjectOfStereotype and SelectObjectOfType automation interface functions. This function can use the following objects and script attributes:

◦ Script.AddResultObject script attribute - called to specify the selected object. Example code:

◦ Script.HitSymbol Script object - is the item that is clicked on the diagram after clicking the toolbar button. If the diagram background is clicked, HitSymbol is set to the diagram.

1 - Means the Activity Partition is being added to the diagram background (Activity frame)

If the SelectObject function returns FALSE and the NewItemName object is not set, the toolbar operation is abandoned.

• SelectType Script function - called when creating an item that requires a linked item on creation. For example, when creating Parts, Ports and IO Flows on a Composite Structure Diagram; when creating action node items and object node items such as Call Behavior Actions and Data Stores on an Activity Diagram; when creating a Submachine on a State Diagram.

Note that the SelectType Script function is not used for Custom Node and Custom Link toolbar button scripts.

Use this function to specify the linked item for the item that is being added to the diagram.

If you want to create an untyped item (for example, a part or port), set the return value of the SelectType script function to TRUE, but do not set the NewItemName or AddResultObject script attributes.

If the SelectType function returns FALSE and the NewItemName object is not set, the toolbar operation is abandoned.

• 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:

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.

◦ Script.HitSymbol Script object - is the item that is clicked on the diagram. If the diagram background is clicked, HitSymbol is set to nothing.

Function OnFinished()
set NewClass = NewSymbol.Item("Dict Item")
call NewClass.Add("Stereotype", ClassST)
OnFinished = True
End Function

Note that the NewSymbol object is not valid when adding Attributes to a diagram, and is not used by Custom Node toolbar button scripts.

1 - Means the Activity Partition is being added to the diagram background (Activity frame)

◦ 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 nodes, the AddedSymbol must be a node symbol.

This script object specifies the new symbol that that was created by the script in the OnFinished function. When adding nodes, the AddedSymbol must be a node symbol, such as CD::Class.

It is the script's responsibility to create the node 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 node symbols that can normally be created on that particular diagram. For example, you cannot create an STRD::Part symbol 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.Script.PasteAtX script attribute - this script attribute is the cursor's absolute x-position at which the mouse button was clicked.

◦ Script.Script.PasteAtY script attribute - this script attribute is the cursor's absolute y-position at which the mouse button was clicked.