DOCERR: How to Manage VBX Picture Properties with MFC

The information in this article applies to:

• The Microsoft Foundation Classes (MFC), included with:

      - Microsoft Visual C++ for Windows, versions 1.0 and 1.5
  

SUMMARY

Microsoft Foundation Class (MFC) TechNote #27 describes how to specify picture properties for VBX controls. However, the information is incomplete in some respects and contains one documentation error.

MORE INFORMATION

Some VBX controls implement a picture property that can be used to display a custom graphical image. In MFC 2.0 and 2.5, the picture property is implemented as an HPIC handle.

The HPIC handle represents an object that can contain an HBITMAP, HICON, or an HMETAFILE. HPIC handles are reference-counted by MFC 2.0 and 2.5 and are automatically destroyed when their reference count drops to zero. The global MFC function AfxReferencePict can be used to increment or decrement the reference count for an HPIC.

The sample code supplied in MFC TechNote #27 contains an error in the call to the LoadBitmap function. The example is making a call to the Windows API (application programming interface) function LoadBitmap(). However, this function expects an instance handle as the first parameter. The sample code below corrects this error.

One other point of confusion is the call to AfxReferencePict(). The sample code from MFC TechNote #27 implies that you should call this function to decrement the usage counter immediately after setting the picture property. In fact, you should wait until the picture is no longer needed. The sample code below shows how to call AfxReferencePict() in the destructor for the dialog box class.

Sample Code

This sample code is taken from the OnInitDialog() function for a dialog box created in App Studio. The dialog box contains a VBX control that implements a picture property. Be sure to select Custom VBX controls support from AppWizard, or call the EnableVBX() in the CWinApp::InitInstance function.

The dialog box class contains a pointer to the VBX control. This pointer was created in Class Wizard with type CVBControl* and given the name pVBXControl. The dialog box class also contains an HPIC with the name hPic.

   BOOL CTestDlg::OnInitDialog()
   {

     CDialog::OnInitDialog();

     // Load a resource that is supported by the HPIC object. In this
     // case, we are loading a bitmap resource.
     HBITMAP hBmp = LoadBitmap(AfxGetInstanceHandle(),
                               MAKEINTRESOURCE(IDBM_MY_PICTURE));
     // Declare a PIC structure and fill in the appropriate fields. For
     // this example, we are using a bitmap.
     PIC picture;
     picture.picData.bmp.hbitmap = hBmp;
     picture.picType = PICTYPE_BITMAP;

     // Initialize the embedded HPIC by Calling AfxSetPict().
     hPic = AfxSetPict(NULL, &picture);

     // Place the picture in a VBX control that has a picture property.
     pVBXControl->SetPictureProperty("picture", hPic);

     return TRUE;  // Return TRUE unless you set the focus to a control.
   }

   // Decrement the reference count for the HPIC in the destructor for
   // the dialog class.
   CTestDlg::~CTestDlg()
   {
     AfxReferencePict(hPic, FALSE);
   }