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.");
#define MAXON_CONFIGURATION_BOOL(CONFIGVALUE, DEFVALUE, DEVCATEGORY, HELPTEXT)
Definition: configuration.h:104
#define MAXON_CONFIGURATION_STRING(CONFIGVALUE, DEFVALUE, DEVCATEGORY, HELPTEXT)
Definition: configuration.h:113
@ REGULAR
Help will be shown when application is started with command line parameter help. Use this value for c...

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: url.h:942
return OK
Definition: apibase.h:2735
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
@ FILE
Url is a file.
#define iferr_return
Definition: resultbase.h:1524

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
#define argument
Definition: graminit.h:83
D
Quality D.
Definition: macros.h:4
const char const char const char int line
Definition: object.h:440
const char const char const char * file
Definition: object.h:439

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());
}
}
static MAXON_METHOD Result< void > QueryBool(const String &key, Bool &result, CONFIGURATIONENTRY_ORIGIN &origin, CONFIGURATIONENTRY_STATE &state)
PyArena _PyASTOptimizeState * state
Definition: compile.h:99
Py_UCS4 * res
Definition: unicodeobject.h:1113
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:195
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
#define iferr(...)
Definition: errorbase.h:388
CONFIGURATIONENTRY_ORIGIN
Source where a configuration value was defined.
Definition: configuration.h:27
CONFIGURATIONENTRY_STATE
State of a configuration value.
Definition: configuration.h:36
static const ERROR_FAILED FAILED
Definition: resultbase.h:68
Definition: grammar.h:37

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);
static MAXON_METHOD Result< void > AddHelpForString(const String &key, const String &defaultValue, CONFIGURATION_CATEGORY category, const Char *help)
Definition: string.h:1237
PyObject * error
Definition: codecs.h:206
const char const char * errors
Definition: codecs.h:83
OK
User has selected a font.
Definition: customgui_fontchooser.h:0
#define MAXON_INITIALIZATION(...)
Definition: module.h:875
The maxon namespace contains all declarations of the MAXON API.
Definition: autoweight.h:14
CONFIGURATION_CATEGORY
Help Category for configuration values.
Definition: configuration.h:15
#define iferr_scope
Definition: resultbase.h:1389

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