SandBar User Guide

Using SandBar Items

Back to Table of Contents

Available Item Types

There are several different types of item available in SandBar, which can be used in many different places. The following table describes the item classes and their uses. All functional items can be extended through inheritance, and custom drawn.

ToolbarItemBase This is the base class from which all items derive, and exposes properties common to all items. All items support the following properties: BeginGroup, Enabled, Font, ForeColor, ItemImportance, MergeAction, MergeIndex, MinimumSize, Padding, Stretch, Tag, Text, ToolBar, ToolTipText and Visible. This properties are used by the SandBar layout and display engine to control how items are positioned, what they look like and how the user can interact with them. You cannot directly inherit from this class.
ControlContainerItem

This is an item that supports embedding an arbitrary windows forms control inside itself. It keeps track of the position of the control and exposes a ControlText property to gain quick access to the hosted control's text, and a ContainedControl property to fully access anything else exposed.

It is easy to extend this class to host any kind of control, all you have to do is pass an instance of the control to the base constructor when inheriting from ComboBoxItem. An example of doing this can be found in the SandBar FAQ.
ComboBoxItem This item wraps the functionality of the FlatComboBox class in to an item that can be hosted on a SandBar toolbar. It exposes the most common properties, the rest can be accessed through the ComboBox property.
ProgressBarItem This item wraps the functionality of the ProgressBar class in to an item that can be hosted on a SandBar toolbar. It exposes the most common properties, the rest can be accessed through the ProgressBar property.
ImageItemBase This item extends ToolbarItemBase by providing support for an image in one of three ways: an imagelist on the parent toolbar, a directly assigned icon or a directly assigned image. It divides the space of the item in to an area for text and an area for the image, depending on the right-to-left and image alignment settings of the toolbar. You cannot directly inherit from this class.
LabelItem This item is meant for simple display of text and an image. It does not get highlighted when the mouse is passed over it.
StatusBarItem This item inherits from LabelItem and adds a ShowBorder property which controls whether the renderer draws a border around the item on a statusbar.
ButtonItemBase This item provides a base for button items. It provides a Checked property, which can be used to display items in a toggled state. You cannot directly inherit from this class.
ButtonItem This is the standard toolbar button, and probably the item you will use most on toolbars. It provides a BuddyMenu property which can be used to tie the button to a corresponding menu item. The menu item will then be activated whenever the toolbar item is automatically, and the toolbar item will also track the Enabled and Checked states of its menu item. This is a great way of avoiding writing duplicate code for handling toolbar item and menu item clicks.
MenuItemBase This class serves as a common base for menu items, and exposes an Items property containing child menu items. If you need to check whether a menu item has any children you should use its HasChildren property, as the child item collection is created only when needed for performance gains. You cannot directly inherit from this class.
TopLevelMenuItemBase This class serves as a common base for menu items that will be shown at the top level, e.g. context menus and menus that will appear on the menubar of an application. It exposes many different Show methods, which can be used in different situations depending on requirements.
DropDownMenuItem This item is a special type of menu item that can be added to a normal toolbar. It displays a dropdown glyph beside the normal image and text, and clicking this glyph will reveal its child items. These items are often used for Undo and Redo commands, or a New command that supports many different types of new documents.
MenuBarItem This item is the most common type of item to add to a MenuBar control. Your File, Edit, View etc items will all be of this type. It adds a little extra padding to the sides of items compared to normal items. It also exposes an MdiWindowList property, which if set to true means that the item will keep track of any open MDI windows in your application. When dropped down it will show a list of these and allow the user to pick which is active.
ContextMenuBarItem This item extends MenuBarItem and simply sets itself to be invisible by default. Any top level item can be used as a context menu, but it is convenient to use this item as a template for most.
MenuButtonItem Most non toplevel menu items are of this type. It can host child menus and supports associating keyboard accelerators with itself. It also changes the purpose of the ItemImportance property, allowing only the Low and Medium options. When set to low, the item is not immediately available on display of its parent menu - instead the user will have to click a chevron to see it. This is useful in large, complex menu systems where you may only want the user to see the most common items at first.

Images

SandBar supports three different ways of using imagery on its items. The different methods with their pros and cons are listed below.

ImageLists

You can associate a toolbar with an ImageList via its ImageList property. Following this assignment, you can assign a numeric index to the ImageIndex property on any item on that toolbar, which will then draw that image from the ImageList. Top level menu items that contains children also support a MenuImageList property - if this is assigned to, menus will use that ImageList instead of the toolbar's.

