Configuration Variables

Table of Contents

• About
• Macros
• Definition
• Configuration
• Further Reading

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;
 
  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.

• 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.

Further Reading

• Application Manual