SandBar User Guide
SandBar Controls
Toolbars
Toolbars form the base class from which the other bar controls in SandBar derive. They contain a collection of items, which all derive from ToolbarItemBase. Toolbars and their derivatives can be either shown in a standalone state, where a Toolbar control is simply added to your form, or as part of a SandBar layout, where it is added to a special container by your SandBarManager.
Docked toolbars are grouped together in to lines by their parent control. There can be multiple lines docked at any side of your form, and multiple toolbars in each line. In its line, a toolbar is offset from the beginning of the line by a given amount, usually chosen by the user by dragging the toolbar. To change this programmatically, use the DockLine and DockOffset properties. Toolbars can optionally take up an entire line to themselves, and not allow any other toolbars to dock with them. This is accomplished by setting the Stretch property.
The item layout engine in toolbars is very powerful. It supports both horizontal and vertical layout of items, in either left-to-right or right-to-left reading order. This layout engine is at the core of all the SandBar classes. When using a toolbar in a standalone state you can manually control whether items are laid out horizontally or vertically with the Flow property. When the toolbar is part of a layout, the flow is governed by whether the toolbar is docked at the top or bottom (horizontal layout) or left or right (vertical layout).
Screen real estate is often limited, and for this reason toolbars may need to be shrunk from time to time. When a container is not wide enough to show all the toolbars on one line, the toolbars are decreased in size proportionally. When this happens, the items held within the toolbar are either hidden or wrapped to a new line. This behaviour is governed by the Overflow property. By default, items are hidden from view but are accessible by clicking on the chevron at the end of the toolbar.
Items within toolbars can be assigned a level of importance, so that when space is limited the less important items are hidden first. There are five levels of importance that you can assign to an item's ItemImportance property. This will only take effect when the Overflow property of the toolbar is set to Hide or Chevron.
Right-to-left layout of items in toolbars does not happen automatically, even if the form's RightToLeft property is set. To allow it, set the toolbar's AllowRightToLeft property. This behaviour is taken from Microsoft Office, where menus support right-to-left layout by default but toolbars do not.
Toolbars have several properties that goven how the toolbar may be interacted with by the user:
| AllowHorizontalDock | Determines whether the user will be able to dock the toolbar at the top or bottom edge of the form. |
| AllowVerticalDock | Determines whether the user will be able to dock the toolbar at the left or right edge of the form. |
| Closable | Determines whether the user will be able to hide the toolbar. |
| DrawActionsButton | Determines whether the actions button at the end of the toolbar is drawn. This button contains the chevron that allows the user to access items that have been hidden due to space constraints. |
| Movable | Determines whether the toolbar will display a gripper allowing the user to move it around in its container. |
| Resizable | Determines whether the user will be able to resize the toolbar when it is floating. Resizing the toolbar will result in items wrapping to new lines. |
| Tearable | Determines whether the user will be able to tear the toolbar out of its docked position in to a floating state. If Movable is set to false, this property has no effect. |
Menus
The MenuBar control extends the ToolBar control to provide menuing facilities. It is fully aware of the MDI architecture and will display appropriate buttons for controlling the layout of MDI windows present in your form. MenuBar changes the default value of the Stretch property to true, so it takes up a whole line by itself in a container, the AllowRightToLeft property to true, so menu items are automatically right-to-left aware when displayed in an appropriate locale.
MenuBars are responsible for listening for keyboard accelerators so they can activate the corresponding item. They must also be aware of the form they are situated in so they can listen for MDI events. If you are using a SandBar layout this will be taken care of automatically, but if you are using a standalone MenuBar control you should ensure its OwnerForm property is correctly set.
When dealing with MDI forms, the SandBar MenuBar can show either all three mdi buttons (close, restore or minimize), close only, or none at all. This is governed by the MdiButtonDisplay property. You can also choose to turn off the display of the MDI system menu and icon by setting the ShowMdiSystemMenu property to false.
Task Panes
Otherwise known as the ContainerBar control, task panes extend the ToolBar control to provide a host for other controls, which is fully designable. A task pane has a titlebar, and a number of child windows which can be switched between with an optional dropdown menu shown in the titlebar. Items belonging to a task pane are shown in a smaller toolbar area just under the titlebar.
By default, when you create a ContainerBar it has one child area ready for placing controls in. You can add further child panels by using the Add Panel verb in the propertygrid at design time, or adding a new instance of the ContainerBarClientPanel class to the ContainerBar's Controls collection at runtime. There can be only one client panel visible at once, and this is controlled by setting the SelectedChildPanel property. A good use of this is to have multiple panels for multiple tasks, and allowing the user to switch between them in your application depending on context.
The optional dropdown menu situated in the titlebar of a ContainerBar can allow automatic access to the different client panels installed. This menu is not available by default, but can be created by setting the UseTitleBarMenu property at design time, or assigning a new menu to the TitleBarMenu property at runtime. Once this property has been set with a menu, the titlebar changes its behaviour to show the menu when clicked.
The titlebar menu in a ContainerBar is of a special type, and when you add child menu items to it at design time they are of a special type too. The ContainerBarTitleBarMenuItem class has a ClientPanel property, which you can set to associate a child menu item with one of the panes in your ContainerBar. It will then automatically get its text from that panel, and clicking that menu item at runtime will cause the ContainerBar to switch to that child panel. Using this powerful set of classes allows you to set up a complex array of task panes with menu items to access each one, without writing a single line of code.
ContainerBars can only be set to horizontal item layout.
Statusbars
Statusbars are the newest addition to the SandBar suite of controls and leverage the existing bar, layout and item architecture. Key differences from toolbars are that they are always standalone (you do not want a dockable statusbar), they can display a size gripper at the bottom-right corner and the default type of item is StatusBarItem.
The existing Stretch property on items allows you to set items that stretch to occupy as much of the statusbar's inner area as possible. If multiple items have this property set to true, they will all proportionally use up the extra space. A statusbar is automatically added to your container when you add a SandBarManager, but the component is always available in the toolbox if you want to add one later.
The size gripper at the bottom right of the statusbar will be shown as long as the ShowGripper property is set to true, the form is not maximized and the form has a sizeable border.
The FlatComboBox
FlatComboBox is an extended version of the windows forms ComboBox control that supports custom rendering via a SandBar renderer and "default" text. The FlatComboBox control is used by the ComboBoxItem component that can be added to toolbars.
Default text is text that is shown in an empty combobox until the user types their own text in. An example of this is in recent Microsoft products, which often display a combobox at the right-hand edge of menubars with the faded text "Type here for help" that disappears when focus is set to the control and text typed in. This effect is easy to achieve by setting the DefaultText property of this control.
Aside from this and the custom painting, this control exactly mimics the windows forms ComboBox control.