QLoggingCategory Class

The QLoggingCategory class represents a category, or 'area' in the logging infrastructure. More...

Header: #include <QLoggingCategory>
qmake: QT += core
Since: Qt 5.2

Public Types

typedef CategoryFilter

Public Functions

QLoggingCategory(const char * category)
~QLoggingCategory()
const char * categoryName() const
bool isCriticalEnabled() const
bool isDebugEnabled() const
bool isEnabled(QtMsgType msgtype) const
bool isTraceEnabled() const
bool isWarningEnabled() const
void setEnabled(QtMsgType type, bool enable)
QLoggingCategory & operator()()

Static Public Members

QLoggingCategory * defaultCategory()
CategoryFilter installFilter(CategoryFilter filter)
void setFilterRules(const QString & rules)

Macros

Q_DECLARE_LOGGING_CATEGORY( name)
Q_LOGGING_CATEGORY( name, string)
qCCritical( category)
qCDebug( category)
qCTrace( category)
qCTraceGuard( category)
qCWarning( category)

Detailed Description

The QLoggingCategory class represents a category, or 'area' in the logging infrastructure.

QLoggingCategory represents a certain logging category - identified by a string - at runtime. Whether a category should be actually logged or not can be checked with the isEnabled() methods.

Creating category objects

The Q_LOGGING_CATEGORY() and the Q_DECLARE_LOGGING_CATEGORY() macros conveniently declare and create QLoggingCategory objects:

// in a header
Q_DECLARE_LOGGING_CATEGORY(QT_DRIVER_USB)

// in one source file
Q_LOGGING_CATEGORY(QT_DRIVER_USB, "qt.driver.usb")

Checking category configuration

QLoggingCategory provides isDebugEnabled(), isWarningEnabled(), isCriticalEnabled(), isTraceEnabled(), as well as isEnabled() to check whether messages for the given message type should be logged.

Note: The qCDebug(), qCWarning(), qCCritical(), qCTrace() and qCTraceGuard() macros prevent arguments from being evaluated if the respective message types are not enabled for the category, so explicit checking is not needed:

    // usbEntries() will only be called if QT_DRIVER_USB category is enabled
    qCDebug(QT_DRIVER_USB) << "devices: " << usbEntries();

Default category configuration

In the default configuration isWarningEnabled() and isCriticalEnabled() will return true. isDebugEnabled() will return true only for the "default" category.

Changing the configuration of a category

Use either setFilterRules() or installFilter() to configure categories, for example

    QLoggingCategory::setFilterRules(QStringLiteral("qt.driver.usb.debug=true"));

Printing the category

Use the %{category} place holder to print the category in the default message handler:

    qSetMessagePattern("%{category} %{message}");

Member Type Documentation

typedef QLoggingCategory::CategoryFilter

This is a typedef for a pointer to a function with the following signature:

void myCategoryFilter(QLoggingCategory *);

A function with this signature can be installed with installFilter().

Member Function Documentation

QLoggingCategory::QLoggingCategory(const char * category)

Constructs a QLoggingCategory object with the provided category name. The object becomes the local identifier for the category.

If category is 0, the category name is changed to "default".

QLoggingCategory::~QLoggingCategory()

Destructs a QLoggingCategory object.

const char * QLoggingCategory::categoryName() const

Returns the name of the category.

QLoggingCategory * QLoggingCategory::defaultCategory() [static]

Returns a pointer to the global category "default" that is used e.g. by qDebug(), qWarning(), qCritical(), qFatal().

Note: The returned pointer may be null during destruction of static objects.

Note: Ownership of the category is not transferred, do not delete the returned pointer.

CategoryFilter QLoggingCategory::installFilter(CategoryFilter filter) [static]

Installs a function filter that is used to determine which categories and message types should be enabled. Returns a pointer to the previous installed filter.

Every QLoggingCategory object created is passed to the filter, and the filter is free to change the respective category configuration with setEnabled().

The filter might be called concurrently from different threads, and therefore has to be reentrant.

Example:

QLoggingCategory::CategoryFilter oldCategoryFilter;

void myCategoryFilter(QLoggingCategory *category)
{
    // configure qt.driver.usb category here, otherwise forward to to default filter.
    if (qstrcmp(category->categoryName(), "qt.driver.usb") == 0)
        category->setEnabled(QtDebugMsg, true);
    else
        oldCategoryFilter(category);
}

An alternative way of configuring the default filter is via setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Returns true if critical messages should be shown for this category. Returns false otherwise.

Note: The qCCritical() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

bool QLoggingCategory::isDebugEnabled() const

Returns true if debug messages should be shown for this category. Returns false otherwise.

Note: The qCDebug() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

