LoggerInterface Manual

Table of Contents

• About
• Custom Loggers
• Using Custom Loggers
• Built-In Loggers
• Logger Types
• Further Reading

About

The logger interface allows to create new custom loggers for specific tasks and to access existing loggers. Loggers are presented in the "Console" window in Cinema 4D and registered at the maxon::Loggers registry.

Messages can be sent to the default logger using ApplicationOutput().

Custom Loggers

A new custom logger can be created with maxon::LoggerRef::Create() and is then registered at maxon::Loggers. A logger type defines the target of the logger (see Logger Types).

• maxon::LoggerInterface::AddLoggerType(): Adds the given logger type to the custom logger.
• maxon::LoggerInterface::RemoveLoggerType(): Removes the given logger type from the logger.
• maxon::LoggerInterface::RemoveLoggerTypes(): Removes all logger types of the given type.
• maxon::LoggerInterface::GetLoggerTypes(): Returns all logger types of the logger.

A custom logger is configured with:

• maxon::LoggerInterface::GetName(): Returns the name of the logger.
• maxon::LoggerInterface::SetName(): Sets the name of the logger.
• maxon::LoggerInterface::Enable(): Enables or disables the logger.
• maxon::LoggerInterface::IsEnabled(): Returns true if the logger is enabled.

  // This example creates a new custom logger and adds it to the registered loggers.
  // g_exampleLogger is a maxon::LoggerRef instance.
 
  // define logger ID
  const maxon::Id loggerID { "net.maxonexample.logger" };
 
  // check if a logger with that ID already exists
  if (!maxon::Loggers::Get(loggerID))
  {
    // create the new logger and store it in a global variable for later access
    // make sure to set this object to nullptr when Cinema shuts down
    iferr (g_exampleLogger = maxon::LoggerRef::Create())
    {
      // if the logger could not be created, use the default logger instead
      g_exampleLogger = maxon::Loggers::Default();
    }
    else
    {
      // if the logger could be created
      // add the logger type "Application" to display logged messages in the "Console" window
      g_exampleLogger.AddLoggerType(maxon::TARGETAUDIENCE::ALL, maxon::LoggerTypes::Application()) iferr_return;
 
      // define logger name
      g_exampleLogger.SetName("Example Logger"_s);
      // insert the logger in the "Loggers" registry
      maxon::Loggers::Insert(loggerID, g_exampleLogger) iferr_return;
 
      // this message must be send to update the console window
      const maxon::Int32 BFM_REBUILDCONSOLETREE = 334295845;
      SpecialEventAdd(BFM_REBUILDCONSOLETREE);
    }
  }

// This example shows how to free the logger reference.
 
static void FreeExampleLogger()
{
  g_exampleLogger = nullptr;  // reference must be freed
 
  // make sure to also remove the entry of your logger from Loggers.
  maxon::Loggers::Erase(maxon::Id { "net.maxonexample.logger" }) iferr_ignore("");
}
 
MAXON_INITIALIZATION(nullptr, FreeExampleLogger);

Using Custom Loggers

A message is sent to a custom logger using the Write() function:

• maxon::LoggerInterface::Write(): Sends the given message to the logger.
• maxon::TARGETAUDIENCE: Specifies who should read the message.
  • maxon::TARGETAUDIENCE::DEBUGGER: Debug message.
  • maxon::TARGETAUDIENCE::DEVELOPERS: Message for developers.
  • maxon::TARGETAUDIENCE::USERS: Message for end-users.
  • maxon::TARGETAUDIENCE::ALL: Message for all audiences.
