How to Use the PowerToy

This document discusses how to install the PowerToy and how to use it to configure multiple editors for a DSL.

For general information about this release, please go here.

How to Install

This release of the PowerToy is installed and configured in exactly the same way as the previous release.

WARNING: You MUST remove any previous versions of this PowerToy before installing this version (v.1.1).
If you have used a previous version of the PowerToy in your DSL's, please remove the PowerToy using the that previous version before installing this newer version.
This version is not backwardly compatible with previous versions.

Please follow the instructions in the How to Get Started section, then come back here to continue.
(Basically, you need to associate the PowerToy GAT package to your DSL solution before you can proceed)

How to Configure

To get started using the PowerToy, right-click on the solution in ‘Solution Explorer’ and select ‘Add DSL Editors’ from the context menu.
Note. You must have already enabled the 'DSL Editors PowerToy' guidance package for your DSL solution, in order for this command to appear on the solution context menu.

Add Recipe.png

A recipe runs, and the ‘Add DSL Editors’ wizard appears, where you define the configuration for your editors.

Note. Detailed technical information about this recipe, and how it works can be found here

Basic Configuration

Add Basic Config.png

The PowerToy needs to collect some basic information to install your editors, this configuration uses the defaults which are used by the DSL toolkit when your DSL solution was created.
  • Select the DSL package project of the DSL you wish to configure. (By default, this is a project with the name ‘DslPackage’)

Advanced Configuration

Add Advanced Config.png

The advanced configuration page contains optional information to customize the installation of the editors. You can use this if you don’t agree with the defaults, or you have somehow changed the structure and naming of the DSL projects created by default with your DSL solution.
  • Enter a folder path within the DSL package project to where the PowerToy will install its files. (By default, this will be a subfolder called ‘DslEditors’ at the root of the project).
  • Enter the full path the project CTC file. (By default, this file is located at ‘CtcComponents/Commands.ctc’)
Note. The settings you chose here will be preserved for later as defaults, should you wish to uninstall the Tool-window.
Once you have defined your configuration, press the ‘Finish’ button to complete the wizard. The wizard will configure your DSL solution.
Note. You can monitor this configuration progress in both the Output Window, and status bar of Visual Studio.

Default Configuration.png

The PowerToy will have added a number of templates, resources files etc. and configured your DSL project.

Generated Files.png

Press 'F5' to compile and run your DSL.

Single Editor ToolWindow.png

How to Configure Editors

The PowerToy comes ready-configured with a single editor using the default selection control. You are presented with a diagram containing the editor, with options to configure it or add/configure more editors.

Each editor defines its own custom control, icon and caption to display to the user. The user of your DSL can then switch between these editors using controls on a toolbar.

Editor Configuration.png

Simply add new editors to the diagram by dragging the 'DSL Editor' shape from the toolbox, or right-clicking on the diagram and selecting 'Add New DSL Editor', and then set its' properties in the 'Properties Window'.

Multiple Editor Configuration.png

How to Configure a Host for the Editors

The editors are, by default, hosted in a tool-window which appears with your DSL. You can also host the editors in place of the graphical designer of your DSL, should a forms-based designer be more appropriate to display your domain model. You customize the configuration of the host and layout by clicking the diagram and changing its settings in the 'Properties Window'.

Diagram Configuration.png

When multiple editors are configured, at runtime, the user switches editor using either buttons, or a dropdown in a toolbar, to the side or above, the editors at runtime. There are several options to the orientation of this toolbar and what controls are shown to help user switch the editors:
  • Vertically, using buttons to change the view

Multiple Editors ToolWindow (Vert).png
  • Horizontally, using a dropdown list to change the view.

Multiple Editors ToolWindow (HorzList).png
  • Horizontally, using tabs to change the view.

Multiple Editors ToolWindow (HorzTabsTop).png

Note. Once you have finished modifying configuration, you must 'Transform Templates' (in the normal way for DSL development) before compiling or running your DSL.

Designing Editors

For design purposes, it is possible to define an editor, but not 'Activate' it for use in the configuration. Each editor, has an 'Activate' property and when this is set to 'false', the editor is not enabled for use (no code is generated for it). The editor appears disabled (grayed out).

Deactivated Editors.png

The purpose of the 'Activate' property is to allow you to partially design editors, and quickly enable or disable them without having to delete their entire configuration.

Note. In this version of the PowerToy, the configuration for the editors is trivial. However, in subsequent releases, the design of editors will require a lot more configuration, which will provide a richer user experience, and this feature will have more importance.

Repair

You can re-run this recipe on the same DSL package project, and it will repair and restore the PowerToy configuration to its original state.

WARNING: In the repair, any modifications to any originally added files will be overwritten! However, any of your own files added to these folders will be preserved

How to Include PowerToy in your DSL Setup Project

The PowerToy adds a number of components which need to be registered with Visual Studio in order to work correctly at runtime (i.e. tool-windows, editors, menus, etc.).
At DSL development time, these components are automatically registered with Visual Studio when you build your DSL solution ('regpkg.exe' is executed on your DSL package project when rebuilt).

However, when you package (MSI) your DSL using the 'Setup Project' template (provided by the DSL tools) the extra components, added by the PowerToy, may not be automatically detected by the setup project.

Note. Typically, this issue occurs if you either: added the PowerToy after you added the setup project to your DSL solution, or you changed the hosting options of the PowerToy (i.e. Tool-window vs. Designer) during development.

Regardless of your actions, and which order you performed them, when you are ready to package your DSL solution, you simply need to 'Transform Templates' in your DSL solution.
This forces the setup project to regenerate all its (Wix) files, and auto-detect any components added by the PowerToy to the DSL solution.

How to Remove

The PowerToy provides a recipe to remove all installed files and configuration, eradicating the PowerToy from the DSL solution. This is good for those wishing to evaluate the PowerToy.

This recipe is only available on DSL package projects that have previously had a tool-window added to them.

Remove Recipe.png

WARNING: This recipe removes all originally added files (even if modified), and configuration by the PowerToy. However, any of your own files added to these folders will be preserved.

To remove the tool-window and its configuration, right-click on the DSL package project and select the ‘Remove DSL Editors’ from the context menu.

A recipe runs, and the ‘Remove DSL Editors’ wizard appears, where you inform it about the current configuration for your editors.

Note. Detailed technical information about this recipe, and how it works can be found here

Basic Configuration

Remove Basic Config.png

This recipe is initialized with the values you originally used to configure the editors:
  • Select the path to the folder where the PowerToy installed its files. (By default this would have been ‘DslEditors’)
  • Select the project CTC file. (By default, this would have been: ‘CtcComponents/Commands.ctc’)
  • Press the ‘Finish’ button to complete the wizard. The wizard will remove all configuration from your DSL.

Note. You can monitor this progress in both the Output Window, and status bar of Visual Studio.

How to Customize

To customize the added Tool-window, see the How to Customize page.

Feedback

Please provide any feedback you have about the PowerToy release, issues, bugs, features, design etc. here

Last edited May 19, 2007 at 7:03 PM by jezzsa, version 16

Comments

No comments yet.