ActiveX Controls: Adding Custom Methods to an ActiveX Control

  • Article

|  Overview |  How Do I |  FAQ |  |  Sample

Custom methods differ from stock methods in that they are not already implemented by COleControl. You must supply the implementation for each custom method you add to your control.

An ActiveX control user can call a custom method at any time to perform control-specific actions. The dispatch map entry for custom methods is of the form DISP_FUNCTION.

Adding a Custom Method With ClassWizard

The following procedure demonstrates adding the custom method PtInCircle to an ActiveX control’s skeleton code. PtInCircle determines whether the coordinates passed to the control are inside or outside the circle. This same procedure can also be used to add other custom methods. Simply substitute your custom method name and its parameters for the PtInCircle method name and parameters. (This example uses the InCircle function from the article Events. For more information on this function, see the article ActiveX Controls: Adding Custom Events to an ActiveX Control.)

To add the PtInCircle custom method using ClassWizard

  1. Load the control’s project.

  2. On the View menu, click ClassWizard.

  3. Click the Automation tab.

  4. Select the control’s class from the Class Name box.

  5. Click Add Method.

  6. In the External name box, type PtInCircle.

  7. In the Internal name box, type the name of the method’s internal function or use the default value provided by ClassWizard (in this case, PtInCircle).

  8. In the Return Type box, click BOOL for the method’s return type.

  9. Using the Parameter List grid control, add a parameter, called xCoord (type OLE_XPOS_PIXELS).

  10. Using the Parameter List grid control, add a second parameter, called yCoord (type OLE_YPOS_PIXELS).

  11. Click OK to close the Add Method dialog box.

  12. Click OK to confirm your choices and close ClassWizard.

ClassWizard Changes for Custom Methods

When you add a custom method, ClassWizard makes some changes to the control class header (.H) and implementation (.CPP) files. The following line is added to the dispatch map declaration in the control class header (.H) file:

afx_msg BOOL PtInCircle(long xCoord, long yCoord);

This code declares a dispatch method handler called PtinCircle. This function can be called by the control user using the external name PtInCircle.

The following line is added to the control’s .ODL file:

[id(1)] boolean PtInCircle(OLE_XPOS_PIXELS xCoord, OLE_YPOS_PIXELS yCoords);

This line assigns the PtInCircle method a specific ID number, taken from the method’s position in ClassWizard’s methods and properties list. Because ClassWizard was used to add the custom method, the entry for it was added automatically to the project’s .ODL file.

In addition, the following line, located in the implementation (.CPP) file of the control class, is added to the control’s dispatch map:

DISP_FUNCTION(CSampleCtrl, "PtInCircle", PtInCircle, VT_BOOL, VTS_I4 VTS_I4)

The DISP_FUNCTION macro maps the method PtInCircle to the control’s handler function, PtInCircle, declares the return type to be BOOL, and declares two parameters of type short to be passed to PtInCircle.

Finally, ClassWizard adds the stub function CSampleCtrl::PtinCircle to the bottom of the control’s implementation (.CPP) file. For PtinCircle to function as stated previously, it must be modified as follows:

BOOL CSampleCtrl::PtInCircle(short xCoord, short yCoord)
{
    return InCircle(CPoint(xCoord, yCoord));
}