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.

RAL colours

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.