dept Wiki & Documentation Rss Feed

UPDATED WIKI: Home

jezzsa — Sat, 28 Jul 2007 17:40:37 GMT

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

This PowerToy aims to provide a new capability that will provide an enhanced user experience for displaying and interacting with different aspects of a domain model in multiple dedicated 'editors'.

The PowerToy will provide your DSL with a new tool-window containing one or more editors that manage configurable 'views' of domain classes, and their relationships. The PowerToy displays these various views by hosting windows controls that display the view, and manage the users interaction with them.

For example, the following screenshot displays one such editor (bottom-half of the screen) specific for manipulating 'Data Contracts' of an existing example DSL used for authoring Web Services.

You can also see a similar example of an editor specific for 'Service Operations' of the same DSL here.
Another example of an alternative implementation used for Data Contracts in another DSL here.

The Basic Idea

The PowerToy will be available for download (also in source form), and will be installed by a DSL developer on their development machine. The DSL author will, within their existing DSL solution, add and configure one or more custom editors to display some aspect of the domain model of their DSL. At runtime these editors will be displayed to the user of their DSL.

The PowerToy will provide (as one choice of editor) a tree-grid-like control that displays a hierarchy of domain models elements and their child relationships. This control then allows the user to interact with and manipulate the domain classes and their properties.

Please check our example User Scenario for more details for one requirement for this kind of editor, and what drove the existing implementation for it.

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

In essence, this power toy primarily provides a better User Experience (UX) for the DSL user by exposing relationships potentially with no visibility on the diagram (i.e. in shapes or connectors), reducing shape clutter, and giving the user the ability to rapidly configuration the exposed domain classes and properties in the editor.

Essentially this PowerToy provides the ability to expose hierarchical 'views' of the underlying domain model, that can be displayed using any windows control or other display technology

The Approach

We are providing a staged approach to completing the implementation this PowerToy. At each stage (milestone) will deliver working code that adds a new capability to a DSL.
Each release is designed to build upon the previous release and enhance it with a new capability and infrastructure to support that capability.
The intention is to provide a DSL developer, using the PowerToy, deliverables that can be taken and customized to solve incremental problems that the PowerToy encounters in its development, that are expected to encounter anyone implementing this type of functionality.

Please see the Milestones page of this project to see what releases we have and what they will deliver.

UPDATED WIKI: Home

jezzsa — Wed, 04 Jul 2007 14:47:31 GMT

Important Update!, We just changed the base URL of this site (from codeplex/dsltreegrideditor to codeplex/dept). There is now a URL redirect in place to manage this, please update your links!

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: Home

jezzsa — Wed, 04 Jul 2007 14:46:48 GMT

Important Update!, We just changed the base URL of this site (from codeplex/dsltreegrideditor to codeplex/dept). There is now a URL redirect in place, please update your links!

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: Home

jezzsa — Wed, 04 Jul 2007 14:46:38 GMT

Important Update!, We just changed the base URL of this site (from codeplex/dsltreegrideditor to codeplex/dept). There is now a URLredirect in place, please update your links!

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: Home

jezzsa — Tue, 26 Jun 2007 10:32:33 GMT

Important Update!, We just changed the base URL of this site (from codeplex/dsltreegrideditor to codeplex/dept).
All previous links to codeplex/dsltreegrideditor redirect to this page only! Please update your links.

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: Home

jezzsa — Tue, 26 Jun 2007 10:30:43 GMT

*Important Update!, We just changed the base URL of this site (from codeplex/dsltreegrideditor to codeplex/dept).
All previous links to codeplex/dsltreegrideditor redirect to this page only!
Please update your links.*

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: ReleaseM1_Customize

jezzsa — Mon, 25 Jun 2007 12:49:26 GMT

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:

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Custom Editor'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'Designer'.
Save, Transform Templates, Rebuild and run.

To restore the default graphical designer for your DSL, complete the following reverse steps.

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Custom Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Designer'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Diagram', 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'ToolWindow'.
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:

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Navigation Style'.
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:

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title'
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:

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title' and 'ToolWindow Bitmaps File'
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:

Open the 'Tool-window.tt' text template found in the GeneratedCode folder
Locate the 'BitmapIndex' property getter
Change the return value to the index of the desired bitmap in the bitmap strip (zero-based)
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:

