This class is a log utility. More...

#include <Log.h>

Static Public Member Functions
static QString	getLevelAsString (InterfaceLogger::LogLevel level)
	get the enum value as a text More...

static InterfaceLogger::LogLevel	getLevelFromString (QString levelString)
	get the enum value from the text More...

static InterfaceLogger *	getLogger ()
	get the current application logger More...

static void	setLogger (InterfaceLogger *logger)
	set the application logger and delete the previous logger Call this method transfers the logger instance ownership to class Log. More...

Static Private Attributes
static InterfaceLogger *	applicationLogger = nullptr
	Global Logger manager. More...

Detailed Description

This class is a log utility.

The aims of the log in CamiTK are:

to simplify and give a flexible way to log message in any application
to be minimally invasive in the source code
to help bug tracking and report
to help new development by providing automatically generated debugging information
to suppress any need to use qDebug macro or std::cout / std::cerr "printf"

There are four types of message (

See also

InterfaceLogger):

ERROR error messages should be used only when a problem occurs that
- cannot be taken care of by the source code
- imply a preventive crash action
- might result in unfinished process / undefined behaviour
WARNING warning messages should be used when something went wrong but is not critical to the application state but might require some corrective or alternative action by the user
INFO: information messages should be used to show normal processing, stage or intermediate step or display some useful data values
TRACE: trace messages should be used to trace anything useful for debugging or log post-processing

These messages are written using the corresponding CAMITK log macros: CAMITK_ERROR, CAMITK_WARNING, CAMITK_INFO and CAMITK_TRACE.

For static methods and non QObject class, use the ALT CAMITK log macros: CAMITK_ERROR_ALT, CAMITK_WARNING_ALT, CAMITK_INFO_ALT and CAMITK_TRACE_ALT.

There are also specific IF CAMITK macros use to log only if a given boolean expression is true: CAMITK_ERROR_IF, CAMITK_WARNING_IF, CAMITK_INFO_IF and CAMITK_TRACE_IF.

And their corresponding counterparts for static methods or non QObject class: CAMITK_ERROR_IF_ALT, CAMITK_WARNING_IF_ALT, CAMITK_INFO_IF_ALT and CAMITK_TRACE_IF_ALT.

Depending on the current application logger log level, not all the messages are displayed.

A default logger is instanciated for all application using the CamiTKLogger class

See also: CamiTKLogger

The current log level can be set to

NONE in this case, no message are logged. Logger is completely silent
ERROR only error messages are logged
WARNING only WARNING and ERROR messages are logged
INFO INFO, WARNING and ERROR messages are logged
TRACE all types of messages are logged

A message box level is also available: any message equals or above the message box level will be shown in a modal QMessageBox dialog.

Debug information are also available: it will automatically print the method name, class or file name and line where the log message originated. This is very useful during debug session.

Debug information are optional.

To log message, use the macro defined in this class header.

The log message time stamp can be turned on and off as well.

Note

How to use the macro in the source:

Make sure that the file Log.h is correctly included in the current source code
Determine the level of your log message: ERROR, WARNING, INFO and TRACE
If the log message should be written only if a corresponding boolean expression is true, use the _IF version
If the log message is in a static method or a non QObject derived class (most CamiTK class derived from QObject), use the ALT version
Start the log message with an uppercase
Do not add the file, class, or method name, this is taken care of automatically by the debug information
The log message should be a QString:
- use QString::number(..) to convert primitive numeric type to QString
- use QString::fromStdString(..) to convert std::string

completely disabling log To void any log message, add the following line at the beginning of the CMakeLists.txt corresponding to the project you want to silence:

add_definitions(-DCAMITK_DISABLE_LOG)

# you can also also add "-DCAMITK_DISABLE_LOG" to the camitk_extension macro DEFINES option

This will transform all CAMITK log macro written in your code to null function. Note that it will not void the camitkcore log entry (to have absolutely no log at all, you need to compile CamiTK SDK with "-DCAMITK_DISABLE_LOG"

Some simple examples:

unsigned int value = 4;
CAMITK_INFO(tr("Current value: %1").arg(QString::number(value)))  // tr(..) is for translation of string to other language
CAMITK_TRACE_IF((value<10), tr("Current value is a digit"))

Note: if the source code is compiled with CAMITK_DISABLE_LOG defined, then any log macro results into a NOOP. This does not mean that there can't be any logger. In this case to add debug information you will explicitely have to call Log::getLogger()->log(...); The default logger can be used/started at any time, even without any camitk application instance. In order to define the default log levels and parameter, you need to set the values before the camitk::Application is instanciated. If the default settings are modified by the user, they will automatically replace the default log values. Here is an example:
// in main.cpp
...
// Instanciate default CamiTKLogger and set default levels
// This level are used for the first run, and may be later overiden by the user if saved in the user settings
camitk::Log::getLogger()->setLogLevel(InterfaceLogger::INFO);
camitk::Log::getLogger()->setMessageBoxLevel(InterfaceLogger::WARNING);
// force to log all messages to a file as well as stdout
camitk::Log::getLogger()->setLogToFile(true);
// Say hello
CAMITK_INFO_ALT(tr("Logger started, log is written to file %1").arg(camitk::Log::getLogger()->getLogFileInfo().fileName()))
...
// init a camitk application context
camitk::Application a("camitk-myapp", argc, argv, true, true);; In order to force log settings and ignore user settings, you need modify the Application property object directly. For a CamiTK application, you can do that in the constructor of the camitk::Application inherited class (as the first lines for instance, if you don't want to miss anything):
MyCamiTKApplication::MyCamiTKApplication(int& argc, char** argv, QString inputFileName, QString outputDirectory) : Application("camitk-myapplication", argc, argv) {
// modify default log options for this application
setProperty("Log to File", true);
setProperty("Logger Level",InterfaceLogger::TRACE);
...
Or you can do that from outside (e.g. in the main.cpp), using the application property object:
#include <PropertyObject.h>
...
main(..) {
// create a camitk application
MyCamiTKApplication myapp(argc, argv, ...);
// Force the log parameters and ignore the user saved settings, by directly changing the application properties
// so that it is recorded at every launch (overriding any previous user choice)
myapp.getPropertyObject()->setProperty("Logger Level",InterfaceLogger::INFO);
myapp.getPropertyObject()->setProperty("Message Box Level",InterfaceLogger::WARNING);
...

Available application property names linked to log settings:

"Logger Level"
"Message Box Level"
"Log to Standard Output"
"Log to File"
"Display Debug Information to Log Message"
"Display Time Stamp Information to Log Message"

Note

for MSVC users A (legacy) MS Windows header defines ERROR as a preprocessor macro. This header is unfortunately sometimes included in low-level library code. This will clash with the CAMITK_ERROR macro. Hints: if you use the CAMITK_ERROR or CAMITK_ERROR_ALT macro in your code and get these compilation errors:

error C2589: 'constant': illegal token on right side of '::'
error C2059: syntax error: '::' Move your include>Log.h> line at the end of your include lines. Therefore include &gtLog.h> should be the last include directive.