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");
}
Definition: string.h:1237
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:195
[data_resourceid_declare]
Definition: resource_id.h:14
MAXON_ATTRIBUTE(maxon::Bool, SETTING_A, "net.maxonexample.setting_a")
// 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);
#define iferr_return
Definition: resultbase.h:1524

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)
{
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;
}
#define MAXON_ATTRIBUTE(TYPE, NAME, RID,...)
Definition: fid.h:257
return OK
Definition: apibase.h:2735
#define iferr_scope
Definition: resultbase.h:1389

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);
}
PyObject * key
Definition: abstract.h:289
#define ID_SWITCH(key)
Definition: fid.h:487
#define ID_CASE(key)
Definition: fid.h:501
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67

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");
};
[data_resourceid_declare]
Definition: resource_id.h:28
MAXON_INTERFACE(SomeDataBaseInterface, MAXON_REFERENCE_CONST, "net.maxonexample.interface.somedatabase")
MAXON_INTERFACE_SINGLE_IMPLEMENTATION
Definition: resource_id.h:30
static MAXON_METHOD void SetData(maxon::DataDictionary &data)
MAXON_ATTRIBUTE_CLASS(maxon::Int, VALUE_A, "net.maxonexample.value_a")
static MAXON_METHOD void PrintData()
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202
#define MAXON_REFERENCE_CONST(FREEIMPL)
Definition: interfacebase.h:1206
#define MAXON_METHOD
Definition: interfacebase.h:1012
#define MAXON_INTERFACE_BASES(...)
Definition: objectbase.h:1049
// 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;

Further Reading