QLoggingCategory Class

QLoggingCategory クラスは、ロギング・インフラストラクチャのカテゴリ、または「エリア」を表します。詳細...

ヘッダー #include <QLoggingCategory>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

注意:このクラスの関数はすべてスレッドセーフです。

パブリック型

パブリック関数

QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)
~QLoggingCategory()
const char *categoryName() const
bool isCriticalEnabled() const
bool isDebugEnabled() const
bool isEnabled(QtMsgType msgtype) const
bool isInfoEnabled() const
bool isWarningEnabled() const
void setEnabled(QtMsgType type, bool enable)
QLoggingCategory &operator()()
const QLoggingCategory &operator()() const

静的パブリックメンバ

QLoggingCategory *defaultCategory()
QLoggingCategory::CategoryFilter installFilter(QLoggingCategory::CategoryFilter filter)
void setFilterRules(const QString &rules)

マクロ

(since 6.5) Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)
Q_DECLARE_LOGGING_CATEGORY(name)
Q_LOGGING_CATEGORY(name, string)
Q_LOGGING_CATEGORY(name, string, msgType)
qCCritical(category)
qCCritical(category, const char *message, ...)
qCDebug(category)
qCDebug(category, const char *message, ...)
(since 6.5) qCFatal(category)
(since 6.5) qCFatal(category, const char *message, ...)
qCInfo(category)
qCInfo(category, const char *message, ...)
qCWarning(category)
qCWarning(category, const char *message, ...)

詳しい説明

QLoggingCategory は、実行時に文字列で識別される特定のロギングカテゴリを表します。カテゴリは、メッセージタイプごとにメッセージのロギングを有効または無効にするように構成できます。例外は致命的なメッセージで、これは常に有効です。

メッセージ・タイプが有効かどうかを調べるには、以下のメソッドのいずれかを使用する:isDebugEnabled()、isInfoEnabled()、isWarningEnabled()、isCriticalEnabled()。

Configuring Categories で説明されているように、すべてのオブジェクトは共通のレジストリで 構成されるようになっています。異なるオブジェクトが同じカテゴリーを表すこともあります。したがって、モジュールの境界を越えてオブジェクトをエクスポートしたり、オブジェクトを直接操作したり、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")

ライブラリの境界を越えてロギングカテゴリーを使用するためにQ_DECLARE_EXPORTED_LOGGING_CATEGORY() マクロもあります。

カテゴリー名はフリーテキストです。Logging Rules を使用してカテゴリーを構成するには、その名前はこの規約に従わなければなりません:

  • カテゴリ名はフリーテキストです。
  • ドットを使用して、カテゴリーをさらに共通の領域に構造化する。
  • カテゴリ名は避けてください:debug infowarningcritical
  • qt の接頭辞を持つカテゴリ名は、Qt モジュール用にのみ予約されています。

Q_LOGGING_CATEGORY() によって暗黙的に定義された QLoggingCategory オブジェクトは、最初の使用時にスレッドセーフな方法で生成されます。

カテゴリー設定のチェック

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)

で宣言されたカテゴリは、QtWarningMsgQtCriticalMsgQtFatalMsg タイプのメッセージを記録しますが、QtDebugMsgQtInfoMsg タイプのメッセージは無視します。

引数が渡されない場合、全てのメッセージがログに記録されます。qt で始まる Qt 内部カテゴリだけが、異なる扱いを受けます:デフォルトでは、QtInfoMsgQtWarningMsgQtCriticalMsgQFatalMsg のタイプのメッセージだけがログに記録されます。

注意: ロギング・カテゴリーは C++ ビルドの設定に影響されません。つまり、コードがデバッグ・シンボル('Debug Build')、最適化('Release Build')、またはその他の組み合わせでコンパイルされているかどうかによって、メッセージが出力されるかどうかが変わることはありません。

カテゴリの設定

カテゴリのデフォルト設定を上書きするには、ロギングルールを設定するか、カスタムフィルタをインストールします。

ロギングルール

ロギングルールによって、柔軟な方法でカテゴリのロギングを有効または無効にできます。ルールはテキストで指定します:

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