• maxon::WRITEMETA: Specifies the type of the message.
  • maxon::WRITEMETA::DEFAULT: Default message.
  • maxon::WRITEMETA::WARNING: Warning message.
  • maxon::WRITEMETA::CRITICAL: Critical message.
  • maxon::WRITEMETA::NONEWLINE: No new line is added to the message.

  // This example writes a message to a custom logger.
 
  // write to a custom logger referenced in g_exampleLogger
  g_exampleLogger.Write(maxon::TARGETAUDIENCE::ALL, "Foo"_s, MAXON_SOURCE_LOCATION, maxon::WRITEMETA::CRITICAL) iferr_return;
 
  // or write to the logger by getting the logger using the logger ID
 
  // get logger
  const maxon::Id        loggerId { "net.maxonexample.logger" };
  const maxon::LoggerRef logger = maxon::Loggers::Get(loggerId);
 
  logger.Write(maxon::TARGETAUDIENCE::ALL, "Bar"_s, MAXON_SOURCE_LOCATION, maxon::WRITEMETA::DEFAULT) iferr_return;

Built-In Loggers

All existing loggers are registered at maxon::Loggers. These three loggers are there for public use:

• maxon::Loggers::Default: The default logger (published object for direct use).
• maxon::ID_LOGGER_PYTHON: The Python logger's ID, defined in python.framework, cpython.h.
• maxon::Loggers::Process: The IDE console logger (published object for direct use).

Note

The default logger is used with ApplicationOutput().

  // This example sends a message to the default logger.
 
  ApplicationOutput("Some Message."_s);

Logger Types

A logger type implements the actual processing of a given message e.g. if that message is displayed in the GUI or written to a file.

• maxon::LoggerTypes::Application(): Displays the message in Cinema 4D's "Console" window. See maxon::UserLoggerTypeInterface.
• maxon::LoggerTypes::File(): Saves the message to a file. See maxon::FileLoggerTypeInterface.
• maxon::LoggerTypes::Process(): Displays the message in the IDE console.

Logger types are based on maxon::LoggerTypeInterface:

• maxon::LoggerTypeInterface::Write(): Sends the given message to the logger type.
• maxon::LoggerTypeInterface::Flush(): Flushes the output.
• maxon::LoggerTypeInterface::ObservableLoggerNotify: This observer is triggered when a new message is sent to the logger type.

  // This example adds an observer to the given logger. This observer
  // will be called if a message is sent to that logger.
 
  for (const auto& loggerTypeAudience : logger.GetLoggerTypes())
  {
    const maxon::LoggerTypeRef loggerType = loggerTypeAudience.GetFirst();  // get first element of the pair
    loggerType.ObservableLoggerNotify().AddObserver(LoggerCallback) iferr_return;
  }

maxon::UserLoggerTypeInterface is the logger type that displays the message in Cinema 4D's "Console" window:

• maxon::UserLoggerTypeInterface::Iterate(): Allows to iterate over all stored lines. See maxon::LoggerLine.
• maxon::UserLoggerTypeInterface::GetCount(): Returns the number of stored lines.
• maxon::UserLoggerTypeInterface::Reset(): Clears the cache.

maxon::FileLoggerTypeInterface is the logger type that writes the message to a file:

• maxon::FileLoggerTypeInterface::Init(): Inits the type with the given maxon::Url.
• maxon::FileLoggerTypeInterface::GetUrl(): Returns the used maxon::Url.

  // This example accesses the default logger and gets all displayed lines.
 
  // get default logger
  const maxon::LoggerRef defaultLogger = maxon::Loggers::Default();
 
  for (const auto& logger : defaultLogger.GetLoggerTypes())
  {
    const maxon::LoggerTypeRef loggerType = logger.GetFirst();  // get first element of the pair
 
    if (loggerType.IsInstanceOf<maxon::UserLoggerTypeRef>())
    {
      const maxon::UserLoggerTypeRef userLoggerType = maxon::Cast<maxon::UserLoggerTypeRef>(loggerType);
 
      // iterate over all lines sent to the logger
      userLoggerType.Iterate([](maxon::LoggerLine& line) -> maxon::Result<void>
        {
          DiagnosticOutput("Line: @", line._str);
          return maxon::OK;
        }) iferr_return;
    }
 
  }

Further Reading

• String Manual
• Url Manual