Open the 'DslEditorsConfiguration.deptec' diagram
From the toolbox, drag a new 'DSL Editor' shape to the diagram surface, or right-click on diagram and select 'Add New Dsl Editor'.
Select the new shape, and in the 'Properties Window' configure the editor's properties.
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:

Create a new class file in the DSL package project (e.g. MyLanguageDslEditorToolWindow.cs)
Add a partial class declaration (e.g. partial class MyLanguageDslEditorToolWindow)
Copy the namespace and class name of the existing tool-window generated by the PowerToy (found in DslPackage\DslEditors\GeneratedCode\ToolWindow.tt\ToolWindow.cs
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)
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:

Overriding existing functionality using partial classes (of double derived classes)
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.

UPDATED WIKI: ReleaseM1_Customize

jezzsa — Mon, 25 Jun 2007 07:59:24 GMT

How to Customize the PowerToy

Editor Hosting

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Custom Editor'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'Designer'.
Save, Transform Templates, Rebuild and run.

To restore the default graphical designer for your DSL, complete the following reverse steps.

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Custom Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Designer'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Diagram', 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'ToolWindow'.
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

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Navigation Style'.
Save, Transform Templates, Rebuild and run.

IDE Integration

Change Menu Icons and Text

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title'
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

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title' and 'ToolWindow Bitmaps File'
Save, Transform Templates, Rebuild and run.

Open the 'Tool-window.tt' text template found in the GeneratedCode folder
Locate the 'BitmapIndex' property getter
Change the return value to the index of the desired bitmap in the bitmap strip (zero-based)
Save, Transform Templates, Rebuild and run.

Change Tool-window Location, Orientation

Editors

Configuring Editors

Open the 'DslEditorsConfiguration.deptec' diagram
From the toolbox, drag a new 'DSL Editor' shape to the diagram surface, or right-click on diagram and select 'Add New Dsl Editor'.
Select the new shape, and in the 'Properties Window' configure the editor's properties.
Save, Transform Templates, Rebuild and run.

Activating Editors

Create a new class file in the DSL package project (e.g. MyLanguageDslEditorToolWindow.cs)
Add a partial class declaration (e.g. partial class MyLanguageDslEditorToolWindow)
Copy the namespace and class name of the existing tool-window generated by the PowerToy (found in DslPackage\DslEditors\GeneratedCode\ToolWindow.tt\ToolWindow.cs
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)
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.Show();
 
                    //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

Provide Selectable Items

Other Customizations

Overriding existing functionality using partial classes (of double derived classes)
Modifying text templates (installed by PowerToy)

UPDATED WIKI: Home

jezzsa — Sun, 24 Jun 2007 19:39:40 GMT

Important Update!, we just changed the URL of this site (from codeplex/dsltreegrideditor to codeplex/dept). All previous links to codeplex/dsltreegrideditor redirect to this page only! Please update your links.

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: ReleaseM2_Planning

jezzsa — Sun, 17 Jun 2007 20:49:57 GMT

Release Milestone 2 - Planning

Business Objectives

Provide a means to configure customizable 'views' or hierarchical relationships of classes from underlying domain model (representing some aspect or relationship), and then provide a hierarchical display of them in a custom editor control.

Technical Objectives

The objectives of this release are:

Provide a means to configure each view using existing graphical configuration language (DSL)
Provide a programmatic means for an editor to access and navigate the view and read/write interface to underlying domain classes and relationships.
Provide a simple hierarchical control to display this view (read-only) and allow user to navigate this view.

This release with continue to follow the patterns of the previous release. And this release will leverage assets from that release.
This release will build upon those patterns and enhance them where necessary to add further functionality.

Technical Implementation

We are considering a few user experiences for configuring the views.
In either case we need a treeview to mark the domain classes/relationships that are included in the view.
Using the graphical designer approach, we could have a UX like this:

If we move to a forms based designer approach, we could have a UX like this:

Currently we are evaluating the benefits of either approach to provide the best presentation for the user.

Technical Constraints

Installation should not be side-by-side (only one version of PowerToy allowed to be installed)
Only targeting VS2005 (Whidbey), not targeting VS2007 (Orcas)

