The button element is the most well known of all the tools in the developer’s toolbox, it specifies a standard push-button control that performs an action when clicked.
Graphical View of button Attributes
The following figure shows all the visible graphical attributes you can set on the button control.
This is specified using the following XML:
<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
<ribbon startFromScratch="true">
<tabs>
<tab id="customTab"
label="Custom Tab">
<group id="customGroup"
label="Custom Group">
<button id="customIcon"
label="Custom Large Icon"
image="custom-icon"
size="large"
keytip="B"
screentip="This is the screentip string"
supertip="This is the supertip string"
onAction="CustomIcon_Click"/>
<button id="NormalButton"
label="Normal Button"
imageMso="HappyFace"
size="normal"
onAction="NormalButton_Click"/>
</group>
</tab>
</tabs>
</ribbon>
</customUI>Parent Elements
- box
- buttonGroup
- dialogBoxLauncher
- documentControls
- dynamicMenu
- gallery
- group
- menu
- splitButton
- officeMenu
Children Elements
The button control does not support child objects of any kind.
Required Attributes
The id, idQ, and idMso attributes are mutually exclusive. At least one of these attributes MUST be specified.
| ATTRIBUTE | WHEN TO USE |
|---|---|
| id | When creating your own button |
| idMso | When using an existing built-in button |
| idQ | When creating a button shared between namespaces |
Required Callback
| DYNAMIC ATTRIBUTE | ALLOWED VALUES | VBA CALLBACK SIGNATURE |
|---|---|---|
| onAction | 1 to 4096 characters | Sub OnAction (control As IRibbonControl) |
| onAction | Repurposing* | Sub OnAction (control As IRibbonControl, byRef cancelDefault) |
*: The second version of the onAction callback is used when “repurposing” a built-in control.
Optional insert Attributes
The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.
| INSERT ATTRIBUTE | ALLOWED VALUES | DEFAULT VALUE | WHEN TO USE |
|---|---|---|---|
| insertAfterMso | Valid Mso Group | Insert at end of group | Insert after built-in control |
| insertBeforeMso | Valid Mso Group | Insert at end of group | Insert before built-in control |
| insertAfterQ | Valid Group idQ | Insert at end of group | Insert after shared namespace control |
| insertBeforeQ | Valid Group idQ | Insert at end of group | Insert before shared namespace control |
Optional Attributes and Callbacks
| STATIC ATTRIBUTE | DYNAMIC ATTRIBUTE | ALLOWED VALUES | DEFAULT VALUE | VBA CALLBACK SIGNATURE FOR DYNAMIC ATTRIBUTE |
|---|---|---|---|---|
| description | getDescription | 1 to 4096 characters | (none) | Sub GetDescription (control As IRibbonControl, ByRef returnedVal) |
| enabled | getEnabled | true, false, 1, 0 | true | Sub GetEnabled (control As IRibbonControl, ByRef returnedVal) |
| image | getImage | 1 to 1024 characters | (none) | Sub GetImage (control As IRibbonControl, ByRef returnedVal) |
| imageMso | getImage | 1 to 1024 characters | (none) | Sub GetImage (control As IRibbonControl, ByRef returnedVal) |
| keytip | getKeytip | 1 to 3 characters | (none) | Sub GetKeytip (control As IRibbonControl, ByRef returnedVal) |
| label | getLabel | 1 to 1024 characters | (none) | Sub GetLabel (control As IRibbonControl, ByRef returnedVal) |
| screentip | getScreentip | 1 to 1024 characters | (none) | Sub GetScreentip (control As IRibbonControl, ByRef returnedVal) |
| showImage | getShowImage | true, false, 1, 0 | true | Sub GetShowImage (control As IRibbonControl, ByRef returnedVal) |
| showLabel | getShowLabel | true, false, 1, 0 | true | Sub GetShowLabel (control As IRibbonControl, ByRef returnedVal) |
| size | getSize | normal, large | normal | Sub GetSize (control As IRibbonControl, ByRef returnedVal) |
| supertip | getSupertip | 1 to 1024 characters | (none) | Sub GetSupertip (control As IRibbonControl, ByRef returnedVal) |
| tag | (none) | 1 to 1024 characters | (none) | (none) |
| visible | getVisible | true, false, 1, 0 | true | Sub GetVisible (control As IRibbonControl, ByRef returnedVal) |
Using Built-in button Controls
The following XML fragment creates a clone of the control with an identifier of "AutoSum".
<button idMso="AutoSum" />The following XML fragment creates a clone of the control with an identifier of "AutoSum", but without the display label.
<button idMso="AutoSum" showLabel="false" />However, when size="large", showLabel="false" does not work.
It is still possible to get the button to display in a large format without the label. The secret is to specify the label text as a blank space:
<button idMso="AutoSum" size="large" label=" " />Where can I find the full list of idMso?
idMSO Full List in Excel for Windows
idMSO Full List in Excel for Mac