You can use a combination of XML and programming code to add you own custom buttons to the Ribbon or reuse one of the many built-in buttons.
XML provides a hierarchical, declarative model of the Ribbon. Add controls, such as buttons, to the Ribbon by using XML elements to specify the type of component. For example, you can add a single button by using the button element. Assign property values to the button by using attributes such as the label attribute. Here is a sample:
<?xml version="1.0" encoding="utf-8" ?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" loadImage="LoadImage" >
<ribbon startFromScratch="false">
<tabs>
<tab id="tab1" label="Button Demo" keytip="z" >
<group id="group1" label="Demo Group">
<button id="button1"
"enabled="true"
"getLabel="GetLabel"
"keytip="A1"
"getScreentip="GetScreentip"
"supertip="This is a supertip for the button."
"getShowLabel="GetShowLabel"
"getShowImage="GetShowImage"
"getSize="GetSize"
"visible="true"
"image="camera.bmp"
"onAction="OnAction" />
<button id="button2"
"getLabel="GetLabel"
"getShowLabel="GetShowLabel"
"size="normal"
"keytip="A2"
"imageMso="TableDrawTable"
"onAction="OnAction" />
</group>
</tab>
</tabs>
</ribbon>
</customUI>
This sample adds a custom tab titled Button Demo to the Ribbon by assigning text to the tab element's label attribute. This tab contains the Demo Group group, which contains two custom buttons named button1 and button2, respectively. The buttons have properties defined by attributes such as visible, enabled, and size.
These properties are assigned explicitly by setting the attribute equal to a string, such as the supertip attribute, or indirectly by pointing to a programming code procedure. The following figure shows the result of applying this XML to the Ribbon in Microsoft Office Excel 2007:
Figure 1. A sample modified Ribbon in Office Excel 2007
.gif)
As in the sample code, you specify built-in components differently than custom components. Some attributes have the Mso suffix and some do not. For example, looking at the above sample, the id attribute does not have the Mso qualifier. This indicates to Office's software that the button is a custom control. In the imageMso attribute, the Mso suffix indicates it as a built-in image. Attributes with the Mso suffix refer to built-in controls, commands, and images. An example of this appears later in this article.
The other attributes of the buttons should be discussed. First, the enabled attribute's property has been set to True which causes the button to be available to use. When it is set to False the control is grayed out, indicating that the button is not active. Next the getLabel attribute points to a callback procedure that defines the label for the button. Callback procedures are described in the Assigning Functionality to Ribbon Components section.
The keytip attribute assigns a KeyTip for the button. KeyTips are sometimes known as access keys or accelerators and are used as shortcut key combinations that can be used to activate the control. To use a KeyTip on a custom tab control, you first set a KeyTip for the tab or use the default KeyTip assigned by Office. Then you assign a KeyTip for the control. For example, in the code, the tab has a KeyTip equal to z. The button1 button has a KeyTip equal to A1. When the Ribbon is displayed, press the key combination Alt + z to bring the focus to the custom tab. Then, press the key combination A+1 to activate the button and execute the procedure defined in the onAction attribute that inserts text into the worksheet.
Next you see the getScreentip attribute. Screentips are those small boxes that appear when you move the mouse pointer over an object on the Ribbon. They are used to provide information about the selected object. Similarly, the supertip attribute (or the getSupertip attribute if you are pointing to a callback procedure) provides additional information about the object.
When an attribute carries the prefix 'get' it indicates that the attribute points to a callback procedure. Thus in the code, the getScreentip attribute points to the callback procedure named GetScreentip.
.gif)
Note:
|
|---|
|
Callback procedures do not have to be named the same as the attribute they are used with. You could just as easily have used the following line of code getScreentip="DoSomething". Also, attributes that point to callback procedures do not have to be prefixed by get. For example, in the XML code, the onAction attribute points to a callback named OnAction.
|
The supertip attribute illustrates another aspect of control attributes. An attribute without the get prefix indicates that you can assign text to it explicitly. In the case of the supertip attribute, the text is assigned directly instead of by a callback procedure. There are exceptions such as the onAction attribute, where the attribute is not prefixed by the word get. You can find more information about which attributes are assigned explicitly and which attributes point to callback in the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3).
The getShowLabel and the getShowImage attributes both point to callback procedures that resolve to Boolean values. For example, setting the getShowLabel attribute to True causes the label for the button to appear when the control is displayed. To set the value of the attribute explicitly, use the showLabel attribute.
The getSize attribute is used to specify the size of the button. If you are setting the size explicitly as seen in button2, the options are normal and large. For more information about setting the size by using the getSize attribute, see Assigning Functionality to Ribbon Components.
Looking again at the above XML code, the visible attribute is set to a Boolean value that determines whether the button is displayed on the Ribbon.
Next, the image attribute for button1 is used to specify a custom image for the button. Likewise, the imageMso attribute for button2 is used to specify a built-in image for the button. To find a spreadsheet of built-in images, see 2007 Office System Add-In: Icons Gallery.
Finally, as mentioned previously, the onAction attribute points to a callback procedure that is executed when you click the button. This procedure is discussed in the next section.
In the previous XML sample, several of the attributes point to callback procedures. For example, the button element has an OnAction attribute. When the button is clicked, the OnAction method, or callback procedure, is called. The code in the OnAction method gives the button its functionality. These procedures are called callbacks because when the button is clicked the action alerts Microsoft Office that the control needs attention. Microsoft Office then calls back to the method defined by the OnAction attribute and performs whatever action is contained in the method. The following paragraphs describe these callback procedures in a little more detail.
The getLabel attribute calls the GetLabel callback procedure.
Public Function GetLabel(ByVal control As IRibbonControl) As String
Dim strLabel As String = ""
Select Case control.Id
Case "button1" : strLabel = "Insert Text"
Case "button2" : strLabel = "Insert More Text"
End Select
Return strLabel
End Function
public stringn GetLabel(IRibbonControl control)
{
private string strLabel = "";
switch (control.Id)
{
case "button1": strLabel = "Insert Text"; break;
case "button2": strLabel = "Insert More Text"; break;
default: strLabel = "Insert Text"; break;
}
return strLabel;
}
When the GetLabel procedure is called by Office, an IRibbonControl object representing the button is passed The procedure tests the Id property of the object and depending on its value, assigns text to a variable. That variable is then returned to Microsoft Office which displays its text as the button's label.
The getScreentip attribute also points to a callback procedure. In this case, the procedure returns a string that is displayed when you move the mouse over the button.
Public Function GetScreenTip(ByVal control As IRibbonControl) As String
Return "Inserts text into the active worksheet."
End Function
public string GetScreenTip(IRibbonControl control)
{
return "Inserts text into the active worksheet.";
}
The getShowLabel and getShowImage callback procedures return a Boolean value to Microsoft Office that specifies whether to display the respective object (a label or an image) when the custom tab is displayed.
Public Function GetShowLabel(ByVal control As IRibbonControl) As Boolean
Dim bolShow As Boolean
Select Case control.Id
Case "button1" : bolShow = True
Case "button2" : bolShow = False
End Select
Return bolShow
End Function
Public Function GetShowImage(ByVal control As IRibbonControl) As Boolean
Return True
End Function
public bool GetShowLabel(IRibbonControl control)
{
private bool bolShow;
switch (control.Id)
{
case "button1": bolShow = true; break;
case "button2": bolShow = false; break;
default: bolShow = true; break;
}
return bolShow;
}
public bool GetShowImage(IRibbonControl control)
{
return true;
}
The GetShowLabel procedure tests the Id property of the control and depending on its value, sets a Boolean variable to True or False. That variable is then returned to Office.
Next is the getSize attribute that points to the GetSize callback procedure.
Public Function GetSize(ByVal control As IRibbonControl) As RibbonControlSize
' Selecting one of the two RibbonControlSize enumeration values
' sets the size of the button.
Return RibbonControlSize.RibbonControlSizeRegular
' RibbonControlSize.RibbonControlSizeLarge
End Function
public RibbonControlSize GetSize(IRibbonControl control)
{
// Selecting one of the two RibbonControlSize enumeration values
// sets the size of the button.
return RibbonControlSize.RibbonControlSizeRegular;
// RibbonControlSize.RibbonControlSizeLarge;
}
In this procedure, a value of the RibbonControlSize enumeration is returned to Office. The RibbonControlSizeRegular is used for the standard sized control and the RibbonControlSizeLarge value is used to represent a larger control.
Finally, the OnAction callback procedure is called when you click the button. In this case, the procedure tests the Id property of the calling control and inserts text specific to that control into the A1 cell in the worksheet.
Public Sub OnAction(ByVal control As IRibbonControl)
Select Case control.Id
Case "button1" : applicationObject.Range("A1").Value = _
"This button inserts text."
Case "button2" : applicationObject.Range("A1").Value = _
"This button inserts more text."
End Select
End Sub
public void OnAction(IRibbonControl control)
{
switch (control.Id)
{
case "button1":
applicationObject.get_Range("A1:A1", missing).Value2 = "This button inserts text."; break;
case "button2":
applicationObject.get_Range("A1:A1", missing).Value2 = "This button inserts more text."; break;
default:
applicationObject.get_Range("A1:A1", missing).Value2 = "There was a problem with your selection."; break;
}
}