QLoggingCategory¶

PyQt5.QtCore.QLoggingCategory

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. A category can be configured to enable or disable logging of messages per message type. Whether a message type is enabled or not can be checked with the isDebugEnabled(), isInfoEnabled(), isWarningEnabled(), and isCriticalEnabled() methods.

All objects are meant to be configured by a common registry (see also Configuring Categories). Different objects can also represent the same category. It is therefore not recommended to export objects across module boundaries, nor to manipulate the objects directly, nor to inherit from QLoggingCategory.

Creating Category Objects¶

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

# This code needs porting to Python.

# /****************************************************************************
# **
# ** Copyright (C) 2016 The Qt Company Ltd.
# ** Contact: https://www.qt.io/licensing/
# **
# ** This file is part of the examples of the Qt Toolkit.
# **
# ** $QT_BEGIN_LICENSE:BSD$
# ** Commercial License Usage
# ** Licensees holding valid commercial Qt licenses may use this file in
# ** accordance with the commercial license agreement provided with the
# ** Software or, alternatively, in accordance with the terms contained in
# ** a written agreement between you and The Qt Company. For licensing terms
# ** and conditions see https://www.qt.io/terms-conditions. For further
# ** information use the contact form at https://www.qt.io/contact-us.
# **
# ** BSD License Usage
# ** Alternatively, you may use this file under the terms of the BSD license
# ** as follows:
# **
# ** "Redistribution and use in source and binary forms, with or without
# ** modification, are permitted provided that the following conditions are
# ** met:
# **   * Redistributions of source code must retain the above copyright
# **     notice, this list of conditions and the following disclaimer.
# **   * Redistributions in binary form must reproduce the above copyright
# **     notice, this list of conditions and the following disclaimer in
# **     the documentation and/or other materials provided with the
# **     distribution.
# **   * Neither the name of The Qt Company Ltd nor the names of its
# **     contributors may be used to endorse or promote products derived
# **     from this software without specific prior written permission.
# **
# **
# ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
# **
# ** $QT_END_LICENSE$
# **
# ****************************************************************************/

# #include <QCoreApplication>
# #include <QLoggingCategory>

# //![1]
# // in a header
# Q_DECLARE_LOGGING_CATEGORY(driverUsb)

# // in one source file
# Q_LOGGING_CATEGORY(driverUsb, "driver.usb")
# //![1]

# //![5]
# Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)
# //![5]

# // Completely made up example, inspired by en.wikipedia.org/wiki/USB :)
# struct UsbEntry {
#     int id;
#     int classtype;
# };

# QDebug operator<<(QDebug &debug, const UsbEntry &entry)
# {
#     QDebugStateSaver saver(debug);
#     debug.nospace() << "" << entry.id << " (" << entry.classtype << ')';
#     return debug;
# }

# QList<UsbEntry> usbEntries() {
#     QList<UsbEntry> entries;
#     return entries;
# }

# //![20]
# void myCategoryFilter(QLoggingCategory *);
# //![20]

# //![21]
# QLoggingCategory::CategoryFilter oldCategoryFilter;

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

# int main(int argc, char *argv[])
# {
#     QCoreApplication a(argc, argv);

# //![2]
#     QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));
# //![2]

# //![22]

# // ...
# oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);
# //![22]

# //![3]
#     qSetMessagePattern("%{category} %{message}");
# //![3]

# //![4]
#     // usbEntries() will only be called if driverUsb category is enabled
#     qCDebug(driverUsb) << "devices: " << usbEntries();
# //![4]

#     {
# //![10]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category) << "a debug message";
# //![10]
#     }

# //![qcinfo_stream]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category) << "an informational message";
# //![qcinfo_stream]

#     {
# //![11]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category) << "a warning message";
# //![11]
#     }

#     {
# //![12]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category) << "a critical message";
# //![12]
#     }

#     {
# //![13]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category, "a debug message logged into category %s", category.categoryName());
# //![13]
#     }

