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 Cells

MicroStation is a computer-aided-design (CAD) tool. It provides many ways to construct 3d and 2D designs. Cells are a drawing shortcut: a cell is a pre-defined group of DGN elements (lines, arcs, text etc.) that a MicroStation operator can place singly or multiply.

MicroStation has several types of cell. The most used types are normal cells (type 2 element), shared cells (type 35 element), and parametric cells.

This article illustrates the programmer's view of cells. The Cell Handler APIs are provided with the C++ MicroStation CONNECT SDK.

Cell Handlers

The MicroStation CONNECT SDK assists programmers with its element handler classes. The abstract base class is simply Handler, from which many more specific classes inherit. Those relevant to cells are …

Usually you will use the NormalCellHeaderHandler and the SharedCellHandler classes.

Get an Element Handler

The ElementHandle class (and hence the derived EditElementHandle class) has a GetHandler() method. Often, you can use the GetDisplayHandler() method, which returns a pointer. You can check for a NULL pointer to verify that you have a valid handler …

#include <DgnPlatform/CellHeaderHandler.h>
ElementHandle eh (... get ElementHandle from somewhere);
DisplayHandlerP handler = eh.GetDisplayHandler ();
if (nullptr != handler)
{
   NormalCellHeaderHandler* cellHandler = std::dynamic_cast<NormalCellHeaderHandler*>(handler);
   if (nullptr != cellHandler)
   {
      DoSomethingWithCellHandler (handler, eh);
   }
}

Create a Cell

Create a Normal Cell

Use static method NormalCellHeaderHandler::CreateCellElement().

#include <DgnPlatform/CellHeaderHandler.h>

Create a Shared Cell

Use static method SharedCellHandler::CreateSharedCellElement().

#include <DgnPlatform/SharedCellHandler.h>

Query a Cell

NormalCellHeaderHandler inherits from several classes, including ICellQuery. In this example we're using ICellQuery::ExtractName …

#include <DgnPlatform/ElementGeometry.h>
void DoSomethingWithCellHandler (NormalCellHeaderHandler* cellHandler, ElementHandleCR element)
{
  ASSERT (nullptr != cellHandler);
  WChar name [MAX_MODEL_NAME_LENGTH];
  cellHandler->ExtractName (name, MAX_MODEL_NAME_LENGTH, element);
}

Legacy API

If you're porting an older application to MicroStation CONNECT from MicroStation V8i, then you can continue to use the mdlCell_api. Some parameters have changed their datatype, and the header files are in sub-folders of the SDK include folder. For example …

#include <Mstn/MdlApi/mscell.fdf>
MSElementCP cell = ... Get cell from somewhere
WChar name [MAX_MODEL_NAME_LENGTH];
mdlCell_extractName (name, MAX_MODEL_NAME_LENGTH, cell);

Return to MicroStationAPI articles index.

Questions

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