SAMPLE: How to Use Enumerated Properties in an OLE Control

WINDOWS        | WINDOWS NT

The information in this article applies to:

• The Microsoft Foundation Classes (MFC) included with: Microsoft OLE Control Developer's Kit (CDK) versions 1.0, 1.1, 1.2

This is the Visual C++ 1.5x and 2.x version of this sample. There is an equivalent Visual C++ 4.x 32-bit sample available under the name ENPROP32.

SUMMARY

The Enumprop sample illustrates using enumerated properties in an OLE control.

Download Enprop.exe, a self-extracting file, from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download Enprop.exe (size: 45810 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the SOFTLIB\MSLFILES directory
        Get Enprop.exe (size: 45810 bytes) 
  

   ENPROP.EXE -d

MORE INFORMATION

The ENUMPROP sample illustrates how to use enumerated properties in an OLE control. An enumerated property is one that has a specific set of possible values. For example, an OLE control might support a property named FillPattern, which it uses to determine the type of brush to use when drawing the control and limit the values the FillPattern property could be set to. Accepted values for a FillPattern property might be cross-hatched, vertical lines, horizontal lines, and so on.

An OLE control can limit a user's possible choices for a property by presenting a drop list comobo box that lists the possibilities on its property page. However, another mechanism is needed to enable a property browser provided by another application to be able to provide the same type of interface when editing the property.

There are two ways to implement an enumerated property so that a property browser can gather enough information about the property to provide the right editing interface. One method involves declaring an enum type in the OLE control's .odl file and manually editing the property's declaration to make it be of that type. For example:

  ...

  typedef enum
  {
    [helpstring("Solid")]        Solid      = 0,
    [helpstring("Dash")]         Dash       = 1,
    [helpstring("Dot")]          Dot        = 2,
    [helpstring("Dash-Dot")]     DashDot    = 3,
    [helpstring("Dash-Dot-Dot")] DashDotDot = 4,
  } enumLineStyle;

  ...

  properties:
  // NOTE - ClassWizard will maintain property information here.
  //    Use extreme caution when editing this section.
  //{{AFX_ODL_PROP(CEnumCtrl)
    [id(1)] enumLineStyle LineStyle;
  //}}AFX_ODL_PROP

  ...

The ENUMPROP sample illustrates using both methods. The OLE control implemented in the sample supports two custom properties, LineStyle and FillPattern. The LineStyle property is declared as an enum in the control's .odl file. Support for using the FillPattern property as an enumerated property is handled by using overrides of the OnGetPredefinedStrings, OnGetPredefinedValue, and OnGetDisplayString methods.

ENUMPROP is based on a ControlWizard-generated OLE control. Files included with the sample, which are directly related to using enumerated properties, are:

   Enum.odl - Shows declaring the enum type for the LineStyle property.

   Enumctl.cpp - Illustrates overriding the COleControl members
   OnGetPredefinedStrings, OnGetPredefinedValue, and
   OnGetDisplayString.

  warning M0002: Warning near line 35 column 35: specified type is not
  supported by IDispatch::Invoke

NOTE: The test container tool provided with the CDK does not implement a drop list comobo box on its property browser page when editing an enumerated property. To see the full benefits of using an enumerated property, use an OLE control container application that provides a property browser with this capability.

RFERENCES

For more information, please see the Per-Property Browsing section in Appendix D, OLE Controls Architecture, in the CDK Books Online.