Script functions, attributes and objects - on drop scripts for diagrams
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 Studio, 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 objects and attributes you can use in an On Drop script depends on whether the script is for a diagram or item:
• For a diagram, the script is called when a drag-and-drop operation or a copy-and-paste operation is performed on the associated diagram in the diagram editor.
• For an item, the script is called when an item is copied or moved to the associated item in a pane.
For Diagrams
An On Drop script can include the following functions for changing the on drop behavior of a diagram (including link reconnections) or item. All script must be within one or more of the following functions.
• For validating the drop and interacting with the user (for example, opening selection dialogs and displaying messages), use the ValidDrop function.
• For making updates to the model, use the OnDrop function.
To open a topic that has a script template for on drop scripts for diagrams, see
Script template for on drop scripts for diagrams. The script template includes the preceding functions (empty).
Note that you cannot share values of variables between the ValidDrop and OnDrop functions.
These functions are case sensitive and cannot be used in any other scripts.
• ValidDrop Script function - for an associated diagram, this function is called when a drag-and-drop operation is performed on the diagram in the diagram editor.
Use this function to validate the drag-and-drop operation. This function is run outside of the On Drop script transaction, so its script should not make any changes to the Model.
Do not use the ValidDrop function to make changes to the model, because the user will have to perform a refresh to see the changes, and the changes cannot be undone.
This function can use the following objects and attributes:
◦ Diagram object - is the diagram on which the dragged item is dropped.
◦ DroppedItem object - is the item that is dragged.
Example code:
if DroppedItem("ClassName")="Attribute" or DroppedItem("ClassName")="Role" then if not DroppedItem.item("stereotype","OperationalNode") is nothing then DropResult("Anonymous")="TRUE" end if end if
◦ Script.AffectedItem Script object - is the item that is affected when an item is dropped. For example, if you drag a Class to a Class Operation on a Class Diagram, the AffectedItem is the Operation (the HitSymbol is the Class symbol).
Note that if a diagram symbol is moved a short distance, the AffectedItem can be the item that is being dragged.
See also Script.HitSymbol.
◦ Script.DisconnectedSymbol script attribute – when reconnecting a link, this is the item that was previously connected to the link. If the link was not previously connected to an item, DisconnectedSymbol is set to nothing.
◦ Script.DropEffect script attribute that determines which mouse pointer is shown:
DropEffect is typically set to 0 when a link symbol is being reconnected.
DropEffect is typically set to 1 when an item is being created through an item or symbol drop, including copies. DropEffect is also set to 1 when setting the type of an item on a Structure Diagram.
DropEffect is typically set to 2 when an item or symbol is being moved. DropEffect is also set to 2 when creating a Port on a Structure Diagram.
DropEffect is typically set to 4 when a new symbol is being created to show an existing item that is being dropped from a pane. DropEffect is also set to 4 when creating a Part on a Structure Diagram and when assigning an item to a Note on a diagram.
◦ Script.HitSymbol Script object - is the item on which the dragged item is dropped. For example, if you drag a Class to a Class Operation on a Class Diagram, the HitSymbol is the Class symbol (the AffectedItem is the Operation). If the dragged item is dropped on to the diagram background, HitSymbol is set to the diagram.
Note that if a diagram symbol is moved a short distance, the HitSymbol can be the item that is being dragged.
See also Script.AffectedItem.
◦ Script.PasteAtX Script attribute - is the X coordinate at which the dragged item is dropped.
◦ Script.PasteAtY Script attribute - is the Y coordinate at which the dragged item is dropped.
If the ValidDrop function returns FALSE, the operation is abandoned.
• OnDrop Script function - This function is called after the ValidDrop function has been called.
Use this function to make updates to the model. 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 OnDrop function to interact with users, because items in the model will be locked and unavailable to other users while that interaction takes place.
This function can use the following object:
◦ Diagram object - is the diagram on which the dragged item is dropped.
◦ DroppedItem object - is the item that is dragged.
Example code:
if DroppedItem("ClassName")="Attribute" or DroppedItem("ClassName")="Role" then if not DroppedItem.item("stereotype","OperationalNode") is nothing then DropResult("Anonymous")="TRUE" end if end if
◦ DropResult object - is usually the symbol that is created from the drop, but it can sometimes be the dragged item.
Example code:
if DroppedItem("ClassName")="Attribute" or DroppedItem("ClassName")="Role" then if not DroppedItem.item("stereotype","OperationalNode") is nothing then DropResult("Anonymous")="TRUE" end if end if
◦ Script.AffectedItem Script object - is the item that is affected when an item is dropped. For example, if you drag a Class to a Class Operation on a Class Diagram, the AffectedItem is the Operation (the HitSymbol is the Class symbol).
Note that if a diagram symbol is moved a short distance, the AffectedItem can be the item that is being dragged.
See also Script.HitSymbol.
◦ Script.DisconnectedSymbol script attribute – when reconnecting a link, this is the item that was previously connected to the link. If the link was not previously connected to an item, DisconnectedSymbol is set to nothing.
◦ Script.DropEffect script attribute that determines which mouse pointer is shown:
DropEffect is typically set to 0 when a link symbol is being reconnected.
DropEffect is typically set to 1 when an item is being created through an item or symbol drop, including copies. DropEffect is also set to 1 when setting the type of an item on a Structure Diagram.
DropEffect is typically set to 2 when an item or symbol is being moved. DropEffect is also set to 2 when creating a Port on a Structure Diagram.
DropEffect is typically set to 4 when a new symbol is being created to show an existing item that is being dropped from a pane. DropEffect is also set to 4 when creating a Part on a Structure Diagram and when assigning an item to a Note on a diagram.
◦ Script.HitSymbol Script object - is the item on which the dragged item is dropped. For example, if you drag a Class to a Class Operation on a Class Diagram, the HitSymbol is the Class symbol (the AffectedItem is the Operation). If the dragged item is dropped on to the diagram background, HitSymbol is set to the diagram.
Note that if a diagram symbol is moved a short distance, the HitSymbol can be the item that is being dragged.
See also Script.AffectedItem.
◦ Script.PasteAtX Script attribute - is the X coordinate at which the dragged item is dropped.
◦ Script.PasteAtY Script attribute - is the Y coordinate at which the dragged item is dropped.
The Dictionary object is not available within an OnDrop function.
If the OnDrop function returns FALSE, the operation is abandoned.