#     {
# //![qcinfo_printf]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category, "an informational message logged into category %s", category.categoryName());
# //![qcinfo_printf]
#     }

#     {
# //![14]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category, "a warning message logged into category %s", category.categoryName());
# //![14]
#     }

#     {
# //![15]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category, "a critical message logged into category %s", category.categoryName());
# //![15]
#     }

#     return 0;
# }

Note: Category names are free text. However, to allow easy configuration of the categories using Logging Rules the names should follow some rules:

Use letters and numbers only.
Further structure categories into common areas by using dots.
Avoid the category names debug, info, warning, and critical.
Category names starting with qt are reserved for Qt modules.

QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY() are created on first use in a thread-safe manner.

Checking Category Configuration¶

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

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

# This code needs porting to Python.

# /****************************************************************************
# **
# ** Copyright (C) 2016 The Qt Company Ltd.
# ** Contact: https://www.qt.io/licensing/
# **
# ** This file is part of the examples of the Qt Toolkit.
# **
# ** $QT_BEGIN_LICENSE:BSD$
# ** Commercial License Usage
# ** Licensees holding valid commercial Qt licenses may use this file in
# ** accordance with the commercial license agreement provided with the
# ** Software or, alternatively, in accordance with the terms contained in
# ** a written agreement between you and The Qt Company. For licensing terms
# ** and conditions see https://www.qt.io/terms-conditions. For further
# ** information use the contact form at https://www.qt.io/contact-us.
# **
# ** BSD License Usage
# ** Alternatively, you may use this file under the terms of the BSD license
# ** as follows:
# **
# ** "Redistribution and use in source and binary forms, with or without
# ** modification, are permitted provided that the following conditions are
# ** met:
# **   * Redistributions of source code must retain the above copyright
# **     notice, this list of conditions and the following disclaimer.
# **   * Redistributions in binary form must reproduce the above copyright
# **     notice, this list of conditions and the following disclaimer in
# **     the documentation and/or other materials provided with the
# **     distribution.
# **   * Neither the name of The Qt Company Ltd nor the names of its
# **     contributors may be used to endorse or promote products derived
# **     from this software without specific prior written permission.
# **
# **
# ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
# **
# ** $QT_END_LICENSE$
# **
# ****************************************************************************/

# #include <QCoreApplication>
# #include <QLoggingCategory>

# //![1]
# // in a header
# Q_DECLARE_LOGGING_CATEGORY(driverUsb)

# // in one source file
# Q_LOGGING_CATEGORY(driverUsb, "driver.usb")
# //![1]

# //![5]
# Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)
# //![5]

# // Completely made up example, inspired by en.wikipedia.org/wiki/USB :)
# struct UsbEntry {
#     int id;
#     int classtype;
# };

# QDebug operator<<(QDebug &debug, const UsbEntry &entry)
# {
#     QDebugStateSaver saver(debug);
#     debug.nospace() << "" << entry.id << " (" << entry.classtype << ')';
#     return debug;
# }

# QList<UsbEntry> usbEntries() {
#     QList<UsbEntry> entries;
#     return entries;
# }

# //![20]
# void myCategoryFilter(QLoggingCategory *);
# //![20]

# //![21]
# QLoggingCategory::CategoryFilter oldCategoryFilter;

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

# int main(int argc, char *argv[])
# {
#     QCoreApplication a(argc, argv);

# //![2]
#     QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));
# //![2]

# //![22]

# // ...
# oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);
# //![22]

# //![3]
#     qSetMessagePattern("%{category} %{message}");
# //![3]

# //![4]
#     // usbEntries() will only be called if driverUsb category is enabled
#     qCDebug(driverUsb) << "devices: " << usbEntries();
# //![4]

#     {
# //![10]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category) << "a debug message";
# //![10]
#     }

# //![qcinfo_stream]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category) << "an informational message";
# //![qcinfo_stream]

#     {
# //![11]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category) << "a warning message";
# //![11]
#     }

#     {
# //![12]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category) << "a critical message";
# //![12]
#     }

