Qt5.6文档翻译：QLoggingCategory类,QLoggingCategory Class

QLoggingCategory 类，表示的是，日志系统中的一个分类，或者说“区域”。 详细说明……

详细说明

QLoggingCategory 类，表示的是，日志系统中的一个分类，或者说“区域”。

QLoggingCategory ，代表 的是，在运行时刻的某个特定的日志分类，这些分类由字符串来区分。对于 一个分类，可对其进行配置，以使得它针对 每种消息类型分别启用或禁用日志功能。对于每种消息类型 ，究竟它是启用了，还是禁用了，可通过 isDebugEnabled () 、 isInfoEnabled () 、 isWarningEnabled () 和 isCriticalEnabled ()方法来查询。

所有 的对象，都可通过一个公共的注册表来配置（参考 配置分类 ）。 不同的对象也可以代表同一个分类。因此 ，不建议将这些对象暴露到模块的边界之外，也不建议直接操作这些对象，也不建议继承 QLoggingCategory 。

创建分类对象

Q_DECLARE_LOGGING_CATEGORY () 和 Q_LOGGING_CATEGORY () 宏，可用来方便地声明及创建 QLoggingCategory 对象：

// 头文件中

Q_DECLARE_LOGGING_CATEGORY(driverUsb)

// 源文件中

Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

检查分类配置

QLoggingCategory 提供 了 isDebugEnabled () 、 isInfoEnabled () 、 isWarningEnabled () 、 isCriticalEnabled () 以及 isEnabled ()方法 ，用于检查，对于指定的消息类型，是否应当向日志中输出消息。

注意 ： qCDebug () 、 qCWarning () 、 qCCritical () 这些宏， 当它们发现指定分类中的对应消息类型未被启用时， 就不会对其参数进行算值动作，因此，使用 这些宏的时候不需要显式地检查：

// 只有 在driverUsb 分类被启用的情况下， usbEntries() 才会被调用

qCDebug(driverUsb) << "devices: " << usbEntries();

默认分类配置

QLoggingCategory 构造函数 和 Q_LOGGING_CATEGORY () 宏都接受一个可选的 QtMsgType 参数， 它会禁用掉严重程度比自己低的消息类型。也就是说，以如下代码声明的分类

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg )

会向日志中输出 QtWarningMsg 、 QtCriticalMsg 、 QtFatalMsg 类型的消息， 但会忽略 QtDebugMsg 和 QtInfoMsg 类型的消息。

如果未传入参数，那么，所有消息类型都会被输出到日志。

配置分类

日志规则

可使用 setFilterRules ()来设置规则。 从Qt 5.3 开始，日志规则 可通过环境变量 QT_LOGGING_RULES 来设置，而且 会自动从某个日志配置文件的 [Rules] 小节中读取。对于 这样的配置文件， 会在QtProject 配置目录中查找，或者，也可以使用环境变量 QT_LOGGING_CONF 来显式设置：

[Rules]

*.debug=false

driver.usb.debug=true

使用 setFilterRules ()设置 的规则，优先 级比 QtProject 配置目录中指定的优先级高 。 同时， 它又会被 QT_LOGGING_CONF 所指定的配置文件中的规则所覆盖，也会被 QT_LOGGING_RULES 中设置的规则所覆盖。

自Qt 5.6 开始， QT_LOGGING_RULES 中可包含多条规则，以分号分隔：

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

解析顺序：

• •. [ QLibraryInfo::DataPath ]/qtlogging.ini

• •.QtProject/qtlogging.ini

• •. setFilterRules ()

• •. QT_LOGGING_CONF

• •. QT_LOGGING_RULES

对于QtProject/qtlogging.ini 文件 ，会在 QStandardPaths::GenericConfigLocation 返回的所有目录中寻找，例如：

• •. 在 Unix 中： ~/.config 、 /etc/xdg

设置 QT_LOGGING_DEBUG 环境变量 ，即可看到，日志规则都是从哪里载入的。

安装一个自定义过滤器

作为对于文本规则 的一个低层次的替代，妳也可以选择通过 installFilter ()来实现一个自定义的过滤器。 在这种情况下，所有的过滤规则都会被忽略。

输出分类

qSetMessagePattern ("%{category} %{message}");

成员类型文档

