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 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 propertyes: 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 of 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.

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 services as 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

Context Menus

Menu and Toolbar Merging