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.
MicroStation Temporary Objects
MicroStation is a 3D CAD tool. Users draw 3D or 2D objects in one of eight views. Drawn objects are termed elements. A graphic element represents something that a user can draw, such as a line, arc, rectangle or cone. Elements are persisted to a DGN file: when a user has drawn an object, she can be confident that after finishing a MicroStation session she can subsequently reopen that DGN file to see the previously-drawn elements.
Developers who write applications for MicroStation one of several APIs …
- MicroStation VBA
- .NET DgnPlatformNet and MstnPlatformNet
- MicroStationAPI
There are times when a developer would like to show a user temporary graphics. For example, during a custom command while constructing a complex object, or an object that relies on adjacent geometry. It is useful to see construction lines that provide clues. Once the command is finished, the temporary graphics vanish: that is, they are never committed to file. Often, the temporary graphics are snappable, meaning that a user can snap a point, such as the beginning of a real line, to the temporary graphics.
Persistent and Non-Persistence Graphic Objects in a MicroStation Session
- View Decoration
- Sprites provide feedback to the user. Each Sprite — a small image — is designed to provide some meaning in the context of the current command state. Sprites are likely to move, change or disappear frame-by-frame as a command progresses. Sprites vanish once the command is complete and are never written to a DGN model
- Transient Elements
- Transients are temporary DGN elements. They are created in just the same way as normal DGN elements but are stored in a non-persistent cache and are never saved to a DGN file. A transient element survives as long as the programmer wants it to survive, or until the DGN model is closed, whichever is the sooner
- Rubber-Banding
- MicroStation draws DGN elements during a command. Rubber-banding provides visual feedback to the user as the command progresses. The elements are recalculated and redrawn frame-by-frame as the command state changes. Usually, once a command is complete, the rubber-banded element is added to a DGN model and becomes permanent
An application designer may choose to use some or all the above techniques when specifying how a MicroStation application should work.
- Sprites are commonplace: you see them frequently when you use MicroStation. For example, the handles on a Selection Set are Sprites
- Rubber-Banding is common in element creation and modification tools
- Transient Elements may be used in complex tools to show some intermediate stage or to show constructions. They may be used for other purposes: for example to show kinematics
Bentley staffer Brien Bastings provided this tip:
A view decorator is good for things that may be changing every frame/cursor motion, an IViewTransient is good for things that don't change often.Transient Elements and Transient Geometry
In MicroStation terminology, such temporary graphics are called transient. Using the MicroStationAPI in MicroStation CONNECT, you can create both transient elements and transient geometry.
The difference between transient elements and transient geometry is that a programmer can convert a normal element to a transient, whereas transient geometry is anything that you can define geometrically. Using the MicroStationAPI to draw transient geometry also gives you finer control over what is drawn during a number of view update events, and whether the geometry is snappable or not.
Transient Objects from the Developer's Perspective
We wrote this solution in response to a question posed on the Be Community Forums. MicroStation lets programmers create transient geometry in one or more views. Transient geometry and transient elements are never written to file. They may be useful in providing a view of constructions for various reasons — for example, to show a user how a possible contruction may appear before committing it to a model permanentley.
Q How do I draw transient geometry in a MicroStation view?
A A simple question, which turns out to have a complex answer. The MicroStationAPI for MicroStation CONNECT provides the ability to draw pure geometry to a view, as well as the ability to create transient DGN elements.
Terminology
Let's clarify some terminology. We need to distinguish between persistent and transient elements, between MicroStation elements and pure geometry, and between dynamic and other graphic display events.
- Persistent Elements
- When you create a MicroStation element, that element is added to a model and ultimately persisted to a file. When you reopen the file, the element is available for viewing and manipulation. MicroStation takes care of drawing persistent elements for you. If you have created a persistent element, then there's no need to use IViewTransients.
- Temporary Graphics
- When you create a MicroStation element, that element is added to a model and ultimately persisted to a file. When you reopen the file, the element is available for viewing and manipulation. MicroStation takes care of drawing persistent elements for you. If you have created a persistent element, then there's no need to use IViewTransients.
With MicroStation CONNECT you can create transient geometry, as opposed to transient elements.
If they are not persistent elements, MicroStation doesn't know about them,
and you are responsible for drawing them.
The IViewTransients interface provides us with numerous events when we can draw stuff.
During a dynamic update, the user is moving the cursor and, yes, your function will be called again and again to create
and draw your geometry (geometry, not elements) based on the current cursor position.
Because your geometry is drawn repeatedly, the callback provides an opportunity for you to stop drawing (CheckStop)
during one of those events.
From the user perspective, this lets your application be responsive rather than slowing everying down
because it insists on drawing everything even when there is no need.
If your geometry is static, and does not need to be recalculated relative to the current cursor position, then drawing it repeatedly during dynamics may be unnecessary.
Transient Elements
Transient elements are not persistent (they are never written to file). However, they are created from a MicroStation element and stored in the transient cache. MicroStation knows about the transient cache and draws its contents for you.
MicroStationAPI: View Transients Project
The purpose of the ViewTransients project is to illustrate the use of the MicroStationAPI and
its IViewTransients interface.
It requires C++, as does any project that uses the MicroStationAPI.
You register at run-time an instance of a class that inherits from IViewTransients.
Subsequently, MicroStation calls your object when certain events happen.
Your code receives an IViewContext* that you can use to react to different events
and draw geometry in one or more views.
By reacting differently to different events, you can simply draw geometry in a view, or make it snappable for pick user operations. For example, you can make a transient line snappable so that a user can snap to a keypoint on the transient while creating genuine MicroStation elements.
Because you draw pure geometry, you don't need to create elements, and you don't have to use the mdlTransient_API.
Building ViewTransients
We assume that you are using the MicroStation development environment to build this project. Consult the MicroStation Software Development Kit (SDK) help for more information, or take a look at our guide to setting up Windows to build MicroStation applications.
As this is a C++ project, you'll need Visual Studio installed. The project builds from a Bentley make (bmake) file, so the purpose of Visual Studio is to provide a compiler and linker rather than an IDE.
As with any application built for native code, the result is in two parts: ViewTransients.ma and ViewTransients.dll.
File ViewTransients.ma contains only resource data: in this case, the information MicroStation requires to load the DLL,
and a command table. ViewTransients.dll is the implementation file.
When a user types mdl load ViewTransients. MicroStation first loads ViewTransients.ma
and finds the resource directive (the DllMdlApp in ViewTransients.r) that instructs it to load a DLL,
then it loads ViewTransients.dll.
Download the ViewTransients Project
Download the ViewTransients project.
This ZIP file contains C++ source code header and implementation files, and a bmake (.mke) file to build the project.
You need
Visual Studio 2015 to be installed in order to compile this project
for MicroStation CONNECT.
Questions
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.
Contact LA Solutions using this
