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 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.
Sometimes you – the programmer – want to show temporary graphics that provide a hint or cue to the user of your application. The hint may take the form of a small image — a sprite — that appears attached to the user's cursor during some phase of your command. Here are some sprites drawn with 24x24 pixels …
Developers who write applications for MicroStation choose one of several APIs …
This article is for developers who use the C++ MicroStationAPI. That API lets a user create DGN elements through their application just as they would using MicroStation's built-in tools.
There are times when a developer would like to show a user temporary graphics. For example, during a custom command you may want to provide a visual cue to your user. The cue, a small graphic also known as a sprite, tells the user that your app. is aware of the current drawing context. As the drawing context changes, you may want to show the user a different sprite.
An application designer may choose to use some or all the above techniques when specifying how a MicroStation application should work.
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.A sprite should be small with a limited colour palette, so it's easy to draw. It should be easy to draw because it will be erased and redrawn each time the user moves the input device (e.g. mouse) by more than one pixel.
You can design your own sprites or download *.ico
files from the Internet.
We wrote this solution in response to a question posed on the Be Community Forums. MicroStation lets programmers create sprites in one or more views.
Q How do I draw sprites in a MicroStation view?
A The MicroStationAPI for MicroStation CONNECT provides the ability to draw sprites to a view.
The steps to use a sprite in your application are …
*.ico
file in your project development folder
*.rc
file
resource.h
file
The steps to display a sprite are …
IViewDecoration
_DrawDecoration ()
method
The purpose of the ViewDecoration project is to illustrate the use of the MicroStationAPI and
its IViewDecoration
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 IViewDecoration
.
Subsequently, MicroStation calls your object when certain events happen.
Your code receives an IndexedViewport*
that you can use to react to different events
and draw a sprite in one or more views.
Load the demonstration app. using MicroStation key-in
mdl load ViewSprites
Once loaded, the following commands become available …
VIEWSPRITES SPRITE ADD | Attaches a sprite to your cursor in a MicroStation view |
VIEWSPRITES SPRITE DELETE | Removes the sprite from your cursor |
VIEWSPRITES EXIT | Unloads the ViewSprites app. |
The VIEWSPRITES SPRITE ADD
command accepts a numeric argument.
That argument, for developers only, is the Icon ID of one of your sprites.
Those IDs are defined in header resource.h
.
The consequence is that you can change your sprite's appearance dynamically by invoking that command …
VIEWSPRITES SPRITE ADD 107
Where 107
is a valid Icon ID.
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: ViewSprites.ma
and ViewSprites.dll
.
File ViewSprites.ma
contains only resource data: in this case, the information MicroStation requires to load the DLL,
and a command table. ViewSprites.dll
is the implementation file.
ViewSprites.dll
also stores the sprite images, which are in Windows icon (*.ico
) format.
When a user types mdl load ViewSprites.
MicroStation first loads ViewSprites.ma
and finds the resource directive (the DllMdlApp
in ViewSprites.r
) that instructs it to load a DLL,
then it loads ViewSprites.dll
.
Download the ViewDecoration 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.
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.