Configuration Variables

About

Configuration variables allow to define the behaviour of the application. Such a variable can be set in various ways (see below) and can be read in the source code.

Note
The help text of all registered configuration variables is listed when Cinema 4D is started with the "help" command line argument. A console window can be opened with the command line argument "g_console=true".

Macros

A configuration variable can be defined inside a source code file using one of these macros. The variable allows then to access its value.

// This example shows the definition of some configuration variables in a source code file.
MAXON_CONFIGURATION_STRING(g_copy_source, "", maxon::CONFIGURATION_CATEGORY::REGULAR, "Path to a file that should be copied.");
MAXON_CONFIGURATION_STRING(g_copy_destination, "", maxon::CONFIGURATION_CATEGORY::REGULAR, "Destination folder the source file is copied to. Folder must exist.");
MAXON_CONFIGURATION_BOOL(g_copy_overwrite, false, maxon::CONFIGURATION_CATEGORY::REGULAR, "Set to true if an existing file should be overwritten.");

The so defined variables can be simply accessed using the created global variable:

// This example uses the global variables defined with the configuration
// variables to copy the given file to the given destination.
// check configuration variables
if (g_copy_source.IsEmpty())
return maxon::OK;
if (g_copy_destination.IsEmpty())
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "g_copy_source is set but g_copy_destination is empty."_s);
// check URLs
const maxon::Url sourceFile(g_copy_source);
if (sourceFile.IoDetect() != maxon::IODETECT::FILE)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "g_copy_source is not a file."_s);
const maxon::Url destinationDir(g_copy_destination);
if (destinationDir.IoDetect() != maxon::IODETECT::DIRECTORY)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "g_copy_destination is not an existing folder."_s);
// copy
const maxon::Url targetFile = (destinationDir + sourceFile.GetName())iferr_return;
sourceFile.IoCopyFile(targetFile, g_copy_overwrite, false) iferr_return;

Definition

The value of a configuration variable can be set in multiple ways. It can be set

  • within the application itself (default value).
  • in a configuration file config.txt next to the application.
  • in an environment variable.
  • as a command line argument.
:: Windows batch file example
:: Start Cinema 4D with the custom command line argument "g_printErrors" and the built-in argument "g_console"
"CINEMA 4D.exe" g_printErrors=true g_console=true

Configuration

A configuration variable can be accessed in any source code file using the maxon::Configuration class:

// This example executes a simple task. Depending on the value of the
// configuration variable "g_printErrors" the error is printed to the console.
// execute task
const maxon::Result<void> res = ExecuteTask();
// get value of configuration variable "g_printErrors"
maxon::Bool printError = false;
if (maxon::Configuration::QueryBool("g_printErrors"_s, printError, origin, state))
{
// if an error occurred and if "g_printErrors" was set to "true"
// print the error
const maxon::Bool executionFailed = res == maxon::FAILED;
if (executionFailed && printError)
{
DiagnosticOutput("Error: @", res.GetError());
}
}

It is also possible to register configuration variables at runtime. With these functions the variables are marked as used (maxon::CONFIGURATIONENTRY_STATE::USED) and the help text will be defined.

// This example declares and configures a new configuration variable at start-up.
static maxon::Result<void> AddCustomDebugLevel()
{
// configuration variable key
const maxon::String customDebug { "g_customDebugLevel" };
maxon::Configuration::AddHelpForString(customDebug, ""_s, category, "Print custom debug messages.") iferr_return;
maxon::Configuration::AddHelpForOption(customDebug, "all"_s, false, true, category, "Print all debug information.") iferr_return;
maxon::Configuration::AddHelpForOption(customDebug, "warning"_s, false, false, category, "Print only warnings.") iferr_return;
maxon::Configuration::AddHelpForOption(customDebug, "error"_s, false, false, category, "Print only errors.") iferr_return;
return maxon::OK;
}
MAXON_INITIALIZATION(AddCustomDebugLevel, nullptr);

This will be displayed in the console like this:

// Print custom debug messages.
g_customDebugLevel=[string|all|warning|error]

These broadcast functions are used to copy a value into all modules that defined the given configuration variable.

Further Reading