UPDATED WIKI: ReleaseM2_Planning

jezzsa — Tue, 12 Jun 2007 06:14:13 GMT

Release Milestone 2 - Planning

Business Objectives

Provide a means to configure customizable 'views' or hierarchical relationships of classes from underlying domain model (representing some aspect or relationship), and then provide a hierarchical display of them in a custom editor control.

Technical Objectives

The objectives of this release are:

Provide a means to configure each view using existing graphical configuration language (DSL)
Provide a programmatic means for an editor to access and navigate the view and read/write interface to underlying domain classes and relationships.
Provide a simple hierarchical control to display this view (read-only) and allow user to navigate this view.

Technical Implementation

We are considering a user experience such as the following to allow us to configure the views:

Technical Constraints

Installation should not be side-by-side (only one version of PowerToy allowed to be installed)
Only targeting VS2005 (Whidbey), not targeting VS2007 (Orcas)

UPDATED WIKI: ReleaseM1

jezzsa — Mon, 21 May 2007 11:03:25 GMT

Release Milestone 1 - Custom Editors

What is it?

A means to add multiple editors to your DSL, either hosted in a tool-window, or replace the graphical designer of your DSL

What is available?

This release is available for download here: M1 Released

Pre-requisites

You will need the following development environment to install and use this PowerToy:

Visual Studio 2005 (Professional/Team Suite)
Visual Studio SDK (v.4 preferred)
Guidance Automation Toolkit (Feb2007CTP prefered) or June2006CTP

This release also has a dependence on the following components (which are installed by the PowerToy):

Guidance Automation Extensions (v.1.3.1) (GEL)

What is it used for?

The intention of this release is to extend the basic functionality of the previous release M0 Released and allow the DSL developer to very quickly enable multiple editors for their DSL.

In this release, there are 3 hosting options for integrating (hosting) the editors to enhance your DSL language:

Host editors a tool-window which appears alongside your graphical DSL designer
Replace your graphical designer with the editors as the forms based user interface to your DSL.
Replace your graphical designer with your own custom forms-based designer, and have the editors in a tool-window which appears alongside your custom forms-based designer.

If hosting the editors in a tool-window, that tool-window appears only when the DSL designer is active in the IDE.

The editors can replace the graphical designer of the DSL, in cases where a forms-based user interface is more appropriate for the DSL.

It is also possible to replace the graphical designer with your own custom forms-based designer and still have the editors hosted in a tool-window along side your custom designer.

What is included?

The PowerToy provides a new configuration language (DSL) to configure the editors and hosts.
The PowerToy adds a new tool-window (or replacement designer ), which contains one or more
The replacement designer can only valid when a 'Custom Editor' has been configured in the DSL. The tool-window and old graphical designer will be replaced with the editors themselves.

editors, each providing a logical view of the underlying domain model of the DSL.

The default editor used in this release is essentially the same basic editor used in previous release which displays basic selection information on the diagram (or IDE), and now provides selectable items.

The next release of the PowerToy will provide a richer editor for visualising domain relationships.

How do you use it?

To install this release, add and configure the editors, see How to Use

How it works?

Detailed information about how the PowerToy works, and the design decisions made in its development can be found in the Technical Design page.

Customizing it?

With this release you can customize various attributes of the host (i.e. layout etc.), and tool-window (i.e. title, icon etc.), and you can add/remove/modify, and customize, any of the contained editors .

For more details on how to customize this release, see How to Customize

What was planned for this release?

The planning details, and technical requirements for this release are detailed here.

Feedback

We would like to capture any feedback you have about this release, or perhaps upcoming releases.

UPDATED WIKI: ReleaseM0

jezzsa — Mon, 21 May 2007 11:00:38 GMT

Release Milestone 0 - Custom Tool Window

What is it?

A means to add a DSL specific tool-window, containing a simple editor, to an existing DSL

What is available?

This release is available for download here: M0 Released

Pre-requisites

You will need the following development environment to install and use this PowerToy:

Visual Studio 2005 (Professional/Team Suite)
Visual Studio SDK (v.4 preferred)
Guidance Automation Toolkit (Feb2007CTP, or June2006CTP)

