QLoggingCategory Class

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

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A category names a part of a program, such as myapp.network, so that its messages can be turned on and off independently. Declare one in a header, define it in a source file, and log with the qCDebug(), qCInfo(), qCWarning(), qCCritical() and qCFatal() macros:

// network.h
Q_DECLARE_LOGGING_CATEGORY(lcNetwork)

// network.cpp
Q_LOGGING_CATEGORY(lcNetwork, "myapp.network")

qCDebug(lcNetwork) << "connecting to" << host;
qCWarning(lcNetwork, "timeout after %d ms", ms);

The arguments of a macro are not evaluated when the category does not enable that type of message.

Filter Rules

Which types of message a category enables is set by rules of the form category[.type] = true|false, where type is debug, info, warning or critical, and category may start and end with *. A rule without a type applies to all four types. Rules are separated by newlines or semicolons, and a later rule that matches overrides an earlier one. For example, "*.debug=false;myapp.network.debug=true" turns debug messages off, except those of myapp.network.

Rules come from these places, from the lowest precedence to the highest:

1. The QT_LOGGING_CONF file, which has them under a [Rules] heading.

2. setFilterRules().

3. The QT_LOGGING_RULES environment variable.

4. The filter installed with installFilter(), which has the last word.

By default all types are enabled. The "default" category, which holds the messages written with qDebug() and its relatives, follows the same rules.

See also QMessageLogger and QDebug.

Differences from Qt

Member Type Documentation

typedef QLoggingCategory::CategoryFilter

The type of a filter function: it is called with a category whose rules have been applied and may change which types are enabled.

Member Function Documentation

[explicit] QLoggingCategory::QLoggingCategory(const char *category, QtMsgType severityLevel = QtDebugMsg)

Constructs a category named category. Messages below the given severityLevel are disabled to begin with: the default, QtDebugMsg, enables all types, QtInfoMsg disables debug messages, QtWarningMsg disables debug and info messages, and QtCriticalMsg enables only critical ones. Filter rules and the installed filter then adjust that.

QLoggingCategory::~QLoggingCategory()

Destroys the category.

const char * QLoggingCategory::categoryName() const

Returns the name of the category.

[static] QLoggingCategory * QLoggingCategory::defaultCategory()

Returns the category of messages written without one, named "default". The qDebug(), qInfo(), qWarning() and qCritical() macros are filtered by it.

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

Installs a filter function that is called for every category, once its rules have been applied, and again whenever the rules change. The filter can enable or disable types of messages with setEnabled(). Returns the previously installed filter, or nullptr if there was none. Pass nullptr to remove the filter.

The filter is called with an internal lock held, so it must not create categories or change rules.

See also setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Returns true if critical messages are enabled for this category.

See also isEnabled().

bool QLoggingCategory::isDebugEnabled() const

Returns true if debug messages are enabled for this category.

See also isEnabled().

bool QLoggingCategory::isEnabled(QtMsgType type) const

Returns true if messages of the given type are enabled for this category. Fatal messages are always enabled.

See also setEnabled().

bool QLoggingCategory::isInfoEnabled() const

Returns true if info messages are enabled for this category.

See also isEnabled().

bool QLoggingCategory::isWarningEnabled() const

Returns true if warning messages are enabled for this category.

See also isEnabled().

QLoggingCategory & QLoggingCategory::operator()()

Returns a reference to this category. This lets a category object be used where a category function is expected, as in qCDebug(category).

const QLoggingCategory & QLoggingCategory::operator()() const

This is an overloaded function.

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

Changes whether messages of the given type are enabled to enable. Fatal messages cannot be disabled. A rule or filter applied later may override the change.

See also isEnabled().

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

Sets the filter rules to rules, replacing those set by an earlier call. The format is described in the class documentation. Rules in the QT_LOGGING_RULES environment variable take precedence.