PropertyPut and PropertySet

f90VB Modules

f90VBDefs, f90VBVariants, f90VBAutomation

Summary

Set the value of the specified object’s property. PropertySet is used only to set properties that receive values by reference.

Syntax

Arguments

VarObj [Input]

A variant containing a reference to the IDispatch interface of a running object.

PropRef [Input]

Can be either a character string with the name of the property or an integer containing the Dispatch ID (DispID) of the property.

PropertyValue [Input]

A Variant containing the new value for the property. Some properties accept values by reference (for example a reference to an object). In these cases, PropertySet and PropertyValue must be a variant with the VT_BYREF flag set in its vt field.

OptParmtr01..OptParmtr50 [Input, Optional]

Variant values containing any additional arguments to set the property. Up to fifty values can be passed.

EInfo [Output, Optional]

A variable of type EXCEPINFO, which will contain extended error information if an error occurs during the process of setting the property value.

IdxArgErr [Output, Optional]

If an error occurs due to an error in one of the arguments in OptParmtr01..OptParmtr50, this value contains the index of the offending parameter. See comments for additional information.

iRet [Output/Optional]

Upon return, iRet contains S_OK or an error code.

Comments

Subroutines PropertyGet and PropertySet are used to set the value of an object’s property. The content of the property is set to the value passed in argument PropertyValue, which can contain any variant type convertible to the type of the property (including a reference to the IDispatch interface of another object). If the variant passed in PropertyValue cannot be converted into the appropriate type for the property, subroutines PropertySet and PropertyPut return with an error condition.

PropertyGet and PropertyPut behave similarly, however, PropertySet can be used to set properties that expect values by reference. PropertyPut and PropertySet are respectively equivalent to the LET and SET statements in Visual Basic.

Argument PropRef

This is the argument used to identify the property. You can either pass the name of the property as a character string, or the property’s DispID, which is a number used by OLE to internally identify properties and methods exposed by an object.

The performance of subroutine PropertyPut (and PropertySet) is strongly affected by whether you use a character string with the property name or the DispID of the property. In the first case, subroutine PropertyPut must internally call IDispatch::GetIDsOfName, to search for the DispID corresponding to the requested property. On the other hand, when PropertyPut is called with a DispID this step is omitted, and so the subroutine performs much faster. This difference in performance can become particularly obvious when the PropertyPut is called many times for the same property. You can easily get the DispIDs of all methods and properties of an object in a single operation by calling f90VB subroutine EnumerateMembers.

When dealing with hierarchies of objects, argument PropRef can contain a path through the hierarchy, as long as the path does not need to use arguments. For example, in Excel, the object Chart, has a property called ChartTitle, which returns a ChartTitle object. The ChartTitle object has a property called Text, which contains the text of the title of a chart. You can use the following string in PropRef, to directly set the Text property of a chart’s title:

vMyText = VariantCreate(VT_BSTR, 'The title of this chart')

Call PropertyPut(vChart, 'ChartTitle.Text', vMyText)

Where vChart is a Variant containing a reference to an Excel Chart object and vMyText is the Variant variable where the new text for the chart title is be stored.

Argument OptParmtr01..OptParmtr50

Some properties, and in particular indexed properties, may need arguments. Use OptParmtr01 to OptParmtr50 to pass indexes for the property being set.

Note that f90VB cannot handle named arguments, so all the arguments passed to an object’s method or property are positional.

Argument EInfo

EInfo is a structured type used to describe IDispatch exceptions and errors. The EXCEPINFO type has the following definition:

type EXCEPINFO

     sequence

     integer(WORD_KIND)::wCode           

     integer(WORD_KIND)::wReserved 

     integer(BSTRHNDL_KIND)::bstrSource 

     integer(BSTRHNDL_KIND)::bstrDescription 

     integer(BSTRHNDL_KIND)::bstrHelpFile 

     integer(DWORD_KIND)::dwHelpContext 

     integer(POINTER_KIND)::pvReserved 

     integer(POINTER_KIND)::pfnDeferredFillIn 

     integer(LONG_KIND)::scode

end type EXCEPINFO

When this argument is passed and the invoked member produces an error, EInfo is filled with more descriptive error information. See Table 6.2 of the User Manual for more information about the content of the structure.

Argument IdxArgErr

If an error condition results as a consequence of an erroneous or incompatible value passed in OptParmtr01 to OptParmtr50, PropertyPut returns the index of the offending argument in IdxArgErr. Note, however, that this index identifies the argument from right to left, i.e. an IdxArgErr value of 1 refers to the last OptParmtrXX used in the call to PropertyPut, rather than OptParmtr01.

Examples

See examples in Chapter 6 – User Manual

Related Topics

Release