Resource IDs

Table of Contents

• About
• IDs
• Switch
• Class IDs
• Further Reading

About

Dedicated resource IDs are used to the define the ID of a key used with a maxon::DataDictionary and the type of the associated stored value (see DataDictionary Manual).

IDs

Within a given namespace one can use the attribute MAXON_ATTRIBUTE to declare resource IDs. This attribute can only be used in a header file since the source processor will create additional code in the included hxx files.

// This example shows the simple declaration of some resource IDs in a header file.
// The header file must also include the automatically generated .hxx files.
 
// custom namespace for IDs
namespace CUSTOMSETTINGS
{
  // declare IDs
 
  MAXON_ATTRIBUTE(maxon::Bool, SETTING_A, "net.maxonexample.setting_a");
  MAXON_ATTRIBUTE(maxon::String, SETTING_B, "net.maxonexample.setting_b");
}

  // This example shows how to use IDs defined with MAXON_ATTRIBUTE
  // to set and get data stored in a DataDictionary.
 
  maxon::DataDictionary data;
 
  // set data
  data.Set(CUSTOMSETTINGS::SETTING_A, true) iferr_return;
  data.Set(CUSTOMSETTINGS::SETTING_B, "Hello World"_s) iferr_return;
 
  // read data
  const maxon::Bool   optionA = data.Get(CUSTOMSETTINGS::SETTING_A, false);
  const maxon::String optionB = data.Get(CUSTOMSETTINGS::SETTING_B, ""_s);

In contrast the attribute ::MAXON_ATTRIBUTE_LOCAL has to be used in a source code file to define IDs that are only relevant within the scope of that source code file.

// This example shows how to declare local IDs
// and how to use them to edit a DataDictionary.
 
// define local resource IDs
 
namespace LOCALSETTINGS
{
  MAXON_ATTRIBUTE(maxon::Bool, SETTING_A, "setting_a");
  MAXON_ATTRIBUTE(maxon::String, SETTING_B, "setting_b");
  MAXON_ATTRIBUTE(maxon::String, SETTING_C, "setting_c");
  /* Previously was
  MAXON_ATTRIBUTE_LOCAL(maxon::Bool, SETTING_A, "setting_a");
  MAXON_ATTRIBUTE_LOCAL(maxon::String, SETTING_B, "setting_b");
  MAXON_ATTRIBUTE_LOCAL(maxon::String, SETTING_C, "setting_c");
  */
}
 
// use local resource IDs
 
static maxon::Result<void> SetSettings(maxon::DataDictionary& data)
{
  iferr_scope;
 
  data.Set(LOCALSETTINGS::SETTING_A, true) iferr_return;
  data.Set(LOCALSETTINGS::SETTING_B, "Hello"_s) iferr_return;
  data.Set(LOCALSETTINGS::SETTING_C, "World"_s) iferr_return;
 
  return maxon::OK;
}

Switch

To use IDs defined with MAXON_ATTRIBUTE in a switch-case statement one must use these macros:

• ID_SWITCH: Allows to use an ID in a switch statement.
• ID_CASE: Allows to use an ID in a case statement.

// This example shows a function that checks
// if the given key is a specific resource ID.
 
static maxon::Result<void> ReadValue(const ConstDataPtr& key, maxon::DataDictionary& data)
{
  switch (ID_SWITCH(key))
  {
    case ID_CASE(CUSTOMSETTINGS::SETTING_A):
    {
      const maxon::Bool option = data.Get(key, false);
      DiagnosticOutput("Option A: @", option);
      return maxon::OK;
    }
    case ID_CASE(CUSTOMSETTINGS::SETTING_B):
    {
      const maxon::String option = data.Get(key, ""_s);
      DiagnosticOutput("Option B: @", option);
      return maxon::OK;
    }
  }
  return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
}

Class IDs

Resource IDs can also be defined within a C++ class using the MAXON_ATTRIBUTE_CLASS attribute. This way the class name is used instead of a namespace to group the IDs.

// This example shows a simple interface. Within the class the macro MAXON_ATTRIBUTE_CLASS
// is used to declare resource IDs. These IDs can be used in conjuncture with functions of the interface.
 
class SomeDataBaseInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(SomeDataBaseInterface, MAXON_REFERENCE_CONST, "net.maxonexample.interface.somedatabase");
  MAXON_INTERFACE_SINGLE_IMPLEMENTATION;
 
public:
  //----------------------------------------------------------------------------------------
  // Sets the data in the database to the data stored in the given DataDictionary.
  // Values in the DataDictionary must be set using the key defined below.
  //----------------------------------------------------------------------------------------
  static MAXON_METHOD void SetData(maxon::DataDictionary & data);
  //----------------------------------------------------------------------------------------
  // Prints the data stored in the database to the IDE console.
  //----------------------------------------------------------------------------------------
  static MAXON_METHOD void PrintData();
 
  // keys for data stored in the database
 
  MAXON_ATTRIBUTE_CLASS(maxon::Int, VALUE_A, "net.maxonexample.value_a");
  MAXON_ATTRIBUTE_CLASS(maxon::String, VALUE_B, "net.maxonexample.value_b");
};

  // This example uses class IDs to set values in a
  // DataDictionary handed over to this class.
 
  maxon::DataDictionary data;
 
  // set data
  data.Set(SomeDataBaseInterface::VALUE_A, maxon::Int(5)) iferr_return;
  data.Set(SomeDataBaseInterface::VALUE_B, "Hello World"_s) iferr_return;
 
  SomeDataBaseInterface::SetData(data);
  SomeDataBaseInterface::PrintData();

Further Reading

• Data Containers & Collections
• Maxon API Containers & Data Collections
• DataDictionary Manual