Returns true if a message of type msgtype for the category should be shown. Returns false otherwise.

bool QLoggingCategory::isTraceEnabled() const

Returns true if the tracers associated with this category should receive messages. Returns false otherwise.

Note: The qCTrace() and qCTraceGuard() macros already do this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

bool QLoggingCategory::isWarningEnabled() const

Returns true if warning messages should be shown for this category. Returns false otherwise.

Note: The qCWarning() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

void QLoggingCategory::setEnabled(QtMsgType type, bool enable)

Changes the message type type for the category to enable.

Note: Changes only affect the current QLoggingCategory object, and won't change the settings of other objects for the same category name. Use either setFilterRules() or installFilter() to change the configuration globally.

Note: QtFatalMsg cannot be changed. It will always return true.

See also isEnabled().

void QLoggingCategory::setFilterRules(const QString & rules) [static]

Configures which categories and message types should be enabled through a a set of rules.

Each line in rules must have the format

<category>[.<type>] = true|false

where <category> is the name of the category, potentially with * as a wildcard symbol at the start and/or the end. The optional <type> must be either debug, warning, critical, or trace.

Example:

    QLoggingCategory::setFilterRules(QStringLiteral("qt.driver.usb.debug=true"));

Note: The rules might be ignored if a custom category filter is installed with installFilter().

QLoggingCategory & QLoggingCategory::operator()()

Returns the object itself. This allows both a QLoggingCategory variable, and a factory method returning a QLoggingCategory, to be used in qCDebug(), qCWarning(), qCCritical() macros.

Macro Documentation

Q_DECLARE_LOGGING_CATEGORY( name)

Declares a logging category name. The macro can be used to declare a common logging category shared in different parts of the program.

This macro must be used outside of a class or method.

This function was introduced in Qt 5.2.

Q_LOGGING_CATEGORY( name, string)

Defines a logging category name, and makes it configurable under the string identifier.

Only one translation unit in a library or executable can define a category with a specific name.

This macro must be used outside of a class or method.

This function was introduced in Qt 5.2.

qCCritical( category)

Returns an output stream for critical messages in the logging category category.

The macro expands to code that checks whether QLoggingCategory::isCriticalEnabled() evaluates to true. If so, the stream arguments are processed and sent to the message handler.

Example:

    QLoggingCategory category("qt.driver.usb");
    qCCritical(category) << "a critical message";

Note: Arguments are not processed if critical output for the category is not enabled, so do not rely on any side effects.

This function was introduced in Qt 5.2.

See also qCritical().

qCDebug( category)

Returns an output stream for debug messages in the logging category category.

The macro expands to code that checks whether QLoggingCategory::isDebugEnabled() evaluates to true. If so, the stream arguments are processed and sent to the message handler.

Example:

    QLoggingCategory category("qt.driver.usb");
    qCDebug(category) << "a debug message";

Note: Arguments are not processed if debug output for the category is not enabled, so do not rely on any side effects.

This function was introduced in Qt 5.2.

See also qDebug().

qCTrace( category)

Returns an output stream for trace messages in the logging category category.

The macro expands to code that checks whether QLoggingCategory::isTraceEnabled() evaluates to true. If so, the stream arguments are processed and sent to the QTracer objects registered with the category.

Note: Arguments are not processed if trace output for the category is not enabled, so do not rely on any side effects.

Example:

int baz(int i)
{
    qCTrace(theBazArea) << 32 << "some stuff";

    return i * i;
}

This function was introduced in Qt 5.2.

See also qCTraceGuard() and QTraceGuard.

qCTraceGuard( category)

The macro expands to code that creates a guard object with automatic storage. The guard constructor checks whether QLoggingCategory::isTraceEnabled() evaluates to true. If so, the stream arguments are processed and the start() functions of the QTracer objects registered with the category are called.

The guard destructor also checks whether the category is enabled for tracing and if so, the end() functions of the QTracer objects registered with the category are called.

Note: Arguments are always processed, even if trace output for the category is disabled. They will, however, in that case not be passed to the record() functions of the registered tracers.

Example:

int foo(int i)
{
    qCTraceGuard(theFooArea);
    // Here could be some lengthy code.
    return i * i;
}

This function was introduced in Qt 5.2.

See also qCTrace() and QTracer.

qCWarning( category)

Returns an output stream for warning messages in the logging category category.

The macro expands to code that checks whether QLoggingCategory::isWarningEnabled() evaluates to true. If so, the stream arguments are processed and sent to the message handler.

Example:

    QLoggingCategory category("qt.driver.usb");
    qCWarning(category) << "a warning message";

Note: Arguments are not processed if warning output for the category is not enabled, so do not rely on any side effects.

This function was introduced in Qt 5.2.

See also qWarning().