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 Development: ColorBook Usage

This article is written for C++ developers of MicroStation applications. A MicroStation Color Book provides a set of named colours. For example, MicroStation CONNECT provides several Color Books, including RAL, Pantone™ and others.

The ColorBook class is part of the C++ MicroStationAPI delivered with MicroStation CONNECT.

MicroStation CONNECT exposes the ColorBook class. This article describes a simple wrapper that shows how to construct a ColorBookPtr smart pointer and load a set of colours.

ColourBookHandler Class

Here's the class definition of ColourBookHandler …

#include	<Bentley/WString.h>
#include	<DgnPlatform/ColorBook.h>
///	A class to handle a MicroStation ColorBook.
struct ColourBookHandler
{
  enum StringControl {  ColorNameLength = 64, };
  ColorBookPtr  colorBook_;
  ///  Wraps ColorBook::LoadFromDgn.
  bool     LoadFromDgn    (WCharCP bookName, bool searchDgnLibs = true);
  ///  Enumerate colours in the open ColorBook.
  size_t   EnumerateColours ();
};

ColourBookHandler Implementation

Here's the class implementation …

#include <Mstn/ISessionMgr.h>
#include <DgnPlatform/DgnPlatform.r.h>

#include "ColourManager.h"

bool ColourBookHandler::LoadFromDgn (WCharCP bookName, bool searchDgnLibs)
{
  using namespace Bentley::DgnPlatform;
  DgnFileP  dgnFile = ISessionMgr::GetManager ().GetActiveDgnFile ();
  //  [Paul Connelly]
  //  That argument [DgnHost] appears to be a vestige of earlier times - it is entirely unused by the function
  DgnHostR  dgnHost = ISessionMgr::GetManager ().GetMicroStationDgnHost ();
  return SUCCESS == ColorBook::LoadFromDgn (colorBook_, bookName, dgnFile, searchDgnLibs, dgnHost);
}

size_t  ColourBookHandler::EnumerateColours ()
{
  const	UInt     nColours  { colorBook_->GetEntryCount () };
  WChar          name      [ColorNameLength];
  Bentley::RgbColorDef	colorDef;
  for (UInt i = 0; i != nColours; ++i)
  {
    colorBook_->GetEntry (&colorDef, name, i);
  }
  return nColours;
}

Example usage of class ColourBookHandler. Look in MicroStation's Colors dialog to see the range of Color Books available …

WCharCP             colorBook = L"RAL DESIGN";
ColourBookHandler   handler;
if (handler.LoadFromDgn (colorBook))
{
  handler.EnumerateColours ();
}

Acknowledgements

Thanks go to Bentley Systems staffers Paul Connelly and Robert Hook. They helped me to understand how to use the ColorBook class by answering my questions on the MicroStation Programming Forum.

Questions

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