ActiveFinish version 1.1 released

A new version of ActiveFinish has been released that modifies the way changes are viewed when an effect is being edited.

When an element is being edited, the changes are reflected on the canvas as they are made. It used to be that when an effect was edited, a small window in the editor would show the changes. The preview window has now been removed, and the changes are now reflected on the canvas.

In addition, changes made to the effect collection are now reflected immediately on the canvas. So, if an effect is added, removed or moved within the collection, you'll see how this effects the layer immediately.

See the change log for the full details of the change.

How to create a .chm and .pdf file from a single web page

I thought I'd pass on the knowledge I've learnt from creating downloadable versions of ActiveFinish website help pages. This article explains how to create a Microsoft HTML Help .chm file and an Adobe .pdf file from a single web page.

If you want to skip the preamble, click here to get straight to the prerequisites.

Preamble

In order to create your files, the first thing you need to do is save the web page, along with all its images, css and any images that the css files refer to. You'll find with most web browsers, such as Firefox and Internet Explorer, that if you save complete, the image and css files are saved fine, but any images that the css refers to are not saved.

I found that the best browser, by far, for complete saves is Opera, which also save the images, such as background images, that are referred to from css files. (I tested with Opera 11.01, but I'm not sure about previous versions). Unfortunately, however, it has a bug whereby any local links, following a #, are truncated and thus lost. My saviour was the Firefox add-on ScrapBook, which saves everything and handles local and external links perfectly.

For creating the .pdf file, I tried all kinds of stand alone apps, and Firefox add-ons, but in all cases either css would be missing, css images missing, or both. Finally, I found an excellent free tool called wkhtmltopdf, which produces an absolutely perfect file which is also searchable - i.e. it doesn't just create an image of your page and slap it in a .pdf document.

Prerequisites

• Download and Install the Firefox ScrapBook add-on
• If you're creating a .chm file, you'll need the Microsoft HTML Help Workshop
• If you're creating a .pdf file, you'll need wkhtmltopdf

 Prepare Your web page

• Navigate to your live web page and click ScrapBook > Capture Page.
  A folder will be created that contains the web page (index.html), the images, and all the css combined into one file (index.css).
• Open up the page, index.htm, and delete any headers, footers or anything else that you don't need.
• If you'll be creating a .chm file and your web page contains conditional references to Internet Explorer css files, or any of your css files contain IE hacks, you'll need to do a little further work. Because all the css is combined into one index.css file, conditional references cannot be used. Unfortunately, if instead you use hacks, ScrapBook removes the entries. For this reason, you'll need to edit index.css and put the hacks back in.

Create the .chm file

• Open notepad, enter the contents in the box below, and save as helpbuilder.hhp, in the same folder that contains index.html:
  
  [OPTIONS]
  
  [FILES]
  index.html
  image_file_referred_to_in_css_1.png
  image_file_referred_to_in_css_2.png
  ...
  Note you only need to add references to files referred to in css in the helpbuilder.hhp file. That is, if you refer to an image in HTML, the HTML Help Workshop compiler will automatically pick it up.
  
• Double click helpbuilder.hhp and click compile.

You'll now have a .chm file called helpbuilder.chm.

Create the .pdf file

1. wkhtmltopdf is command line based, so I recommend creating a folder that is easy to navigate to in a command prompt, such as zTemp1. Then, copy all the ScrapBook output files over.
2. Open up a command prompt, navigate to zTemp1 and type: wkhtmltopdf index.html index.pdf
3. You now have the .pdf document called index.pdf. Open it up, and see if there are any parts of the document that have clumsy splits between pages. If there are, you can edit the index.html file and do one of the following:
   
   • Create a line break before the block that you don't want splitting with: <div style="page-break-after: always;"><span style="display: none;">&nbsp;</span></div>
   • Wrap the block with the following: <div style="page-break-inside: avoid;">...</div>
   Note it is fine to add the css page-break entries to your original website pages and they won't affect its layout.
   
4. Repeat from step 2, until you're happy with the page breaks.

That's all there is to it! If, like me, you have a bunch of help pages that all use the same css files, and hence the same css referenced images, you only need to create the HTML Help Workshop .hhp file once. Once you've created the file, it takes no time at all to save your web page, using ScrapBook, and then copy the .hhp template to the output directory and compile the file.

 

A step by step guide to creating a rollover button with ActiveFinish

We're pleased to announce the release of a guide that takes you step-by-step through the stages of creating two rollover buttons with ActiveFinish. With the guide, you learn how to:

1. Create the button class
2. Design the button surface
3. Change an element's properties at run-time
4. Change an effect's properties at run-time
5. Create a click effect

The guide is 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

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.

 

Express Edition Released!

We’ve decided to release a cut-down free Express edition of the framework so that anyone can start designing control surfaces, whether they're prepared to part with their hard earned cash or not.

It’s a tough balancing act deciding what limitations to place on such an edition because, on the one hand you want the product to be usable and on the other, you don’t want to eradicate the demand for a paid version!

The Express Edition is the same as the Standard Home Edition, but with the following limitations:

• The Canvas is limited to 1 Layer at design-time.
• You can add a maximum of 3 Elements to the Canvas at design-time.
• You can add a maximum of 1 Effect to the Layer at design-time.
• No access to the Angle and Bounds Menu Items.

I should stress that the first 3 limitations, above, apply only at design-time. You can add as many Layers, Elements and Effects at run-time as your PC can handle.

Click here to see a full product comparison.

I’d like the comments in this blog entry to serve as feedback on the Express edition; whether good or bad, all are welcome.