Current Revision posted to Bentley Map | OpenCities Map Wiki by Inga Morozoff on 4/8/2019 2:16:35 PM
In this article, we will explain some basic concepts of the XFM API. You need to have an understanding of programming with XFM before you will find it useful. All code references are in MicroStation VBA but you can easily find the equivalents in MDL.
The feature object is at the center of the XFM API. We will focus on this object and some of its properties. A feature has a name, can be included in a group, and can have an alias. We will describe how names, groups and aliases are useful to manipulate a feature in the XFM API. Using the key-in mdl command showfeatureinfo, you can inspect the name and the alias of a feature.
For the users of our application, a feature has a geometry and properties, but for the developers, mastering the supplemental information in a feature definition like its name, group and alias can help you build better applications.
The Feature Name
Each XFM feature in a DGN file has a name. This is mandatory as the name allows linking this object to its description in the active schema. The feature name is case-sensitive and must exactly match the feature definition name of the schema. For example, when you create a feature with the following code:
Dim oFeature As New xft.feature
or:
Set oFeature = xft.FeatureMgr.CreateFeature (MicrostationElement)
You have to associate a name to this feature with something like the following:
oFeature.Name = "Lake"
The active schema will be used to associate all the characteristics of the lake feature to this new object. You can also use the feature name to inform a LocateOp object that you only need to locate a particular feature type:
oLocateOp.IncludeFeatureName "Lake"
The feature name can also be useful to identify a feature the user selects in your application.
In addition, you can use oLocateOp.GetLocatedFeatures to get an enumerator of located features. For each feature in the enumerator, you can get its feature name.
The Feature Group
You can set the feature group using its group property:
oFeature.Group = "Placement"
Once the feature group is set, a reference to this feature is added to the global feature list. A feature is commonly added to the global feature list for XFM placement and manipulation operations, and for access to this feature by the XFM Dialog Manager.
Since feature object instances are counted reference by reference, the feature instance will not be deleted until the reference count goes to zero.
Note: The global feature list is always cleared at the start of an XFM command.
If an XFM command must work with multiple features during many operations, it is convenient to use the global feature list to hold the feature instance references. By using different group names, a programmer can store different instances for different purposes. For example, a placement operation has to locate existing features with different names, so you store them in a group named "locate". A feature placement operation has to use the located features as start and end points of a new linear feature which will be stored in the "placement" group. When the placement operation is complete, the application can write all features in the "placement" group.
Note: A feature group is not the same as a method group. A method group is a set of methods associated to a feature definition using the Geospatial Administrator in the Methods section of the workspace definition. As an example, you can use the Command Manager method "MethodExists" to check if a method exists in the XFM Methods Cache using the method group. You can also start a specific method using its name and its group with the method ActivateMethod of the Command Manager.
The Feature Alias
If you do not set an alias for a feature, the XFM API will use the feature name in place of the alias for all the methods using an alias. The alias can be useful to distinguish two features with the same name. For example, look in the code for the placement of a two gas valves on a gas main in the Developer Guide and in the examples provided with Bentley Map. You need to get two gas valves, but you also need to distinguish the first valve from the second one selected. We could use the UUID of the selected features, but it is better to use the alias method. First, set the locate operator object to retrieve gas valve features using the feature name:
oLocateOp.IncludeFeatureName "GasValve"
When the first gas valve is retrieved, set its alias to "gasvalve1" in the clsGasValve1Events class. oCurrentFeature.Alias = "gasvalve1"
When the second gas valve is retrieved, set its alias to "gasvalve2" in the clsGasValve2Events class.
oCurrentFeature.Alias = "gasvalve2"
This procedure allows distinguishing the first gas valve from the second one.
The methods RemoveFromTheFeatureList and LoadFeatureFromList of the Feature Manager (FeatureMgr) can use the feature alias to manage a feature from the global feature list in the feature manager. Here are some examples:
FeatureMgr.RemoveFromFeatureList "", "gasvalve1"
FeatureMgr.LoadFeatureFromList "", "gasvalve2"
Note: As seen in the previous description of the group name, you must first set the group name of a feature in order to add a reference to the feature in the feature list.
Storing and retrieving Names, Aliases and Groups with the Command Manager
The Command Manager can use the SetProperty method to store the name, alias and group values:
xft.CmdMgr.SetProperty "placementFeature", "GasMain"
xft.CmdMgr.SetProperty "placementAlias", "GasMain"
xft.CmdMgr.SetProperty "placementGroup", "placement"
You can retrieve these values anywhere in your application. You do not have to use global variables to keep information between the call of your multiple events handlers, so your code will be cleaner.
oCurrentFeature.Feature = xft.CmdMgr.GetProperty("placementFeature ")
oCurrentFeature.Alias = xft.CmdMgr.GetProperty("placementAlias")
oCurrentFeature.Group = xft.CmdMgr.GetProperty("placementGroup")
Conclusion
In this article, we explained the concepts of feature names, groups and aliases:
- A feature always has a case-sensitive name.
- You can group different features with different names in a feature group for a common process.
- You can differentiate many occurrences of a feature named with the same feature name using their aliases.
We recommend that you look at the examples delivered with MicroStation GeoGraphics and follow the code to ensure that these notions are used consistently.
Any comments or questions regarding this article should be directed to jeff.bielefeld@bentley.com.
Tags: XFM, API, BDNzine
