ActiveXObject (class)
public abstract sealed ActiveXObject {inherits ExternalObject}
Package: CURL.GRAPHICS.ACTIVEX

ActiveXObject allows access to COM and ActiveX objects.

Notes

The ActiveXObject allows you to instantiate ActiveX objects and use their methods and fields. If an ActiveX control has a visual display, it can be placed in a Curl page using ActiveXGraphic. ActiveXObject is only available on the Microsoft Windows™ version of the Curl runtime.

Constructors
default:This is used to get an interface to a Microsoft COM object.
factory public {ActiveXObject.default
ProgId:#String = null,
ClsId:#String = null,
FileExtension:#String = null,
DataFile:#String = null,
initial-url:#Url = null,
initial-read-only?:bool = false,
...
}:ActiveXObject

Properties
com-clsid:Provides the CLSID string corresponding to the underlying COM object.
accessor public abstract ActiveXObject.com-clsid:#String
com-identity:Provides unique identity of the underlying COM object.
accessor public abstract ActiveXObject.com-identity:int64
event-count:Returns the number of different events supported by this ActiveX object.
accessor public abstract ActiveXObject.event-count:int
getter-count:Returns the number of getters available on this ActiveX object.
accessor public abstract ActiveXObject.getter-count:int
method-count:Returns the number of methods available on this ActiveX object.
accessor public abstract ActiveXObject.method-count:int
object-destroyed?:Returns true if this ActiveXObject has already been destroyed.
accessor public final ActiveXObject.object-destroyed?:bool
setter-count:Returns the number of setters available on this ActiveX object.
accessor public abstract ActiveXObject.setter-count:int

Methods
destroy-object:Destroy the ActiveXObject and release the associated ActiveX control.
public sealed {ActiveXObject.destroy-object}:void
get-event-info:Allows enumerating the events of this ActiveX object.
public abstract {ActiveXObject.get-event-info
index:int
}:ActiveXMethodInfo
get-getter-info:Allows enumerating the getters of this ActiveX object.
public abstract {ActiveXObject.get-getter-info
index:int
}:ActiveXFieldInfo
get-method-info:Allows enumerating the methods of this ActiveX object.
public abstract {ActiveXObject.get-method-info
index:int
}:ActiveXMethodInfo
get-property:Get the value of a COM property.
public abstract sealed {ActiveXObject.get-property
name:String,
...:any
}:any
get-setter-info:Allows enumerating the setters of this ActiveX object.
public abstract {ActiveXObject.get-setter-info
index:int
}:ActiveXFieldInfo
set-event-handler:Allows to specify a Curl procedure to act as an event handler for a COM event.
public abstract {ActiveXObject.set-event-handler
name:String,
handler:any,
error-if-missing?:bool = true
}:void
set-property:Set a COM property.
public abstract sealed {ActiveXObject.set-property
name:String,
value:any,
...:any
}:void
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize



Constructor Details
default (factory)
public {ActiveXObject.default
ProgId:#String = null,
ClsId:#String = null,
FileExtension:#String = null,
DataFile:#String = null,
initial-url:#Url = null,
initial-read-only?:bool = false,
...
}:ActiveXObject

This is used to get an interface to a Microsoft COM object.

initial-url: Local file Url to tell COM object to load on start up.
initial-read-only?: Should initial-url be loaded read-only.

Notes

This is most often used for getting an interface to a Microsoft ActiveX control or to an Automation server.

Only privileged applets can call this factory.


Property Details
com-clsid (accessor)
accessor public abstract ActiveXObject.com-clsid:#String

Provides the CLSID string corresponding to the underlying COM object.

Description

Not all COM objects have a CLSID available. A valid CLSID string is returned if the object was created using ClsId or ProgId keyword arguments to ActiveXObject.default#factory or if the underlying COM object supports the IProvideClassInfo interface. Otherwise the return value is null.
Introduced in: version 7.0

com-identity (accessor)
accessor public abstract ActiveXObject.com-identity:int64

Provides unique identity of the underlying COM object.

Description

Two ActiveXObject objects represent two interfaces of the same COM object if and only if their ActiveXObject.com-identity values are the same. This property can be used for comparisons or hashing.

event-count (accessor)
accessor public abstract ActiveXObject.event-count:int

Returns the number of different events supported by this ActiveX object.

Notes

This is very similar to ActiveXObject.method-count, except that this returns the number of events.
Introduced in: version 6.0

getter-count (accessor)
accessor public abstract ActiveXObject.getter-count:int

Returns the number of getters available on this ActiveX object.

Notes

This is very similar to ActiveXObject.method-count, except that this returns the number of getters. See also ActiveXObject.setter-count.

method-count (accessor)
accessor public abstract ActiveXObject.method-count:int

Returns the number of methods available on this ActiveX object.

Notes

This getter returns the number of methods that are available on the ActiveX control referred to by this ActiveXObject. To get a description of a particular method, use ActiveXObject.get-method-info.

Example

