Accessing COM object properties and methods

Accessing COM object properties and methods

A COM object property is a value that defines the visible, functional, and other characteristics of a COM object (ActiveX Automation object or ActiveX control). An ActiveX control property is classified as a design-time or run-time property depending on when you can change it. A design-time property can be changed using the Properties Window of the AppBuilder. A run-time property can be changed from ABL at run time. Generally, you can read both design-time and run-time properties at run time. In all other respects, COM object properties are functionally analogous to handle attributes.

A COM object method is a specialized function associated with a COM object that performs an action on the COM object or alters the behavior of the COM object. COM object methods may or may not return a value and may or may not require parameters. A return value may be a component handle to another COM object; however, many methods return other types of information or no information at all. Like handle methods, you execute COM object methods by calling them directly as statements rather than as part of an expression. In all other respects, COM object methods are functionally analogous to handle methods.

The basic syntax for accessing COM object properties and methods from ABL is similar to accessing handle attributes and methods. These are the main differences:

You must access a COM object property or method with reference to an instantiated COM object. ABL supports the COM-HANDLE data type to provide COM object references for accessing properties and methods.

You might have to specify the parameters of COM object methods with more type information, depending on the method and how the COM object is implemented.

All COM objects are dynamic objects, so you never qualify a COM object reference by a static container reference (such as a static frame or menu widget).

Syntax for accessing COM object properties and methods

These are the three basic types of ABL statements for accessing properties and methods:

Property write

Property read

Method call

Note:

You can access COM object properties and methods from many other types of ABL statements that use these properties and methods in a similar fashion. The following statements, however, illustrate all the basic mechanisms for accessing COM objects from ABL.

Property write

The following syntax describes a basic assignment (=) statement for writing a COM object property:
Syntax
Com-Handle-Var :COMProperty [ AS Data-type ] = expression
  [ NO-ERROR ] 
Com-Handle-Var is any COM-HANDLE variable set to the handle of an instantiated COM object. COMProperty is a COM object property access (see the “COMProperty” section). Data-type is any supported COM data type (see the “Data-type” section) that is compatible with expression. The expression is any combination of ABL elements that results in a single value. NO-ERROR allows the application to handle any ABL ERROR conditions raised by the statement.

Property read

The following syntax describes a basic assignment (=) statement for writing a COM object property:
Syntax
[ { field | COMProperty } = ]
  Com-Handle-Var :COMProperty [ NO-ERROR ]
A field is any ABL variable, database field, class-based data member or property, or handle attribute of a compatible data type. COMProperty is a COM object property access (see the “COMProperty” section). Com-Handle-Var is any COM-HANDLE variable set to the handle of an instantiated COM object. NO-ERROR allows the application to handle any ABL ERROR conditions raised by the statement.

Method call

The following syntax describes either a basic assignment (=) statement for invoking a COM object method that returns a value or the basic statement for invoking a COM object method directly that ignores any returned value:
Syntax
[ { field | COMProperty } = | NO-RETURN-VALUE ]
  Com-Handle-Var :COMMethod [ NO-ERROR ]
A field is any ABL variable, database field, class-based data member or property, or handle attribute of a compatible data type. COMProperty is a COM object property access (see the “COMProperty” section). NO-RETURN-VALUE indicates that you are invoking the COM object method directly, as a statement, without returning its value. Com-Handle-Var is any COM-HANDLE variable set to the handle of an instantiated COM object. COMMethod is a COM object method access (see the “COMMethod” section section). NO-ERROR allows the application to handle any ABL ERROR conditions raised by the statement.

Note:

You can invoke both a property read and a method as part of an expression within another statement (such as in a DISPLAY statement or the right side of an assignment (=) statement). You can also directly invoke both property reads and methods as statements in themselves. However, direct invocation is meaningful only for methods.

COMProperty

The following syntax describes a COM object property access with optional chaining of COM object references:
Syntax
[ { COMProperty | COMMethod } : ] ...
  Property-Name [ ( index [ , index ] ... ) ]
Property-Name is the name of the accessed property. The optional multi-level index is an integer expression as required by the property. You must not follow the colon separator by a space.

Any COMProperty or COMMethod that precedes the final Property-Name must return a COM object reference that provides access to the immediately following Property-Name. The final property access can return any supported COM data type.

COMMethod

The following syntax describes a COM object method access with optional chaining of COM object references:
Syntax
[ { COMProperty | COMMethod } : ] ...
  Method-Name ( [ COMparm [ , COMparm ] ... ] )
This syntax describes a potential chain of COM object references that result in a COM object method call. Method-Name is the effective name of the invoked method. COMparm is a parameter as required by the method (see the “COMParm” section). You must not follow the colon separator by a space.

Any COMProperty or COMMethod that precedes the final Method-Name must return a COM object reference that provides access to the immediately following Method-Name. The final method call can return any supported COM data type.

COMParm

The following syntax describes how to specify a COMparm for a COM object method:
Syntax
{ [ OUTPUT | INPUT-OUTPUT ] expression [ AS Data-type ]
    [ BY-POINTER | BY-VARIANT-POINTER ]
  | null-parm
}
The expression can be any valid ABL expression or data element. Data-type is a supported COM data type that is compatible with the expression. A null-parm is any amount of white space. For information on COM data types and on OUTPUT, INPUT-OUTPUT, BY-POINTER, and BY-VARIANT-POINTER, see the “Data-type” section.

Note:

There is currently no support for named parameters, for example:
Method-Name(Color="GREEN", Shape="SQUARE") Data-type.

Data-type

The following syntax lists the supported COM data types for specifying any Data-type required for accessing a COM object property or method:
Syntax
SHORT | FLOAT | CURRENCY | UNSIGNED-BYTE | ERROR-CODE | IUNKNOWN
The requirements for using the OUTPUT, INPUT-OUTPUT, BY-VARIANT-POINTER, BY-POINTER, and AS Data-type options depend on the COM object method or property, the implementation of the COM object, and how you plan to use the parameter or property in your application. In many cases, expression is all that you require for a property write or method parameter. For more information on and examples of accessing COM object properties and methods, see the information on COM object references in the chapter on ActiveX Automation and in the chapter on control container support in OpenEdge Development: Programming Interfaces.