New to CorelDRAW X7 Update 1 and Corel DESIGNER X7 is the ability to create your own tools in VBA, C# or C++. This is done using the new tool interface called ToolState and a set of many new functions and classes that are specifically geared towards creating tools.
While new tools can be implemented in any language that supports COM, this article will focus on C#.
Prerequisites
Creating a New Project
Once the "CorelDRAW and Corel DESIGNER Tool Addon" extension is installed in Visual Studio, it will be available through the File->New Project list. Go to File->New Project and navigate to Installed->Templates->Other Languages->C#, and select "CorelDRAW and Corel DESIGNER Tool Addon" from the list. Choose a name for the tool (e.g. "MyTool") and press OK to create the project.
Next the Addon Settings dialog is displayed from which the startup application can be selected. This choice can be changed later through the project's properties dialog (Start external program). Note: The application choices are only enabled if the template detects that the application is installed on the computer.
Compile and Run
To compile the addon, select Build->Build Solution (or press F7). Press F5 and it will launch the application (CorelDRAW or Corel DESIGNER) that was selected earlier and the new tool will be added to the toolbox.
This sample tool allows the user to create 2-point lines and demonstrates how easy it is to create a custom tool. It has on screen preview UI, snapping, constraints, a property bar, and everything else one would expect for a tool.
The Code
The project has two .cs files. Addon.cs contains the entry point. This class will be instantiated by the host application (CorelDRAW or Corel DESIGNER) when the application is started. This is where the new tool is registered, any other data sources or other tasks that need to be performed on application startup.
///<summary> /// Constructor for the Addon. This is called by CorelDRAW or Corel DESIGNER when it is discovered. ///</summary> public Addon(Application Application) { // Create and register our tool ToolState toolState = new CGS.MyTool(Application); Application.RegisterToolState("b17f7ca0-0062-4dd8-adf6-1ea2192a3d35", "MyTool", toolState); }
The function RegisterToolState tells that application that the GUID (Globally Unique IDentifier) "b17f7ca0-0062-4dd8-adf6-1ea2192a3d35" identifies the MyTool addon. This GUID must be different for every tool and the Visual Studio extension will generates a new one for every project. Multiple tools can be created within the project and all registered at this place. Each tool will need a unique GUID. This can be created using Tools->Create GUID in Visual Studio or an equivalent GUID generator that are available on the web.
The MyTool.cs file contains the code for the tool. This sample tool is less than 200 lines long, but could be extended to do whatever custom logic is required. The MyTool class inherits from the ToolState interface. The host application, when using the tool, will call into the various functions that are implemented. For example, when the tool starts, the OnStartState() function will be called, allowing the tool to be set for use. When you move the mouse across the view, the OnMouseMove() function will be called. This function can be used to update the UI or collect mouse positions for curve creation.
The code for the sample tool is documented well, please take a few moments to read through the code and the comments to gain a basic understanding of the functions. The pseudo code for the line tool is as follows:
OnLButtonDownLeaveGrace save the left mouse button down position
OnMouseMove if the left mouse is down update the xor'd on screen UI with a line from the saved location to the current position
OnLButtonUp Create a line from the saved position to the current position
The UI
In the project there are two XSLT files: AppUI.xslt and UserUI.xslt. XSLT is an XML transformation file. It's purpose is to update the user's workspace to include the new tool. This sample will just add the new tool button to the end of the Toolbox. More complex changes to the workspace are possible using other XSLT transformations. If you're attempting to create any complicated UI, you may want to read up on XSLT to better understand it.
The AppUI.xslt file is responsible for defining new items (e.g. buttons) and adding new dockers or dialogs. Anything that isn't customizable can be defined here. In the sample line tool, it adds one new item.
<!-- C# Test Line Tool --> <itemData guid="b17f7ca0-0062-4dd8-adf6-1ea2192a3d35" type="groupedRadioButton" currentActiveOfGroup="*Bind(DataSource=WAppDataSource;Path=ActiveTool;BindType=TwoWay)" enable="*Bind(DataSource=WAppDataSource;Path=ToolboxEnable)" identifier="b17f7ca0-0062-4dd8-adf6-1ea2192a3d35"/>
A GUID is used to identify the tool button ("b17f7ca0-0062-4dd8-adf6-1ea2192a3d35"). This GUID is set for both the item and the grouped radio identifier. This is also the same GUID that was registered as MyTool with the application. This is important as it causes MyTool activate when the button is clicked.
UserUI.xslt is for modifying any UI that is customizable, for example, adding buttons to existing toolbars or menus, or creating new toolbars for the tools, etc.
<!-- Add tool item to the Toolbox --> <xsl:template match="//commandBarData[@guid='7c905e2a-cb64-4ba1-aff0-c306f392680c']/toolbar"> <xsl:apply-templates mode="insert-item" select="."> <xsl:with-param name="content"> <xsl:if test="not(./item[@guidRef='6b5b83bb-e7b8-4f9d-8dfd-36f59bf545cf'])"> <!-- Only insert if its not already there --> <item guidRef="6b5b83bb-e7b8-4f9d-8dfd-36f59bf545cf"/> </xsl:if> </xsl:with-param> </xsl:apply-templates> </xsl:template>
<xsl:template match="uiConfig/commandBars/commandBarData[@guid='74e03d83-404c-49f5-824a-fe0fd02ab29a']/toolbar"> <xsl:copy> <xsl:apply-templates select="node()|@*"/> <modeData guid="fd9a53f7-05cc-4cdc-b2ad-0fd6a7ea3480" captionRef="01965a34-ae38-01a0-4271-cd903b48e518"> <item guidRef="3148e122-4f73-6e8a-4dfb-b2f6a84090d5"/> <item guidRef="a41164ff-c9e9-4b2c-954a-095f4204538e"/> <item guidRef="266435b4-6e53-460f-9fa7-f45be187d400"/> <item guidRef="325d7c86-da3a-4610-bd25-5cf98cf66a41"/> <item guidRef="42bef211-16e5-4b4f-b9ee-52b7b5476232"/> <item guidRef="d289f32b-3808-4510-b892-fd2cb0820209"/> <item guidRef="266435b4-6e53-460f-9fa7-f45be187d400"/> <item guidRef="8723ad52-3e31-473c-8756-7ae85abcc483"/> <item guidRef="266435b4-6e53-460f-9fa7-f45be187d400"/> <item guidRef="e6644135-9dab-4935-8ab9-fc85527810ca"/> <item guidRef="6ae897fd-2eab-4dad-b172-f4fb768c273e"/> <item guidRef="266435b4-6e53-460f-9fa7-f45be187d400"/> <item guidRef="97e5c8b9-f7e2-453c-92a2-af7fb61e67b2"/> <item guidRef="266435b4-6e53-460f-9fa7-f45be187d400"/> <item guidRef="76dd9e0c-e9c2-42b6-b8bb-f7717482164e"/> <item guidRef="6bd00383-d132-4686-8a21-8d7052b6a81b"/> <item guidRef="40cc3adc-498a-4256-a98a-d1210a4019f7"/> </modeData> </xsl:copy> </xsl:template>
The first section adds the new tool button to the end of the Toolbox. It makes use of template the helper insert-item also defined in the XSLT. The second section defines a new property bar mode for the tool. The guid "fd9a53f7-05cc-4cdc-b2ad-0fd6a7ea3480" is unique for this tool as well, and in MyTool::StartAtState(), you'll find the following line:
currentAttribs.PropertyBarGuid = "fd9a53f7-05cc-4cdc-b2ad-0fd6a7ea3480";
This tells the host application that we want to use this property bar when the tool is selected. The items on this sample property bar mode come from the application, mostly from the real line tool. Custom items can be created and included here as well.
The Resources
The three types of resources that can be defined are icons, cursors and strings. The config.xml ties a GUID for an item to a particular resource. In this case we tie "b17f7ca0-0062-4dd8-adf6-1ea2192a3d35" to string "10223" and icon "104. These resources can be found in the project by double-clicking on resources.rct.
Note: It may be easier to create icons using an external editor instead of using the built-in editor and then use "Add Resource", "Icon", Import.
The APIs
Below is a list of all of the new functions added to the CorelDRAW X7.1 and Corel DESIGNER X7 object model:
This is a replacement for ActiveTool. It uses a GUID to identify the tool. Unlike ActiveTool, it can be used to get or set any state.
This allows third parties to register or unregister custom tools with CorelDRAW. UnregisterToolState does not need to be called before shutdown. RegisterToolState can be called multiple times with the same tool (e.g. if the code has been updated)
Notes: