Introduction

The C++ MicroStationAPI and its predecessor the MicroStation Development Library (MDL) 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.

Describe Element

The MicroStationAPI provides the Bentley::DgnPlatform::Handler and Bentley::DgnPlatform::ElementHandle classes. The function described below uses the Handler.GetDescription method to obtain an element description. The method 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 ElementHandle and Handler to obtain the description. The description is returned in a Bentley string class Bentley::WString. That Bentley::WString class is a specialised extension of std::wstring.

Presumably, though I haven't tested it, this function also responds 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 <ElementHandle.h>  //  mdl/MicroStationAPI for ElementHandle & 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::DgnPlatform::Element;
    ElementHandle         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.

Questions

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