SandBar User Guide

Getting Started

Back to Table of Contents

What is SandBar?

SandBar is a toolbar library with advanced layout functionality that utilises the same codebase to also provide menuing, task panes and statusbars. It makes the task of creating a complex, dockable toolbar and menu command structure easy by being fully configurable with drag and drop design.

Its main controls can be used in both a "managed" state where they are part of a layout, and standalone. The benefits of having a managed layout include being able to tear controls off in to a floating state, resize them and dock them in different parts of your form. It also makes layout serialization easy.

SandBar Primary Components

The following table lists the primary SandBar components - those that are added to your toolbox during installation and which you will place on the design surface.

ToolBar A bar that usually contains buttons, dropdown menus and labels. Can be used standalone or as part of a SandBar layout.
ContainerBar Extends the ToolBar class to provide Office task pane functionality, where multiple panels can be selected depending on the task the user wished to achieve. Can be used standalone or as part of a SandBar layout.
FlatComboBox Extends the windows forms ComboBox control to give it a flat, Office look. Also adds "default text" functionality. This control can be used in any container, including a toolbar.
MenuBar Extends the ToolBar class to provide menuing functionality. This type of bar usually just contains top level menu items. Also provides MDI controls for child windows. Can be used standalone or as part of a SandBar layout.
SandBarManager The core of a SandBar layout, add this component to your form when you want a whole layout of dockable toolbars and menus. Also provides layout serialization capabilities and a central renderer for all bars that are part of the layout.
StatusBar Extends the ToolBar class to provide statusbar functionality. This type of bar usually just contains statusbar panels. Also provides form resizing via a size grip. This control is usually only used in a standalone state (i.e. not part of a layout).

In most cases simply adding a SandBarManager component to your form is all you will need to do, as the manager provides its own controls for adding controls to your layout afterwards. It also adds a default StatusBar docked to the bottom of your form.

How a SandBar Layout is Formed

When using a SandBar layout, a SandBarManager component is responsible for keeping track of the various components. The manager keeps a renderer instance in memory which all member bars use to lay out and draw their child elements. It holds lists of the containers and bars which make up the layout.

When you add a SandBarManager to your form it adds four instances of the ToolBarContainer class to your form, one at each side. You should not modify these as they exist only to hold bars when the user wishes to dock to that side of your form. The containers each hold a reference to the SandBarManager and are responsible for layout out toolbars and menus, which are placed inside them.

Depending on the settings you have configured, the user can "grab" a toolbar and drag it either to other containers on your form or in to a floating state above the form. When the containers have no bars inside them they shrink so they cannot be seen.

Next: SandBar Controls