Split Button
Split and split/toggle buttons are controls with two distinct areas. One portion can be clicked similar to a regular button, which then executes a command or raises an event. Another portion can be clicked to open a popup menu, similar to a popup button.
Note
This topic extends the Control Basics topic with additional information specific to the control types described below. Please refer to the base topic for more generalized concepts that apply to all controls, including this one.
Control Implementations
There are separate split and split/toggle button concept control implementations based on the usage context.
Ribbon and Toolbar Contexts
Use the BarSplitButton control to implement a split non-checkable button within a ribbon or toolbar context.
If the button should be checkable, use the BarSplitToggleButton control instead. This control class inherits BarSplitButton and all its features, but adds toggle support.
BarSplitButton examples in several variant sizes (large, medium, and small)
Specification | Details |
---|---|
Base class | BarPopupButton, which indirectly inherits native Menu . |
Has key | Yes, via the Key property. |
Has label | Yes, via the Label property. Auto-generated from the Key value if not specified. |
Has image | Yes, via the SmallImageSource, MediumImageSource, and LargeImageSource properties. |
Has popup | Yes. |
Is checkable | Yes, but only when using BarSplitToggleButton. |
Variant sizes | Small (image only), Medium (image and label), Large (tall size, image and multi-line label). |
Command support | Yes, via the Command property (related to the button portion) and the PopupOpeningCommand property (related to the popup portion). |
Key tip support | Yes, via the KeyTipText property. Auto-generated from the Label value if not specified. |
Ribbon QAT support | Yes, via the CanCloneToRibbonQuickAccessToolBar property. |
UI density support | Yes, via the UserInterfaceDensity property. |
MVVM Library VM | BarSplitButtonViewModel class for regular buttons, BarSplitToggleButtonViewModel class for toggle buttons. |
xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
...
<bars:StandaloneToolBar>
<!-- Label is auto-generated from Key -->
<bars:BarSplitButton
Key="Shapes"
SmallImageSource="/Images/Shapes16.png"
Command="{Binding InsertLastShapeCommand">
<bars:BarSplitButton.Items>
<bars:BarMenuItem
Key="Rectangle"
Command="{Binding InsertRectangleCommand}"
/>
</bars:BarSplitButton.Items>
</bars:BarSplitButton>
...
</bars:StandaloneToolBar>
Menu Contexts
Use the BarSplitMenuItem control to implement a split button concept within a menu context.
The BarSplitMenuItem class indirectly inherits the native MenuItem
control class and therefore supports a checkable state.
A BarSplitMenuItem example
Specification | Details |
---|---|
Base class | BarMenuItem, which indirectly inherits native MenuItem . |
Has key | Yes, via the Key property. |
Has label | Yes, via the Label property. Auto-generated from the Key value if not specified. |
Has image | Yes, via the SmallImageSource and LargeImageSource properties. |
Has popup | Yes. |
Is checkable | Yes, when the IsCheckable property is set to true . |
Variant sizes | None, but has a UseLargeSize property that triggers a large height and displays an extended Description. |
Command support | Yes, via the Command property (related to the button portion) and the PopupOpeningCommand property (related to the popup portion). |
Key tip support | Yes, via the KeyTipText property. Auto-generated from the Label value if not specified. |
Ribbon QAT support | Yes, via the CanCloneToRibbonQuickAccessToolBar property. |
UI density support | None. |
MVVM Library VM | BarSplitButtonViewModel class for non-checkable menu items, BarSplitToggleButtonViewModel class for checkable menu items. |
xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
...
<bars:BarContextMenu>
<!-- Label is auto-generated from Key -->
<bars:BarSplitMenuItem
Key="Shapes"
SmallImageSource="/Images/Shapes16.png">
Command="{Binding InsertLastShapeCommand}">
<bars:BarMenuItem
Key="Rectangle"
Command="{Binding InsertRectangleCommand}"
/>
</bars:BarSplitMenuItem>
...
</bars:BarContextMenu>
Appearance
There are several appearance-related properties that determine how the controls render.
Label
The controls have a string Label
that can be set, which is visible in UI.
The Label
can be auto-generated based on the control's Key
property. For instance, a control with Key
of "FormatPainter"
will automatically assign "Format Painter"
as the Label
value. The auto-generated default can be overridden by setting the Label
property.
The BarSplitButton.Label is rendered on the button when it is in a Medium
or Large
variant size. When using a Large
variant size button, the label will wrap words to two lines to minimize overall width. In cases where a run of label text should not be broken up into two lines, use a non-breaking space character (ASCII code 160) in place of any whitespace, like this:
xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
...
<bars:BarSplitButton ... Label="Data Set" />
The BarSplitMenuItem.Label is rendered on the menu item as its primary content.
Images
The controls can display images that help identify their function.
All BarSplitButton instances should set a SmallImageSource at a minimum, which is generally used for Small
and Medium
variants, as well as in the Ribbon Quick Access Toolbar and if the control overflows to a menu. If the button supports a Large
variant size, it should also define a LargeImageSource. When the button has a Spacious
UI density, it will try to use MediumImageSource.
Tip
See the Control Basics topic for more detail on the fallback logic for button images.
BarSplitMenuItem instances can optionally define a SmallImageSource that appears in the menu's icon column. When UseLargeSize is set to create a large menu item, the LargeImageSource property is used instead. When the menu item is checked, a highlight box will appear around the image. If no image is specified, a standard check glyph will be used in place of the image.
Description (BarSplitMenuItem only)
When UseLargeSize is set to create a large menu item, the Description property's string value is displayed under the menu item's bold label as an extended description.
Title
An optional string BarSplitButton.Title and BarSplitMenuItem.Title can be specified, which are intended to override the control's Label
when displayed in screen tips and customization UI.
Variant Sizes
BarSplitButton supports multiple variant sizes via its VariantSize property. This feature can be used in conjunction with RibbonControlGroup within a ribbon in Classic
layout mode to achieve various button layouts as available width changes.
When a ribbon is in Simplified
layout mode, the BarSplitButton control will render in a Small
variant size by default and will collapse to an overflow menu when necessary. The ToolBarItemVariantBehavior property can be set to All
to show a label. Alternatively, the ToolBarItemCollapseBehavior property can be set to Always
to always have the button in the overflow menu.
While BarSplitMenuItem doesn't support variant sizes, it does have a UseLargeSize property that can be set to show a large version of the menu item. This large version uses a large image and can display an extended Description.
See the Resizing and Variants topic for more information on ribbon's variant sizing features.
User Interface Density (BarSplitButton only)
The UserInterfaceDensity property can alter the appearance of the button, such as its size, padding, and image used. This property is not generally set on the button instance itself, and is instead meant to be set on the root bar control to inherit down, such as with the Ribbon.UserInterfaceDensity property.
Checked State (BarToggleSplitButton and BarSplitMenuItem only)
Whereas BarSplitButton implements a non-toggleable button, the BarSplitToggleButton and BarSplitMenuItem controls both support a checked state.
Set the BarSplitToggleButton.IsChecked or BarSplitMenuItem.IsChecked
property to true
to render the control in a checked state.
Key Tips
The controls support key tips. When a control's key tip is accessed, the popup menu is opened.
The KeyTipText
can be auto-generated based on the control's Label
property. For instance, a control with Label
of "Copy"
will automatically assign "C"
as the KeyTipText
value. The auto-generated default can be overridden by setting the KeyTipText
property.
The BarSplitButton.KeyTipText and BarSplitMenuItem.KeyTipText properties designate the key tip text to use for the control.
See the Key Tips topic for more information on key tips.
Commands and Events
The ICommand
in the BarSplitButton.Command and BarSplitMenuItem.Command
properties is executed when the control's button portion is clicked. The command's can-execute result determines the enabled state of the control's button portion.
A BarSplitButton.Click and BarSplitMenuItem.Click
event is also raised in these scenarios.
The PopupOpeningCommand command, if assigned, is executed prior to the popup opening. This command can be handled in a view model, allowing for a MVVM way to update the items on the popup prior to display. The command's can-execute result determines the enabled state of the control's popup portion.
See the Using Commands topic for more information on commands.
Input Gesture Text
The control can have input gesture text associated with it that describes a related keyboard shortcut, and is displayed in the screen tip for the control or in the menu item itself.
This input gesture text is automatically derived from commands that inherit RoutedCommand
and have a KeyGesture
set.
Or input gesture text can be specified in the BarSplitButton.InputGestureText and BarSplitMenuItem.InputGestureText
properties.
Input gesture text may be hidden altogether in UI by setting the BarSplitButton.IsInputGestureTextVisible and BarSplitMenuItem.IsInputGestureTextVisible properties to false
.
Screen Tips
The controls support screen tips, which are formatted tool tips.
The control's Title
is used as the default screen tip header, falling back to Label
if no Title
is available. The BarSplitButton.ScreenTipHeader and BarSplitMenuItem.ScreenTipHeader properties can override the default screen tip header value if desired.
If the control's ToolTip
property is set to a value that doesn't derive from a native ToolTip
control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed.
If the optional BarSplitButton.ScreenTipFooter and BarSplitMenuItem.ScreenTipFooter properties are specified, they will appear in a footer area of the screen tip.
See the Screen Tips topic for more information on screen tips.
MVVM Support
The optional companion MVVM Library defines BarSplitButtonViewModel (regular buttons) and BarSplitToggleButtonViewModel (toggle buttons) classes that are intended to be used as view models for split buttons.
These view model classes map over to the appropriate view controls described above based on usage context and configure all necessary bindings between the view models and the view controls.
Tip
See the MVVM Support topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques.