How to Customize the PowerToy

The following page describes the means to customize various areas of the artefacts 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.

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.

In the current release of the DSL tools, the packages use a CTC file to statically define commands. Also the package and language assemblies of the DSL are deployed into the GAC. This means that they don’t have codebase to load from by the runtime. This is important to Visual Studio, since you cannot define custom bitmap icons, using the BITMAPS section for CTC commands if your assembly is not codebased.

Instead, you are limited to having to use an icon already defined by Microsoft Office (MSO). These icon ID’s are defined in the included ‘msobtnid.h’ header file of the CTC file. You can browse this file by default installed in the ‘\VisualStudioIntegration\Common\Inc\office10’ of the VS SDK. This file simply defines the name and integer of the command, you have no way to visualise the command with this file. However, there is a tool described here that you can view the icons with and determine their ID, which allows you to browse all the icons (some 7500) of them!

Once you know the ID of the icon you want to change, complete the following steps:
  1. Open the ‘msobtnid.h’ file from your installation of VS SDK
  2. Locate the ‘#define’ statement for the value of the Icon ID you want (e.g. #define msotcidLegend 439)
  3. Open the 'CustomCmd.tt' template from Tool-window installation folder of the package project
  4. Locate the ‘Command Identifiers’ section at the top of this file
  5. Add a #define statement for your new icon identifier, (e.g. #define OI_MYNEWICON guidOfficeIcon:msotcidLegend)
  6. Locate the command definition in the {DSLEDITORPOWERTOY_BUTTONS} section below. The icon value is the 4th parameter (by default, OI_DSLEDITOR)
  7. Replace the 4th parameter with your defined ID (e.g. OI_DSLEDITOR)
  8. Save, Rebuild and run
In some cases, your new menu command may not change, this is because VS sometimes caches the commands. Your DSL automatically re-registers itself on every build using (RegPkg.exe) which should flush these commands.

However, if that is still not working you can try to manually flush this cache, either at the command line execute ‘devenv /setup /rootsuffix exp’, or try the following things:
  1. Open the 'package.tt' template from the 'GeneratedCode' folder of the package project
  2. Locate the ‘ProvideMenuResource‘ attribute on the package class (e.g. [ProvideMenuResource(1000, 1)])
  3. Increment the second parameter of this attribute
  4. Save, Transform Templates, Rebuild and run

Change Tool-window Icon and Text

Objective: To change the icon and text used on the tool-window.

Unlike the menu commands defined in the CTC file. The tool-window icon and text are assigned within the templates used to create its class. The title and icon are declared in the 'ToolWindowResource.tt' template located in the tool-window installation folder of the package project.
To change these values, complete the following steps:
  1. Open 'ToolWindowResources.tt' template from Tool-window installation folder of the package project
  2. Locate the last '<data>' element (at very bottom of file) which contains the current title of the tool-window, and change its value.
  3. Save, Transform Templates, Rebuild and run
Alternatively, if you want to provide this value at runtime, you can override the tool-window class and provide your own value. To do this, complete the following steps:
  1. Create a new class file in the Tool-window installation folder of the package project (e.g. ToolWindowEx.cs)
  2. Add a partial class declaration of the generated tool-window class (e.g. partial class MyLanguageDslEditorToolWindow), taking care that the namespace of this class is the same as the generated tool-window class.
  3. Override the ‘WindowTitle’ property, and provide your own implementation to return a title for the tool-window.
  4. Rebuild and run.

Change Tool-window Location, Orientation

Objective: To change the start-up positioning and orientation of the tool-window.

