Description
Link or unlink a feature with an McGraphObj instance.
-
Return Type
-
A Boolean value.
| Value |
Meaning |
VARIANT_BOOL
|
TRUE if the link is made.
|
-
Syntax
-
object.LinkFeatureToGraphObj (lFeatureIndex, pimcgraphobjToLink)
The LinkFeatureToGraphObj Method syntax has these parts: |
| object | An expression evaluating to an object of type McDisplayOverlays. | | lFeatureIndex | Required. A Long value. If non-negative, then it is the index of an existing feature to be linked (if the pimcgraphobjToLink argument is non-NULL).
If lFeatureIndex is -1, then the given pimcgraphobjToLink is to be used to append a new feature if it is is of an appropriate class and has a TemplateID equal to the AutoDisplayTemplateID property. That is, this performs the same action that would be performed when a graph object is created by the user with a graphic tool (see McGraphOverlay.SelectTool). A linked feature is created and appended only if the pimcgraphobjToLink is of a class that matches a feature type (e.g., it is an McObjGraphLine and this is an McLines type of McFeatures). The pimcgraphobjToLink must also have a TemplateID property that is equal to our current AutoDisplayTemplateID property.
If lFeatureIndex is -2, then the given pimcgraphobjToLink instance is to be unlinked rather than linked.
| | pimcgraphobjToLink | Required. An Unknown object. If NULL, then all McGraphObj instances to which the lFeatureIndex'ed feature is linked are unlinked. If non-NULL, then this must be an instance of an McGraphObj-derived interface compatible with the lFeatureIndex'ed feature's type. The required McGraphObj ClassName property is given by the ClassNameForFeature method. If the McGraphObj's parent McGraphOverlay instance is not already a member of our McDisplayOverlays collection, it is Added automatically.
|
Remarks
This method may be used to link a particular feature with an McGraphObj-derived instance for display. It may also be used to break the link between a given McGraphObj instance and whatever feature it is currently linked to, or to break the link between a given feature and all McGraphObj instances to which it is linked.
This method rarely needs to be called, since feature display linking and unlinking is usually handled automatically by assigning a Template ID value to the AutoDisplayTemplateID property.
The link will remain as long as the feature is not changed in such a way that its type changes or it needs to be completely recreated (see Example).
When a link to a given pimcgraphobjToLink is explicitly broken (by passing in a negative lFeatureIndex), then the unlinked McGraphObj instance not Removed from its McGraphOverlay. If the link is broken any other way (by removing the linked feature, by passing a NULL pimcgraphobjToLink argument to explicitly unlinking all links to a linked feature, or by changing the type of the linked feature), then the Remove method is called on the unlinked McGraphObj (this will destroy the object unless someone is still holding a reference on it).
Exceptions
If lFeatureIndex is non-negative, it must reference an existing feature. If linking, the pimcgraphobjToLink must be an instance of an McGraphObj class that is compatible with the lFeatureIndex'ed feature. Also if linking, pimcgraphobjToLink must not already be linked to another feature; if you need to switch a link on pimcgraphobjToLink from one feature to another, you must explicitly break the existing link (this will rarely ever need to be done).
If you are adding a feature from a source graph object (lFeatureIndex argument is -1), it is not an error to have the addition fail. Check the return value for TRUE to see if the addition succeeded. The new feature index will always be equal to the McFeatures.Count property minus one.
Notes
The link will remain as long as the feature is not changed in such a way that its type changes or it needs to be completely recreated (see Example).
When a link to a given pimcgraphobjToLink is explicitly broken (by passing in a negative lFeatureIndex), then the unlinked McGraphObj instance not Removed from its McGraphOverlay. If the link is broken any other way (by removing the linked feature, by passing a NULL pimcgraphobjToLink argument to explicitly unlinking all links to a linked feature, or by changing the type of the linked feature), then the Remove method is called on the unlinked McGraphObj (this will destroy the object unless someone is still holding a reference on it).
|
LinkFeatureToGraphObj Method