The main advantage of using ImageLists is that you can easily share images between controls on your form. However, using .NET 1.x you subject yourself to bugs inherant in the .NET ImageList implementation which prevent the use of high quality images with alpha channels, as used in Office 2003.
Direct Icon Assignment

Items have an Icon property, to which can be assigned a standard Windows icon. They also support an IconSize property. Depending on the IconSize setting a different icon will be retrieved from the Icon property for measurement and drawing.

Using icons directly enables alpha shadows on Windows XP, and provides a good way of allowing the user to choose between toolbar icon sizes. Because of icons' inherant capabilities for storing multiple images of different sizes, all you have to do is change the IconSize property and your toolbar can instantly update itself with new sized icons.
Direct Image Assignment

Items have an Image property, to which can be assigned any image that can be loaded with the standard GDI+ .NET wrappers. The recommended method of using images with SandBar is to use the Image property and PNG format images. These images allow full alpha information and are managed by SandBar, so do not suffer the bugs of the ImageList control.

Using Visual Studio 2005, you can assign images from any central resource file in your project, thereby avoiding duplicate storing of images.

Context Menus

SandBar supports showing any toplevel menu as a context menu on a control. At design time, you will see that a SandBarMenu property has been added to all the controls on your form, if you have a MenuBar on that form. This design-time property allows you to easily associate context menus. At runtime, you can use the SetSandBarMenu method of your MenuBar to do the same thing.

Once you have associated a context menu in this fashion, SandBar will intercept normal win32 context menu events and display the menu you specified instead of the default menu. Context menus are usually shown upon right-click or the user pressing the menu button on the keyboard.

When a menu is about to be displayed, its BeforePopup event is triggered. In this event you can specify the point around which the menu is centered, if showing a context menu. This is useful in situations such as a treeview control where you may want the menu to appear next to the selected node, as opposed to the centre of the control (default behaviour).

Menu and Toolbar Merging

SandBar supports merging of items from one toolbar or menubar to another. This is achieved through several properties on the toolbars and items in question. Firstly, the AllowMerge properties of both the source and destination toolbars need to be set to true.

When using MDI child forms in your application, SandBar will automatically merge a standalone menubar on the active MDI child into the menubar on the parent form. If you are using a third-party product such as SandDock to switch between documents, you will need to call SandBarManager.Merge manually. This is all you will need to do, however - SandBar keeps track of merged toolbars and will unmerge any previous operation before another.

How the items on the source toolbar are merged with items on the destination toolbar is controlled with the MergeAction and MergeIndex properties of the source items. With these properties it should be possible to configure most menu systems.

Some MergeAction values depend on matching the source item to an item in the destination collection. This matching usually takes place using the MergeIndex property to indicate the numeric index of an item in the target collection. However, SandBar will also merge on the Text properties of items, if a matching item is found. A description of the MergeAction possibilities and their actions follows:

Add

The source item is added to the end of the destination collection. For example, a Help menu would usually have this MergeAction so that it gets added to the end of the target menu bar. Any child items of the source item are also merged across, unconditionally. The MergeIndex property is ignored in this case.
Insert

The source item is inserted in the destination collection at the numeric index governed by the MergeIndex property. For example, you could create a menu item called Tools that you wanted to be inserted as the third item in the destination menu bar. You would set MergeAction to Insert and MergeIndex to 2.

Any other items in the source collection with the same settings would be inserted after the first, in the order they appear in the source collection. Any child items of the source item are also merged across, unconditionally.
Remove

The source item is ignored, but the matched item found in the destination collection is removed. You would typically create a simple item just for the purposes of removing a destination item.
Replace

The matched item in the destination collection is removed and replaced with the source item. Any child items of the source item are also merged across, unconditionally.
MergeChildren

The most powerful merge option, this will recurse over an item's child items if it finds a match.

Imagine you have a File menu on both source and destination menu bars, and you want to add Save and Close options to the destination menubar when your source menubar is active. You would need to set MergeAction to MergeChildren on the source File menu. As long as the two menu items have the same text (&File, for instance) you do not need to set MergeIndex.

Your source File menu has two items, Save and Close. Those items would both have their MergeAction set to Insert, and MergeIndex properties set to insert them at appropriate locations in the target menu. These settings are all you need to accomplish the above scenario.

Of course, you can also use MergeChildren on child menu items. If all you want to do is add a child menu item to your File -> New menu, for instance, you would create a File menu (MergeChildren) with a New item (also MergeChildren) and then a child of that item set to Add.

Next: Advanced Topics