This release also has a dependence on the following components (which are installed by the PowerToy):

Guidance Automation Extensions (GEL)

What is it used for?

This release can be used as a starting point for enabling a tool-window for your DSL, containing a custom editor.

The intention is to provide the basic infrastructure for providing a tool-window and editor to display elements or aspects of a DSL diagram. This will be built upon in subsequent versions of the PowerToy.

What is included?

The PowerToy adds a tool-window containing an editor which provides some kind of ‘view’ on the domain model of the DSL. The editor provides the means to interact with this view.
The editor for this release is very basic indeed, simply handling and displaying basic information about the current selection in diagram. This editor is expected to be replaced with a better editor throughout the development of this PowerToy.
The tool-window is only active for the specific DSL diagram, and is not present when editing other types of DSL’s or source files.
The tool-window can be activated from either a context menu on the diagram, or from a top level menu in Visual Studio (found on the View | Other Windows menu).

How do you use it?

To install this release, add and configure a custom tool-window editor, see How to Use

How it works?

Detailed information about how the PowerToy works, and the design decisions made in its development can be found in the Technical Design page.

Customizing it?

With this release you can customize various attributes about the tool-window (i.e. title, icon, placement etc), and you can customize or replace the user control contained within the tool-window with one of your own.

For more details on how to customize this release, see How to Customize the Editor

Feedback

We would like to capture any feedback you have about this release, or perhaps upcoming releases.

UPDATED WIKI: ReleaseM2_Planning

jezzsa — Sun, 20 May 2007 13:07:06 GMT

Release Milestone 2 - Planning

Business Objectives

Provide a means to configure customizable 'views' or hierarchical relationships of classes from underlying domain model (representing some aspect or relationship), and then provide a hierarchical display of them in a custom editor control.

Technical Objectives

The objectives of this release are:

Provide a means to configure each view using existing graphical configuration language (DSL)
Provide a programmatic means for an editor to access and navigate the view and read/write interface to underlying domain classes and relationships.
Provide a simple hierarchical control to display this view (read-only) and allow user to navigate this view.

Technical Implementation

Technical Constraints

Installation should not be side-by-side (only one version of PowerToy allowed to be installed)
Only targeting VS2005 (Whidbey), not targeting VS2007 (Orcas)

UPDATED WIKI: ReleaseM2

jezzsa — Sun, 20 May 2007 12:58:32 GMT

Release Milestone 2 - Basic Custom Control

What is it?

A means to define and display a view (domain classes and relationships) of the underlying domain model of the DSL

What is available?

This release is in Planning and Development.

What is it used for?

This release can be used as a starting point for adding your own controls for viewing domain classes and relationships arranged into a custom 'view'. This 'view' (collection of domain classes and relationships) typically shows a single hierarchical child relationship in or aspect across the underlying domain model. This release delivers a custom control that demonstrates one way to display such a view.

The intention is to extend the basic functionality of the previous release M1 Released and allow the user of the PowerToy to define these custom views using the existing configuration language. This release will then provide all the hooks and access required for an editor control to display and interact with the view and the underlying domain model.

UPDATED WIKI: Home

jezzsa — Sun, 20 May 2007 06:36:04 GMT

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a DSL enhancement PowerToy for displaying multiple customized views of a domain specific languages (DSL's).

Quick links

Current Release:	M1 Released
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

The Basic Idea

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one editor per aspect)
Each aspect or 'view' on the domain model would have a separate editor.
Can replace the grpahical designer of the DSL, with forms based editors where a box-line user interface is not optimal for the domain.

Increased Usability!

The Approach

UPDATED WIKI: Milestones

jezzsa — Sat, 19 May 2007 22:10:20 GMT

This page describes the development plan, the features and the deliverables from each milestone.

We are still seeking further Requirements for the PowerToy, so please contribute your ideas to the Discussions.

Milestone 0 - 'Custom Tool Window'

A means to add a DSL specific tool-window containing a simple editor, and menu commands to existing DSL

Features:

Runtime:

Adds a single tool-window, containing simple control that tracks current selection of a host DSL.
Adds a menu on the View | Other Windows menu to show the tool-window.
Adds a DSL designer context menu to show the tool-window.

DesignTime:

