HomeSite Help

Toolbar Tips

 

We're moving!

This whole site is being moved to a shiny new server - as are all my sites, in fact. Apologies for the bumpy road ahead, but at the end of that road things will become fast and smooth.

Once the site at the new server is ready, this message will automatically disappear!

Meanwhile, you can see how the move is progressing at the status page.

 
   Home | HTML section | VTML section
On this page:
Introduction
Toolbar images
Distributing toolbars
 
 

Introduction

Here are some tips for creating custom toolbars that you will not find in the program documentation. I found these techniques by simple experimentation. Since they're useful, I'm sharing them with you.

Images

When you create a toolbar button for an external application in HomeSite or ColdFusion Studio, the easiest way to do that from the Customize dialog is to browse to the executable file to include the full path for it; then in the next entry field you can add any command-line parameters. The special symbol %CURRENT% is handy for running applications that support a file name as (a part of) a command-line parameter. The program will then display the program icon it finds in the executable as a toolbar button. Great idea.

But I found it's not always as simple as that. The first topic on this page will teach you how to control which link images appear on the toolbar when the ones that appear automatically just won't do. Using some undocumented features...

Distribution

The second topic on this page contains a whole number of tips for when you don't just create toolbars for yourself, but want to distribute them to fellow developers as well. With more undocumented features!

Code

Since most of these techniques somehow involve editing the text file that defines a toolbar, there are some code examples; if your browser supports JavaScript 1.2 (both version 4 browsers do), you can see them in side-by-side popup windows: two windows for each example since the code for HomeSite and ColdFusion Studio 3.x is different from that for the 4.0 versions of these programs. This works best if your screen resolution is set to at least 600x800. The windows can be left open; other examples will then show up in the same windows. They can be resized and repositioned.

If you are using Internet Explorer, size and position of the windows will be retained as long as you leave them open. The link on the right is for pre-sizing the windows, if you like; if you don't see a link here, your browser doesn't support JavaScript 1.2 or it's disabled.

In case you can't use these popups, all code examples have also been gathered on this page.  to menu

 
 

Toolbar images

Images and executables

When creating the RCS toolbars I ran into a problem: almost all commands are for the same executable: they differed only in the command-line argument. My first attempt at creating this toolbar ended looking something like this:
 The RCS toolbar as it shouldn't be
Of course, that was not exactly what I intended: you'd have to rely on the tooltips to find out which button is for what. I tried adding image files in the toolbar definition files, but HomeSite showed the program icons regardless. The separators I added help a little to remember what function is where, but the whole idea of having icons is easy recognition.

So how did I create a toolbar with different images for each? With hindsight, the principle is quite simple:

  • HomeSite needs the full path to an executable to find it to display its program icon.
  • Windows (like DOS) does not really need the extension: when the extension is not defined (or the path is not defined) it has a searching mechanism to locate the executable command or program.
  • By simply leaving off the .exe extension, HomeSite cannot find the program to display its icon, but Windows can still find it to execute.
  • When HomeSite cannot find the program icon, it will display the Windows default icon - unless an image file is specified in the toolbar definition file! Then that image is used on the toolbar. This works with both HomeSite 3.01 and HomeSite 4.0 - and of course in the corresponding versions of ColdFusion Studio.

So: I simply left off the .exe extension of csrcs.exe and supplied my own function icons. I did the same for DocumentManager.exe: it did have a different program icon but that didn't scale very well to the 18x18 format needed for toolbars; so I substituted my own. All image colors are carefully matched, too so they really look like they belong together. The result (latest version) looks like this:
 The RCS toolbar with custom images
If an image is not located in the Toolbar directory, supply the full path, otherwise all you need is the image name.

Example code

If you want to apply this technique for your own custom toolbars, start by creating the toolbar from the normal interface. Since you cannot specify an image there, the next step is to edit the .tbr file you created with a text editor (not HomeSite or ColdFusion Studio!) and make the necessary changes. Note that for 3.x the image only needs to be filled in while for 4.0 the whole line must be added.

Images and non-program files

No wait... there's more. If you look at the screen shots of the toolbar above, you'll also see a little 'Help' icon. Which is cause for another toolbar image tip.

The 'Help' icon appeared because I simply put the .hlp file on the toolbar. Now HomeSite or ColdFusion Studio does what Windows does (or, more likely, they let Windows do it for them): it goes and finds the application that is associated with the file type, and displays the program icon for that associated program.

While that's nice for a single 'Help' icon, what if you want to put a a whole bunch of (say) .pdf files on a toolbar? You'd be back with the same problem we had above: all the same icons.