Tool-windows in the current version of the DSL tools use Managed Package Framework (MPF) attributes on the package class to declare tool-window orientation and location relative to other tool-windows in the IDE.
A tool-window is always placed relative to another known tool-window by GUID of that tool-window, and these attributes state the start-up position orientation and appearance of the tool-window for the user. The GUID of other known tool-windows can be found as sub-keys under the following key in the Windows Registry: ‘HKLM\Software\Microsoft\VisualStudio\8.0Exp\ToolWindows’
To change the start-up appearance, complete these steps:
  1. Open the 'package.tt' template from the 'GeneratedCode' folder of the package project
  2. Locate the ‘ProvideToolWindow’ attribute for the tool-window on the package class.
  3. Change the ‘Style’, ‘Orientation’ and ‘Window’ parameters.
  4. Save, Transform Templates, Rebuild and run
  5. Close all instance of Visual Studio
  6. At the command line, execute ‘devenv /resetuserdata /rootsuffix exp’ to reset all user’s settings to initial values.

Editor

Customize/Extend Editor

Objective: To extend or customize the editor control (in general).

To change most things about the editor control you simply need to provide implementation or override existing methods of the generated base class.
To provide your own implementation, complete the following steps:
  1. Create a new class file in the tool-window installation folder of the package project (e.g. EditorEx.cs)
  2. Add a partial class declaration of the generated editor class (e.g. partial class SelectionTracker), taking care that the namespace of this class is the same as the generated tool-window class.
  3. Override the various properties and methods of the base classes to provide your implementation.
  4. Rebuild and run.

Replace Editor Control

Objective: To replace the current editor control with your own.

In the very likely event that you wish to replace the current control with one of your own, with your own functionality, the generated code needs to be removed, and replaced with code for your own control. The tool-window class does reference and instantiate the contained editor control, and therefore the implementation of the tool-window class needs modifying also.
To replace the editor control with a new control, complete the following steps:
  1. Add a new class file in the tool-window installation folder of the package project (e.g. MyNewEditor.cs) containing implementation of new editor control.
  2. Delete the 'Editor.tt' template from Tool-window installation folder of the package project
  3. Add a new class file in the tool-window installation folder of the package project (e.g. ToolWindowEx.cs)
  4. Add a partial class declaration of the generated tool-window class (e.g. partial class MyLanguageDslEditorToolWindow), taking care that the namespace of this class is the same as the generated tool-window class.
  5. Override the ‘Control’ property, and provide your own implementation to return an instance of your custom editor.
  6. Rebuild and run.

Handle Selection Changes

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

Selection in general in Visual Studio is managed by a number of unmanaged COM interfaces, that are difficult to implement. Managed code defines a single interface called ‘ISelectionService’ to managed bi-directional selection. The broker between the unmanaged interfaces of Visual Studio and managed interfaces of the editor control is the tool-window. The tool-window class forwards selection change notifications and acts as a container for selectable items. (By default, the tool window does not have any selectable items). This implementation makes it very easy for editor controls to both listen for selection changes, and provide selectable objects (next section).

The tool-window listens, and filters only for selection changes to only the DSL diagram and the Model Explorer control of the diagram. The editor can receive notifications of these selection changes by implementing the ‘IMonitorSelection’ interface. Furthermore the editor can chose to receive only selection changes from diagram, or from both diagram and Model Explorer.
To handle selection changes in your editor control, complete the following steps:
  1. Implement the ‘IMonitorSelection’ interface
  2. Rebuild and run.

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).

As mentioned in the previous section, the tool-window acts as a broker for the editor control for notifying the editor of selection changes in the IDE, and for notifying the IDE of selectable objects and their selection changes.

In order for an editor to ‘expose’ its own selectable objects, it must implement the ‘ISelectionService’ interface, and ensure that it raises the ‘SelectionChanged’ events. The tool-window registers for these events from the editor at runtime, and handles the exchange of selection, using the ‘ISelectionService’ interface, between editor and VS IDE.
To implement selectable objects in your editor control, complete the following steps:
  1. Implement the ‘ISelectionService’ interface, ensuring to implement all methods and events.
  2. Rebuild and run.

Last edited Mar 18, 2007 at 6:59 AM by jezzsa, version 9

Comments

No comments yet.