typedef QLoggingCategory::CategoryFilter

void myCategoryFilter( QLoggingCategory *);

具有 这种格式的函数，可通过 installFilter ()来进行安装。

成员函数文档

QLoggingCategory::QLoggingCategory(const char *category)

构造 一个 QLoggingCategory 对象，并采用指定的分类名 category 。 这个分类的所有消息类型，默认都是启用的。

如果 category 为 0 ，则，分类名会被修改为 "default" 。

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

构造 一个 QLoggingCategory 对象，采用指定的分类名 category ，并且针对所有 其严重性大于或等于 enableForLevel 的消息都启用其输出。

如果 category 为 0 ，则，分类名会被修改为 "default" 。

此函数是从Qt 5.4 开始引入的。

QLoggingCategory::~QLoggingCategory()

销毁 一个 QLoggingCategory 对象。

const char *QLoggingCategory::categoryName() const

[static] QLoggingCategory  *QLoggingCategory:: defaultCategory ()

返回指向全局分类 "default" 的一个指针， 它被 qDebug () 、 qInfo () 、 qWarning () 、 qCritical () 、 qFatal ()等代码使用。

注意 ： 在对静态对象进行析构的过程中，所返回的这个指针可能为空。

注意 ： 该分类的所有权并未转移，不要对这里所返回的指针进行删除（ delete ）操作。

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

安装一个函数 filter ，它会被用来决定，哪些分类和消息种类应当被启用。返回指向前任过滤器的一个指针。

每一个被创建的 QLoggingCategory 对象，都会被传递给该过滤器， 该过滤器可以自由 地使用 setEnabled ()来改变对应分类 的配置。

这个过滤器可能会被多个线程并发调用，因此，必须是可重入的。

示例：

QLoggingCategory ::CategoryFilter oldCategoryFilter;

void myCategoryFilter( QLoggingCategory *category)

{

// 此处 只对driver.usb 分类进行配置，对于其它分类，转发给默认过滤器。

if (qstrcmp(category->categoryName(), "driver.usb") == 0)

category->setEnabled( QtDebugMsg , true);

else

oldCategoryFilter(category);

}

另一种方式就是，配置默认过滤器，即，调用 setFilterRules ()。

bool QLoggingCategory::isCriticalEnabled() const

注意 ： qCCritical () 宏，在执行任何代码之前，会进行这项检查。然而 ，调用 这个方法还是有用处的，例如， 可用来避免生成那些 狠耗资源却又只用于调试用途的数据。

bool QLoggingCategory::isDebugEnabled() const

注意 ： qCDebug () 宏，在执行任何代码之前，会进行这项检查。然而 ，调用 这个方法还是有用处的，例如， 可用来避免生成那些 狠耗资源却又只用于调试用途的数据。

bool  QLoggingCategory:: isEnabled ( QtMsgType msgtype ) const

如果对于 这个分类应当输出 msgtype 类型的消息，则返回真（ true ）。否则返回假（ false ）。

bool QLoggingCategory::isInfoEnabled() const

注意 ： qCInfo () 宏，在执行任何代码之前，会进行这项检查。然而 ，调用 这个方法还是有用处的，例如， 可用来避免生成那些 狠耗资源却又只用于调试用途的数据。

此函数是从Qt 5.5 开始引入的。

bool QLoggingCategory::isWarningEnabled() const

注意 ： qCWarning () 宏，在执行任何代码之前，会进行这项检查。然而 ，调用 这个方法还是有用处的，例如， 可用来避免生成那些 狠耗资源却又只用于调试用途的数据。

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

将此分类中 type 消息类型的设定修改为 enable 。

注意 ： 这只会影响到当前 QLoggingCategory 对象， 而不会影响到具有相同分类名字的其它对象中的设置。使用 setFilterRules () 或 installFilter ()来在全局范围改变该配置。

注意 ： QtFatalMsg 无法 被改变。它一定会返回真（ true ）。

参考 isEnabled () 。

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

利用一组规则集合 rules 来配置要启用哪些分类和哪些消息类型。

示例：

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

注意 ： 以下情况下，此处设置的规则可能会被忽略：使用 installFilter ()安装 了一个自定义过滤器；或者 ，用户定义了 QT_LOGGING_CONF 或 QT_LOGGING_RULES 环境变量。