#     {
# //![13]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category, "a debug message logged into category %s", category.categoryName());
# //![13]
#     }

#     {
# //![qcinfo_printf]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category, "an informational message logged into category %s", category.categoryName());
# //![qcinfo_printf]
#     }

#     {
# //![14]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category, "a warning message logged into category %s", category.categoryName());
# //![14]
#     }

#     {
# //![15]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category, "a critical message logged into category %s", category.categoryName());
# //![15]
#     }

#     return 0;
# }

Default Category Configuration¶

Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro accept an optional QtMsgType argument, which disables all message types with a lower severity. That is, a category declared with

# This code needs porting to Python.

# /****************************************************************************
# **
# ** Copyright (C) 2016 The Qt Company Ltd.
# ** Contact: https://www.qt.io/licensing/
# **
# ** This file is part of the examples of the Qt Toolkit.
# **
# ** $QT_BEGIN_LICENSE:BSD$
# ** Commercial License Usage
# ** Licensees holding valid commercial Qt licenses may use this file in
# ** accordance with the commercial license agreement provided with the
# ** Software or, alternatively, in accordance with the terms contained in
# ** a written agreement between you and The Qt Company. For licensing terms
# ** and conditions see https://www.qt.io/terms-conditions. For further
# ** information use the contact form at https://www.qt.io/contact-us.
# **
# ** BSD License Usage
# ** Alternatively, you may use this file under the terms of the BSD license
# ** as follows:
# **
# ** "Redistribution and use in source and binary forms, with or without
# ** modification, are permitted provided that the following conditions are
# ** met:
# **   * Redistributions of source code must retain the above copyright
# **     notice, this list of conditions and the following disclaimer.
# **   * Redistributions in binary form must reproduce the above copyright
# **     notice, this list of conditions and the following disclaimer in
# **     the documentation and/or other materials provided with the
# **     distribution.
# **   * Neither the name of The Qt Company Ltd nor the names of its
# **     contributors may be used to endorse or promote products derived
# **     from this software without specific prior written permission.
# **
# **
# ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
# **
# ** $QT_END_LICENSE$
# **
# ****************************************************************************/

# #include <QCoreApplication>
# #include <QLoggingCategory>

# //![1]
# // in a header
# Q_DECLARE_LOGGING_CATEGORY(driverUsb)

# // in one source file
# Q_LOGGING_CATEGORY(driverUsb, "driver.usb")
# //![1]

# //![5]
# Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)
# //![5]

# // Completely made up example, inspired by en.wikipedia.org/wiki/USB :)
# struct UsbEntry {
#     int id;
#     int classtype;
# };

# QDebug operator<<(QDebug &debug, const UsbEntry &entry)
# {
#     QDebugStateSaver saver(debug);
#     debug.nospace() << "" << entry.id << " (" << entry.classtype << ')';
#     return debug;
# }

# QList<UsbEntry> usbEntries() {
#     QList<UsbEntry> entries;
#     return entries;
# }

# //![20]
# void myCategoryFilter(QLoggingCategory *);
# //![20]

# //![21]
# QLoggingCategory::CategoryFilter oldCategoryFilter;

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

# int main(int argc, char *argv[])
# {
#     QCoreApplication a(argc, argv);

# //![2]
#     QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));
# //![2]

# //![22]

# // ...
# oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);
# //![22]

# //![3]
#     qSetMessagePattern("%{category} %{message}");
# //![3]

# //![4]
#     // usbEntries() will only be called if driverUsb category is enabled
#     qCDebug(driverUsb) << "devices: " << usbEntries();
# //![4]

#     {
# //![10]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category) << "a debug message";
# //![10]
#     }

# //![qcinfo_stream]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category) << "an informational message";
# //![qcinfo_stream]

#     {
# //![11]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category) << "a warning message";
# //![11]
#     }

#     {
# //![12]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category) << "a critical message";
# //![12]
#     }

#     {
# //![13]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category, "a debug message logged into category %s", category.categoryName());
# //![13]
#     }

