Introduction

The MicroStation Development Library (MDL) and MicroStationAPI provide APIs for developers wanting to create custom applications for MicroStation^® from Bentley Systems. We create a MicroStation application as a DLL, written using C++ and built with the Microsoft C++ compiler and linker provided with Visual Studio.

When editing your source code, you can choose whether to use Microsoft Visual Studio, Microsoft Visual Studio Code, or one of your favourite text editors.

When building your app, you can use Visual Studio or the Bentley Systems make (bmake) tools.

Iterating Elements in a DGN Model

Enumerating Elements

A MicroStation DGN model's primary purpose is to be a container of graphic elements. A user creates and manipulates elements in one of eight views of a DGN model. As developers, we often want to enumerate the elements in, say, a view or a fence; or find all the elements on a certain level; or those elements that satisfy certain spatial constraints.

In the topics that follow, I'll show some MicroStationAPI collections and the MDL function family each replaces.

Object	Description	Example
ReachableElementCollection	Get an iterable collection of elements reachable from a modelRef	ReachableElementCollection Example
PersistentElementRefList	Get an iterable collection of elements from a DgnModel	PersistentElementRefList Example
Element Count	Get number of elements from a DgnModel	Element Count Example

Element Count Example

A DgnModel knows how many elements it contains. There are several DgnModelSections to choose from; you will usually want to retrieve GraphicElements.

#include <DgnPlatform/DgnModel.h>

DgnModelP  model     = ISessionMgr::GetActiveDgnModelP ();
UInt32     nElements = model->GetElementCount (DgnModelSections::GraphicElements);

PersistentElementRefList Example

Use DgnModel.GetGraphicElementsP() to obtain a PersistentElementRefList. Iterate the list to obtain an ElementRefP for each element in the model.

#include <DgnPlatform/DgnModel.h>
#include <Mstn/ISessionMgr.h>

DgnModelP  model = ISessionMgr::GetActiveDgnModelP ();
if (nullptr != model->GetGraphicElementsP ())
{
  for (PersistentElementRefP const& elemRef: *model.GetGraphicElementsP ())
  {
    //  do something with PersistentElementRefP
  }
}

ReachableElementCollection Example

Use DgnModelRef.GetReachableElements() to obtain a ReachableElementCollection. Alternatively, construct a ReachableElementCollection passing a DgnModelRef. Only const iteration is possible.

#include <DgnPlatform/DgnModelRef.h>
#include <Mstn/ISessionMgr.h>

DgnModelRefP                modelRef = ISessionMgr::GetActiveDgnModelRefP ();
ReachableElementOptionsPtr  options  = ReachableElementOptions::CreateOptions ();
//  We're interested only in graphic elements
options->ExcludeControlSection ();
ReachableElementCollection  elements = modelRef->GetReachableElements (options.get ());
for (ElementHandleCR eh: elements)
{
  // do something with ElementHandle
}

Legacy Element Iteration using MDL

The 20^th century way to iterate over a DGN model's elements was the scanner. Scanning technology evolved over several decades from its original implementation as hardware bolted on to a mini computer.

The mdlScan_api provides detailed access to a DGN model. It lets you harvest elements using criteria specified in bit masks and C structs. It dates from the earliest implementation of MDL in about 1990. It was superseded by the mdlScanCriteria_api with the introduction of MicroStation V8.

The mdlScanCriteria_api is a development of the mdlScan_api. It wraps some of the bit-twiddling into function calls and generally simplifies the task of scanning a DGN model. It remains a rather tedious way of harvesting DGN elements. However, it offers some benefits over the MicroStationAPI classes. For example …

• You can specify a spatial filter (a scan range) to restrict elements to those that satisfy certain geometric requirements
• You can retrieve only those elements in a specified Graphic Group (GG)

#include <Mstn/ISessionMgr.h>

DgnModelRefP   modelRef = ISessionMgr::GetActiveDgnModelRefP ();
ScanCriteria   criteria = mdlScanCriteria_create ();
mdlScanCriteria_setModel (criteria, modelRef);
mdlScanCriteria_setElmDscrCallback (criteria, callback-function, callback-args);
//  Execute a scan, calling your callback function for each DGN element
mdlScanCriteria_scan (criteria, nullptr, nullptr, nullptr);
mdlScanCriteria_free (criteria);

Spatial Filter

You can include a spatial test for those elements that lie within a geometric area, known as a scan range. Every graphic DGN element has a range, given in 64-bit 3D integer coordinates. See the ScanRange struct definition in MicroStationAPI help. Use function mdlScanCriteria_setRangeTest() to include a range test in your scan code. Use function mdlScanCriteria_setExtendedRangeTest() to test several ranges.

Graphic Group Filter

You can include a test for a specified Graphic Group (GG). Use mdlScanCriteria_setGraphicGroupTest() to adjust your scan criteria to accept only the DGN elements that are in the GG. Thanks to YongAn Fu, an enthusiastic member of the Bentley Developer Network support team, for suggesting that idea.

Back to the Iterator main page.

Questions

Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.