You can use a combination of XML and programming code to add you own custom checkboxes to the Ribbon or reuse one of the many built-in checkboxes.
XML provides a hierarchical, declarative model of the Ribbon. Add controls, such as check boxes, to the Ribbon by using XML elements to specify the type of component. For example, you can add a single check box by using the checkBox element. assign property values to the checkbox by using attributes such as the >label attribute. Here is a sample:
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
<ribbon startFromScratch="false">
<tabs>
<tab id="tab1" label="CheckBox Demo" keytip="z" >
<group id="group1" label="Demo Group">
<checkBox id="checkbox1"
"enabled="true"
"getLabel="GetLabel"
"keytip="A1"
"getScreentip="GetScreentip"
"supertip="This is a super tip for the checkBox."
"visible="true"
"getPressed="GetPressed"
"onAction="OnAction" />
<checkBox id="checkbox2"
"getLabel="GetLabel"
"onAction="OnAction" />
</group>
</tab>
</tabs>
</ribbon>
</customUI>
This sample adds a custom tab titled CheckBox Demo to the Office Fluent Ribbon by assigning text to the tab element's label attribute. This tab contains the Demo Group group, which contains two custom check boxes named checkBox1 and checkbox2, respectively. The check boxes have properties defined by attributes such as >visible, >enabled, and >keytip. You can assign these properties 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 Office Fluent Ribbon in Microsoft Office Excel 2007.
Figure 1. A sample modified Ribbon in Office Excel 2007
.gif)
The enabled attribute's property is set to True, which causes the check box to be available to use. When it is set to False, the control is grayed out, indicating that the check box is not active. Next the >getLabel attribute points to a callback procedure that defines the label for the check box. For more information about callback procedures, see Assigning Functionality to Office Fluent Ribbon Components.
The keytip attribute assigns a KeyTip for the check box. KeyTips are sometimes known as access keys or accelerators and are used as shortcut key combinations that activate controls. To use a KeyTip on a custom tab control, you first set a KeyTip for the tab or use the default KeyTip assigned by Microsoft Office. Then you assign a KeyTip for the control. For example, in the code, the tab has a KeyTip equal to z. The checkbox1 check box has a KeyTip equal to A1. When the Office Fluent 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 check box 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 item on the Office Fluent Ribbon. They 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 procedure 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. For more information about which attributes are assigned explicitly and which attributes point to callback, see Customizing the 2007 Office Fluent Ribbon for Developers (Part 3 of 3).
Looking again at the XML code in the previous example, the visible attribute is set to a Boolean value that determines whether the check box is displayed on the Ribbon.
Next, the >getPressed attribute specifies the default behavior for the check box. If the value of the attribute resolves to True when the check box is displayed, it shows as selected, with the box checked. If the value resolves to False, the check box is cleared.
Finally, the onAction attribute points to a callback procedure that is executed when you click the check box. This procedure is discussed in the next section.
In the previous XML sample, some of the attributes point to callback procedures. For example, the checkbox element has an >OnAction attribute. When the check box is clicked, the OnAction method, or callback procedure, is called. The code in the OnAction method gives the check box its functionality. These procedures are called callbacks because when the check box 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 "checkbox1" : strLabel = "Insert text."
Case "checkbox2" : strLabel = "Insert more text."
End Select
Return strLabel
End Function
public stringn GetLabel(IRibbonControl control)
{
private string strLabel = "";
switch (control.Id)
{
case "checkbox1": strLabel = "Insert text."; break;
case "checkbox2": strLabel = "Insert more text."; break;
default: strLabel = "Insert text."; break;
}
return strLabel;
}
When the GetLabel procedure is called by Microsoft Office, an >IRibbonControl object representing the check box 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 check box'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 check box.
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 GetPressed callback procedure returns a Boolean value to Microsoft Office that specifies the default condition of the check box. If the call resolves to True, the check box is displayed as checked when it is initially displayed. Returning False (the default value) specifies that the check box's initial display state is unchecked.
Public pressedState As Boolean = False
Public Function GetPressed(ByVal control As IRibbonControl) As Boolean
Return pressedState
End Function
public bool pressedState = false;
public bool GetPressed(IRibbonControl control)
{
return pressedState;
}
Finally, the OnAction callback procedure is called when you click the check box. 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, ByVal pressed As Boolean)
If pressed Then
applicationObject.Range("A1").Value = _
"You selected the check box."
Else
applicationObject.Range("A1").Value = _
"You cleared the check box."
End If
pressedState = pressed
End Sub
public void OnAction(IRibbonControl control, bool pressed)
{
if(pressed)
{
applicationObject.get_Range("A1:A1", missing).Value2 = "You selected the check box;
}
else
{
applicationObject.get_Range("A1:A1", missing).Value2 = "You cleared the check box.";
}
pressedState = pressed;
}