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.

MAXON_CONFIGURATION_BOOL(): Defines a maxon::Bool configuration variable.
MAXON_CONFIGURATION_INT(): Defines a maxon::Int configuration variable.
MAXON_CONFIGURATION_FLOAT(): Defines a maxon::Float configuration variable.
MAXON_CONFIGURATION_STRING(): Defines a maxon::String configuration variable.

// 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:

maxon::Configuration::QueryBool(): Reads a maxon::Bool configuration variable.
maxon::Configuration::QueryInt(): Reads a maxon::Int configuration variable.
maxon::Configuration::QueryFloat(): Reads a maxon::Float configuration variable.
maxon::Configuration::QueryString(): Reads a maxon::String configuration variable.

  // 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::CONFIGURATIONENTRY_ORIGIN origin;
  maxon::CONFIGURATIONENTRY_STATE  state;
  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.

maxon::Configuration::AddHelpForBool(): Adds information on a maxon::Bool configuration variable.
maxon::Configuration::AddHelpForInt(): Adds information on a maxon::Int configuration variable.
maxon::Configuration::AddHelpForFloat(): Adds information on a maxon::Float configuration variable.
maxon::Configuration::AddHelpForString(): Adds information on a maxon::String configuration variable.
maxon::Configuration::AddHelpForOption(): Adds information on different options of the given configuration variable.

// This example declares and configures a new configuration variable at start-up.
static maxon::Result<void> AddCustomDebugLevel()
{
  iferr_scope;
  // configuration variable key
  const maxon::String customDebug { "g_customDebugLevel" };
  const maxon::CONFIGURATION_CATEGORY category = maxon::CONFIGURATION_CATEGORY::REGULAR;
  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.

maxon::Configuration::BroadcastBool(): Broadcast a maxon::Bool value.
maxon::Configuration::BroadcastInt(): Broadcast a maxon::Int value.
maxon::Configuration::BroadcastFloat(): Broadcast a maxon::Float value.
maxon::Configuration::BroadcastString(): Broadcast a maxon::String value.

Table of Contents

About

Macros

Definition

Configuration

Further Reading