Whether you want to add you own custom combo boxes to the default Office Fluent Ribbon or reuse one of the many built-in combo boxes, you use a combination of XML and programming code.
XML provides a hierarchical, declarative model of the Office Fluent Ribbon. You add controls, such as combo boxes, to the Office Fluent Ribbon by using XML elements to specify the type of component. For example, you add a single combo box by using the comboBox element. You assign property values to the combo box by using attributes such as the label attribute.
<?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="ComboBox Demo" keytip="z" >
<group id="group1" label="Demo Group">
<comboBox id="comboBox1"
enabled="true"
getText="GetText"
getLabel="GetLabel"
image="camera.bmp"
getShowLabel="GetShowLabel"
getShowImage="GetShowImage"
getScreentip="GetScreentip"
supertip="This is a supertip for the combo box."
keytip="A1"
visible="true"
getItemCount="GetItemCount"
getItemLabel="GetItemLabel"
getItemImage="GetItemImage"
getItemScreentip="GetItemScreentip"
getItemSupertip="GetItemSupertip"
onChange="OnChange" />
<comboBox id="comboBox2"
label="Insert More Text."
getText="GetText"
imageMso="TableDrawTable" />
</group>
</tab>
</tabs>
</ribbon>
</customUI>
This sample adds a custom tab titled ComboBox 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 combo boxes named comboBox1 and comboBox2, respectively. The combo boxes have properties defined for them by using attributes such as visible, enabled, and label. 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 Office Fluent 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 sample, the id attribute does not have the Mso qualifier. This indicates to Microsoft Office that the combo box 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.
Examining the other attributes of the combo box, first, you see the enabled attribute. Setting this property to true causes the combo box to be available for use. Setting it to false grays out the control, indicating that the combo box is not active.
Then you see the getText attribute. The getText attribute points to a callback procedure that defines the text that is displayed in the combo box when it is initially displayed. Callback procedures are described in the Assigning Functionality to Ribbon Components section.
The getLabel attribute also points to a callback procedure that returns the label that is displayed for the combo box. Next, the image attribute for comboBox1 specifies a custom image for the combo box. Likewise, the imageMso attribute for comboBbox2 specifies a built-in image for the combo box. For a spreadsheet of built-in images, see 2007 Office Icon Library.
You can use the image and imageMso attributes in conjunction with the loadImage attribute of the customUI element. When you specify an image with the image attribute, the loadImage callback procedure is called to load the image. The image is then displayed on the Ribbon.
Public Function LoadImage(ByVal imageName As String) As Bitmap
Dim assembly As Assembly = Assembly.GetExecutingAssembly()
Dim stream As Stream = assembly.GetManifestResourceStream("CodeSnippetTester." & imageName)
Return New Bitmap(stream)
End Function
public Bitmap LoadImage(string imageName)
{
Assembly assembly = Assembly.GetExecutingAssembly();
Stream stream = assembly.GetManifestResourceStream("your project name here" & imageName)
return new Bitmap(stream);
}
In this procedure, a bitmap image is returned to Microsoft Office. When the procedure is called, the image is retrieved as an assembly resource and assigned to a Stream object. Finally the image is returned as a Bitmap object.
The getShowLabel attribute and the getShowImage attribute point to callback procedures that resolve to Boolean values. For example, setting the getShowLabel attribute to true causes the label for the combo box to appear when the control is displayed. If you want to set the value of the attribute explicitly, you use the showLabel attribute.
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 brief context-sensitive help about the item. Likewise, the supertip attribute (or the getSupertip attribute if you are pointing to a callback procedure) provides additional information about the object.
Another thing to notice about the getScreentip and the supertip attributes is that whenever you see an attribute prefixed by the word get, that attribute points to a callback procedure. Therefore, in the code, the getScreentip attribute points to the callback procedure named GetScreentip.
.gif)
Note:
|
|---|
|
You are not required to name callback procedures the same as the attribute with which they are used. You can just as easily use the following line of code: getScreentip="DoSomething". Also, you are not required to prefix attributes that point to callback procedures with the word get. For example, in the XML code, the onChange attribute points to a callback named OnChange.
|
The supertip attribute illustrates another aspect of control attributes. When you see the attribute without the get prefix, this typically indicates that you assign text to them explicitly. So in the case of the supertip attribute, the text is assigned directly instead of by a callback procedure. Again, there are exceptions such as the onAction attribute, where the attribute is not prefixed by the word get. To find more information about which attributes are assigned explicitly and which attributes point to callbacks, see the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3).
The keytip attribute assigns a KeyTip for the combo box. KeyTips are sometimes known as access keys or accelerators. KeyTips indicate what key to press to access program functionality when using the keyboard access systems. To use a KeyTip for a control on a custom tab, 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 example, below, the tab has a KeyTip equal to Z. The comboBox1 combo box has a KeyTip equal to A1. When the Office Fluent Ribbon is displayed, pressing the key combination ALT displays the Keytips for the tabs. Then pressing z brings the focus to the custom tab. And finally, pressing the key combination A+1 shifts the focus to the combo box.
Looking at the XML code, the visible attribute is set to a boolean value that determines whether the combo box is displayed on the Office Fluent Ribbon.
The next few attributes refer to the items in the combo box's drop-down list. For example, the getItemCount attribute returns the number of items in the drop-down list to Microsoft Office when the user clicks the combo box.
The getItemLabel and getItemImage attributes perform functions similar to the getLabel and getImage attributes, but for drop-down items. The getItemScreentip and getItemSupertip attributes specify screentip and supertips for the drop-down items.
Finally, as mentioned previously, the onChange attribute points to a callback procedure that executes when the user clicks an item in the combo box. This procedure is discussed in the next section.
In the previous XML sample, several of the attributes point to callback procedures. For example, the comboBox element has an onChange attribute. When the user clicks the combo box, the OnChange method, or callback procedure, is called. The code in the OnChange method gives the combo box its functionality. These procedures are called callbacks because when a user clicks an item in the drop-down list of the combo box, the action alerts Microsoft Office that the control needs its attention. Microsoft Office then calls back to the method defined by the onChange attribute and performs whatever action is contained in the method. The following paragraphs describe these callback procedures in detail.
The getText attribute points to the GetText callback procedure that specifies the text that is displayed in the combo box when the control is initially displayed.
Public Function GetText(ByVal control As IRibbonControl) As String
Select Case control.Id
Case "comboBox1" : strText = "Camera"
Case "comboBox2" : strText = "Video"
End Select
Return strText
End Function
public string GetText(IRibbonControl control)
{
Switch (control.Id)
{
case "comboBox1" : strText = "Camera"; break;
case "comboBox2" : strText = "Video"; break;
default : strText = "Camera"; break;
}
return strText
}
When Microsoft Office calls the GetText procedure, an IRibbonControl object representing the combo box is passed in. 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 default text in the combo box.
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 "combo box1" : strLabel = "Insert text."
Case "combo box2" : strLabel = "Insert more text."
End Select
Return strLabel
End Function
public stringn GetLabel(IRibbonControl control)
{
private string strLabel = "";
switch (control.Id)
{
case "combo box1": strLabel = "Insert Text."; break;
case "combo box2": strLabel = "Insert More Text."; break;
default: strLabel = "Insert Text."; break;
}
return strLabel;
}
Similar to the GetText callback procedure, when the GetLabel procedure is called by Microsoft Office, an IRibbonControl object representing the combo box is passed in. 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 combo box's label.
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 GetShowImage(ByVal control As IRibbonControl) As Boolean
Return True
End Function
public bool GetShowImage(IRibbonControl control)
{
return true;
}
Public Function GetShowLabel(ByVal control As IRibbonControl) As Boolean
Select Case (control.Id)
Case "comboBox1" : Return True
Case "comboBox2" : Return False
End Select
End Function
public bool GetShowLabel(IRibbonControl control)
{
bool boolShow = false;
switch (control.Id)
{
case "comboBox1" : boolShow = true; break;
case "comboBox2" : boolShow = false; break;
default: boolShow = true; break;
}
return boolShow;
}
In the case of the GetShowLabel procedure, the 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 Microsoft Office.
The getScreentip attribute also points to a callback procedure. In this case, the procedure returns a string to Microsoft Office that is displayed when you move the mouse over the combo 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 getItemCount callback procedure returns an integer 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 GetItemCount(ByVal control As IRibbonControl) As Integer
Return 3
End Function
public int GetShowImage(IRibbonControl control)
{
return 3;
}
Next is the getItemImage attribute that points to the GetItemIamgee callback procedure.
Public Function GetItemImage(ByVal control As IRibbonControl, ByVal itemIndex As Integer) As Bitmap
Dim imageName As String
Select Case (itemIndex)
Case 0 : imageName = "camera.bmp"
Case 1 : imageName = "video.bmp"
Case 2 : imageName = "mp3device.bmp"
End Select
Dim assembly As Assembly = Assembly.GetExecutingAssembly()
Dim stream As Stream = assembly.GetManifestResourceStream("CodeSnippetTester." & imageName)
Return New Bitmap(stream)
End Function
public Bitmap GetItemImage(IRibbonControl control, int itemIndex)
{
string imageName;
switch (itemIndex)
{
case 0 : imageName = "camera.bmp"; break;
case 1 : imageName = "video.bmp"; break;
case 2 : imageName = "mp3device.bmp"; break;
default: imageName = "camera.bmp"; break;
}
Assembly assembly = Assembly.GetExecutingAssembly();
Stream stream = assembly.GetManifestResourceStream("<your project name here>." & imageName)
return new Bitmap(stream);
}
In this procedure, a bitmap image is returned to Microsoft Office. When the procedure is called the image is assigned to a variable. That image file is then retrieved as an assembly resource stream and assigned to a Stream object. Finally, the image is returned as a Bitmap object.
Next, the OnChange callback procedure is called when you click an item in the combo 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 OnChange(ByVal control As IRibbonControl, ByVal text As String)
applicationObject.Range("A1").Value = _
"You selected " & text
End Sub
public void OnChange(IRibbonControl control, string text)
{
switch (control.Id)
{
case "combo box1":
applicationObject.get_Range("A1:A1", missing).Value2 = "This combo box inserts text."; break;
case "combo box2":
applicationObject.get_Range("A1:A1", missing).Value2 = "This combo box inserts more text."; break;
default:
applicationObject.get_Range("A1:A1", missing).Value2 = "There was a problem with your selection."; break;
}
}