Checkable Buttons

Bars controls support several features to make it easy to work with checkable buttons.

IBarCheckableCommand Interface

The IBarCheckableCommand interface is used to define a checkable button. Both the BarButtonCommand and BarSplitButtonCommand implement it and support checkable button features.

This table indicates the members of the IBarCheckableCommand interface:

Working with Checkable Buttons

A command must be flagged as Checkable before it can be checked. If the Checkable property is false, the command cannot be checked by the end user. If the Checkable property is true, the command's Checked property value can be toggled by the end user.

The Checked property value can be toggled programmatically as well.

((IBarCheckableCommand)barManager.Commands["Format.TextAlignmentLeft"]).Checked = true;

If the AutoUpdateChecks property is set to true, any checkable buttons that are clicked by the end user will be automatically toggled. If that property is false, the checkable buttons can only have their Checked state toggled programmatically.

Working with Check Groups

Check groups are a powerful feature found in Bars. When working with checkable buttons, there are two scenarios. The first is where the checkable button provides an on/off toggle for a specific feature. This sort of checkable button stands alone. The second is where the checkable button is a toggle for a specific feature within a feature group. For instance, in a text editing application, there would be a check group for text alignment (left, center, right, and justify).

By specifying a CheckGroupName for all the checkable buttons in a check group, Bars adds numerous features for easily working with check groups. In our above scenario, all the checkable buttons for the text alignment check group could have a CheckGroupName value of TextAlignment.

If the AutoUpdateCheckGroups property is set to true, any checkable buttons in a check group that are clicked by the end user will be automatically checked and all other checkable buttons in the check group will be unchecked. If that property is false, the checkable buttons can only have their Checked state toggled programmatically.

To return the IBarCheckableCommand that is current checked in a check group, call the BarManager.GetCheckGroupValue method and pass in the desired check group name. If the check group is not found, or no command is checked within the check group, null is returned.

IBarCheckableCommand checkableCommand = barManager.GetCheckGroupValue("TextAlignment");

To set the value of a check group, call the SetCheckGroupValue method and pass in the check group name and the IBarCheckableCommand that should be checked. Any other IBarCheckableCommand in the group that was previously checked will automatically be unchecked.

barManager.SetCheckGroupValue("TextAlignment", (IBarCheckableCommand)barManager.Commands["Format.TextAlignmentLeft"]);

To get an array of all the check group names being managed by the BarManager, call the GetCheckGroupNames method.

string[] checkGroupNames = barManager.GetCheckGroupNames();