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.

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 …

Accept Icon

Add Icon

Camera Icon

Developers who write applications for MicroStation choose one of several APIs …

• MicroStation VBA
• .NET DgnPlatformNet and MstnPlatformNet
• MicroStationAPI

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.

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

Decoration 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.

Sprites and View Decoration

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.

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 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 …

1. Include the sprite image *.ico file in your project development folder
2. List the image file in the Windows resource *.rc file
   • The icon must have an ID specified in the resource.h file
3. Build the Windows resource file with your other source code
   • The linker embeds the icon resource into your DLL

The steps to display a sprite are …

1. Load the sprite into your application's memory
2. Write a class that inherits from IViewDecoration
3. Register that class with MicroStation so it can call your decorator as required
4. Implement the (pure, virtual) _DrawDecoration () method
   • Display the sprite in that method
5. Unregister your class with MicroStation when you want to stop showing sprites

MicroStationAPI: View Decoration Project

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.

ViewDecoration Commands

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.

Building ViewDecoration

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

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.

Questions

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