Класс QLoggingCategory

Класс QLoggingCategory представляет категорию или «область» в инфраструктуре регистрации. Подробнее...

• Список всех членов, включая унаследованные

Открытые типы

Открытые функции

Статические публичные члены

Макросы

Подробное описание

Класс QLoggingCategory представляет категорию или «область» в инфраструктуре ведения журнала.

QLoggingCategory представляет определённую категорию ведения журнала — идентифицируемую строкой — во время выполнения. Категория может быть настроена для включения или отключения ведения журнала сообщений по типу сообщения. Возможность включения или выключения типа сообщения можно проверить с помощью методов isDebugEnabled(), isInfoEnabled(), isWarningEnabled() и isCriticalEnabled().

Все объекты предназначены для настройки с помощью общего реестра (см. также Настройка категорий). Разные объекты также могут представлять одну и ту же категорию. Поэтому не рекомендуется экспортировать объекты через граничные модули, манипулировать объектами напрямую или наследоваться от QLoggingCategory.

Создание объектов категории

Макросы Q_DECLARE_LOGGING_CATEGORY() и Q_LOGGING_CATEGORY() удобно объявляют и создают объекты QLoggingCategory:

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)

// in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

Примечание: Имена категорий — свободный текст. Однако для удобной настройки категорий с помощью Правил ведения журнала имена должны следовать некоторым правилам:

• Используйте только буквы и цифры.
• Дальнейшую структуру категорий в общие области создайте с помощью точек.
• Избегайте имён категорий debug, info, warning, и critical.
• Имена категорий, начинающиеся с qt, зарезервированы для модулей Qt.

Проверка конфигурации категории

QLoggingCategory предоставляет isDebugEnabled(), isInfoEnabled(), isWarningEnabled(), isCriticalEnabled(), а также isEnabled() для проверки, должны ли сообщения данного типа сообщения быть записаны в журнал.

Примечание: Макросы qCDebug(), qCWarning(), qCCritical() предотвращают оценку аргументов, если соответствующие типы сообщений не включены для категории, поэтому явную проверку не требуется:

    // usbEntries() will only be called if driverUsb category is enabled
    qCDebug(driverUsb) << "devices: " << usbEntries();

Настройка категории по умолчанию

И конструктор QLoggingCategory, и макрос Q_LOGGING_CATEGORY() принимают необязательный аргумент QtMsgType, который отключает все типы сообщений с более низким уровнем серьезности. То есть категория, объявленная

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

будет регистрировать сообщения типа QtWarningMsg, QtCriticalMsg, QtFatalMsg, но проигнорирует сообщения типа QtDebugMsg и QtInfoMsg.

Если аргумент не передан, все сообщения будут зарегистрированы.

Настройка категорий

Значения по умолчанию для категорий можно переопределить, либо установив правила ведения журнала, либо установив пользовательский фильтр.

Правила ведения журнала

Правила ведения журнала позволяют гибко включать или отключать ведение журнала для категорий. Правила задаются в текстовом формате, где каждая строка должна иметь формат

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

<category> — имя категории, потенциально с * в качестве символа подстановки в качестве первого или последнего символа (или в обоих позициях). Необязательный <type> должен быть debug, info, warning, или critical. Строки, не соответствующие этому формату, игнорируются.

Правила оцениваются в текстовом порядке, от первой к последней. То есть, если два правила применяются к категории/типу, применяется правило, которое идёт позже.

Правила могут быть установлены с помощью 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, например:

• на macOS и iOS: ~/Library/Preferences
• на Unix: ~/.config, /etc/xdg
• на Windows: %LOCALAPPDATA%, %ProgramData%, QCoreApplication::applicationDirPath(), QCoreApplication::applicationDirPath() + "/data"

Установите переменную среды QT_LOGGING_DEBUG для отображения места загрузки правил регистрации.

Установка пользовательского фильтра

В качестве альтернативы правилам текста на более низком уровне вы также можете реализовать пользовательский фильтр с помощью installFilter(). В этом случае все правила фильтра игнорируются.

Вывод категории

Используйте заполнитель %{category} для вывода категории в обработчике сообщений по умолчанию:

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

Документация по типу членов

typedef QLoggingCategory::CategoryFilter

Это typedef для указателя на функцию со следующей сигнатурой:

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)
{
    // 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);
}

Альтернативный способ конфигурирования фильтра по умолчанию — через setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Возвращает true, если критические сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCCritical() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего создания данных, которые используются только для отладки.

bool QLoggingCategory::isDebugEnabled() const

Возвращает true, если сообщения отладки должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCDebug() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего создания данных, которые используются только для отладки.

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

Возвращает true, если сообщение типа msgtype для категории должно отображаться. Возвращает false в противном случае.

bool QLoggingCategory::isInfoEnabled() const

Возвращает true , если информационные сообщения должны отображаться для этой категории. В противном случае возвращает false.

Примечание: Макрос qCInfo() уже выполняет эту проверку перед выполнением кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего создания данных, которые используются только для отладки.

Эта функция была добавлена в Qt 5.5.

bool QLoggingCategory::isWarningEnabled() const

Возвращает true , если предупреждающие сообщения должны отображаться для этой категории. В противном случае возвращает false.

Примечание: Макрос 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().

    QLoggingCategory category("driver.usb");
    qCCritical(category) << "a critical message";

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

    QLoggingCategory category("driver.usb");
    qCDebug(category) << "a debug message";

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

    QLoggingCategory category("driver.usb");
    qCInfo(category) << "an informational message";

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

    QLoggingCategory category("driver.usb");
    qCWarning(category) << "a warning message";

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