QLoggingCategory  &QLoggingCategory:: operator() ()

返回 该对象本身。 这样，就使得， QLoggingCategory 变量，以及返回 QLoggingCategory 的工厂方法，能够被 qCDebug () 、 qCWarning () 、 qCCritical ()宏所使用。

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

返回 该对象本身。 这样，就使得， QLoggingCategory 变量，以及返回 QLoggingCategory 的工厂方法，能够被 qCDebug () 、 qCWarning () 、 qCCritical ()宏所使用。

宏文档

Q_DECLARE_LOGGING_CATEGORY(name)

参考 Q_LOGGING_CATEGORY () 。

Q_LOGGING_CATEGORY(name, string)

参考 Q_DECLARE_LOGGING_CATEGORY () 。

Q_LOGGING_CATEGORY(name, string, msgType)

定义 一个日志分类名 name ，并且使得它可以通过 string 标识符来配置。默认情况 下，严重程度 为 QtMsgType msgType 及以上的消息会被启用，严重程度低于它的消息会被禁用。

在一个库或可执行程序中，只能有一个翻译单元能定义带有特殊名字的分类。

这个宏，必须在类或方法的范围之外使用。只有在支持变长参数宏的情况下，它才会被定义。

此函数是从Qt 5.4 开始引入的。

参考 Q_DECLARE_LOGGING_CATEGORY () 。

qCCritical(category)

这个宏，展开后，其代码会检查 QLoggingCategory::isCriticalEnabled ()是否为真（ true ）。如果 确实为真，则， 向该流提供的参数会被处理，并且发往消息处理器。

示例：

QLoggingCategory category("driver.usb");

qCCritical(category) << "a critical message";

注意 ：如果对于该分类未启用致命级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.2 开始引入的。

参考 qCritical () 。

qCCritical(category, const char *message, ... )

QLoggingCategory category("driver.usb");

qCCritical(category, "a critical message logged into category %s", category.categoryName());

注意 ：如果对于该分类未启用致命级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.3 开始引入的。

参考 qCritical () 。

qCDebug(category)

这个宏，展开后，其代码会检查 QLoggingCategory::isDebugEnabled ()是否为真（ true ）。 如果 确实为真，则， 向该流提供的参数会被处理，并且发往消息处理器。

示例：

QLoggingCategory category("driver.usb");

qCDebug(category) << "a debug message";

注意 ：如果对于该分类未启用调试级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.2 开始引入的。

参考 qDebug () 。

qCDebug(category, const char *message, ... )

QLoggingCategory category("driver.usb");

qCDebug(category, "a debug message logged into category %s", category.categoryName());

注意 ：如果对于该分类未启用调试级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.3 开始引入的。

参考 qDebug () 。

qCInfo(category)

这个宏，展开后，其代码会检查 QLoggingCategory::isInfoEnabled ()是否为真（ true ）。 如果 确实为真，则， 向该流提供的参数会被处理，并且发往消息处理器。

示例：

QLoggingCategory category("driver.usb");

qCInfo(category) << "an informational message";

注意 ：如果对于该分类未启用信息级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.5 开始引入的。

参考 qInfo () 。

qCInfo(category, const char *message, ... )

QLoggingCategory category("driver.usb");

qCInfo(category, "an informational message logged into category %s", category.categoryName());

注意 ：如果对于该分类未启用信息级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.5 开始引入的。

参考 qInfo () 。

qCWarning(category)

这个宏，展开后，其代码会检查 QLoggingCategory::isWarningEnabled ()是否为真（ true ）。 如果 确实为真，则， 向该流提供的参数会被处理，并且发往消息处理器。

示例：

QLoggingCategory category("driver.usb");

qCWarning(category) << "a warning message";

注意 ：如果对于该分类未启用警告级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.2 开始引入的。

参考 qWarning () 。

qCWarning(category, const char *message, ... )

QLoggingCategory category("driver.usb");

qCWarning(category, "a warning message logged into category %s", category.categoryName());

注意 ：如果对于该分类未启用警告级别的消息输出，那么，参数都不会被处理，因此，不要想着依靠任何副作用来工作。

此函数是从Qt 5.3 开始引入的。

参考 qWarning () 。

江欣燕

伊能静，但伊不肯