Resource IDs

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_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)
{
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");
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