HOW TO: Set the Mask Property and the Picture Property for an Office 2003 CommandBar Button

This step-by-step article describes how to set the Mask and the Picture properties of a Microsoft Office 2003 CommandBar control from a managed code extension that is created with Visual Studio Tools for the Microsoft Office System. The Picture properties permit you to set the image that appears on a CommandBar control. The Mask properties may be used to create a transparent background for that image.

Create a New Visual Basic .NET Excel Workbook Project

1. On the File menu in Microsoft Visual Studio .NET 2003, point to New, and then click Project.
   
   The New Project dialog box appears.
   1. In the Project Types list, expand Microsoft Office System Projects, and then click Visual Basic Projects.
   2. In the Templates list, click Excel Workbook.
   3. In the Name box, type ExcelCommandbar, and then click OK.
      
      The Microsoft Office Project Wizard appears.
   4. Click Finish.
2. On the Project menu, click Add Reference.
   
   The Add Reference dialog box appears.
   1. Click the .NET tab. In the list of components, click System.Drawing.dll, and then click Select.
   2. In the list of components, click stdole, and then click Select.
   3. Click OK.
3. Add the following directive at the top of ThisWorkbook.vb:

   Imports System.Reflection

Add Image Resources to Your Project

In this section, you will add two embedded image resources to the project. One resource is for the Picture properties of the CommandBar control. The other resource is for the Mask properties.

Add an Image Resource to Your Project That Serves As the Image for Your CommandBar Control

1. On the Project menu, click Add Component. The Add New Item dialog box appears.
2. In the Templates list, click Bitmap File.
3. Name the image Picture.bmp, and then click Open.
   
   The bitmap is opened for editing in the Bitmap Editor.
4. On the View menu, click Properties Window. Set both the Width property and the Height property of the bitmap to 16.
5. Fill the whole bitmap area with red, and then draw a green circle in the center of the bitmap.
6. In Solution Explorer, right-click Picture.bmp, and then click Properties. Change the Build Action property to Embedded Resource.
7. On the File menu, click Save Picture.bmp.

Add an Image Resource to Your Project That Serves As the Mask for Your CommandBar Control Image

1. In Solution Explorer, click Picture.bmp.
2. On the File menu, click Copy.
3. On the File menu, click Paste.
   
   A new file that is named Copy of Picture.bmp is added to your project.
4. In Solution Explorer, right-click Mask.bmp, and then click Rename. Change the name to Mask.bmp.
5. In Solution Explorer, right-click Mask.bmp, and then click Open. Change the image background color to white and change the circle color to black.
   
   Note When the picture with the mask is added to the CommandBar control, the black areas of the mask are visible. The white areas are transparent.
6. On the File menu, click Save Mask.bmp.

Add Code to Create a CommandBar and a CommandBar Control

In this section, you add code to the project that loads the embedded image resources in streams, builds the CommandBar and the CommandBar control, and then sets the Picture properties and the Mask properties for the CommandBar control.

1. Add the following class-level variable to the OfficeCodeBehind class:

   WithEvents CBarButton As Office.CommandBarButton

2. Add the following code to the ThisWorkbook_Open event handler in ThisWorkbook.vb:

       'Get a reference to this assembly.
       Dim ThisAssembly As [Assembly]
       ThisAssembly = [Assembly].GetExecutingAssembly()
   
       'Load the Picture and the Mask image resources.
       Dim imgStreamPic As System.IO.Stream, imgStreamMask As System.IO.Stream
       imgStreamPic = ThisAssembly.GetManifestResourceStream("ExcelCommandBar.Picture.bmp")
       imgStreamMask = ThisAssembly.GetManifestResourceStream("ExcelCommandBar.Mask.bmp")
   
       'Obtain references to IPictureDisp for both images.
       Dim ax As New MyAxHost
       Dim Pic As stdole.IPictureDisp, Mask As stdole.IPictureDisp
       Pic = ax.IPictureDisp(Drawing.Image.FromStream(imgStreamPic))
       Mask = ax.IPictureDisp(Drawing.Image.FromStream(imgStreamMask))
   
       'Add a temporary CommandBar and a CommandBar button.
       Dim CBar As Office.CommandBar
       CBar = ThisApplication.CommandBars.Add("My CommandBar", , , True)
       CBarButton = CType(CBar.Controls.Add(Office.MsoControlType.msoControlButton), _
                   Office.CommandBarButton)
       CBarButton.Style = Office.MsoButtonStyle.msoButtonIconAndCaption
       CBarButton.Caption = "My Button"
       CBarButton.Tag = "My_Button"
       CBarButton.Picture = Pic
       CBarButton.Mask = Mask
       CBar.Visible = True
   
   

3. Add the following class, MyAxHost, immediately after the ThisWorkbook_Open event handler in ThisWorkbook.vb:

   Public Class MyAxHost
   
       Inherits System.Windows.Forms.AxHost
   
       Public Sub New()
           MyBase.New("59EE46BA-677D-4d20-BF10-8D8067CB8B33")
       End Sub
   
       Public Shared Function IPictureDisp(ByVal Image As System.Drawing.Image) As stdole.IPictureDisp
           IPictureDisp = CType(AxHost.GetIPictureDispFromPicture(Image), stdole.IPictureDisp)
       End Function
   
   End Class

4. Add the following function to the OfficeCodeBehind class:

   Private Sub CBarButton_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton,  _
       ByRef CancelDefault As Boolean) Handles CBarButton.Click
       MessageBox.Show("You clicked My Button!")
   End Sub

5. Press F5 to build and to run the project.
   
   You notice that ExcelCommandBar.xls opens in Excel. When the workbook opens, My CommandBar appears. My CommandBar has one CommandButton control with a transparent image.

For additional information, click the following article number to view the article in the Microsoft Knowledge Base: