Customizing Tools and the Toolbox

  • Article

You must define toolbox items for the elements that you want to let users add to their models. There are two kinds of tools: element tools and connection tools. In the generated designer, a user can select an element tool to drag shapes to the diagram, and then select a connection tool to draw links between the shapes. In general, element tools let users add instances of domain classes to their models, and connection tools let them add instances of domain relationships.

Modifying Toolbox Tabs

By default, there is one tab in the generated designer toolbox, and the text in the tab header is the name of the domain-specific language. If you want to display different header text, in the DSL Explorer expand the Editor node, expand Toolbox Tabs, and select the toolbox tab, and then in the Properties window, set Tab Text to the text you want.

You can add tabs to the toolbox. Right-click the Editor node in the DSL Explorer, and then click Add New Toolbox Tab. Set the tab header by selecting the new toolbox tab, and then in the Properties window, setting a new value for Tab Text.

Note

If you change the toolbox layout, you may have to reset the Toolbox in the generated designer before the changes are displayed correctly. Right-click anywhere in the Toolbox, and then click Reset Toolbox. When a message box about custom toolbox settings appears, click Yes to continue.

Adding Element Tools to the Toolbox

The following procedure shows how to add an element tool to a domain-specific language designer.

To add an element tool to the Toolbox

  1. Create a Domain-Specific Language Tools solution by using the MinimalLanguage solution template. Name the solution ToolboxExample.

  2. Add a domain class named Comment.

  3. Add an embedding relationship from ExampleModel to Comment.

  4. Add a geometry shape named CommentShape.

  5. Map Comment to CommentShape by clicking Diagram Element Map in the Toolbox and, on the diagram, clicking Comment and then CommentShape.

  6. In the DSL Editor, expand the Editor node, then the Toolbox Tabs node, then the ToolboxExample node. By default, the name of the Toolbox tab in the generated designer for this solution is ToolboxExample.

  7. Right-click the ToolboxExample node, and then click Add New Element Tool.

  8. Name the new element tool CommentTool.

  9. Select CommentTool, and in the Properties window, set the Class value to Comment.

  10. Set the Toolbox Icon value to Resources\ExampleShapeToolBitmap.bmp.

  11. Save the solution and transform all templates by clicking the Transform All templates button in the header of Solution Explorer.

  12. Build and run the solution.

  13. In the new instance of Visual Studio, open the Sample diagram.

  14. You should see a Toolbox tab named ToolboxExample that contains a tool named CommentTool.

  15. You should be able to select CommentTool in the Toolbox and drag it to the diagram.

Adding Connection Tools to the Toolbox

The following procedure shows how to add a connection tool to a domain-specific language designer.

To add a connection tool to the Toolbox

  1. Open the Domain-Specific Language Tools solution that you created in the previous procedure.

  2. Add a reference domain relationship between ExampleElement and Comment and name it ExampleElementReferencesComments.

  3. Add a connector named CommentReferenceConnector.

  4. Map ExampleElementReferencesComments to CommentReferenceConnector by selecting Diagram Element Map in the Toolbox and, on the diagram, clicking ExampleElementReferencesComments and then CommentReferenceConnector.

  5. In the DSL Editor, expand the Editor node, then the Toolbox Tabs node, then the ToolboxExample node. By default, the name of the Toolbox tab in the generated designer for this solution is ToolboxExample.

  6. Right-click the ToolboxExample node, and then click Add New Connection Tool.

  7. Name the new connection tool CommentReferenceTool.

  8. Connection tools map to connection builders, not to specific classes or domain relationships. Select CommentReferenceTool, and then in the Properties window, set the value of the Connection Builder property to ExampleElementReferencesCommentsBuilder.

    For more information about connection builders, see Customizing Connection Builders.

  9. Set the Toolbox Icon value to Resources\ExampleConnectorToolBitmap.bmp.

  10. Set Source Cursor Icon (the icon that is used when you click the source element of the link) to Resources\ConnectorSourceSearch.cur. Set Target Cursor Icon (the icon that is used when you click the target element of the link) to Resources\ConnectorTargetSearch.cur.

  11. If you want to reverse the direction of the connection (that is, make the first element the target of the connection and the second element the source), set the Reverses Direction property to True.

  12. Save the solution and transform all templates by clicking the Transform All templates button in the header of Solution Explorer.

  13. Build and run the solution.

  14. In the new instance of Visual Studio, open the Sample diagram.

  15. You should see a Toolbox tab named ToolboxExample that contains a tool named CommentReferenceTool.

  16. You should be able to select CommentReferenceTool in the Toolbox to connect an ExampleElement to a Comment on the diagram.

Changing the Order of Toolbox Items

By default, the tools in the Toolbox will appear top to bottom in the order in which you have defined them. You can change this order by right-clicking the tool you want to move in the DSL Explorer, and then selecting Move Up or Move Down.

See Also

Other Resources

Domain-Specific Language Tools Glossary

Change History

Date

History

Reason

July 2008

Rewrote and refactored project.

Content bug fix.