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().