SandBar FAQ

This thread will be used to post answers to questions commonly asked about SandBar.

Some forms in Office, such as Microsoft Outlook, set their background colour so that it matches the toolbar system. This helps gives the form a consistent look when it does not show much background.

Assuming you are using the Office 2003 renderer you can cast your renderer to that type and use the BackgroundGradientColor2 property. This property exposes the colour used to draw the right-hand side of the gradient behind toolbars.

[code]
// c#
this.BackColor = ((TD.SandBar.Office2003Renderer)sandBarManager1.Renderer).BackgroundGradientColor2;

' VB
Me.BackColor = DirectCast(sandBarManager1.Renderer, TD.SandBar.Office2003Renderer).BackgroundGradientColor2
[/code]

NOTE: The user can change their theme at runtime. If they do this, you must ensure that you update your form with the new background colour that SandBar will have calculated.

To receive notification when the user changes their display preferences like this, subscribe to the Microsoft.Win32.SystemEvents.UserPreferenceChanged event.

Yes, you can. Simply use the SandBarContextMenu property that SandBar will have added to your NotifyIcon component at design time to assign the menu that you want to be displayed.

At runtime you can use the SetSandBarContextMenu method of your MenuBar to achieve the same effect. To remove a SandBar menu from your NotifyIcon component, use this method passing a null reference.

This can happen when a toolbar is copied and pasted within the designer to create a new one. Toolbars have a Guid property that uniquely identifies them within the toolbar layout. This is essential for layout persistance. If two toolbars end up with the same Guid the layout persistance will not work entirely as expected.

This property is not exposed to the propertygrid, so the best way of changing it is to locate the instance of a duplicated Guid in the designer-generated code and remove that line of code. The next time the designer is opened a new Guid will be generated and saved with the rest of the layout.

The ComboBoxItem is not meant to encapsulate a ComboBox, only to host one. As such, only the few most common properties from the combo box are echoed to the ComboBoxItem class. It exposes a ComboBox property that allows access to the underlying windows forms combo box control.

For instance, to bind an event to the inner combo box's SelectedIndexChanged event:

[code]
// c#
comboBoxItem1.ComboBox.SelectedIndexChanged += new EventHandler(OnComboBoxSelectedIndexChanged);

' VB
AddHandler comboBoxItem1.ComboBox.SelectedIndexChanged, AddressOf OnComboBoxSelectedIndexChanged
[/code]

All bars within SandBar can host any arbitrary control within an item. You can therefore achieve common tasks such as hosting a combobox in a toolbar or a progressbar in a statusbar.

Although an item that hosts a combobox is packaged with the SandBar library, if you need to host any other kind of control you will need to create your own item that hosts it. This is very easy to do.

You must derive from the ControlContainerItem class. The minimum you have to do is create a constructor which calls the base constructor passing a new instance of whatever control you wish to host. You can then use the ContainedControl property to gain access to the control created. SandBar will take care of hosting and positioning the control in the toolbar.

For instance, to create an item that hosts a checkbox, you would do the following:

[code]
public class CheckBoxItem : TD.SandBar.ControlContainerItem
{
public CheckBoxItem() : base(new System.Windows.Forms.CheckBox())
{
// Make checkbox background transparent so any gradients etc show through
ContainedControl.BackColor = System.Drawing.Color.Transparent;

// Set default text
ContainedControl.Text = "CheckBox";
}
}
[/code]

There is often a case where toolbar buttons have no text, but you want text to appear next to the image when the button is shown in the chevron menu or add/remove buttons menu. In the case where no text is present, SandBar will use the button's ToolTip text instead.

These are controls used by SandBar to host toolbars in a dockable toolbar layout. When you first add a SandBarManager to your form they are created automatically by the designer. They offer no user-configurable properties and it is important that they are left in place.

To prevent a toolbar from being docked in any particular location use its AllowHorizontalDock and AllowVerticalDock properties.

In advanced situations you may wish to extend SandBar by having more than the default four ToolBarContainers on your form. SandBar will allow this, and you can add as many as you like, however ensure their Manager property is set to the instance of your SandBarManager otherwise they will not accept toolbars.

Several recent Microsoft products have included a combobox on the menubar at the right-hand side, to provide quick access to the help system. SandBar fully supports this by giving you the option of having the last item on your tool/menubar aligned at the far side.

First of all you need to create a ComboBoxItem on your menubar. By default the designers only let you add menu items to a menubar, so create the ComboBoxItem on another toolbar in your form and drag it over so it is the last item on the menubar.

Lastly set the menubar's FlipLastItem property to True to make the item jump to the far side.

Any top-level menu present on a menubar in your container can be used as a context menu on any control within that container. You will notice that once you have added a menubar, other controls gain a SandBarMenu property. When you drop this down you will see you can select any top-level menu to assign to that control. SandBar will then show the selected menu instead of the default windows context menu for that control.

If you require only context menus on your form, you still need to add a menubar but you can set its Visible property to false. It will still be visible at design time and you can design your context menus using the menu designer.