ActiveX

Note: This statement is presently for internal use by Trihedral Engineering Limited only, and as such, this documentation is preliminary and subject to change.

Description: This statement instantiates an ActiveX object. An ActiveX object is treated as a COM client interface that requires a client window area in which to draw.

Format: ActiveX(X0, Y0, X1, Y1, ObjectIdentifier [, EventSearchScope, EventParent, EventCaller])

Parameters: X0, Y0, X1, Y1 { numeric } { required } { no default }

These are the coordinates of the client window area in which the COM object is to draw itself.

ObjectIdentifier { varies } { required } { no default }

ObjectIdentifier specifies a unique identifier for the object to be instantiated. It may take one of the following forms:

• a text string representing a ProgID (e.g. "Excel.Application").

• a textual GUID in registry format (e.g. "{000208-0000-0000-C000-000000000046}"). Note that the curly braces are compulsory.

• a binary GUID (e.g. the result from "GetGUID(1, 00020812-0000-0000-C000-000000000046)").

EventSearchScope { object value } { optional } { default: Self() }

EventSearchScope an optional parameter which, if present, specifies the scope in which to search for event subroutines, and may be any expression that yields a module value or object value.

EventParent { object value } { optional } { default: Self() }

EventParent an optional parameter which, if present, specifies the context that is used to resolve scope for event subroutines. May be any expression that yields an object value.

EventCaller { object value } { optional } { default: Self() }

EventCaller is an optional parameter which, if present, specifies an "auxiliary" context for event subroutines, and may be any expression that yields an object value. An event subroutine can retrieve this value using Caller(Self()).

Comments: If the statement succeeds, a COM client interface is returned, allowing subsequent access to the object. If it fails, Invalid is returned.

There are two significant parametric differences between an ActiveX function and a COMClient function. Firstly, the ActiveX function requires a client window are in which to draw. Secondly, there is no ObjectContext parameter. ActiveX objects are only instantiated in process, as they require direct GDI access to process resources [such as the client window area].

A window in VTS acts as a container for ActiveX objects, in the true OLE definitions of the OC96 specification. This architecture provides a container enumerator so that an ActiveX object can interact with other ActiveX objects in the same container.

Like the COMClient function, this function returns an opaque COM Client Interface handle, through which subsequent object manipulations are performed.

Unlike the COMClient function, this statement may be only be used as a steady-state statement.

The ActiveX object will only remain instantiated while the steady-state statement is still running (i.e. a change of state or destruction of the module instance which is running the statement will cause the ActiveX object to be destroyed). Any variables that hold a handle to the COM Client Interface will be invalidated at that time.

Example:

BrowserObj = ActiveX(12, 52, w - 22, h - 42, "SHDocVw\IWebBrowser2");