How to Customize the PowerToy

The following page describes the means to customize various areas of the components added to a DSL for this release.

If you are looking for help on getting started installing and using the PowerToy go here.

If you want a better understanding of how the PowerToy works, look at the Technical Design page.

Editor Hosting

Objective: To change the host for the DSL editors

In this release of the PowerToy the editors can be hosted either in a tool-window (displayed with the designer of the DSL), or, they can be hosted as a replacement for the graphical designer of your DSL. This is desirable in cases where a forms-based designer is more appropriate for your DSL, and you want to use the editors as this replacement designer.

If you want to replace the graphical designer of you DSL, complete the following steps:
  1. Open the 'DslDefinition.dsl' diagram for your DSL
  2. In the 'DSL Explorer' window, right-click on the 'Editor' node and click Delete.
  3. Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Custom Editor'
  4. Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Root Class' and 'FileExtension' (at minimum).
  5. Close the 'DslDefinition.dsl' diagram and save changes.
  6. Open the 'DslEditorsConfiguration.deptec' diagram
  7. Click anywhere on the diagram surface
  8. In the 'Properties Window', change the 'Hosting Style' property to 'Designer'.
  9. Save, Transform Templates, Rebuild and run.

To restore the default graphical designer for your DSL, complete the following reverse steps.
  1. Open the 'DslDefinition.dsl' diagram for your DSL
  2. In the 'DSL Explorer' window, right-click on the 'Custom Editor' node and click Delete.
  3. Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Designer'
  4. Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Diagram', 'Root Class' and 'FileExtension' (at minimum).
  5. Close the 'DslDefinition.dsl' diagram and save changes.
  6. Open the 'DslEditorsConfiguration.deptec' diagram
  7. Click anywhere on the diagram surface
  8. In the 'Properties Window', change the 'Hosting Style' property to 'ToolWindow'.
  9. Save, Transform Templates, Rebuild and run.

Note. It is valid to have a 'Custom Editor' forms-based designer already defined elsewhere in code for your DSL, and still host the editors in a tool-window along side that custom editor.

Change Editor Layout

Objective: To change the layout of the controls that switch between the editors (multiple editors only)

When multiple editors are configured, the PowerToy displays various navigation controls to switch between the views. Using either a column of buttons (vertical orientation), or a dropdown (horizontal orientation), and also a row of buttons next to the dropdown.

To change the layout and orientation of the controls, complete the following steps:
  1. Open the 'DslEditorsConfiguration.deptec' diagram
  2. Click anywhere on the diagram surface
  3. In the 'Properties Window', change the 'Navigation Style'.
  4. Save, Transform Templates, Rebuild and run.

IDE Integration

Change Menu Icons and Text

Objective: To change the icon and text used on either the top level menu (View | Other Windows), or the diagram context menu ('Details...').

In this release, the top level menu text is automatically generated from the 'ToolWindowTitle' property specified in the configuration language. This is to keep it in sync with the title of the tool-window and the name of the host DSL language.

To change the text of the top level menu, complete the following steps:
  1. Open the 'DslEditorsConfiguration.deptec' diagram
  2. Click anywhere on the diagram surface
  3. In the 'Properties Window', change the 'ToolWindow Title'
  4. Save, Transform Templates, Rebuild and run.

Changing the icon of the top level menu, or the text of the diagram context menu, is done in the same way as described in previous release.

Change Tool-window Appearance

Objective: To change the appearance of the tool-window (i.e. bitmap and title).

In this release of the PowerToy, basic customization of the tool-window's appearance is done in the configuration designer.

To change the appearance of the tool-window, complete the following steps:
  1. Open the 'DslEditorsConfiguration.deptec' diagram
  2. Click anywhere on the diagram surface
  3. In the 'Properties Window', change the 'ToolWindow Title' and 'ToolWindow Bitmaps File'
  4. Save, Transform Templates, Rebuild and run.

Note. You can only modify the tool-window appearance properties when you have chosen to host your editors in a Tool-window and not as the Designer.

If the bitmap defined by the 'Tool-window Bitmaps File' property contains more than one bitmap (in a strip of bitmaps), it is the first bitmap that is used (by default). To change the bitmap index used, complete the following steps:
  1. Open the 'Tool-window.tt' text template found in the GeneratedCode folder
  2. Locate the 'BitmapIndex' property getter
  3. Change the return value to the index of the desired bitmap in the bitmap strip (zero-based)
  4. Save, Transform Templates, Rebuild and run.

Change Tool-window Location, Orientation

Objective: To change the start-up location and orientation of the tool-window, relative to other tool-windows in the IDE.

This is done in the same way as described in previous release.

Note. The necessary code for the tool-window and package is only generated when you have chosen to host your editors in a Tool-window and not as the Designer.

Editors

Configuring Editors

Objective: To add or configure multiple editors

In this release of the PowerToy it is now possible to define more than one editor (containing a custom control). Each editor contains a corresponding control, which can be any UserControl.

