MicroStationAPI Cell Handlers

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 …

• Type2Handler is the interface to a normal cell header structure
• ICellQuery extracts normal cell information
• NormalCellHeaderHandler specialised for normal cells
• ISharedCellQuery extracts shared cell information
• SharedCellHandler specialised for shared cells

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>

#include <DgnPlatform/SharedCellHandler.h>

#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);
}

#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);