button
In the object model this is RibbonButton.
Is a single clickable item which could have an image and/or caption
Can be added to a group, button group, drop-down list, gallery, menu or split button.
<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
<ribbon startFromScratch="true">
<tabs>
<tab id="CustomTab" label="My Tab">
<group id="Group1" label="MyGroup">
<button id="button1"
label="Large Button"
imageMso="HappyFace"
size="large"
onAction="Button_OnAction"/>
</group>
</tab>
</tabs>
</ribbon>
</customUI>
Attributes (properties)
description | (Description) Additional text when a large button is added to the Office Menu |
enabled | (Enabled) "true" | "false" |
id | (Name) Unique identifier. This is passed as a property on an IRibbonControl object to the callback functions. |
idMso | (OfficeImageId) Microsoft built-in command id |
idQ | A qualifier identifier, prefixed with a namespace. This allows two different add-ins to add to the same custom group. |
image | (Image) |
imageMso | (OfficeImageId) Microsoft built-in image id |
insertAfterMso | |
insertAfterQ | |
insertBeforeMso | |
insertBeforeQ | |
keytip | (KeyTip) shortcut key to access the control shown when you press the Alt key |
label | (Label) control's caption |
screentip | (ScreenTip) appears in bold text when the mouse hovers over |
showImage | (ShowImage) "true" | "false" |
showLabel | (ShowLabel) "true" | "false" if size if large then this is always true |
size | (ControlSize) "large" | "normal" (large is 3 rows) This is not required when inside a SplitButton |
supertip | (Added in 2010) (SuperTip) multi-line text appears when the mouse hovers over (1 to 1024 characters). Carriage returns can be entered using [& #13;] |
tag | (Tag) 1 to 1024 characters |
visible | (Visible) "true" | "false" |
(GenerateMember) | |
(Modifiers) the access modifier assigned Internal | |
(ImageName) | |
(Locked) | |
(Position) Default | BeforeOfficeId | AfterOfficeId |
C# Events (design-time)
The Button control has a Click event which can be accessed if you use the Visual Studio Ribbon Designer
' C#
void Button_Click(object sender, RibbonControlEventArgs e)
{
}
this.Button.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(this.Button_Click);
Callbacks (run-time)
onAction | Button_OnAction - This is the run-time equivalent to the design-time Click event |
getDescription | Button_OnGetDescription - |
getEnabled | Button_OnGetEnabled - |
getImage | Button_OnGetImage - |
getImageMso | No callback use the following method instead - CommandBars.GetImageMso("officeimagename,16,16) |
getKeytip | Button_OnGetKeytip - |
getLabel | Button_OnGetLabel - |
getScreentip | Button_OnGetScreentip - |
getShowImage | Button_OnGetShowImage - |
getShowLabel | Button_OnGetShowLabel - |
getSize | Button_OnGetSize - |
getSupertip | Button_OnGetSupertip - |
getVisible | Button_OnGetVisible - |
' VBA
Public Sub Button_OnAction( _
ByRef control As Office.IRibbonControl)
End Sub
' C# Equivalent
void Button_OnAction(
Microsoft.Office.Core.IRibbonControl control)
{
}
'VB.Net Equivalent
Public Sub Button_OnAction( _
ByVal Control As Microsoft.Office.Core.IRibbonControl)
End Sub
' VBA
Public Sub Button_OnGetDescription( _
ByRef control As Office.IRibbonControl, _
ByRef Description As Variant)
Description = "my dynamic description"
End Sub
' C# Equivalent
string Button_OnGetDescription(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetEnabled( _
ByRef control As Office.IRibbonControl, _
ByRef ReturnValue As Variant)
ReturnValue = False
End Sub
' C# Equivalent
bool Button_OnGetEnabled(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetImage( _
ByRef control As Office.IRibbonControl, _
ByRef Bitmap As Variant)
End Sub
' C# Equivalent
System.Drawing.Bitmap Button_OnGetImage(
Microsoft.Office.Core.IRibbonControl control)
{
return new System.Drawing.Bitmap(Properties.Resources.untitled);
}
' VBA
Public Sub Button_OnGetKeytip( _
ByRef control As Office.IRibbonControl, _
ByRef Keytip As Variant)
Keytip = "my dynamic keytip"
End Sub
' C# Equivalent
string Button_OnGetKeytip(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetLabel( _
ByRef control As Office.IRibbonControl, _
ByRef Label As Variant)
Label = "my dynamic label"
End Sub
' C# Equivalent
string Button_OnGetLabel(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetScreentip( _
ByRef control As Office.IRibbonControl, _
ByRef Screentip As Variant)
End Sub
' C# Equivalent
string Button_OnGetScreentip(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetShowImage( _
ByRef control As Office.IRibbonControl, _
ByRef ShowImage As Variant)
End Sub
' C# Equivalent
bool Button_OnGetShowImage(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetShowLabel( _
ByRef control As Office.IRibbonControl, _
ByRef ShowLabel As Variant)
End Sub
' C# Equivalent
bool Button_OnGetShowLabel(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetSize( _
ByRef control As Office.IRibbonControl, _
ByRef Size As Variant)
End Sub
' C# Equivalent
Office.RibbonControlSize Button_OnGetSize(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetSupertip( _
ByRef control As Office.IRibbonControl, _
ByRef Supertip As Variant)
End Sub
' C# Equivalent
string Button_OnGetSupertip(
Microsoft.Office.Core.IRibbonControl control)
{
}
' VBA
Public Sub Button_OnGetVisible( _
ByRef control As Office.IRibbonControl, _
ByRef Visible as Variant)
End Sub
' C# Equivalent
bool Button_OnGetVisible(
Microsoft.Office.Core.IRibbonControl control)
{
}
ID vs Tag
It is best practice to use the ID attribute to identify which macro to run when a button is pressed.
However some people use the Tag attribute to hard-code the name of the macro in the Tag attribute.
Using the ID
In the XML, the ID attribute is used to identify the macro.
<button id="ID_Button" label="MyButton" onAction="Ribbon_Callback" />
The callback function uses the ID to identify which macro to run.
Using this approach means you can easily change the name of the macro later on.
Sub Ribbon_Callback(button As IRibbonControl)
Select Case control.ID
Case "ID_Button": Call MyMacro()
End Select
End Sub
Using the Tag
In the XML, the Tag attribute is used with the name of the subroutine.
<button id="ID_Button" label="MyButton" onAction="Ribbon_Callback" tag="MyMacro" />
The callback function calls Application.Run.
Using this approach means you have to update the XML every time you want to change the name of a macro.
Sub Ribbon_Callback(button As IRibbonControl)
Application.Run button.Tag
End Sub
© 2024 Better Solutions Limited. All Rights Reserved. © 2024 Better Solutions Limited TopPrevNext