The following piece of code creates an ActiveXObject that refers to the Internet Explorer ActiveX control. It creates this ActiveX object and then queries the number of methods available. This example applet requires privilege, it only works on Microsoft Windows™ platforms, and Microsoft Internet Explorer™ must be installed.

{curl 8.0 applet}
{import * from CURL.GRAPHICS.ACTIVEX}
{let active-x-control:ActiveXObject = 
    {ActiveXObject.create ProgId = "Shell.Explorer"}
}
{value active-x-control.method-count}

object-destroyed? (accessor)
accessor public final ActiveXObject.object-destroyed?:bool

Returns true if this ActiveXObject has already been destroyed.

Notes

An instance of ActiveXObject can be destroyed by calling its ActiveXObject.destroy-object method, by calling the destroy method on the containing ActiveXWindow, or by calling the destroy method on the containing ActiveXGraphic.

setter-count (accessor)
accessor public abstract ActiveXObject.setter-count:int

Returns the number of setters available on this ActiveX object.

Notes

This is very similar to ActiveXObject.getter-count or ActiveXObject.method-count.




Method Details
destroy-object (method)
public sealed {ActiveXObject.destroy-object}:void

Destroy the ActiveXObject and release the associated ActiveX control.

Notes

It is illegal to call this method more than once on an ActiveXObject.

If you have passed this ActiveXObject to an ActiveXGraphic, then you should not use ActiveXObject.destroy-object, instead use ActiveXGraphic.destroy-object.

get-event-info (method)
public abstract {ActiveXObject.get-event-info
index:int
}:ActiveXMethodInfo

Allows enumerating the events of this ActiveX object.

index: The index of the event for which information is to be retrieved. Legal values of index are from zero to the number returned by ActiveXObject.event-count - 1.
Introduced in: version 6.0

get-getter-info (method)
public abstract {ActiveXObject.get-getter-info
index:int
}:ActiveXFieldInfo

Allows enumerating the getters of this ActiveX object.

index: The index of the getter for which information is to be retrieved. Legal values of index are from zero to the number returned by ActiveXObject.getter-count - 1.

get-method-info (method)
public abstract {ActiveXObject.get-method-info
index:int
}:ActiveXMethodInfo

Allows enumerating the methods of this ActiveX object.

index: The index of the method for which information is to be retrieved. Legal values of index are from zero to the number returned by ActiveXObject.method-count - 1.

Notes

Client code can request information about each method on the ActiveX control using ActiveXObject.get-method-info.

Example

This code example retrieves the ActiveXMethodInfo for each method on the ActiveX control, and it places the name of the method in a VBox. This sample applet requires privilege, it will only run on Microsoft Windows™ platforms, and Microsoft Internet Explorer™ must be installed.

{curl 8.0 applet}

{import * from CURL.GRAPHICS.ACTIVEX}
{value 
    let active-x-object:ActiveXObject = 
        {ActiveXObject.create ProgId = "Shell.Explorer"}
    let num-methods:int = active-x-object.method-count
    let vbox:VBox = {VBox}
    {for i:int = 0 below num-methods do
        let method-info:ActiveXMethodInfo = 
            {active-x-object.get-method-info i}
        
        {if-non-null name = method-info.name then
            {vbox.add name}
         else
            {vbox.add {format "Couldn't get method-name for %d", i}}
        }
    }
    vbox
}

get-property (method)
public abstract sealed {ActiveXObject.get-property
name:String,
...:any
}:any

Get the value of a COM property.

Description

Retrieves the value of the property named name. If additional arguments are specified, they are passed as arguments to parameterized properties.
Introduced in: version 6.0

get-setter-info (method)
public abstract {ActiveXObject.get-setter-info
index:int
}:ActiveXFieldInfo

Allows enumerating the setters of this ActiveX object.

index: The index of the setter for which information is to be retrieved. Legal values of index are from zero to the number returned by ActiveXObject.setter-count - 1.

set-event-handler (method)
public abstract {ActiveXObject.set-event-handler
name:String,
handler:any,
error-if-missing?:bool = true
}:void

Allows to specify a Curl procedure to act as an event handler for a COM event.

name: The name of the event.
handler: The event handler procedure. Its signature must correspond to the event signature in the object's type library. Set it to null to remove an existing event handler.
error-if-missing?: If set to false prevents the exception being thrown if the COM object does not support the named event or (in case of null handler) the requested event handler was not previously specified.

Notes

Whenever an ActiveXObject has an active event handler, it and the associated COM object cannot be garbage collected. You should call ActiveXObject.destroy-object or remove all event handlers if you want the object's resources to be reclaimed.

The Curl RTE processes ActiveX events during blocking HTTP calls, so event handlers on an ActiveX object must not enter any sort of event loop or do blocking HTTP calls.
Introduced in: version 6.0

set-property (method)
public abstract sealed {ActiveXObject.set-property
name:String,
value:any,
...:any
}:void

Set a COM property.

Description

Sets the value of the property named name to value. If additional arguments are specified, they are passed as arguments to parameterized properties.

Notes

The parameterized properties arguments are specified after the value.
Introduced in: version 6.0