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.

View Classes

This article provides an overview of several viewing classes. It attempts to disentangle the somewhat opaque documentation provided with the MicroStationAPI and the DgnPlatformNet help files.

MicroStation User Views

The MicroStationAPI user sees eight views that she can turn on or off and modify in other ways. Different views show different parts of a DGN model. Two views may show different DGN models, although that is not apparent to a user. The physical contents of a view may be modified to show, for example, a different perspective of the DGN model. The symbolic contents of a view may be modified to show, for example, those elements on a certain set of MicroStation levels.

Object-Orientated View Classes

A DGN file owns a ViewGroupCollection. Note that it's the DGN file, not any particular DGN model, that owns the collection.

The ViewGroupCollection is a collection of ViewGroup objects.

Each ViewGroup controls the views of a DGN root model. For each view, the ViewGroup has a ViewInfo class and a ViewPortInfo class. It is through those that a ViewGroup provides information about the contents, positioning and ordering of each view.

The collection is elastic: a user may create multiple view groups, and you can create multiple ViewGroups programmatically.

A viewport maps a model (the root model of the Viewport) and all of its references to an output device through a camera (a view frustum) and filters (e.g. levels, view flags, etc).

The ViewInfo class holds information needed to display the contents of a view. ViewInfo contains information about the portion of the model that is visible in the view, the level masks that determine the per-view on/off state of every level, the background color, the auxiliary coordinate system; and the dynamic view settings for the view. Programmers generally obtain ViewInfo instances from ViewGroups or NamedViews. It is rare that an application needs to create an instance of ViewInfo.

View Class Idioms

ViewGroupCollection class

A DGN file stores a ViewGroupCollection, so we obtain that collection from the DGN file …

ViewGroupCollectionCR   viewGroupCollection = dgnFile->GetViewGroups();
for each (ViewGroupPtr viewGroup in viewGroupCollection)
{
  // do something with the viewGroup here
}

ViewGroup class

Each ViewGroup contains information about eight numbered views, any of which can be turned off by the user. There is a ViewInfo and a ViewPortInfo associated with each numbered view, and these contain all of the information necessary to position and size a window to hold each view, and to determine what subset of DgnFile information that the user has chosen to display. Each ViewInfo contains a Root Model, which is always one of the DgnModels that are contained within the DgnFile that contains the ViewGroup. Different Views can display different Root Models.

You can enumerate the ViewGroups of a ViewGroupCollection like this …

ViewGroupCollectionCR   viewGroupCollection = dgnFile->GetViewGroups();
for each (ViewGroupPtr viewGroup in viewGroupCollection)
{
  // do something with the viewGroup here
}

Alternatively, obtain a specific ViewGroup using viewGroupCollection.GetActive() or a similar method.

ViewGeomInfo class

ViewGeomInfo contains the description of the portion of the model that is visible within a view. The members of the structure are public, but whenever possible the methods provided should be used to manipulate their values.

ViewInfo class

Use GetViewInfo() to obtain view information from a ViewGroup. Programmers generally obtain ViewInfo instances from ViewGroups or NamedViews. It is rare that an application needs to create an instance of ViewInfo.

ViewPortInfo class

A ViewPort is a control structure for fitting views. A ViewPort maps a DGN model (the root model of the ViewPort) and all of its references to an output device through a camera (a view frustum) and filters (e.g. levels, view flags etc).

Use ViewPortInfo() to obtain ViewPort information from a ViewGroup.

Questions

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