<category> はカテゴリー名で、最初か最後の文字にワイルドカードシンボルとして を指定することもできます。オプションの は、 、 、 、 のいずれかでなければならない。このスキームに合わない行は無視される。* <type> debug info warning critical

ルールは、テキストの先頭から末尾の順に評価される。つまり、1つのカテゴリー/タイプに2つのルールが適用される場合、後に来るルールが適用される。

ルールはsetFilterRules() で設定できる:

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

ロギング・ルールは、ロギング設定ファイルの[Rules] セクションから自動的にロードされる。これらの設定ファイルは QtProject の設定ディレクトリで検索されるか、QT_LOGGING_CONF 環境変数で明示的に設定されます:

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

QT_LOGGING_RULES 複数のルールをセミコロンで区切ることもできます:

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

setFilterRules() で設定されたルールは、QtProject 設定ディレクトリで指定されたルールよりも優先されます。これらのルールは、QT_LOGGING_CONF で指定された設定ファイルや、QT_LOGGING_RULES で設定された設定ファイルによって上書きされます。

評価の順序は以下の通りです:

  1. [QLibraryInfo::DataPath]/qtlogging.ini
  2. QtProject/qtlogging.ini
  3. setFilterRules()
  4. QT_LOGGING_CONF
  5. QT_LOGGING_RULES

QtProject/qtlogging.ini ファイルは、QStandardPaths::GenericConfigLocation によって返されたすべてのディレクトリで検索されます。

QT_LOGGING_DEBUG 環境変数を設定して、ロギングルールがどこからロードされるかを調べてください。

カスタムフィルターのインストール

テキスト・ルールの低レベルの代替として、installFilter() を使ってカスタム・フィルターを実装することもできます。この場合、すべてのフィルター・ルールは無視されます。

カテゴリの印刷

デフォルトのメッセージ・ハンドラでカテゴリを表示するには、%{category} プレースホルダを使用します:

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

メンバー型ドキュメント

QLoggingCategory::CategoryFilter

これは、以下のシグネチャを持つ関数へのポインタの typedef である:

void myCategoryFilter(QLoggingCategory *);

このシグネチャを持つ関数はinstallFilter() でインストールできる。

メンバ関数ドキュメント

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

提供されたcategory 名で QLoggingCategory オブジェクトを構築し、少なくともenableForLevel と同程度の冗長なタイプを持つすべてのメッセージを有効にします。デフォルトはQtDebugMsg (すべてのカテゴリを有効にします) です。

categorynullptr の場合、カテゴリ名"default" が使用されます。

注意: category は、このオブジェクトの有効期間中、有効にしておく必要があります。これを実現するには、文字列リテラルを使用するのが一般的です。

[noexcept] QLoggingCategory::~QLoggingCategory()

QLoggingCategory オブジェクトを破壊する。

const char *QLoggingCategory::categoryName() const

カテゴリーの名前を返します。

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

qDebug()、qInfo()、qWarning()、qCritical()、qFatal() などで使用されるグローバル・カテゴリ"default" へのポインタを返します。

注意: 静的オブジェクトの破棄時に、返されるポインタがNULLになることがあります。また、delete 、カテゴリの所有権は移譲されないので、このポインタを返さないでください。

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

ロギング・カテゴリーをどのように設定するかを制御する。

どのカテゴリーとメッセージタイプを有効にするかを決定するために使用される関数filter をインストールします。filternullptr の場合、デフォルトのメッセージ・フィルタが復活します。以前にインストールされたフィルタへのポインタを返します。

installFilter() が返される前に、すでに存在するすべてのQLoggingCategory オブジェクトがフィルタに渡され、フィルタはsetEnabled() で各カテゴリの設定を自由に変更できます。フィルターが変更しなかったカテゴリーは、前のフィルターによって与えられた設定を保持するので、新しいフィルターは、既存のカテゴリーに対するこの最初のパスの間、前のフィルターに委譲する必要はありません。

ロギングポリシーを完全に上書きするのではなく、選択されたいくつかのカテゴリの設定を調整することだけを目的とするフィルタは、最初に新しいカテゴリを先行フィルタに渡して標準の設定を与え、それがフィルタにとって特定の関心のあるカテゴリの1つであれば、必要に応じてそれを調整することができます。新しいフィルタをインストールするコードは、installFilter() からの返り値を記録して、フィルタが後の呼び出しで使用できるようにすることができます。

