PropertyGet

f90VB Modules

f90VBDefs, f90VBVariants, f90VBAutomation

Summary

Gets the value of the specified object’s property.

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 requested property or an integer containing the Dispatch ID (DispID) of the requested property.

OptParmtr01..OptParmtr50 [Input, Optional]

Variant values containing any arguments necessary to retrieve the requested 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 retrieving 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

Function PropertyGet is used to retrieve the value of an object’s property. The content of the property is returned by the function as a variant, which can contain any valid variant type (including a reference to the IDispatch interface of another object).

Argument PropRef

This is the argument used to identify the requested 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 function PropertyGet is strongly affected by whether you use a character string with the property name or the DispID of the property. In the first case, function PropertyGet must internally call IDispatch::GetIDsOfName, to search for the DispID corresponding to the requested property. On the other hand, when PropertyGet is called with a DispID this step is omitted, and so the function performs much faster. This difference in performance can become particularly obvious when the PropertyGet 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 refer to the Text property of a chart’s title:

vText = PropertyGet(vChart, 'ChartTitle.Text')

Where vChart is a Variant containing a reference to an Excel Chart object and vText is the Variant variable where the text of the chart title will be stored.

Argument OptParmtr01..OptParmtr50

Some properties, and in particular indexed properties, may need arguments. Collections of objects are the most common example of indexed properties. To retrieve a particular element of the collection, you must pass its index (or key) as an argument. For example, if you have a Variant containing a collection of Workbooks, you can retrieve the second item of the collection using the following statement:

vThisWorkbook = PropertyGet(vWorkbooks, 'item', VariantCreate(VT_INT,2))

Note that the index (the value two in this case) is passed as an argument (after it has been converted into a Variant).

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, PropertyGet 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 PropertyGet, rather than the first.

Examples

See examples in Chapter 6 – User Manual

Related Topics

PropertyPut and PropertySet