Adds GAT recipes for installing/uninstalling the PowerToy to a DSL Solution (installs/uninstalls necessary files and libraries into DSL Host solution).

Release Details...

Milestone 1 - 'Custom Editors'

A means to add multiple editors to your DSL, either hosted in a tool-window, or replace the graphical designer of your DSL

Planning Details...
Features:

Runtime:

Adds multiple editors (and tabs)
Hosts the editors within the tool-window, or as the replacement design surface for the DSL.

DesignTime:

Adds small DSL language to host DSL solution for configuring the editors and hosting options

Release Details...

Milestone 2 - 'Basic Custom Control'

A means to define and display a view (domain classes and relationships) of the underlying domain model of the DSL.

Features:

Runtime:

Enhanced configuration language to orchestrate a 'view' of the domain model
A simple hierarchical control (Explorer, Navigator type control) to view these relationships (limited read/write capability)

DesignTime:

Refines configuration language

Milestone 3 - 'Advanced Custom Control'

A means to display a tree-grid-like UI to navigate and interact with the contents of each view.

Features:

Runtime:

An advanced hierarchical control (Tree-grid-like control) to view and modify these relationships (full read/write capability)

UPDATED WIKI: ReleaseM1

jezzsa — Sat, 19 May 2007 22:09:25 GMT

Release Milestone 1 - Custom Editors

What is it?

A means to add multiple editors to your DSL, either hosted in a tool-window, or replace the graphical designer of your DSL

What is available?

This release is available for download here: M1 Released

What is it used for?

Host editors a tool-window which appears alongside your graphical DSL designer
Replace your graphical designer with the editors as the forms based user interface to your DSL.
Replace your graphical designer with your own custom forms-based designer, and have the editors in a tool-window which appears alongside your custom forms-based designer.

What is included?

The PowerToy provides a new configuration language (DSL) to configure the editors and hosts.
The PowerToy adds a new tool-window (or replacement designer ), which contains one or more
The replacement designer can only valid when a 'Custom Editor' has been configured in the DSL. The tool-window and old graphical designer will be replaced with the editors themselves.

editors, each providing a logical view of the underlying domain model of the DSL.

The default editor used in this release is essentially the same basic editor used in previous release which displays basic selection information on the diagram (or IDE), and now provides selectable items.

The next release of the PowerToy will provide a richer editor for visualising domain relationships.

What do you need?

The pre-requisites for this release are the same as the previous release ReleaseM0.

How do you use it?

To install this release, add and configure the editors, see How to Use

How it works?

Detailed information about how the PowerToy works, and the design decisions made in its development can be found in the Technical Design page.

Customizing it?

What was planned for this release?

The planning details, and technical requirements for this release are detailed here.

Feedback

We would like to capture any feedback you have about this release, or perhaps upcoming releases.

UPDATED WIKI: Home

jezzsa — Sat, 19 May 2007 21:46:06 GMT

Welcome