#     {
# //![qcinfo_printf]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category, "an informational message logged into category %s", category.categoryName());
# //![qcinfo_printf]
#     }

#     {
# //![14]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category, "a warning message logged into category %s", category.categoryName());
# //![14]
#     }

#     {
# //![15]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category, "a critical message logged into category %s", category.categoryName());
# //![15]
#     }

#     return 0;
# }

will log messages of type QtWarningMsg, QtCriticalMsg, QtFatalMsg, but will ignore messages of type QtDebugMsg and QtInfoMsg.

If no argument is passed, all messages will be logged.

Configuring Categories¶

The default configuration of categories can be overridden either by setting logging rules, or by installing a custom filter.

Logging Rules¶

Logging rules allow logging for categories to be enabled or disabled in a flexible way. Rules are specified in text, where every line must have the format

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

<category> is the name of the category, potentially with \* as a wildcard symbol as the first or last character (or at both positions). The optional <type> must be either debug, info, warning, or critical. Lines that do not fit this scheme are ignored.

Rules are evaluated in text order, from first to last. That is, if two rules apply to a category/type, the rule that comes later is applied.

Rules can be set via setFilterRules():

#     QLoggingCategory::setFilterRules("*.debug=false\n"
#                                      "driver.usb.debug=true");

Since Qt 5.3, logging rules are also automatically loaded from the [Rules] section of a logging configuration file. Such configuration files are looked up in the QtProject configuration directory, or explicitly set in a QT_LOGGING_CONF environment variable:

#     [Rules]
#     *.debug=false
#     driver.usb.debug=true

Since Qt 5.3, logging rules can also be specified in a QT_LOGGING_RULES environment variable. And since Qt 5.6, multiple rules can also be separated by semicolons:

#     QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"

Rules set by setFilterRules() take precedence over rules specified in the QtProject configuration directory, and can, in turn, be overwritten by rules from the configuration file specified by QT_LOGGING_CONF, and rules set by QT_LOGGING_RULES.

Order of evaluation:

[DataPath]/qtlogging.ini
QtProject/qtlogging.ini
setFilterRules()
QT_LOGGING_CONF
QT_LOGGING_RULES

The QtProject/qtlogging.ini file is looked up in all directories returned by GenericConfigLocation, e.g.

on macOS and iOS: ~/Library/Preferences
on Unix: ~/.config, /etc/xdg
on Windows: %LOCALAPPDATA%, %ProgramData%, applicationDirPath(), applicationDirPath() + "/data"

Set the QT_LOGGING_DEBUG environment variable to see from where logging rules are loaded.

Installing a Custom Filter¶

As a lower-level alternative to the text rules, you can also implement a custom filter via installFilter(). All filter rules are ignored in this case.

Printing the Category¶

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

# This code needs porting to Python.

# /****************************************************************************
# **
# ** Copyright (C) 2016 The Qt Company Ltd.
# ** Contact: https://www.qt.io/licensing/
# **
# ** This file is part of the examples of the Qt Toolkit.
# **
# ** $QT_BEGIN_LICENSE:BSD$
# ** Commercial License Usage
# ** Licensees holding valid commercial Qt licenses may use this file in
# ** accordance with the commercial license agreement provided with the
# ** Software or, alternatively, in accordance with the terms contained in
# ** a written agreement between you and The Qt Company. For licensing terms
# ** and conditions see https://www.qt.io/terms-conditions. For further
# ** information use the contact form at https://www.qt.io/contact-us.
# **
# ** BSD License Usage
# ** Alternatively, you may use this file under the terms of the BSD license
# ** as follows:
# **
# ** "Redistribution and use in source and binary forms, with or without
# ** modification, are permitted provided that the following conditions are
# ** met:
# **   * Redistributions of source code must retain the above copyright
# **     notice, this list of conditions and the following disclaimer.
# **   * Redistributions in binary form must reproduce the above copyright
# **     notice, this list of conditions and the following disclaimer in
# **     the documentation and/or other materials provided with the
# **     distribution.
# **   * Neither the name of The Qt Company Ltd nor the names of its
# **     contributors may be used to endorse or promote products derived
# **     from this software without specific prior written permission.
# **
# **
# ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
# **
# ** $QT_END_LICENSE$
# **
# ****************************************************************************/

