MicroStation and Application Development
MicroStation® is a computer-aided-design (CAD) tool produced by Bentley Systems. It is used by engineers, architects, and draughting technicians to create 3D models and 2D drawings.
MicroStation can be customised. Bentley Systems themselves have many applications for specialised markets that use MicroStation as a platform. Third-parties likewise may use MicroStation as a platform on which to develop their application software. Bentley Systems provide the MicroStation Software Development Kit (SDK) that software developers use to create their applications.
MicroStation has several development libraries …
- the MicroStationAPI is a C++ library
- the DgnPlatformNet and MstnPlatformNet are .NET libraries
- The C++ and .NET libraries, plus documentation and examples, are delivered with the MicroStation SDK
- Python
- Python is delivered with MicroStation
This article concerns the MicroStationAPI. The MicroStationAPI contains thousands of functions that provide a C++ interface.
This article provides a note about the various iterators available to examine or modify DGN data.
MicroStationAPI Enumerable Objects
A MicroStation DGN file is a container: it contains one or more DGN models. A DGN model is also a container: it contains DGN elements, reference attachments and other objects. Some DGN elements, such as a cell, are also containers: they contain nested elements and perhaps other data.
If we want to interrogate or modify a DGN file, DGN model or a complex DGN element we need some way of iterating that structure to enumerate each object that it contains. This article provides a brief overview of those enumerators.
Enumeration Patterns
We can enumerate each object in a conforming container using C++ 11's ranged-for syntax …
for (auto o: container) { /* do something with o */ }
That provides a concise replacement for the hand-written for loop you may have written in the 20th century …
for (int index = 0; index != some-value; ++index) { auto o = container [i]; }
However, the container must be iterable for the ranged-for to compile successfully. More precisely, it must provide the following methods and operators …
- A
begin()method - An
end()method - A pre-increment (
++) operator - A dereference (
*) operator
The standard containers, such as
std::vector<>,
meet those requirements.
For example, if you have a vector of 3D data points, you can iterate it like this …
VectorDPoint3D points { /* fill point array from somewhere */ };
for (DPoint3dCR point: points)
{
/* Do something with point */
}
For an explanation of VectorDPoint3D, see
MicroStationAPI Boost and the C++ Standard Library.
For an explanation of DPoint3dCR, see
MicroStationAPI Structures, Typedefs, and #include
.
Enumerable Classes in the MicroStationAPI
The MicroStationAPI and its ancestor MDL (the MicroStation Development Library) provide both legacy (i.e. C-style) enumeration functions and 21st century enumerable collections. Many C++ class methods fill a standard collection of objects (e.g. bvector<T>) which are simple to enumerate using legacy or ranged-for iteration.
The Bentley Vector (bvector<>) is a proprietary design based on
std::vector<>.
The MicroStationAPI documentation tells us:
This class is used in the Bentley APIs to avoid dependencies on compiler-supplied implementations of std::vector<>
that sometimes vary with compiler settings or compiler versions. The bvector<> class does not suffer from these problems.
This makes bvector<> suitable for use in Bentley public APIs.
In our own code, we can use the standard collection classes
std::vector<>,
std::deque<>,
std::map<> etc.
VirtualCollectionIterator class
The MicroStationAPI provides a template class
VirtualCollectionIterator<IteratorImplementation>.
You can inherit from that class to make your own class iterable if you don't want to reveal its internal structure.
If your IteratorImplementation class has the following public methods,
then you can use it in ranged-for and other loops …
- De-reference
operator* () const - Comparison
operator== (VirtualCollectionIterator const &rhs) const - Comparison
operator!= (VirtualCollectionIterator const &rhs) const -
IsNull () const - Pre-Increment
VirtualCollectionIterator& operator++ ()
For example, the ModelIndex class, mentioned below, inherits from VirtualCollectionIterator<IteratorImplementation>.
In the topics that follow, I'll show some MicroStationAPI collections and the MDL function family they replace.
| Object | Description | Example |
|---|---|---|
| ModelIndex | Each DGN file has a list of models, stored in the model index | ModelIndex Example |
| Loaded Models Collection | A list of DGN models that are currently loaded | Reachable Model Collection Example |
| Reachable ModelRef Collection | A list of references attached to a model | Reference Iteration Example |
| Enumerating Elements | Enumerate the elements in a DGN model | Element Iterators |
| Complex Element Iteration | Enumerate the nested elements in a complex header | ChildElemIter Example |
| Item Type Instance Iteration | Find instances of Item Types attached to a DGN element | EC Instance Iterator Example |
| Text Table Seeds | Seeking TextTables in DGNLibs | TextTable Enumerator Example |
Questions
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.