This is the home of the DSL Editor ‘PowerToy’ project - a User-Experience enhancement PowerToy for domains specific languages (DSL's).

Quick links

Current Release:	M1 Alpha
	Documentation
	What is this release?
	How to install and use it?
	How to customize it?
Next Release:	What is the next release?
All Releases

What is it?

This PowerToy aims to provide a new capability that will provide an enhanced user experience for manipulating domain classes and their relationships alongside the DSL designer in a hierarchical tree-grid-like editor.

The PowerToy will provide your DSL with a new tool-window containing one or more editors that provide configurable 'views' of domain classes, and their relationships. The PowerToy presents these various views by hosting windows controls that display the view, and manage the users interaction with them.

For example, the following screenshot displays the proposed editor window (bottom-half of the screen) specific to the selected 'Data Contract' of an existing example DSL used for authoring Web Services.

You can also see a similar example of an editor specific for 'Service Operations' of the same DSL here.
Another example of an alternative implementation used for Data Contracts in another DSL here.

The Basic Idea

The PowerToy will be available for download, and will be installed by a developer on their development machine. The DSL author will, within their existing DSL solution, add and configure one or more custom editors to display some aspect of the domain model of their DSL.

The PowerToy will provide, as one choice of editor, a tree-grid-like control that displays a hierarchy of domain models elements and their child relationships. This control then allows the user to interact with and manipulate the domain classes and their properties.

Please check our example User Scenario for more details for one requirement for this kind of editor, and what drove the existing implementation for it.

Benefits

The benefits of the PowerToy include:

Provides a means to view/edit relationships and domain classes that have no visible representation on the diagram
Reduces shape clutter on the diagram surface
Provides a hierarchical view of (possibly hidden) child relationships
Provides a better UX (keyboard navigation) for editing multiple properties of domain classes as part of hierarchical relationships, bulk editing.
Also improves visibility of key properties and enables better comparisons of related instances alongside each other.
Allows aspect focused editors (one view or aspect per tool window)
Each aspect or view on the domain model would have a separate editor.

Increased Usability!

In essence, this power toy primarily provides a better User Experience (UX) for the DSL user by exposing relationships not represented on the diagram (i.e. in shapes or connectors), reducing shape clutter, and giving the user the ability to rapidly configuration the exposed domain classes and properties in the editor.

Essentially this PowerToy provides the ability to expose hierarchical 'views' of the underlying domain model, that can be displayed using any windows control or other display technology

The Approach

We are providing a staged approach to completing the implementation this PowerToy. At each stage (release) will deliver working code that adds a new capability to a DSL.
Each release is designed to build upon the previous release and enhance it with a new capability and infrastructure to support that capability.
The intention is to provide a DSL developer, using the PowerToy, deliverables that can be taken and customized to solve incremental problems that the PowerToy encounters in its development, that are expected to encounter anyone implementing this type of functionality.

Please see the Milestones page of this project to see what releases we have and what they will deliver.

UPDATED WIKI: ReleaseM1_Customize

jezzsa — Sat, 19 May 2007 20:45:01 GMT

How to Customize the PowerToy

Editor Hosting

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Custom Editor'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'Designer'.
Save, Transform Templates, Rebuild and run.

To restore the default graphical designer for your DSL, complete the following reverse steps.

Open the 'DslDefinition.dsl' diagram for your DSL
In the 'DSL Explorer' window, right-click on the 'Custom Editor' node and click Delete.
Right-click on the root node in the 'DSL Explorer' for your DSL and select 'Add New Designer'
Select the 'Editor' node, and in the 'Properties Window', reset the values for 'Diagram', 'Root Class' and 'FileExtension' (at minimum).
Close the 'DslDefinition.dsl' diagram and save changes.
Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Hosting Style' property to 'ToolWindow'.
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

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'Navigation Style'.
Save, Transform Templates, Rebuild and run.

IDE Integration

Change Menu Icons and Text

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title'
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

Open the 'DslEditorsConfiguration.deptec' diagram
Click anywhere on the diagram surface
In the 'Properties Window', change the 'ToolWindow Title' and 'ToolWindow Bitmaps File'
Save, Transform Templates, Rebuild and run.

Open the 'Tool-window.tt' text template found in the GeneratedCode folder
Locate the 'BitmapIndex' property getter
Change the return value to the index of the desired bitmap in the bitmap strip (zero-based)
Save, Transform Templates, Rebuild and run.

Change Tool-window Location, Orientation

Editors

Configuring Editors

Open the 'DslEditorsConfiguration.deptec' diagram
From the toolbox, drag a new 'DSL Editor' shape to the diagram surface, or right-click on diagram and select 'Add New Dsl Editor'.
Select the new shape, and in the 'Properties Window' configure the editor's properties.
Save, Transform Templates, Rebuild and run.

Activating Editors

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

It is possible to 'activate' a specific editor when the user of your DSL selects certain shapes 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 disabled. 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 programmatically activate a specific editor based upon context in the designer, complete the following steps:

Create a new class file in the package project (e.g. MyLanguageDslEditorToolWindow.cs)
Add a partial class declaration (e.g. partial class MyLanguageDslEditorToolWindow), taking care that the namespace of this class is the same as the generated PowerToy tool-window class.
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 id of the editor from the DslEditor shape in configuration language.)
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)
                {
                    //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

Provide Selectable Items

Other Customizations

Overriding existing functionality using partial classes (of double derived classes)
Modifying text templates (installed by PowerToy)