As a convenience to the IDL programmer, COM object methods that have been defined using the propget and propput attributes are accessible via the IDLcomIDispatch object’s GetProperty and SetProperty methods. This means that rather than calling the COM object’s methods directly to get and set property values, you use the standard IDL syntax.
Note: If a COM object method’s interface definition includes either the propget or the propput attribute, you must use the IDL GetProperty and SetProperty methods to get and set values. IDL does not allow you to call these methods directly.
As with all IDL objects, the IDLcomIDispatch object’s GetProperty and SetProperty methods use procedure syntax. Keywords to the methods represent the names of the properties being retrieved or set, and the keyword values represent either an IDL variable into which the property value is placed or an IDL expression that is the value to which the property is set. You must use the procedure syntax when calling either method, even if the underlying COM object methods being used are functions rather than procedures.
Setting Properties
To set a property value on a COM object, use the following syntax:
ObjRef->SetProperty, KEYWORD=Expression
where ObjRef is the IDLcomIDispatch object that encapsulates the COM object, KEYWORD is the COM object property name, and Expression is an IDL expression representing the property value to be set.
If the underlying COM object’s propput method requires additional arguments, the arguments are supplied in the setProperty method call, using the following syntax:
ObjRef->SetProperty [, arg0, arg1, ... argn], KEYWORD=Expression
Note: KEYWORD must map exactly to the full name of the underlying COM object’s property setting method. The partial keyword name functionality provided by IDL is not valid with IDLcomIDispatch objects.
You can set multiple property values in a single statement by supplying multiple KEYWORD=Expression pairs.
IDL lets you to set multiple properties at once in the same SetProperty call. For example:
ObjRef->SetProperty, OPTION=1, INDEX=99L
This command is equivalent to the following lines:
ObjRef->SetProperty, OPTION=1
ObjRef->SetProperty, INDEX=99L
If you pass parameters when setting multiple properties, the parameter or parameters are sent to each property being set. For example:
ObjRef->SetProperty, 'Parm1', 24L, oRef, OPTION=1, INDEX=99L
This command is equivalent to the following lines:
ObjRef->SetProperty, 'Parm1', 24L, oRef, OPTION=1
ObjRef->SetProperty, 'Parm1', 24L, oRef, INDEX=99L
Thus, when you are setting multiple properties at the same time and passing parameters, all the properties that are set at the same time must be defined as receiving the same sets of parameters.
Getting Properties
To retrieve a property value from a COM object, use the following syntax:
ObjRef->GetProperty, KEYWORD=Variable
where ObjRef is the IDLcomIDispatch object that encapsulates the COM object, KEYWORD is the COM object property name, and Variable is the name of an IDL variable that will contain the retrieved property value.
Note: KEYWORD must map exactly to the full name of the underlying COM object’s property getting method. The partial keyword name functionality provided by IDL is not valid with IDLcomIDispatch objects.
You can get multiple property values in a single statement by supplying multiple KEYWORD=Variable pairs.
Because some of the underlying COM object’s propget methods may require arguments, the IDLcomIDispatch object’s GetProperty method will accept optional arguments. To retrieve a property using a method that takes arguments, use the following syntax:
ObjRef->GetProperty [, arg0, arg1, ... argn], KEYWORD=Variable
Note, however, that if arguments are required, you can only specify one property to retrieve.