フィルタを定義するときは、異なるスレッドから呼び出すことができることに注意してください。このフィルターは、QLoggingCategory から静的関数を呼び出すことはできません。

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

によって(例えばmain() に)インストールされている。

oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);

また、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 ()マクロは、コードを実行する前にすでにこのチェックを行う。しかし、このメソッドを呼び出すと、デバッグ出力のためだけの高価なデータ生成を避けることができるので便利です。

bool QLoggingCategory::isWarningEnabled() const

このカテゴリーに対して警告メッセージを表示すべき場合はtrue を、そうでない場合はfalse を返す。

注: qCWarning ()マクロは、コードを実行する前にすでにこのチェックを行う。しかし、このメソッドを呼び出すと、デバッグ出力のためだけの高価なデータ生成を避けることができるので便利です。

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

カテゴリのメッセージ・タイプtypeenable に変更します。

このメソッドは、installFilter() でインストールされたフィルタの内部からのみ使用できます。カテゴリをグローバルに設定する方法の概要については、Configuring Categories を参照してください。

注: 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(),qCFatal() マクロで使用することができます。

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

オブジェクト自身を返します。これにより、QLoggingCategory 変数と、QLoggingCategory を返すファクトリ・メソッドの両方を、qCDebug()、qCWarning()、qCCritical()、qCFatal() マクロで使用できます。

マクロ・ドキュメント

[since 6.5] Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)

ロギングカテゴリーを宣言するname 。このマクロは、プログラムの異なる部分で共有される共通のロギング・カテゴリーを宣言するために使うことができる。

これはQ_DECLARE_LOGGING_CATEGORY() と全く同じように動作する。しかし、このマクロで宣言されたロギングカテゴリは、さらにEXPORT_MACRO で修飾されます。これは、ロギングカテゴリーをダイナミックライブラリからエクスポートする必要がある場合に便利です。

例えば

Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)

このマクロはクラスや関数の外部で使用する必要があります。

このマクロは Qt 6.5 で導入されました。

Q_LOGGING_CATEGORY() とQ_DECLARE_LOGGING_CATEGORY()も参照してください

Q_DECLARE_LOGGING_CATEGORY(name)

ロギングカテゴリーを宣言するname 。このマクロは、プログラムの異なる部分で共有される共通のロギング・カテゴリを宣言するために使うことができます。

このマクロはクラスやメソッドの外で使用しなければなりません。

Q_LOGGING_CATEGORY() およびQ_DECLARE_EXPORTED_LOGGING_CATEGORY()も参照して ください。

Q_LOGGING_CATEGORY(name, string)

ロギング・カテゴリーname を定義し、string 識別子の下で設定可能にします。デフォルトでは、すべてのメッセージ・タイプが有効になります。

ライブラリまたは実行可能ファイル内の1つの翻訳ユニットだけが、特定の名前のカテゴリを定義できます。暗黙的に定義されたQLoggingCategory オブジェクトは、最初の使用時にスレッドセーフな方法で生成されます。

このマクロは、クラスまたはメソッドの外部で使用する必要があります。

Q_DECLARE_LOGGING_CATEGORY() およびQ_DECLARE_EXPORTED_LOGGING_CATEGORY()も参照のこと

Q_LOGGING_CATEGORY(name, string, msgType)

ロギング・カテゴリーname を定義し、string 識別子の下で設定可能にします。デフォルトでは、QtMsgType msgType 以上のメッセージは有効になり、それ以下のメッセージは無効になります。

ライブラリまたは実行可能ファイル内の1つの翻訳ユニットだけが、特定の名前のカテゴリを定義できます。暗黙的に定義されたQLoggingCategory オブジェクトは、最初の使用時にスレッドセーフな方法で生成されます。

このマクロは、クラスまたはメソッドの外部で使用する必要があります。

Q_DECLARE_LOGGING_CATEGORY()も参照のこと

qCCritical(category)

ロギング・カテゴリのクリティカル・メッセージの出力ストリームを返すcategory

このマクロは、QLoggingCategory::isCriticalEnabled() がtrue と評価されるかどうかをチェックするコードに展開されます。評価される場合、ストリーム引数は処理され、メッセージハンドラに送られます。

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

