\inmodule QtCore More...

#include <qloggingcategory.h>

Inheritance diagram for QLoggingCategory:

Collaboration diagram for QLoggingCategory:

Public Types
typedef void(*	CategoryFilter) (QLoggingCategory *)
	This is a typedef for a pointer to a function with the following signature:

Public Member Functions
	QLoggingCategory (const char *category, QtMsgType severityLevel=QtDebugMsg)
	Constructs a QLoggingCategory object with the provided category name, and enables all messages with types at least as verbose as enableForLevel, which defaults to QtDebugMsg (which enables all categories).

	~QLoggingCategory ()
	Destroys a QLoggingCategory object.

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

void	setEnabled (QtMsgType type, bool enable)
	Changes the message type type for the category to enable.

bool	isDebugEnabled () const
	Returns `true` if debug messages should be shown for this category; `false` otherwise.

bool	isInfoEnabled () const
	Returns `true` if informational messages should be shown for this category; `false` otherwise.

bool	isWarningEnabled () const
	Returns `true` if warning messages should be shown for this category; `false` otherwise.

bool	isCriticalEnabled () const
	Returns `true` if critical messages should be shown for this category; `false` otherwise.

const char *	categoryName () const
	Returns the name of the category.

QLoggingCategory &	operator() ()
	Returns the object itself.

const QLoggingCategory &	operator() () const
	Returns the object itself.

Static Public Member Functions
static QLoggingCategory *	defaultCategory ()
	Returns a pointer to the global category `"default"` that is used, for example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().

static CategoryFilter	installFilter (CategoryFilter)
	Take control of how logging categories are configured.

static void	setFilterRules (const QString &rules)
	Configures which categories and message types should be enabled through a set of rules.

Detailed Description

\inmodule QtCore

Since: 5.2 \threadsafe

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. An exception are fatal messages, which are always enabled.

To check whether a message type is enabled or not, use one of these methods: \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and \l isCriticalEnabled().

All objects are meant to be configured by a common registry, as described in \l{Configuring Categories}. Different objects can also represent the same category. Therefore, it's {not} recommended to export objects across module boundaries, to manipulate the objects directly, or to inherit from QLoggingCategory.

Definition at line 12 of file qloggingcategory.h.

Member Typedef Documentation

◆ CategoryFilter

typedef void(* QLoggingCategory::CategoryFilter) (QLoggingCategory *)

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 \l installFilter().

Definition at line 35 of file qloggingcategory.h.

Constructor & Destructor Documentation

◆ QLoggingCategory()

QLoggingCategory::QLoggingCategory	(	const char *	category,
		QtMsgType	enableForLevel = QtDebugMsg )

explicit

Constructs a QLoggingCategory object with the provided category name, and enables all messages with types at least as verbose as enableForLevel, which defaults to QtDebugMsg (which enables all categories).

If category is \nullptr, the category name "default" is used.

Note: category must be kept valid during the lifetime of this object. Using a string literal for it is the usual way to achieve this.

Since: 5.4

Definition at line 172 of file qloggingcategory.cpp.

◆ ~QLoggingCategory()

QLoggingCategory::~QLoggingCategory ( )

Destroys a QLoggingCategory object.

Definition at line 190 of file qloggingcategory.cpp.

Member Function Documentation

◆ categoryName()

const char * QLoggingCategory::categoryName ( ) const

inline

Returns the name of the category.

Definition at line 27 of file qloggingcategory.h.

◆ defaultCategory()

QLoggingCategory * QLoggingCategory::defaultCategory ( )

static

Returns a pointer to the global category "default" that is used, for example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().

Note: The pointer returned may be null during destruction of static objects. Also, don't delete this pointer, as ownership of the category isn't transferred.

Definition at line 310 of file qloggingcategory.cpp.

◆ installFilter()

QLoggingCategory::CategoryFilter QLoggingCategory::installFilter ( QLoggingCategory::CategoryFilter filter )

static

Take control of how logging categories are configured.

Installs a function filter that is used to determine which categories and message types should be enabled. If 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 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 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.

Example:

static QLoggingCategory::CategoryFilter oldCategoryFilter = nullptr;
 
void myCategoryFilter(QLoggingCategory *category)
{
    // 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);
}

installed (in {main()}, for example) by

oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);

Alternatively, you can configure the default filter via \l setFilterRules().

Definition at line 361 of file qloggingcategory.cpp.

◆ isCriticalEnabled()

bool QLoggingCategory::isCriticalEnabled ( ) const

inline

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

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

Definition at line 25 of file qloggingcategory.h.

◆ isDebugEnabled()

bool QLoggingCategory::isDebugEnabled ( ) const

inline

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

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

Definition at line 22 of file qloggingcategory.h.

◆ isEnabled()

bool QLoggingCategory::isEnabled ( QtMsgType type ) const

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

Definition at line 254 of file qloggingcategory.cpp.

◆ isInfoEnabled()

bool QLoggingCategory::isInfoEnabled ( ) const

inline

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

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

Since: 5.5

Definition at line 23 of file qloggingcategory.h.

◆ isWarningEnabled()

bool QLoggingCategory::isWarningEnabled ( ) const

inline

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

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

Definition at line 24 of file qloggingcategory.h.

◆ operator()() [1/2]

QLoggingCategory & QLoggingCategory::operator() ( )

inline

Returns the object itself.

This allows for both: a QLoggingCategory variable, and a factory method that returns a QLoggingCategory, to be used in \l qCDebug(), \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.

Definition at line 30 of file qloggingcategory.h.

◆ operator()() [2/2]

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

inline

Returns the object itself.

This allows for both: a QLoggingCategory variable, and a factory method that returns a QLoggingCategory, to be used in \l qCDebug(), \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.

Definition at line 31 of file qloggingcategory.h.

◆ setEnabled()

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

Changes the message type type for the category to enable.

This method is meant for use only from inside a filter installed with \l installFilter(). For an overview on how to configure categories globally, see \l {Configuring Categories}.

Note: QtFatalMsg cannot be changed; it will always remain true.

Definition at line 275 of file qloggingcategory.cpp.

◆ setFilterRules()

void QLoggingCategory::setFilterRules ( const QString & rules )

static

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

Example:

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

Note: The rules might be ignored if a custom category filter is installed with \l installFilter(), or if the user has defined the QT_LOGGING_CONF or the QT_LOGGING_RULES environment variable.

Definition at line 378 of file qloggingcategory.cpp.

Member Data Documentation

◆ bools

AtomicBools QLoggingCategory::bools

Definition at line 51 of file qloggingcategory.h.

◆ enabled

QBasicAtomicInt QLoggingCategory::enabled

Definition at line 52 of file qloggingcategory.h.

The documentation for this class was generated from the following files:

qtbase/src/corelib/io/qloggingcategory.h (c7ec043e4643d4b18731fdf2efc14976a81e1809)
qtbase/src/corelib/io/qloggingcategory.cpp (c7ec043e4643d4b18731fdf2efc14976a81e1809)

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CategoryFilter

Constructor & Destructor Documentation

◆ QLoggingCategory()

◆ ~QLoggingCategory()

Member Function Documentation

◆ categoryName()

◆ defaultCategory()

◆ installFilter()

◆ isCriticalEnabled()

◆ isDebugEnabled()

◆ isEnabled()

◆ isInfoEnabled()

◆ isWarningEnabled()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ setEnabled()

◆ setFilterRules()

Member Data Documentation

◆ bools

◆ enabled