PerlCtrl Tour

This simple Perl control exposes a single method, Hello(), which returns the text 'Hello, World'. This example can be found in the HelloCtrl subdirectory of the Perl Dev Kit example directory (by default C:\Program Files\ActiveState Perl Dev Kit 7.x\Samples\HelloCtrl).

A Perl control source file has two parts. The first is the code you want to expose, and the second is a %TypeLib hash containing information about your control and how much of it will be exposed.

A Walk Through the Code

This sample begins with a package declaration and a subroutine. In a regular Perl program, you can invoke the Hello() method with the statement Hello::Hello.

    package Hello;
    sub Hello {
        return "Hello, World";
    }

Following the the source code for the control is the %TypeLib hash. This is enclosed by =pod and =begin PerlCtrl directives at the beginning, and =end PerlCtrl and =cut directives at the end:

    =pod
    
    =begin PerlCtrl

After the =begin PerlCtrl directive, the %TypeLib definition appears. This hash includes a number of key/value pairs. With the exception of the Methods and Properties keys, all of these keys have scalar values. The PackageName key contains the name of the Perl package with the source code:

    %TypeLib = (
        PackageName => 'Hello',

The TypeLibGUID, ControlGUID, and DispInterfaceIID are globally unique identifiers (GUIDs) that are used internally by COM and ActiveX to identify your control. Like fingerprints, no two GUIDs are the same.

    # DO NOT edit the next 3 lines.
    TypeLibGUID => '{E91B25C6-2B15-11D2-B466-0800365DA902}',
    ControlGUID => '{E91B25C7-2B15-11D2-B466-0800365DA902}',
    DispInterfaceIID=> '{E91B25C8-2B15-11D2-B466-0800365DA902}',

The GUIDs provide internal identification for the control. The ControlName, ControlVer, and ProgID provide identification for the control that can be used by programmers. The ControlName is the COM class name for the control; the ControlVer is its version, and the ProgID is the name that can be used to launch the control from other programs:

    ControlName => 'HelloWorldControl',
    ControlVer => 1,
    ProgID => 'Hello.World',

The DefaultMethod is the name of a method that should be invoked if a programmer invokes the control in a context where a return value is expected but does not supply a method or property name:

    DefaultMethod => '',

The Methods key contains a reference to a hash. This hash consists of keys that are references to a hash that describes each method in the control. Each method should be described by its return type (RetType), the number of parameters (TotalParams), the number of optional parameters (NumOptionalParams), and a list that describes the parameters (ParamList). In this example, the Hello() method is described as returning a VT_BSTR value (a binary string Variant) and taking no parameters:

    Methods => {
        'Hello' => {
        RetType => VT_BSTR,
        TotalParams => 0,
        NumOptionalParams => 0,
        ParamList =>[ ]
        },
    }, # end of 'Methods'

You can also declare properties for a control. The Hello.World control doesn't have any properties, so the Properties hash is empty:

    Properties => {
    } ,
    # end of 'Properties'

The Properties hash is the last part of the TypeLib definition, which is followed by the =end PerlCtrl and =cut directives.

    ); # end of %TypeLib
    
    =end PerlCtrl
    
    =cut