# #include <QCoreApplication>
# #include <QLoggingCategory>

# //![1]
# // in a header
# Q_DECLARE_LOGGING_CATEGORY(driverUsb)

# // in one source file
# Q_LOGGING_CATEGORY(driverUsb, "driver.usb")
# //![1]

# //![5]
# Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)
# //![5]

# // Completely made up example, inspired by en.wikipedia.org/wiki/USB :)
# struct UsbEntry {
#     int id;
#     int classtype;
# };

# QDebug operator<<(QDebug &debug, const UsbEntry &entry)
# {
#     QDebugStateSaver saver(debug);
#     debug.nospace() << "" << entry.id << " (" << entry.classtype << ')';
#     return debug;
# }

# QList<UsbEntry> usbEntries() {
#     QList<UsbEntry> entries;
#     return entries;
# }

# //![20]
# void myCategoryFilter(QLoggingCategory *);
# //![20]

# //![21]
# QLoggingCategory::CategoryFilter oldCategoryFilter;

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

# int main(int argc, char *argv[])
# {
#     QCoreApplication a(argc, argv);

# //![2]
#     QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));
# //![2]

# //![22]

# // ...
# oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);
# //![22]

# //![3]
#     qSetMessagePattern("%{category} %{message}");
# //![3]

# //![4]
#     // usbEntries() will only be called if driverUsb category is enabled
#     qCDebug(driverUsb) << "devices: " << usbEntries();
# //![4]

#     {
# //![10]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category) << "a debug message";
# //![10]
#     }

# //![qcinfo_stream]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category) << "an informational message";
# //![qcinfo_stream]

#     {
# //![11]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category) << "a warning message";
# //![11]
#     }

#     {
# //![12]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category) << "a critical message";
# //![12]
#     }

#     {
# //![13]
#     QLoggingCategory category("driver.usb");
#     qCDebug(category, "a debug message logged into category %s", category.categoryName());
# //![13]
#     }

#     {
# //![qcinfo_printf]
#     QLoggingCategory category("driver.usb");
#     qCInfo(category, "an informational message logged into category %s", category.categoryName());
# //![qcinfo_printf]
#     }

#     {
# //![14]
#     QLoggingCategory category("driver.usb");
#     qCWarning(category, "a warning message logged into category %s", category.categoryName());
# //![14]
#     }

#     {
# //![15]
#     QLoggingCategory category("driver.usb");
#     qCCritical(category, "a critical message logged into category %s", category.categoryName());
# //![15]
#     }

#     return 0;
# }

Methods¶

__init__(str)

Constructs a QLoggingCategory object with the provided category name. All message types for this category are enabled by default.

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

Note that category must be kept valid during the lifetime of this object.

__init__(str, QtMsgType)

Constructs a QLoggingCategory object with the provided category name, and enables all messages with types more severe or equal than enableForLevel.

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

Note that category must be kept valid during the lifetime of this object.

__call__() → QLoggingCategory: TODO

categoryName() → str: TODO

@staticmethod defaultCategory() → QLoggingCategory

Returns a pointer to the global category "default" that is used e.g. by qDebug(), qInfo(), 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.

isCriticalEnabled() → bool: TODO

isDebugEnabled() → bool: TODO

isEnabled(QtMsgType) → bool: Returns true if a message of type msgtype for the category should be shown. Returns false otherwise.

isInfoEnabled() → bool: TODO

isWarningEnabled() → bool: TODO

setEnabled(QtMsgType, bool)

Changes the message type type for the category to enable.

This method is meant to be used only from inside a filter installed by installFilter(). See Configuring Categories for an overview on how to configure categories globally.

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