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;
iferr (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

MAXON_CONFIGURATION_BOOL
#define MAXON_CONFIGURATION_BOOL(CONFIGVALUE, DEFVALUE, DEVCATEGORY, HELPTEXT)
Definition: configuration.h:104
maxon::CONFIGURATION_CATEGORY
CONFIGURATION_CATEGORY
Help Category for configuration values.
Definition: configuration.h:16
maxon::Configuration::AddHelpForString
static MAXON_METHOD Result< void > AddHelpForString(const String &key, const String &defaultValue, CONFIGURATION_CATEGORY category, const Char *help)
maxon
The maxon namespace contains all declarations of the MAXON API.
Definition: c4d_basedocument.h:16
maxon::IODETECT::DIRECTORY
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
maxon::String
Definition: string.h:1198
maxon::CONFIGURATION_CATEGORY::REGULAR
@ REGULAR
Help will be shown when application is started with command line parameter help. Use this value for c...
maxon::OK
return OK
Definition: apibase.h:2518
maxon::Configuration::QueryBool
static MAXON_METHOD Result< void > QueryBool(const String &key, Bool &result, CONFIGURATIONENTRY_ORIGIN &origin, CONFIGURATIONENTRY_STATE &state)
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
iferr_return
#define iferr_return
Definition: resultbase.h:1434
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
MAXON_CONFIGURATION_STRING
#define MAXON_CONFIGURATION_STRING(CONFIGVALUE, DEFVALUE, DEVCATEGORY, HELPTEXT)
Definition: configuration.h:113
maxon::CONFIGURATIONENTRY_ORIGIN
CONFIGURATIONENTRY_ORIGIN
Source where a configuration value was defined.
Definition: configuration.h:27
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::Url
Definition: url.h:820
MAXON_INITIALIZATION
#define MAXON_INITIALIZATION(...)
Definition: module.h:733
maxon::Result< void >
OK
OK
Ok.
Definition: ge_prepass.h:0
iferr_scope
#define iferr_scope
Definition: resultbase.h:1343
maxon::FAILED
static const ERROR_FAILED FAILED
Definition: resultbase.h:68
maxon::IODETECT::FILE
@ FILE
Url is a file.
maxon::Result::GetError
const Error & GetError() const
Definition: resultbase.h:1026
iferr
#define iferr(...)
Definition: errorbase.h:380
maxon::CONFIGURATIONENTRY_STATE
CONFIGURATIONENTRY_STATE
State of a configuration value.
Definition: configuration.h:36