ArcGIS Engine Developer Guide

DEVELOPING WITH A RCOBJECTS
Dim pEnv As IEnvelope
Set pEnv = New Envelope
pPolygon.QueryEnvelope pEnv
How do you know when to create and when not to create? In general, all methods
that begin with “Query”, such as QueryEnvelope, expect you to create the
object. If the method name is GetEnvelope, then an object will be created for you.
The reason for this client-side storage is performance. When it is anticipated that
the method on an object will be called in a tight loop, the parameters need only
be created once and simply populated. This is faster than creating new objects
inside the method each time.
Property by value and by reference
Occasionally, you will see a property that can be set by value or by reference,
meaning that it has both a put_XXX and a putref_XXX method. On first appearance,
this may seem odd—Why does a property need to support both? A Visual
C++ developer sees this as simply giving the client the opportunity to pass ownership
of a resource over to the server (using the putref_XXX method). A Visual
Basic developer will see this as quite different; indeed, it is likely because of the
Visual Basic developer that both By Reference and By Value are supported on the
property.
To illustrate this, assume there are two text boxes on a form, Text1 and Text2.
With a propput, it is possible to do the following in Visual Basic:
DISPIDs are unique IDs given to properties and
methods for the IDispatch interface to efficiently
call the appropriate method using the
Invoke method.
Notice the use of the “Set”.
Text1.text = Text2.text
It is also possible to write this:
Text1.text = Text2
or this:
Text1 = Text2
All these cases make use of the propput method to assign the text string of text
box Text2 to the text string of text box Text1. The second and third cases work
because no specific property is stated, so Visual Basic looks for the property with
a DISPID of 0.
This all makes sense assuming that it is the text string property of the text box
that is manipulated. What happens if the actual object referenced by the variable
Text2 is to be assigned to the variable Text1? If there were only a propput method,
it would not be possible; hence, the need for a propputref method. With the
propputref method, the following code will achieve the setting of the object
reference:
Set Text1 = Text2
Initializing Outbound interfaces
When initializing an Outbound interface, it is important to only initialize the
variable if the variable does not already listen to events from the server object.
Failure to follow this rule will result in an infinite loop.
Chapter 4 • Developer environments • 73