Microsoft Office 2000/Visual Basic Programmer's Guide

Working with Images on Command Bar Buttons

Every built-in command bar button has an image associated with it. You can use these images on your own command bar buttons as long as you know the FaceId property value of the built-in button that contains the image. The values for the FaceId property range from zero (no image) to the total number of button images used in the host application (typically a few thousand). One easy way to browse the available button images is to build a toolbar, add some buttons, and assign FaceId property values to those buttons. The buttons display the image associated with the specified FaceId property value. The modCommandBarCode module in CommandBarSamples.mdb in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM contains the CBShowButtonFaceIDs procedure, which accepts starting and ending FaceId property values and builds a toolbar that displays all the specified images. For example, to see button images with values from 200 to 299, you would call CBShowButtonFaceIDs from the Immediate window like this:

? CBShowButtonFaceIDs(200, 299)

And the button images would display as shown in Figure 6.4.

Figure 6.4 A Collection of Built-in Toolbar Icons

You can see the value of the FaceId property for any image on the command bar by resting your mouse pointer on the image until the value appears in the button's ToolTip.

Another way to copy the image from one command bar button to another is to use the FindControl method of the CommandBars collection to determine the value of the FaceId property for the image you want to copy. You can then use the CommandBarControl object's CopyFace and PasteFace methods to copy the image to a new control. The following sample code illustrates how to use these methods to paste the icon associated with an existing command bar button to a new command bar button.

Private Sub CBCopyIconDemo()
   ' This procedure demonstrates how to copy the image associated
   ' with a known toolbar button to a new toolbar button. This example
   ' copies the image associated with the "Contents and Index" control
   ' on the Help menu to a new command bar control.
   
   Dim cbrNew                As CommandBar
   Dim ctlNew                As CommandBarControl
   Const ERR_CMDBAR_EXISTS   As Long = 5
   
   On Error Resume Next
   Set cbrNew = CommandBars.Add("TestCopyFaceIcon")
   If Err = ERR_CMDBAR_EXISTS Then
      Call CBDeleteCommandBar("TestCopyFaceIcon")
      Set cbrNew = CommandBars.Add("TestCopyFaceIcon")
   ElseIf Err <> 0 Then
      Exit Sub
   End If
   On Error GoTo 0
   Set ctlNew = cbrNew.Controls.Add(msoControlButton)
   Call CBCopyControlFace("Help", "Contents and Index")
   
   With ctlNew
      .PasteFace
   End With
   cbrNew.Visible = True
End Sub

The CBCopyIconDemo procedure is available in the modCommandBarCode module in CH06_2.mdb in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM.

This procedure calls two other custom procedures. The CBDeleteCommandbar procedure was discussed in the previous section and is used to delete the command bar if it already exists. The CBCopyControlFace procedure copies the image of the specified control to the Clipboard:

Function CBCopyControlFace(strCBarName As String, _
                         strCtlCaption As String)
                     
   ' This procedure uses the CopyFace method to copy the image associated
   ' with the control specified in the strCtlCaption argument to the Clipboard.
   
   Dim ctlCBarControl As CommandBarControl
   
   Set ctlCBarControl = CommandBars.FindControl(msoControlButton, _
      CBGetControlID(strCBarName, strCtlCaption))
   ctlCBarControl.CopyFace
End Function

The CBCopyControlFace procedure is available in the modCommandBarCode module in CommandBarSamples.mdb in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM.

The CBCopyControlFace procedure uses the CBGetControlID procedure as the Id argument for the FindControl method. CBGetControlID returns the Id property for the specified control by using the following line:

CBGetControlID = Application.CommandBars(strCBarName) _
   .Controls(strControlCaption).ID

The CommandBar object also supports a FindControl method that searches for the specified control only on the CommandBar object itself.

To see these procedures working together, place the insertion point (cursor) anywhere in the CBCopyIconDemo procedure and use the F8 key to step through the code. Try changing the command bar name and control name to copy different images to the new control.