LabelUtils Protocol Extensions

Yury Lebedev

November 24, 2022

LabelUtilsPE is a protocol extension (PE) intended to move the label-related functionality outside of the core BimRv functionality. It allows BimRv users to implement their own version of the PE to support different locales.

LabelUtils Interface

The full list of available methods is available in the API Reference, but here are a few that allow you to get a label.

The getLabelFor(enum_value) method returns a label for a built-in enum value. The following enum values are supported:

  • OdBm::BuiltInParameter::Enum
  • OdBm::BuiltInParameterGroup::Enum
  • OdBm::BuiltInCategory::Enum
  • OdBm::ParameterType::Enum
  • OdBm::FamilyName::Enum
  • OdBm::SystemType::Enum
  • OdBm::AreaSpaceType::Enum
  • OdBm::ColorSchemeMessage::Enum
  • OdBm::CurveElemNameType::Enum
  • OdBm::PipeJointType::Enum
  • OdBm::BuiltInCircuitNamingScheme::Enum
  • OdBm::CableTrayShapeType::Enum
  • OdBm::ScheduleFieldMultipleValuesDisplayType::Enum
  • OdBm::LabelResource::Enum
  • OdBm::PartitionType::Enum

The getLabelForUnit() method returns a label for a unit.

The getLabelForSymbol() method returns a label for a unit symbol.

The getLabelForSpec() method returns a label for a unit specification (type).

Use the LabelUtilsPE Methods

To use PE methods, first load the library with the PE implementation. For example, to use the English implementation, call the following command:

::odrxDynamicLinker()->loadModule(L"TB_ExLabelUtils");

To support different locales, write and register the LabelUtilsPE implementation with the required resources instead:

// Load custom LabelUtils implementation
MyLabelUtils::rxInit();
s_MyLabelsUtils = MyLabelUtils::createObject();
// Register MyLabelUtils instance as global OdBmLabelUtilsPE one
OdBmObject::desc()->addX(OdBmLabelUtilsPE::desc(), s_MyLabelUtils);

Register the custom implementation only once during SDK initialization. The LabelUtils instance cannot be replaced at runtime. Also, unregister the implementation during SDK shutdown:

// Unregister and release LabelUtils instance
OdBmObject::desc()->delX(OdBmLabelUtilsPE::desc());
s_MyLabelUtils.release();
MyLabelUtils::rxUninit();

Next, link the PE implementation with the OdBmElement class and access it using the following call:

OdBmLabelUtilsPEPtr pLabelUtils = OdBmElement::desc()->getX(OdBmLabelUtilsPE::desc());

The custom implementation can be accessed in the same way or by using your global pointer (s_MyLabelUtils here) directly. If no PE module is loaded, pLabelUtils gets a null pointer as a result.

Use in BimRv

The LabelUtilsPE functionality is used for building tables of built-in parameters (ParamDef.caption) and built-in categories (Category.name). If no LabelUtilsPE module is loaded when a database is opened, the built-in parameter and category elements get names that correspond to their enum element names. Also, OdBmElement::getParamValueAsString() methods implicitly call getParamValueAsString() of LabelUtilsPE.

Example

The TB_ExLabelUtils module is a sample implementation of the OdBmLabelUtilsPE interface that supports the English language.

This module has two modes:

  • Regular — CSV files can be modified using a simple text editor and without building source code. Modifications can be done even during runtime (before the first access to its content because afterwards the values are cached and changes have no effect). The CSV folder must be near the TB_ExLabelUtils binary, and removal of these CSV files can lead to runtime errors. Regular mode was the initial BimRv implementation but is no longer the default.
  • Embedded (default mode) — CSV files are embedded in TB_ExLabelUtils, so there is no need to maintain the CSV folder. However, you cannot make fast changes to the CSV files because each modification requires building of the TB_ExLabelUtils module.

You can change the mode at any time during development. In the BimRv/Extensions/TB_ExLabelUtils/CMakeLists.txt file, use the ENV{EMBEDED_CSV} variable to control the build mode of TB_ExLabelUtils:

  • If set to 1 ("SET(ENV{EMBEDED_CSV} 1)"), embedded mode is used.
  • If set to 0 ("SET(ENV{EMBEDED_CSV} 0)"), regular mode is used.

The sample implementation is located in the Extensions/TB_ExLabelUtils/BmSampleLabelUtilsPE.h and Extensions/TB_ExLabelUtils/BmSampleLabelUtilsPE.cpp files.