Qtilities::Logging::AbstractFormattingEngine Class Reference

The base class of all formatting engines. More...

#include <AbstractFormattingEngine.h>

Inheritance diagram for Qtilities::Logging::AbstractFormattingEngine:

List of all members.

Public Member Functions
bool	addColorFormattingHint (CustomFormattingHint color_formatting_hint)
	Adds a color formatting hint to the formatting engine.
void	clearColorFormattingHints ()
	Clear all color formatting hint rules specified for this engine.
QList< CustomFormattingHint >	colorFormattingHints () const
	Returns all color formatting hint rules specified for this engine.
virtual QString	endOfLineChar () const =0
	Function which provides the end of line character used by the formatting engine.
virtual QString	fileExtension () const =0
	Function which provides a file extension which will be used if the logger engine is a File logger engine.
virtual QString	finalizeString () const =0
	Function which is used to provide the finalization string for the logger engine. This string will be sent to the logger engine after all messages.
virtual QString	formatMessage (Logger::MessageType message_type, const QList< QVariant > &messages) const =0
	Function which is called to format the message.
virtual QString	initializeString () const =0
	Function which is used to provide the initialization string for the logger engine. This string will be sent to the logger engine before any messages.
QString	matchColorFormattingHint (const QString &message, Logger::MessageTypeFlags message_type_flags) const
	Checks a color formatting hint against a log message to see if they match.
virtual QString	name () const =0
	Function which provides a name for this formatting engine.
void	removeColorFormattingHint (CustomFormattingHint custom_formatting_hint)
	Removes a specific color formatting hint.

Static Public Member Functions
static QString	escape (const QString &plain)
	Function that does the same as QTextDocument::escape(). Since the Logging module does not depend on QtGui, we cannot use that function directly.

---

Detailed Description

The base class of all formatting engines.

Formatting engines gets a list of messages as a QList<QVariant> list through formatMessage() and returns a formatted string.

Each formatting engine can return its custom initialization string through initializeString(), a finalization string through finalizeString() and a custom end of line character through endOfLineChar(). Lastly, a formatting engine can return a fileExtension() which guides Qtilities on the type of files that the log engine represent (if any).

All the default formatting engines in Qtilities are constructed for you during initialization of the Logger. All logger engine will share the instances of these formatting engines with each other.

Custom Formatting Hints

Formatting engines allows you to set custom color formatting hints by providing QRegExp expressions with matching colors. This allows you to format messages using different color schemes without having to create a complete new formatting engine. Formatting engines must build in support for this functionality, and it won't apply to all engines. For example, the FormattingEngine_Default engine does not use coloring, therefore it does not support this functionality. Other engine however, such as FormattingEngine_Rich_Text, does use coloring information and therefore supports these custom color rules.

By default engines would use colors that you would expect for different messages. For example, errors are colored in red, warnings in orange etc. However you can color messages by their contents using these rules. For example if you want to color messages which represents a succesfull operation in green, you can do this by using the correct matching expression.

Lets look at an example where we color all messages starting with translations of "Successfully" to be green. We add this custom color hint to the FormattingEngine_Rich_Text engine after log initialization. Thus, all logger engines that uses the Rich Text formatting engine will make use of this custom hint.

// Initialize the logger:
Log->setLoggerSessionConfigPath(QtilitiesApplication::applicationSessionPath());
LOG_INITIALIZE();

// Add a formatting hint to the RichText formatting engine.
AbstractFormattingEngine* rich_text_engine = Log->formattingEngineReference(qti_def_FORMATTING_ENGINE_RICH_TEXT);
if (rich_text_engine) {
    QRegExp reg_exp_success_color = QRegExp(QObject::tr("Successfully") + "*",Qt::CaseInsensitive,QRegExp::Wildcard);
    CustomFormattingHint success_message_hint(reg_exp_success_color,"green",Logger::Info);
    rich_text_engine->addColorFormattingHint(success_message_hint);
}

Since all the default Qtilities provided formatting engines are shared by all engines its only neccesarry to add custom hints to the single instance and the rule will be applied to all logger engines that uses that formatting engine.

Note that previous versions of Qtilities had the above rule built in to FormattingEngine_Rich_Text in order to match successfull messages. Since that design was flawed because it depended on English as your language, this built in functionality was removed and you must now set the above rule manually if you depended on the previous mode of operation.

---

Member Function Documentation

bool Qtilities::Logging::AbstractFormattingEngine::addColorFormattingHint ( CustomFormattingHint  color_formatting_hint )

inline

Adds a color formatting hint to the formatting engine.

Parameters:

color_formatting_hint

The CustomFormattingHint describing the format (with the hint being the color, such as "#112233").

Returns:

True when successfull, false otherwise.

Note:

If the color formatting hint has an invalid regular expression, this function will do nothing.

A regular expression can only be used to specify a hint once. While it duplicates will still be added to the list, the first matching expression in the list will always be used.

This function was added in Qtilities v1.1.

void Qtilities::Logging::AbstractFormattingEngine::clearColorFormattingHints ( )

inline

Clear all color formatting hint rules specified for this engine.

This function was added in Qtilities v1.1.

QList<CustomFormattingHint> Qtilities::Logging::AbstractFormattingEngine::colorFormattingHints ( ) const

inline

Returns all color formatting hint rules specified for this engine.

Returns:

A QMap with the keys beign the expressions, and the values the CustomFormattingHint describing the format (with the hint being the color, such as "#112233").

This function was added in Qtilities v1.1.

virtual QString Qtilities::Logging::AbstractFormattingEngine::fileExtension ( ) const

pure virtual

Function which provides a file extension which will be used if the logger engine is a File logger engine.

If this is not applicable just return QString(). Example format = QString("log"). Note that the point is not part of the extension.

Implemented in Qtilities::Logging::FormattingEngine_QtMsgEngineFormat, Qtilities::Logging::FormattingEngine_HTML, Qtilities::Logging::FormattingEngine_XML, Qtilities::Logging::FormattingEngine_Rich_Text, and Qtilities::Logging::FormattingEngine_Default.

QString Qtilities::Logging::AbstractFormattingEngine::matchColorFormattingHint ( const QString &  message, Logger::MessageTypeFlags  message_type_flags  ) const

inline

Checks a color formatting hint against a log message to see if they match.

This function will check the message type and the message contents against all color formatting hints specified. When a match if found, the color that must be used is returned.

Returns:

The color that must be used to format the message if a match was found. If not match was found and empty string is returned.

This function was added in Qtilities v1.1.

void Qtilities::Logging::AbstractFormattingEngine::removeColorFormattingHint ( CustomFormattingHint  custom_formatting_hint )

inline

Removes a specific color formatting hint.

This function was added in Qtilities v1.1.