注意: 特定のカテゴリのクリティカル出力が有効になっていない場合、引数は処理されな いため、副作用を当てにしないでください。

qCritical()も参照のこと

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

クリティカル・メッセージmessage を、ロギング・カテゴリーcategory に記録する。message には、Cのprintf()関数と同様に、追加引数で置き換えるプレースホルダーを含めることができる。

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

注意: 特定のカテゴリのクリティカル出力が有効になっていない場合、引数は処理されないので、副作用を当てにしないでください。

qCritical()も参照のこと

qCDebug(category)

ロギング・カテゴリcategory のデバッグ・メッセージの出力ストリームを返す。

このマクロは、QLoggingCategory::isDebugEnabled() がtrue と評価されるかどうかをチェックするコードに展開されます。評価される場合、ストリーム引数は処理され、メッセージハンドラに送られます。

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

注意: category のデバッグ出力が有効になっていない場合、引数は処理されないので、 副作用を当てにしないでください。

qDebug()も参照のこと

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

デバッグ・メッセージmessage をロギング・カテゴリーcategory に記録する。message には、Cのprintf()関数と同様に、追加引数で置き換えるプレースホルダーを含めることができる。

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

注意: category のデバッグ出力が有効になっていない場合、引数は処理されないので、 副作用を当てにしないこと。

qDebug()も参照のこと

[since 6.5] qCFatal(category)

ロギング・カテゴリーcategory の致命的メッセージの出力ストリームを返します。

デフォルトのメッセージ・ハンドラを使用している場合、返されたストリームはコア・ダンプを作成するためにアボートします。Windowsでは、デバッグビルドの場合、この関数はアプリケーションにデバッガを接続できるように_CRT_ERROR

    QLoggingCategory category("driver.usb");
    qCFatal(category) << "a fatal message. Program will be terminated!";

このマクロは Qt 6.5 で導入されました。

qFatal()も参照してください

[since 6.5] qCFatal(category, const char *message, ...)

致命的なメッセージmessage を、ログ・カテゴリーcategory に記録する。message には、Cのprintf()関数と同様に、追加引数で置き換えられるプレースホルダーを含めることができる。

    QLoggingCategory category("driver.usb");
    qCFatal(category, "a fatal message. Program will be terminated!");

例:デフォルトのメッセージ・ハンドラを使用している場合、この関数はコア・ダンプを作成するためにアボートします。Windows では、デバッグビルドの場合、この関数は_CRT_ERROR を報告し、アプリケーションにデバッガを接続できるようにします。

このマクロは Qt 6.5 で導入されました。

qFatal()も参照してください

qCInfo(category)

ロギング・カテゴリcategory の情報メッセージの出力ストリームを返す。

このマクロは、QLoggingCategory::isInfoEnabled() がtrue と評価されるかどうかをチェックするコードに展開されます。評価される場合、ストリーム引数は処理され、メッセージハンドラに送られます。

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

注意: 特定のカテゴリのデバッグ出力が有効になっていない場合、引数は処理されないので、 副作用を当てにしないでください。

qInfo()も参照のこと

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

message category 。 は、Cのprintf()関数と同様に、追加引数で置き換えられるプレースホルダーを含むことができる。message

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

注意: 特定のカテゴリのデバッグ出力が有効になっていない場合、引数は処理されないので、副作用を当てにしないこと。

qInfo()も参照のこと

qCWarning(category)

ロギング・カテゴリの警告メッセージの出力ストリームを返すcategory

このマクロは、QLoggingCategory::isWarningEnabled() がtrue と評価されるかどうかをチェックするコードに展開されます。評価される場合、ストリーム引数は処理され、メッセージハンドラに送られます。

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

注意: 特定のカテゴリの警告出力が有効になっていない場合、引数は処理されないので、 副作用を当てにしないでください。

qWarning()も参照のこと

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

警告メッセージmessage をログ・カテゴリーcategory に記録する。message には、Cのprintf()関数と同様に、追加引数で置き換えるプレースホルダーを含めることができる。

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

注意: 特定のカテゴリの警告出力が有効でない場合、引数は処理されないので、 副作用を当てにしないでください。

qWarning()も参照のこと

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.