SandBar Release Notes

Home / Products / SandBar

Version 1.0.9

Event Model Changes

It was necessary in this release to change the type of the delegate assigned to MenuButtonItem's Activate event handlers to the generic System.EventHandler type. The first reason for this was to facilitate the move to a generic Activate event for all ButtonItemBase-derived toolbar items, and the second and more important reason was to make possible the use of SandBar with Visual C++. A bug in the VC++ serialization engine had previously prevented correct serialization of menu events.

Changing this type was a difficult decision to make because it will make it necessary for 99% of people using SandBar with C# to update their code. Thankfully the update is a trivial one and I hope you can accept my apologies for the inconvenience. To be sure of a successful update, please follow the steps below.

Please note that because of the shielding VB provides against event handler types, VB.NET users should not be affected by this change and will not have to follow these steps.

1. Make sure all designer windows are closed.

   Open your project/solution in Visual Studio, and close any open designer windows. When the windows have been closed, close Visual Studio again.

2. Update your SandBar library.
3. Use find/replace to update old code references

   Open your project/solution in Visual Studio. There should be only code windows open, and expanding your References node should reveal that Visual Studio is looking at the 1.0.9 version of SandBar. Attempting to build your project at this point will almost certainly produce errors.

   • Go to Edit -> Find and Replace -> Replace in Files
   • In the Find box, type TD.SandBar.MenuButtonItem.ActivateEventHandler
   • In the Replace box, type System.EventHandler
   • Make sure "Look in" is set to Entire Solution.
   • Perform the replace - Visual Studio will warn about global find and replace operations.

   That's it! After updating your event handler references with this global find/replace your project should build. In some instances, you might have referred to only MenuButtonItem.ActivateEventHandler if you had the using TD.SandBar statement in your code. If so, you will need to perform another find/replace to replace this string too.

Unified Event Model

The Activate event is now common to all button types, including both toolbar and menu items. Previously, unless a toolbar item was linked to a menu item, you had to catch the Toolbar.ButtonClick and filter through your toolbar items to see which one was clicked. With the changes in this build, every toolbar button has its own event.

This does not mean your code will be broken - the ButtonClick event of the Toolbar class is still there and in fact both events are called, ensuring that whatever your preference of event model, SandBar will cater for you. The only difference to be aware of is that at design time, double-clicking on a toolbar item will take you to the event handler for that button, not the Toolbar's ButtonClick event.

Direct Image Assignment

All toolbar and menu items now have an Image property, which can be used to directly assign an image to them rather than go through an ImageList. This is great for situations where you need to display incidental images but don't want to have to create an imagelist to show them.

There are several flaws with using ImageLists to store the images used on toolbars. The first is that because of a bug in the underlying GDI+ technology, any image added to an ImageList loses its alpha-channel information, thus making it impossible to use 32bit images with smooth edges. The second is that the paradigm for centrally-stored lists of images is changing. The ImageList is a holdover from Win32 days, and forthcoming versions of Visual Studio and .NET will see project-wide image repositories and direct image assignment as you are seeing with SandBar.

I already mentioned the easier ability to use 32bit images in SandBar. Use of high-quality PNG images for toolbar icons is now the recommended method of producing Office 2003 style toolbars, and the results can be compared below. Note the smooth edges of icons and therefore much more visually appealing toolbar.

Before

After

User Resizing of ContainerBars

Unfortunately this feature just missed the last release because of time constraints. It is now fully implemented, and Container Bars can be resized by the user while they are docked and while they are floating. Two new properties, MinimumDepth and MaximumDepth allow control over the limitations of resizing.

The toolbar layout serialization feature has also been updated to persist the sizes of these controls.

ContextMenus and RichTextBoxes

RichTextBoxes have an unusual bug, where they do not send the standard WM_CONTEXTMENU message when they are about to display their context menu. In previous versions of SandBar this had meant that a SandBar menu assigned to a RichTextBox would never be displayed.

The recommended workaround for this bug has so far been to trap the control's MouseUp event and show the SandBar menu manually. This is no longer necessary as the workaround has been built in to SandBar. Context Menus assigned to RichTextBoxes in the standard way (SetSandBarMenu) will now appear correctly.