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.
The SDK has two libraries: the MicroStation Development Library (MDL) and the MicroStationAPI. The MicroStation Development Library contains thousands of functions that provide a C-language interface. The MicroStationAPI provides an object-oriented C++ interface.
While MDL has been available since 1993, the MicroStationAPI is relatively recent and ill-understood by developers. This article attempts to clarify and explain the MicroStationAPI from a developer's viewpoint. In particular, it provides a set of commented source files that will build to a working example. The entire source code for the project is available to download.
Create Element Tool
The MicroStationAPI provides classes from which we derive our own specialist classes.
In this example we inherit from Bentley::Ustn::MstnTool (subsequently we drop the namespace,
and refer to simply MstnTool).
The example code has the following classes that inherit from MstnTool …
| Class | Purpose |
|---|---|
CirclePlacementTool | Creates an ellipse element having equal axes |
LinePlacementTool | Creates a type 3 line element |
TextPlacementTool | Creates a text element |
The Create Element Tool classes borrow heavily from the toolExample delivered with the MicroStation V8i SDK. We have added extra code that demonstrates more features of the MicroStationAPI, and removed some irrelevant code that had leaked in from another Bentley example.
Create Element Tool Commands
Load the Create Element Tool using the MicroStation keyin …
mdl load CreateExample
Once loaded, the following commands become available …
| Command | Purpose |
|---|---|
CREATEEXAMPLE PLACE CIRCLE | Creates an ellipse element having equal axes |
CREATEEXAMPLE PLACE LINE | Creates a type 3 line element |
CREATEEXAMPLE PLACE TEXT [text] | Creates a text element |
CREATEEXAMPLE EXIT | Unloads the application |
Create Element Tool Example Features
The Create Element Tool example provides several tools.
The main entry point (MdlMain in CreateTool.cpp) does the usual
things required to initialise a MicroStation add-in …
- Load resources (command table, message lists, etc)
- Register commands
- Register command and prompt message lists
- Set the application version number
When each command is instantiated, its command message ID and prompt message ID are passed to the constructor,
which passes them on to the base class MstnTool.
This ensures that the user sees (i) your prompts when a command is started
(e.g. Place Line>Enter datapoint)
and
(ii) the command name in MicroStation's menu Edit|Undo and Edit|Redo.
The PLACE CIRCLE & PLACE TEXT tools accept a single datapoint,
which is the origin of the element being created.
Because they need only one datapoint, they start dynamics immediately,
so the element about to be created is attached to the cursor.
The PLACE TEXT tool accepts a text string when
you start the command. The unparsed string received by the command is
passed to the class string variable.
For example …
CREATEEXAMPLE PLACE TEXT Be Community
The PLACE TEXT tool also demonstrates use of the STATE_KEYIN
callback function set by mdlState_setFunction (STATE_KEYIN, StateKeyinCallback).
It's a little klunky because we rely on a static public variable to hold the string
captured by that callback when a user keys a string.
The PLACE LINE tool requires two datapoints.
Once the first datapoint is accepted, the tool changes the prompt seen by the user
and starts dynamics.
Until a second datapoint is accepted, the incipient line is created as a 'rubber band'
between the first datapoint and the cursor.
Building the Create Element Tool example
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: CreateTool.ma and CreateTool.dll.
File CreateTool.ma contains only resource data: in this case, the information MicroStation requires to load the DLL,
and a command table. CreateTool.dll is the implementation file.
When a user types mdl load CreateTool MicroStation first loads CreateTool.ma
and finds the resource directive (the DllMdlApp in CreateTool.r) that instructs it to load a DLL,
then it loads CreateTool.dll.
Download the Create Tool Project
Download the CreateTool 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 2005 to be installed in order to compile this project.
Contact LA Solutions using this 