diff --git a/src/corelib/doc/snippets/qloggingcategory/main.cpp b/src/corelib/doc/snippets/qloggingcategory/main.cpp index b8483087c84..33aba3bf354 100644 --- a/src/corelib/doc/snippets/qloggingcategory/main.cpp +++ b/src/corelib/doc/snippets/qloggingcategory/main.cpp @@ -1,4 +1,4 @@ -// Copyright (C) 2016 The Qt Company Ltd. +// Copyright (C) 2022 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include @@ -39,15 +39,20 @@ void myCategoryFilter(QLoggingCategory *); //![20] //![21] -QLoggingCategory::CategoryFilter oldCategoryFilter; +static QLoggingCategory::CategoryFilter oldCategoryFilter = nullptr; void myCategoryFilter(QLoggingCategory *category) { - // configure driver.usb category here, otherwise forward to to default filter. + // For a category set up after this filter is installed, we first set it up + // with the old filter. This ensures that any driver.usb logging configured + // by the user is kept, aside from the one level we override; and any new + // categories we're not interested in get configured by the old filter. + if (oldCategoryFilter) + oldCategoryFilter(category); + + // Tweak driver.usb's logging, over-riding the default filter: if (qstrcmp(category->categoryName(), "driver.usb") == 0) category->setEnabled(QtDebugMsg, true); - else - oldCategoryFilter(category); } //![21] @@ -60,8 +65,6 @@ int main(int argc, char *argv[]) //![2] //![22] - -// ... oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter); //![22] diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp index 1a84f6359cf..08b7b2d5848 100644 --- a/src/corelib/io/qloggingcategory.cpp +++ b/src/corelib/io/qloggingcategory.cpp @@ -343,13 +343,27 @@ QLoggingCategory *QLoggingCategory::defaultCategory() */ /*! - Installs a function \a filter that is used to determine which categories - and message types should be enabled. Returns a pointer to the previous - installed filter. + \brief Take control of how logging categories are configured. - Every QLoggingCategory object created is passed to the filter, and the - filter is free to change the respective category configuration with - \l setEnabled(). + Installs a function \a filter that is used to determine which categories and + message types should be enabled. If \a filter is \nullptr, the default + message filter is reinstated. Returns a pointer to the previously-installed + filter. + + Every QLoggingCategory object that already exists is passed to the filter + before \c installFilter() returns, and the filter is free to change each + category's configuration with \l setEnabled(). Any category it doesn't + change will retain the configuration it was given by the prior filter, so + the new filter does not need to delegate to the prior filter during this + initial pass over existing categories. + + Any new categories added later will be passed to the new filter; a filter + that only aims to tweak the configuration of a select few categories, rather + than completely overriding the logging policy, can first pass the new + category to the prior filter, to give it its standard configuration, and + then tweak that as desired, if it is one of the categories of specific + interest to the filter. The code that installs the new filter can record the + return from \c installFilter() for the filter to use in such later calls. When you define your filter, note that it can be called from different threads; but never concurrently. This filter cannot call any static functions from QLoggingCategory. @@ -357,6 +371,10 @@ QLoggingCategory *QLoggingCategory::defaultCategory() Example: \snippet qloggingcategory/main.cpp 21 + installed (in \c{main()}, for example) by + + \snippet qloggingcategory/main.cpp 22 + Alternatively, you can configure the default filter via \l setFilterRules(). */ QLoggingCategory::CategoryFilter