In order to configure an editor, the PowerToy provides a configuration language designer (DslEditorsConfiguration.deptec) which contains shapes to represent the editors. Each shape has associated properties for the editor. The user can add as many editors as required, and each one has a 'Caption', 'Icon' and 'Editor Control' associated with it.

Each editor can also be deactivated (Activate=false) if under partial configuration at the present time. In this state the editor will not be used.

To add or configure the editors, complete the following steps:
  1. Open the 'DslEditorsConfiguration.deptec' diagram
  2. From the toolbox, drag a new 'DSL Editor' shape to the diagram surface, or right-click on diagram and select 'Add New Dsl Editor'.
  3. Select the new shape, and in the 'Properties Window' configure the editor's properties.
  4. Save, Transform Templates, Rebuild and run.

Activating Editors

Objective: To 'activate' a specific editor (display it) based upon current selection in DSL at runtime.

When you have multiple editors defined, it is reasonable to want to 'activate' a specific editor when the user of your DSL selects certain shapes or when certain conditions arise in your DSL. For example, the editor may be tailored to specific shapes or event in the DSL, and only is valid for those shapes or events. All other times, the editor may be effectively unused.
By default, no specific editor activation rules are applied, but in some cases this behaviour is desirable with multiple editors to guide the user to the right editor in the right context of designer use.

To do this you extend the basic functionality of the existing generated tool-window and handle selection changes within it. You can also ensure this tool-window is currently displayed in the IDE.

To programmatically activate a specific editor based upon context in the designer, complete the following steps:
  1. Create a new class file in the DSL package project (e.g. MyLanguageDslEditorToolWindow.cs)
  2. Add a partial class declaration (e.g. partial class MyLanguageDslEditorToolWindow)
  3. Copy the namespace and class name of the existing tool-window generated by the PowerToy (found in DslPackage\DslEditors\GeneratedCode\ToolWindow.tt\ToolWindow.cs
  4. Override the OnEnvironmentSelectionChanged(ISelectionProvider, SelectionChangeSource) method. Ensuring you call the base method. Add your logic to determine which shapes/model elements you want to detect in the selection, and call ActivateEditor() method to show a specific editor. Obtain the GUID of your specific editor from the 'Editor Id' property of the 'DSL Editor' shape in configuration language DslPackage\DslEditors\DslEditorsDefintion.deptec)
  5. Transform Templates, Rebuild and Run.
Example:
using DslEditorPowerToy.Controls;
using DslEditorPowerToy.Languages;

namespace Company.MyLanguage.DslEditorPowerToy.Controls
{
    partial class MyLanguageDslEditorToolWindow
    {
        protected override void OnEnvironmentSelectionChanged(ISelectionProvider selectionProvider, SelectionChangeSource source)
        {
            base.OnEnvironmentSelectionChanged(selectionProvider, source);

            //Ensure diagram selection change
            if (SelectionChangeSource.Diagram == source)
            {
                //Get the represented model element
                if (ModelHelper.GetRepresentedElement(selectionProvider.PrimarySelection) is MyExampleElement)
                {
                    //Ensures the tool-window is shown
                    this.ShowNoActivate();

                    //Activates the appropriate editor
                    this.ActivateEditor(new Guid("GUID_OF_THE_EDITOR_YOU_WANT_TO_ACTIVATE"));
                }
            }
        }
    }
}

Editor Controls

These customizations are for custom editor controls

Handle Selection Changes

Objective: To handle, within the editor control, selection changes in the diagram or model explorer.

This is done in the same way as described in previous release.
(see the SelectionTackerEditor control (SelectionTackerEditor.cs) as an example of how this can be achieved)

Provide Selectable Items

Objective: To provide selectable objects in the editor control, that can be exposed and edited by the ‘Properties Window’, (or other controls).

This is done in the same way as described in previous release.
(see the SelectionTackerEditor control (SelectionTackerEditor.cs) as an example of how this can be achieved)

Other Customizations

Objective: To customize other aspects of the added and generated code of the PowerToy.

The PowerToy makes extensive use of text templates and the double-derived pattern for all its classes, and for extending and integrating with classes of the host DSL (provided by the DSL tools).

In most cases of all other customizations to PowerToy components, there are 2 levels of customization possible:
  1. Overriding existing functionality using partial classes (of double derived classes)
  2. Modifying text templates (installed by PowerToy)

In the first case, to enhance existing generated code, simply add a new partial class definition (in a separate source file to the DSL package project) and override the members of the partial class providing new behaviour or functionality.
The next level of customization is typically required only if partial classes can't achieve the required customization. In these cases, you can edit the text templates themselves to generate custom code to achieve the customization.

WARNING: Be aware that modifications to text templates will be lost if either re-adding or removing the PowerToy using the recipes provided by the PowerToy.

Last edited Jun 25, 2007 at 1:49 PM by jezzsa, version 10

Comments

No comments yet.