A button control with a drop down that can contain other controls.
Parent Elements
This element can appear as a child of the following elements.
| Element | Description | Version Introduced | Pro Version Introduced |
|---|---|---|---|
| <Backstage> | The list of buttons and pages in the popup that appears when the user clicks the system button. | 1.0 | 3.2 |
| <Group> | A single group that appears within a single tab and contains controls. | 1.0 | 3.2 |
| <QuickAccessControls> | A list of controls that appear in the quick access toolbar. | 1.0 | 3.2 |
| A button control with a drop down that can contain other controls. | 1.0 | 3.2 | |
| <TabBarControls> | The list of controls that appear on the right end of the tab bar area. | 1.0 | 3.2 |
Child Elements
The following elements can be children of this one.
| Element | Description | Appears | Version Introduced | Pro Version Introduced |
|---|---|---|---|---|
| <Button> | A button control associated with a command. | Zero or once | 1.0 | 3.2 |
| <CheckBox> | A check box control. | Zero or once | 1.0 | 3.2 |
| <ComboBox> | A combo box control. | Zero or once | 1.0 | 3.2 |
| <Command> | A single command that is associated to one or more buttons on the ribbon. | Zero or once | 1.0 | 3.2 |
| <DateField> | A date field control with a calendar drop down. | Zero or once | 1.0 | 3.2 |
| <EditField> | An edit field control. | 1.0 | 3.2 | |
| <Label> | A label control that only display some text. | 1.0 | 3.2 | |
| <SplitButton> | A button control with a drop down that can contain other controls. | Zero or once | 1.0 | 3.2 |
Attributes
This element supports the following attributes:
| Attribute | Description | Version Introduced | Pro Version Introduced |
|---|---|---|---|
| BeginGroup | Determines if this control begins a new group. | 1.0 | 3.2 |
| Command | The command associated with this button | 1.0 | 3.2 |
| Key | The unique identifier of the button. (Required) | 1.0 | 3.2 |
| ForceSmall | Forces the button to use the small button layout. | n/a | 4.0.1 |
BeginGroup
The BeginGroup attribute can be set to "True" or "False". When set to "True", it informs the ribbon that this control should not be grouped with the control before it and should be the first control in a new group. This attribute only works if the control is in a group whose GroupControls attribute is "True".
Command
The Command attribute lets you associate an existing command with this split button. Associating a split button to a command is the only way to set it's icon, caption, etc. If you omit this attribute, then you need to include a child <Command> element within the button element.
Key
The Key attribute defines a unique identifier for the split button. The identifier must be unique among controls but can share the same identifier as other elements such as commands or tabs.
ForceSmall
The ForceSmall attribute can be used to ensure that a button will always use the small button layout even if there is room for a large button layout. Useful when you want to demphasize a button or have a little more control over layout. Set this to "true" to activate. (Only available in 4.0.1 or later.)
Remarks
The SplitButton element defines a split button control. A split button is a button with a drop down arrow. The user can either click on the button portion, which will execute the associated command or the drop down to get a popup with more controls. In order to set the button's caption, icon, and other attributes, you must associate it with a command. You can do this using either the Command attribute as explained above or by including a child <Command> element.
You can add any number of other controls to a split button. Those controls will appear in the popup the is triggered by the drop down portion of the control. Note that you can even have child split buttons, making this feature infinitely recursive.
Example
<SplitButton Key="SPL_PASTE"> <Command Key="PASTE" Caption="Paste" Shortcut="Alt+F1" LargeIcon="Images\32x32\clipboard_paste.png" SmallIcon="Images\16x16\clipboard_paste.png" Tooltip="Inserts text from the clipboard." /> <Button Key="BTN_PASTEWITHFORMAT"> <Command Key="PASTEWITHFORMAT" Caption="Keep Source Formatting" LargeIcon="Images\32x32\clipboard_paste.png" SmallIcon="Images\16x16\clipboard_paste.png" Tooltip="Inserts formatted text from the clipboard." /> </Button> <Button Key="BTN_PASTEMERGE"> <Command Key="PASTEMERGE" Caption="Merge Formatting" Enabled="False" LargeIcon="Images\32x32\clipboard-add2.png" SmallIcon="Images\16x16\clipboard-add2.png" Tooltip="Inserts text from the clipboard using the current selection's formatting." /> </Button> <Button Key="BTN_PASTETEXTONLY"> <Command Key="PASTETEXTONLY" Caption="Keep Text Only" LargeIcon="Images\32x32\clipboard.png" SmallIcon="Images\16x16\clipboard.png" Tooltip="Inserts text only from the clipboard." /> </Button> </SplitButton>
