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
idQA 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)

onActionButton_OnAction - This is the run-time equivalent to the design-time Click event
getDescriptionButton_OnGetDescription -
getEnabledButton_OnGetEnabled -
getImageButton_OnGetImage -
getImageMsoNo callback use the following method instead - CommandBars.GetImageMso("officeimagename,16,16)
getKeytipButton_OnGetKeytip -
getLabelButton_OnGetLabel -
getScreentipButton_OnGetScreentip -
getShowImageButton_OnGetShowImage -
getShowLabelButton_OnGetShowLabel -
getSizeButton_OnGetSize -
getSupertipButton_OnGetSupertip -
getVisibleButton_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