4.12 The OLE-AUTOMATION module

<variable-description>

Sealed concrete class

Summary

Describes a single property of a dispinterface.

Superclasses

<object>

Init-keywords

name:

A string name for the property. Required.

getter:

A Dylan function that takes the dispinterface as its sole argument and returns the value of the property, or #f if the property is not externally readable. Default value: #f.

setter:

A Dylan function that changes the value of the property, taking the new value and the dispinterface as its arguments, or #f if the client is not permitted to change the property value. Default value: #f.

Note that there is a special case. If the value of the property is an interface pointer (such as <LPUNKNOWN> or <LPDISPATCH>), the setter method must call AddRef on the new value and must call Release on the old value.

type:

A C designator type from the C-FFI library. It is used to specify the datatype that an Automation client written in C or C++ will use to represent the property value. The following values are legal:

<C-int>, <C-short>, <C-long>, <C-float>, <C-double>, <C-signed-char>, <C-character>, <CY>, <DATE>, <ole-array>, <class-factory>, <LPDISPATCH>, <C-HRESULT>, <VARIANT-BOOL>, <VARIANT>

You can also specify the corresponding Dylan type (such as <single-float>, <double-float>, <character>, or <boolean>). The class <integer> is considered equivalent to <C-long>, and <string> is equivalent to <ole-array>.

(In addition, the low-level representation as an instance of <LPTYPEDESC> can be used here.)

For an array, you must also specify the element type. Do this by using the function ole-array-type to construct a type description. For example, ole-array-type(<C-float>) for a vector or array of single floats, or ole-array-type(<VARIANT>) for a heterogeneous array. Note that dimensions are not specified here.

If you do not specify the type:, the OLE-Automation library will select one automatically to most closely match the Dylan type declared for the result value of the getter function. One way or the other, the type must be specified.

Note that the default is the type declared for the generic function. It is not sufficient simply to specify the type for a slot, since there is not enough information here to know which method is applicable.

documentation:

A optional string describing the property. This is called a helpstring in IDL.

help-context:

The position in the WinHelp file (from help-file: in the <coclass-type-info> instance) where this property is documented. Optional.

disp-id:

An <integer> which is the DISPID (dispatch ID) by which the client will refer to the property. Usually you would not specify this, and the OLE-Automation library would automatically assign a DISPID. You do need to specify a DISPID when implementing a stock property. For example:

                  make(<variable-description>, 
                       name: "Value", 
                       disp-id: $DISPID-VALUE ...)

Description

Describes a single property of a dispinterface.