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 commented code fragment that illustrates a common requirement: to obtain a description of the MicroStation element being considered.

Describe Element

The MicroStationAPI provides the Bentley::Ustn::Handler and Bentley::Ustn::ElemHandle classes. The function described below uses the Handler.GetDescription method to obtain an element description. The function is overloaded: we can supply either a file position and a model reference, or an element reference and a model reference.

This method has the benefit that it's terse, and it provides us developers with MicroStation's understanding of an element type. Unlike an MDL implementation, we don't have to construct a giant switch statement to return our own element description from the element type value.

The function relies on MicroStationAPI classes ElemHandle and Handler to obtain the description. The description is returned in a Bentley string class Bentley::WString. Bentley::WString is a specialised class that inherits from std::wstring.

Presumably, though I haven't tested it, this function also response to locale. That is, it should return a local language description of an element.

//  Header file (.h)
#include <string>        //  For std::wstring
std::wstring    DescribeElement    (UInt32          filePos,
                                   DgnModelRefP     modelRef);
std::wstring    DescribeElement    (ElementRef      elemRef,
                                   DgnModelRefP     modelRef);

//  Implementation file (.cpp)
#include <ElemHandle.h>  //  mdl/MicroStationAPI for ElemHandle & Handler
#include <WString.h>     //  mdl/include for WString
////////////////////////////////////////////////////////////////////////////////////////////////////
std::wstring    DescribeElement    (UInt32          filePos,
                                   DgnModelRefP     modelRef)
{
	return DescribeElement (mdlModelRef_getElementRef (modelRef, filePos), modelRef);
}
////////////////////////////////////////////////////////////////////////////////////////////////////
std::wstring    DescribeElement    (ElementRef      elemRef,
                                   DgnModelRefP     modelRef)
{
    using namespace Bentley::Ustn::Element;
    ElemHandle         eh (elemRef, modelRef);
    Handler&           handler = eh.GetHandler ();
    Bentley::WString   wcDescr;
    enum StringLength
    {
       DesiredLength = 128,   //  See MicroStationAPI documentation
    };
    handler.GetDescription (eh, wcDescr, DesiredLength);
    return std::wstring (wcDescr);
}

DesiredLength

The DesiredLength argument is indeterminate. Here's what the MicroStationAPI documentation has to say about it …

DesiredLength: the largest number of characters the caller wishes to see in the description. Implementers should endeavour to honour this if possible, and should return the most elaborate description possible within the desired length. However, implementers should never truncate the description to nonsense, even if the minimum sensible length exceeds DesiredLength. Callers must be prepared for strings that exceed DesiredLength.