A step by step guide to developing a plugin for ActiveFinish

We're pleased to announce the release of a user-friendly guide for plugin developers that demonstrates each stage of creating an element/ effect plugin, along with its design-time editor.

The guide is included, as a .chm and .pdf file,  with the plugin developer kit, and can also be view online here.

The code samples in the guide are at present only in the Visual Basic language, but we hope to have a C# version very soon...

Update 1st March 2011

The guide is now available on-line in both the Visual Basic and C# languages, and contains links to download the source code and the guide in the .chm and .pdf formats :

• Visual Basic Guide
• C# Guide

Creating a link to a Sandcastle Help File Builder page

Just a quick tip for anyone wishing to link to a page within a Sandcastle help file from a page that is outside of the help file. You can, of course, just create a direct link to the page, but what if you want the page to be displayed with the contents side-bar and search facility? Here's how:

<a href="http://index.aspx?topic=html/required_page.htm">click here</a></p>

It's also useful to change the project NamingMethod property from the default value of Guid to MemberName, so that you have user friendly names for your pages.

 

Associating an Image with a Plugin and ToolboxBitmapAttribute

The ActiveFinish Canvas editor has an Element picker control that appears and behaves much like the Visual Studio toolbox. For this reason, when developing an element, it is possible to associate an image with the class, so that a pictorial representation can be displayed next to the description in the picker control. This is implemented via an attribute so that the classes don't have to be instantiated in order to get at the image.

There are two ways to achieve this:

Firstly, you can attach the Microsoft .Net ToolboxBitmapAttribute which allows you to refer to an Image or Icon that is contained in a resource.

One interesting quirk I noticed about this attribute is that when attaching it in VB.Net, the resource name must not be qualified with the root namespace, whereas with C#, it must be qualified. As an example, consider an embedded resource, 'myButtonImage.bmp', that you want to attach to the class, 'myButton', whose root namespace is 'myControls'. To attach the attribute in VB.Net, you would type:

<ToolboxBitmap(GetType(myButton), "myButton.bmp")>

... but to attach the attribute in C#, you would type:

[ToolboxBitmap(typeof(myButton), "myControls.myButtonImage.bmp")]

Secondly, you can attach a new AssociatedImageAttribute which allows you to refer to an Image or Icon that is contained in a resource file.

A resource file is a resource which, itself, contains a collection of resources. There is a default resource file created with every new project which you can find by going to the property pages and clicking the Resources tab. There you can add Icons, Images, Strings, etc.

As far as I know, it is not possible, using the ToolboxBitmapAttribute, to refer to a resource contained in a resource file, which is why I created the new attribute. Let me know in the comments if I'm wrong in this.

The syntax of the AssociatedImageAttribute is very similar to the ToolboxBitmapAttribute:

<AssociatedImage(GetType(TextPlugin), "TextPluginIcon")>

The attachment, above, tells ActiveFinish to search the default resource file for a resource called TextPluginIcon. It is also possible to target a specific resource file:

<AssociatedImage("rootNamespace.MyResources", GetType(myPlugin), "myPluginIcon")>

 

For the rules on targeting a specific resource file, see the description of the baseName parameter of the ResourceManager class on MSDN.