RibbonX for Dummies: Chapter 6 (Part 1) (
Page 2 of 4 )
Setting the style
The user begins all the way to the left of the Letter/Memo tab in the Style group. The Split button defaults to the Letter style for new documents. The other styles include a memo, an invitation, and a past due notice. You could add as many styles as needed to support your organization. Each of the styles sports a special icon, label, and appearance. Of course, RibbonX provides no obvious means of changing either the icon or the label as the user
works with the application. The trick is to provide the required functionality as a callback. Listing 6-1 shows the required XML for the Style group.
Listing 6-1: Creating a Style Group
<group id=“Style” label=”Style”>
<splitButton id=”UseStyle” size=”large”>
<button id=”StSelected”
onAction=”StyleDefault”
getImage=”StyleGetImage”
getLabel=”StyleGetLabel”/>
<menu id=”OtherStyles”>
<button id=”StLetter”
label=”Letter”
onAction=”StyleLetter” />
<button id=”StPastDue”
label=”Past Due Notice”
onAction=”StylePastDue” />
<button id=”StMemo”
label=”Memo” onAction=”StyleMemo” />
<button id=”StInvitation”
label=”Invitation”
onAction=”StyleInvitation” />
</menu>
</splitButton>
</group>
Notice that the StSelected selected button has no image or label assigned to it. This button uses the getImage and getLabel attributes instead to assign a VBA callback to handle the image and label needs. The default button actually shows the current document selection, so it doesn’t really do anything, in this case, when you press it. This is an alternative use for a Split button; it acts as a status indicator. The buttons that actually perform a change appear as part of the OtherStyles menu. The code for performing the image and label updates appears in Listing 6-2.
Listing 6-2: Modifying Labels and Images at Runtime
'Callback for StDefault getLabel
Sub StyleGetLabel(control As IRibbonControl, _
ByRef returnedVal)
' Return the currently selected document style.
returnedVal = DocType
End Sub
'Callback for StDefault getImage
Sub StyleGetImage(control As IRibbonControl, _
ByRef returnedVal)
' Choose an image based on the document type.
Select Case (DocType)
Case “Letter”
returnedVal = “EnvelopesAndLabelsDialog”
Case “Past Due Notice”
returnedVal = “PermissionRestrict”
Case “Memo”
returnedVal = “Paste”
Case “Invitation”
returnedVal = “FileCreateDocumentWorkspace”
Case Else
returnedVal = “EnvelopesAndLabelsDialog”
End Select
End Sub
The StyleGetLabel Sub simply returns a string called DocType. The DocType variable is global, and the application uses it to track the document type. You can use this information to add text to the document, change the styles based on document type, and to control the actual document content. In this case, the example adds special text for each of the document types and modifies the labels and images.
The image change occurs when Word calls the StyleGetImage callback. The code uses a Select Case statement to choose the image based on the document type. All these images are built in rather than custom. If you use a custom image, you must embed it as part of the document and then use the name you supplied for the image.
You’ve seen the physical interface and the code that modifies the appearance of the split button. However, the application still requires some code to trigger the change. Listing 6-3 shows a typical example of one of the button callbacks.
Listing 6-3: Changing the Document Type
'Callback for StLetter onAction
Sub StyleLetter(control As IRibbonControl)
'Set the new default document style.
DocType = “Letter”
' Change the custom document properties.
ActiveDocument.CustomDocumentProperties( _
“DocType”).Value = “Letter”
' Update the Ribbon.
Rib.InvalidateControl “StSelected”
' Set the document headers.
SetHeaders
End Sub
The code begins by changing the DocType variable to reflect the change in document type. It then stores this information in a custom document property using the CustomDocumentProperties() method. This step is extremely important because without it, the document won’t know what type it is when you open it later. The custom property acts as a permanent memory of the current document type. You can see this custom property by performing the following steps.
1. Choose Office Menu->Prepare->Properties.
You see the Document Properties window.
2. Click the down arrow next to Document Properties and choose
Advanced Properties from the menu.
You see a Properties dialog box.
3. Select the Custom tab.
Word displays a list of custom properties, including the DocType property, as shown in Figure 6-2.
4. Click Cancel to close the Properties dialog box. Click the close box to close the Document Properties window.
Figure 6-2: Word stores the custom properties you create as part of each document.
The next code step in Listing 6-3 is the most important because it demonstrates a RibbonX principle you need to remember. Notice that the InvalidateControl method doesn’t use the control identifier for the current control. Instead, the control identifier refers to the default button for the Split button. By invalidating the default button, the code triggers the getLabel and getImage methods described in Listing 6-2. Even though you can’t modify the Ribbon controls directly, you can use these roundabout methods to perform a change in appearance.
The code finally calls a Sub called SetHeaders. The SetHeaders Sub is an example of business logic. You could use the same code in earlier versions of Office to modify the content of the document. In this case, the Sub changes the document style features including some heading text. It relies on search techniques to find text that belongs to the older style and then updates the document with any new style-specific entries.
The final step in the document type process is to ensure the document type is correct when the user opens the document. Listing 6-4 shows the document type code that appears in the OnLoad callback.
Listing 6-4: Restoring the Document Type After the Ribbon Loads
' Check the document type and add a custom property
' for the document if necessary.
DocType = “”
Dim CurrProp As DocumentProperty
For Each CurrProp In _
ActiveDocument.CustomDocumentProperties
If CurrProp.Name = “DocType” Then
DocType = CurrProp.Value
End If
Next
If DocType = “” Then
ActiveDocument.CustomDocumentProperties.Add _
Name:=”DocType”, _
LinkToContent:=False, _
Type:=msoPropertyTypeString, _
Value:=”Letter”, _
LinkSource:=False
DocType = “Letter”
End If
The code begins by initializing DocType to an empty string. It then looks for the DocType custom property. If this property doesn’t appear in the document, the code sets the property and the DocType variable to a default type of Letter. Because so many parts of the application rely on DocType, you must ensure that new documents receive the proper initialization.
Techniques 
