ComHelper

COM and ACTIVEX Programming made easier in HotBasic

Part V – Using an ActiveX helper file

General Summary

Part I – Getting started

Part II – Using ComHelper

Part III – Using a helper file with the Use Invoke option

Part IV – Using a helper file without the Use Invoke option

Part V – Using an ActiveX helper file

 Part VI – Using COM events

 

ActiveX objects

Compared to other COM objects, ActiveX objects have 2 additional capabilities:

-          they can be placed on a form like buttons, edit fields, etc.
-          they can trigger events.

When the ActiveX objects option is checked, the helper file contains:

- some generic declarations for COM programming (unless you unchecked the Include COM Generics option),
- the declaration of the data types you chose to include (if any),
- the declaration of the constants you chose to include (if any),
- templates to help you use the objects’ subs and functions,
- templates to help you use the objects’ events.

When you check the ActiveX option, you can choose to check the Use Invoke option or not.

 

Creating an object

1) with Use Invoke

You create an ActiveX object by dimensioning an ACTIVEX variable and by calling CreateActiveX. Example:

create f as form
    create cal as ACTIVEX
        width=300: height=300
        CreateActiveX(Microsoft.Calendar”)
    end create
end create

2) without Use Invoke

You create an ActiveX object by dimensioning an object of the specific type and by calling a specific CreateXXX sub. Example:

create f as form
    create cal as ICalendar
        width=300: height=300
        CreateCalendar
    end create
end create

In both cases 1) and 2), this is pretty similar to how you create a button on your form. The difference with a button is that you need to call CreateXXX once for the activeX object to be generated.

Technically, an ActiveX object is declared as a user-defined type that extends HotBasic's CANVAS control. That is why you can create it on a form like any other control, and also resize it, make it visible/invisible, etc.

In example 1) above, Microsoft.Calendar is the identifier of the object type. It is called the object’s ProgID.

Alternatively, you can pass the object’s CLSID. The CLSID is an uncivilized-looking string between curly brackets. The result is the same. Example:

cal.CreateActiveX (“{8E27C92B-1264-101C-8A2F-040224009C02}”)

 

Using an ActiveX object

Once created, you can use the different subs and functions of the ActiveX object. The helper file contains templates for all of them, indicating their syntax. What some of them do is pretty straightforward from their name and the kind of arguments they take. For some others, it is not obvious and you should look for some documentation or some third-party code to help you.

1) with Use Invoke

You access the object’s subs and functions through 3 HotBasic keywords: invoke, getnum and getstr (exactly like any other object created with the Use Invoke option).

Invoke is used to make a call that doesn’t return a result. You specify the name of the method to call as the first argument of invoke. Example:

obj.invoke(“Quit”)

Getnum is used when the call returns a number. Example:

x= obj.getnum(“Height”)

Sometimes the result is a pointer to another object. Example:

defint newdocument=docs.getnum(“Add”, 1) ‘new document

Getstr is ised when the call returns a string. Example:

s$=obj.getstr(“Name”)

2) without Use Invoke

You access the object’s subs and functions through explicit sub and function names (exactly like any other object created with the Use Invoke option unchecked).

obj.Quit
x = obj.Height
defint newdocument = docs.Add (1)
s$ = obj.Name

 

Passing arguments to a sub or function

Some subs and functions take arguments. Just add them as additional parameters after the method name. Example:

wb.invoke(“Navigate”, a$, 1) ‘Invoke-style

wb.Navigate (a$, 1)          ‘non-Invoke-style

Some arguments are optional, that is, you may omit them. In the corresponding template, those arguments bear the [optional] comment. In order to omit an optional parameter, you must pass void instead. Void is a pre-defined variant variable used for that purpose. Example:

dd.invoke(“Add”, void, void, void, void) ‘Invoke-style

dd.Add (void, void, void, void)          ‘non-Invoke-style

 

Finishing touch: receiving events

Yes, like HotBasic form objects, ActiveX objects have events! Those events are triggered in different situations, depending on the object type. Many objects have onClick, onKeyDown events, etc. Other events are more exotic and relate to what the object does.

ComHelper provides you with a convenient wrapper so that you can handle activeX events. See more details in chapter VI: Using COM events