The solution is similar to the first tip:

  • Use Windows Explorer or the Registry editor to find the program that is associated with the files you want to put on the toolbar
  • Put that program's full path as the program on the toolbar, and define the file to be displayed as its command-line parameter
  • Now again leave off the .exe from the executable program, and supply your own toolbar image.
Image format

Toolbar icons must be bitmaps (.bmp) of 18x18 pixels. Smaller is possible but you'd leave the positioning to the program.

If you create your own, remember that the lower left pixel color is always taken as the transparent color.  to menu

 
 

Distributing toolbars

There was a question on the HomeSite Conference recently that went something like this: "I've downloaded a toolbar; now how do I install it?". There was really only one answer I could give: "It depends.... Ask whoever distributed the toolbar..."

There are a few things you should keep in mind if you want to prepare toolbars for distribution to fellow users. I'm still learning how to do it better; meanwhile I'll pass on the tricks I've learned so far:

Different versions
  • First of all: The format of the text files that that define toolbars has changed from version 3.x of HomeSite/ColdFusion Studio to version 4.0 of those programs. They are not compatible. While there may be good reasons for this change, it does mean two things: You should be aware of the difference and you should make sure your (potential) users are aware of the difference:

    • The very least you can do is make very clear which version of the programs the toolbar has been developed for; make the version clear somehow before people download your toolbar rather than only in a file included with a downloadable archive;
    • If at all possible, develop two versions of your toolbar: one for each program version (and study the differences in their definition files before distributing anything!).
    • If the toolbar was prepared before the versions 4.0 of the programs were released: update your information to make it clear for which version the toolbar was developed; or create an additional version for version 4.0!

  • Second: always have installation instructions (on-line or included in an archive: as long as they're there!); some people may be interested in using your toolbar but have no clue about what to put where and how to proceed from there. And the process is different for version 4.0 from that needed for version 3.x.  to menu

Images

The best way to include toolbar images is to have them installed in the Toolbars directory and refer to them from the toolbar definition with just the file name. Remember: both versions of the programs have a Toolbars directory; it's just located in different places in the directory tree for each. Include the toolbar images in the archive you're making available.  to menu

External programs
Example code

Do not ever make any assumptions about the user's installation path of a program: it may be on a different drive letter and under a different directory than yours. There's a number of things you can do about this - regardless of program version:

  • When creating a toolbar button the path to an external program will always show up as a fully-qualified path, complete with drive letter. Include something in your installation instructions about what needs to be changed where to correspond to user's own installation path to that same program.
  • If your users will need to edit the toolbar definition file(s), make sure it's as readable as possible for humans: the programs don't care about white space but for humans it can help divide the information into chunks: use empty lines to separate the definitions of each button.  to menu

Tag Editors
Example code

When creating a toolbar button for a Tag Editor (.vtm) both versions of the programs will also write the complete file path to the .vtm file. Previously, I suggested you eliminate the path to leave only a path relative to the program's installation directory. However, due to a bug in older versions of the programs, this will only work until the user activates the browse tab: after that, the program "forgets" where it is installed and the relative path will no longer work - until you close and reopen the program.

This problem is fixed as of beta 4 of the 4.01 maintenance release for HomeSite and ColdFusion Studio. Alas, this also means that you'll have to tell your users to edit the paths for all older versions. I'd suggest the following strategy for distribution:

HomeSite 3.01 or ColdFusion Studio 3.11
[full path]\Whatever.vtm
Tell your users to edit the path with their own installation path.
HomeSite 4.0x or ColdFusion Studio 4.0x
Edit the toolbar definition file to show only the path relative to the program's installation directory:
Extensions\TagDefs\Whatever.vtm
Tell your users to add the installation path if they have not yet upgraded to the 4.01 maintenance release.  to menu

Distribution archives

Make sure the archive you distribute does not itself contain any path names to the toolbar files: only that way it can be installed in wherever the Toolbars directory is for the program version(s) you developed it for without making assumptions about the user's installation paths or directory trees.

The basic principle: You already know what to do with that toolbar; make sure your users do as well!

For some inspiration, have a look at the toolbars I'm distributing for integration with the Windows version control system CS-RCS, and of course the installation instructions for them: they contain paths to external programs and the instructions make clear they should be edited.

The toolbar included with my HTML Tag Definitions is another example: it contains file paths to the Tag Definition files that are relative to the program installation path: with the latest program versions (maintenance release 4.01) they will always work regardless of where or on what drive the user installed the program.  to menu