Qt QFont::exactMatch()徹底解説: フォントの完全一致を判定する

QFont::exactMatch() とは？

QFont::exactMatch()は、QtのQFontクラスのメンバー関数で、現在のQFontオブジェクトが設定しているフォントプロパティ（フォントファミリー、サイズ、太さ、イタリックなど）と全く同じフォントが、実行中のシステムに存在するかどうかを判定します。

この関数は、bool型の値を返します。

• false: 完全一致するフォントが存在しない場合。この場合、Qtは設定に最も近いフォントを自動的に選択して使用します。
• true: 指定されたQFontの設定に完全に一致するフォントが、システムに存在する場合。

なぜこれが重要なのか？

Qtでフォントを使用する場合、QFontオブジェクトを作成して、フォントファミリー名（例: "メイリオ"、"Times New Roman"）、ポイントサイズ、太さ、イタリックなどの属性を設定します。しかし、指定したフォントがユーザーのシステムに必ずしもインストールされているとは限りません。

QFont::exactMatch()を使用することで、以下のことを確認できます。

1. フォントの可用性の確認: アプリケーションで特定のフォントデザインを厳密に再現したい場合に、そのフォントがユーザーの環境で利用可能かどうかを事前にチェックできます。
2. 代替フォントの処理: exactMatch()がfalseを返した場合、プログラマーは代替フォントの選択肢をユーザーに提示したり、デザインが崩れる可能性を考慮して別の処理を行ったりすることができます。例えば、「このフォントはインストールされていません。代わりに標準フォントを使用しますか？」といったメッセージを表示するといったことが考えられます。
3. デバッグとテスト: 開発中に、意図したフォントが正しく読み込まれているかを確認するのに役立ちます。

#include <QApplication>
#include <QFont>
#include <QFontInfo>
#include <QLabel>
#include <QDebug> // デバッグ出力用

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    // 存在しない可能性のあるフォントを設定
    QFont myFont("MyCustomFontThatMightNotExist", 12, QFont::Bold, true);

    qDebug() << "要求されたフォントファミリー:" << myFont.family();
    qDebug() << "要求されたフォントサイズ:" << myFont.pointSize();
    qDebug() << "要求された太さ:" << myFont.weight();
    qDebug() << "要求されたイタリック:" << myFont.italic();

    if (myFont.exactMatch()) {
        qDebug() << "システムに完全に一致するフォントが見つかりました！";
    } else {
        qDebug() << "システムに完全に一致するフォントは見つかりませんでした。Qtは最も近いフォントを使用します。";
        // 実際にQtが選択したフォントの情報を取得
        QFontInfo fontInfo(myFont);
        qDebug() << "実際に使用されるフォントファミリー:" << fontInfo.family();
        qDebug() << "実際に使用されるフォントサイズ:" << fontInfo.pointSize();
        qDebug() << "実際に使用される太さ:" << fontInfo.weight();
        qDebug() << "実際に使用されるイタリック:" << fontInfo.italic();
    }

    QLabel label("Qt QFont::exactMatch()の例です。", nullptr);
    label.setFont(myFont);
    label.show();

    return app.exec();
}

この例では、"MyCustomFontThatMightNotExist"というフォントを設定していますが、ほとんどのシステムにはこのフォントは存在しないでしょう。そのため、myFont.exactMatch()はfalseを返し、Qtは「最も近い」と判断した代替フォント（例えば、システムのデフォルトのゴシック体や明朝体フォント）でテキストを表示します。QFontInfoを使用することで、実際にQtが選択したフォントの情報を確認できます。

---

QFont::exactMatch()は、指定されたフォントプロパティに完全に一致するフォントがシステムに存在するかどうかを厳密にチェックするための強力なツールですが、その性質上、開発者が意図しない挙動に遭遇することがあります。

想定外の false が返される（フォントが存在するはずなのに）

これは最もよくある問題です。開発者が「このフォントはインストールされているはずだ」と思っていても、exactMatch()がfalseを返す場合があります。

考えられる原因とトラブルシューティング

• ファウンドリー名の指定
  

  • 原因
    フォントファミリー名に"Helvetica [Cronyx]"のようにファウンドリー名を含めて指定した場合、システムにそのファウンドリーからのフォントが正確に存在しないとexactMatch()はfalseを返します。ファウンドリー名を省略すると、Qtは任意のファウンドリーからフォントを選択しようとします。
  • トラブルシューティング
    
    • 特別な理由がない限り、フォントファミリー名にファウンドリー名を含めないようにします。含める場合は、そのファウンドリー名のフォントが確実にシステムにインストールされていることを確認します。

• QApplication/QGuiApplication インスタンスの欠如
  

  • 原因
    QFontオブジェクトを使用する前に、QApplicationまたはQGuiApplicationインスタンスが初期化されていない場合、フォントシステムが正しく機能せず、exactMatch()が正しく動作しないことがあります。
  • トラブルシューティング
    
    • アプリケーションのメイン関数で、必ずQApplication app(argc, argv);のようにアプリケーションインスタンスを最初に作成するようにします。

• ポイントサイズのマッチングの許容範囲
  

  • 原因
    Qtは、pointSize()に関しては、完全に一致しない場合でも「近い」と判断することがあります。ドキュメントによると、要求されたポイントサイズの20%以内であれば「一致」と見なされることがあります。しかし、exactMatch()は文字通り「完全一致」を要求するため、この「近い」マッチングではfalseを返します。例えば、12ptを要求してもシステムが11.8ptしか持っていない場合など。
  • トラブルシューティング
    
    • exactMatch()はポイントサイズまで厳密にチェックするため、特に問題はありません。しかし、ユーザーが設定したサイズがそのまま使われるか確認したい場合は、QFontInfo(myFont).pointSize()で実際に適用されたサイズを確認してください。

• フォントスタイル/ウェイト/ストレッチの不一致
  

  • 原因
    QFontオブジェクトで設定した太さ（weight）、イタリック（italic）、ストレッチ（stretch）などのスタイル属性が、システムにインストールされているフォントの特定のバリアントと完全に一致しない場合があります。例えば、"Arial Bold Italic"のようなフォントが存在しないシステムで、"Arial"を指定し、setBold(true)とsetItalic(true)を設定した場合、exactMatch()はfalseを返すことがあります。
  • トラブルシューティング
    
    • 設定した太さやスタイルが、実際に存在するフォントのバリアントと一致しているか確認します。
    • QFontInfoを使用して、Qtが実際に選択したフォントのweight()、italic()、stretch()などを調べ、exactMatch()がfalseを返した際にどの属性が一致していないのかを特定します。
• • 原因
    指定したフォントファミリー名が、システムにインストールされているフォントの正確な名前と一致していない可能性があります。例えば、"Arial"と"Arial Regular"、"メイリオ"と"Meiryo UI"のように、わずかな違いがあることがあります。OSやフォントベンダーによって、同じフォントでも名前の表記が異なる場合があります。
  • トラブルシューティング
    
    • QFontDatabase::families()を使用して、システムにインストールされている正確なフォントファミリー名のリストを取得し、それと比較します。
    • QFontInfo(myFont).family()を使って、Qtが実際に選択したフォントのファミリー名を確認します。これにより、Qtが内部的にどのようにフォント名を解釈しているかがわかります。
    • フォントビューア（Windowsのフォント設定、macOSのFont Bookなど）で、フォントの正式な名前を確認します。

exactMatch() が常に true を返す、あるいは意味がない

稀に、exactMatch()が常にtrueを返すように見えたり、期待したフォントが適用されていないのにtrueを返したりするような錯覚を覚えることがあります。

考えられる原因とトラブルシューティング

• 基本的なフォント属性のみを考慮しているという誤解
  

  • 原因
    exactMatch()は、フォントファミリーだけでなく、ポイントサイズ、太さ、イタリック、固定ピッチ（fixedPitch）、ストレッチ（stretch）など、QFontオブジェクトに設定されたすべての属性を考慮します。これらすべての属性が完全に一致しない限り、trueは返されません。
  • トラブルシューティング
    
    • フォントのどの属性を厳密にマッチさせたいのかを明確にし、それらの属性をQFontオブジェクトに正しく設定しているかを確認します。

• デフォルトフォントによる見かけ上のマッチ
  

  • 原因
    特定のフォントが見つからない場合、Qtはシステムのデフォルトフォントや汎用フォント（例: "Sans Serif", "Serif", "Monospace"）にフォールバックします。このフォールバックされたフォントが、偶然にもexactMatch()がtrueを返す条件を満たしてしまう場合があります。これは実際には問題ではありませんが、ユーザーの意図と異なる結果に見えることがあります。
  • トラブルシューティング
    
    • QFontInfo(myFont).family()を使用して、実際に適用されたフォントのファミリー名を確認します。exactMatch()がtrueでも、myFont.family()とQFontInfo(myFont).family()が異なる場合は、Qtが代替フォントを選択した結果である可能性が高いです。

文字が表示されない、豆腐文字（□）になる

これはexactMatch()の結果が直接の原因ではありませんが、フォントの可用性に関連する一般的な問題です。

考えられる原因とトラブルシューティング

• 選択されたフォントに特定の文字のグリフがない
  
  • 原因
    exactMatch()がtrueを返したとしても、そのフォントが、表示したい特定の文字（例えば、絵文字、特殊記号、非ラテン文字など）をサポートしていない場合があります。この場合、Qtは足りない文字を他のフォントから補おうとしますが、それでも見つからなければ「豆腐文字」（□）として表示されます。
  • トラブルシューティング
    
    • 表示したい文字が、選択したフォントに実際に含まれているかを確認します。
    • 複数のフォントを組み合わせて使用するか、より広範な文字セットをサポートするフォント（例: Noto Sans, Arial Unicode MSなど）を検討します。
    • QFont::setResolveMask()やQFont::setHintingPreference()など、レンダリングに関する他のQFont設定を試してみることも有効な場合があります。

パフォーマンスへの影響

exactMatch()自体がパフォーマンス上の大きなボトルネックになることは稀ですが、フォントの検索やマッチングはリソースを消費する可能性があります。

考えられる原因とトラブルシューティング

• 頻繁なフォントオブジェクトの作成とチェック
  
  • 原因
    ループ内や描画処理のような頻繁に呼び出される場所で、毎回新しいQFontオブジェクトを作成し、exactMatch()を呼び出すと、パフォーマンスに影響を与える可能性があります。
  • トラブルシューティング
    
    • フォントオブジェクトは必要なときに一度だけ作成し、キャッシュして再利用することを検討します。
    • フォントの存在チェックは、アプリケーションの起動時や設定変更時など、頻度の低いタイミングで行うようにします。

---

QFont::exactMatch()は、QFontオブジェクトが持つフォントプロパティ（ファミリー、サイズ、太さ、イタリックなど）に完全に一致するフォントが、現在のシステムに存在するかどうかを判定します。

例1: 基本的な使用法 - フォントの存在確認

この例では、特定のフォントが存在するかどうかを確認し、その結果をデバッグ出力で表示します。

#include <QApplication>
#include <QFont>
#include <QFontInfo>
#include <QDebug> // デバッグ出力用
#include <QLabel> // 表示用

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    // --- 例1: 存在する可能性が高いフォント ---
    QFont font1("Arial", 12, QFont::Normal, false); // Arial, 12pt, 通常, 非イタリック

    qDebug() << "--- Font 1 (Arial) ---";
    qDebug() << "要求されたフォントファミリー:" << font1.family();
    qDebug() << "要求されたサイズ:" << font1.pointSize();
    qDebug() << "要求された太さ:" << font1.weight();
    qDebug() << "要求されたイタリック:" << font1.italic();

    if (font1.exactMatch()) {
        qDebug() << "→ 完全に一致するフォントが見つかりました！";
    } else {
        qDebug() << "→ 完全に一致するフォントは見つかりませんでした。";
    }
    // 実際に適用されたフォントの情報を取得
    QFontInfo fontInfo1(font1);
    qDebug() << "実際に適用されるフォントファミリー:" << fontInfo1.family();
    qDebug() << "実際に適用されるサイズ:" << fontInfo1.pointSize();
    qDebug() << "実際に適用される太さ:" << fontInfo1.weight();
    qDebug() << "実際に適用されるイタリック:" << fontInfo1.italic();
    qDebug() << "";

    // --- 例2: 存在しない可能性が高いフォント ---
    // あなたのシステムに「FantasyFontXYZ」というフォントは通常存在しないでしょう
    QFont font2("FantasyFontXYZ", 18, QFont::Bold, true); // 存在しない可能性のあるフォント

    qDebug() << "--- Font 2 (FantasyFontXYZ) ---";
    qDebug() << "要求されたフォントファミリー:" << font2.family();
    qDebug() << "要求されたサイズ:" << font2.pointSize();
    qDebug() << "要求された太さ:" << font2.weight();
    qDebug() << "要求されたイタリック:" << font2.italic();

    if (font2.exactMatch()) {
        qDebug() << "→ 完全に一致するフォントが見つかりました！";
    } else {
        qDebug() << "→ 完全に一致するフォントは見つかりませんでした。";
    }
    // 実際に適用されたフォントの情報を取得
    QFontInfo fontInfo2(font2);
    qDebug() << "実際に適用されるフォントファミリー:" << fontInfo2.family();
    qDebug() << "実際に適用されるサイズ:" << fontInfo2.pointSize();
    qDebug() << "実際に適用される太さ:" << fontInfo2.weight();
    qDebug() << "実際に適用されるイタリック:" << fontInfo2.italic();
    qDebug() << "";

    // QLabelにフォントを適用して表示
    QLabel label1("このテキストはArialで表示されます（おそらく）。");
    label1.setFont(font1);
    label1.show();

    QLabel label2("このテキストはFantasyFontXYZ（代替）で表示されます。");
    label2.setFont(font2);
    label2.move(0, 50); // 位置をずらして表示
    label2.show();

    return app.exec();
}

解説

• font2 (FantasyFontXYZ)
  通常、この名前のフォントはシステムに存在しません。そのため、font2.exactMatch()はfalseを返します。Qtは、この場合でも何らかのフォント（通常はシステムのデフォルトフォントや汎用フォント）でテキストを表示しようとします。QFontInfoで確認すると、font2.family()で設定した"FantasyFontXYZ"とは異なるフォントファミリー（例: "Noto Sans CJK JP" や "Segoe UI" など）が実際に使用されていることがわかります。
• font1 (Arial)
  ほとんどのシステムにArialは存在するため、font1.exactMatch()はtrueを返す可能性が高いです。QFontInfoで確認すると、要求した設定と実際に適用された設定が一致していることがわかります。

例2: 特定のスタイルがシステムに存在するかどうかを確認する

フォントファミリーだけでなく、太さやイタリックなどのスタイルも厳密にマッチするかどうかを確認します。

#include <QApplication>
#include <QFont>
#include <QFontInfo>
#include <QDebug>
#include <QLabel>
#include <QVBoxLayout> // レイアウト用
#include <QWidget> // メインウィンドウ用

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    QWidget window;
    QVBoxLayout *layout = new QVBoxLayout(&window);

    // --- フォント1: BoldとItalicの両方が存在する可能性のあるフォント (例: Arial) ---
    QFont fontA("Arial", 14);
    fontA.setBold(true);
    fontA.setItalic(true);

    QString textA = "Arial Bold Italic: ";
    if (fontA.exactMatch()) {
        textA += " (完全に一致するフォントが存在します)";
    } else {
        textA += " (完全に一致するフォントが見つかりません)";
    }
    QLabel *labelA = new QLabel(textA);
    labelA->setFont(fontA);
    layout->addWidget(labelA);

    // 実際に適用されたフォントの情報を確認
    QFontInfo infoA(fontA);
    qDebug() << "Arial Bold Italic (Actual): Family=" << infoA.family()
             << ", Bold=" << infoA.bold()
             << ", Italic=" << infoA.italic();


    // --- フォント2: 特定の太さのバリアントが存在しない可能性のあるフォント (例: 細すぎる/太すぎる) ---
    // システムによっては、全ての太さのバリアントが存在しない場合があります
    QFont fontB("Times New Roman", 14);
    fontB.setWeight(QFont::Black); // QFont::Black は非常に太い
    
    QString textB = "Times New Roman Black (要求): ";
    if (fontB.exactMatch()) {
        textB += " (完全に一致するフォントが存在します)";
    } else {
        textB += " (完全に一致するフォントが見つかりません)";
    }
    QLabel *labelB = new QLabel(textB);
    labelB->setFont(fontB);
    layout->addWidget(labelB);

    // 実際に適用されたフォントの情報を確認
    QFontInfo infoB(fontB);
    qDebug() << "Times New Roman Black (Actual): Family=" << infoB.family()
             << ", Weight=" << infoB.weight();


    // --- フォント3: システムのデフォルトフォント ---
    QFont fontC = QApplication::font(); // アプリケーションのデフォルトフォント
    fontC.setPointSize(16);

    QString textC = "システムのデフォルトフォント: ";
    if (fontC.exactMatch()) {
        textC += " (完全に一致するフォントが存在します)";
    } else {
        textC += " (完全に一致するフォントが見つかりません)";
    }
    QLabel *labelC = new QLabel(textC);
    labelC->setFont(fontC);
    layout->addWidget(labelC);

    // 実際に適用されたフォントの情報を確認
    QFontInfo infoC(fontC);
    qDebug() << "Default App Font (Actual): Family=" << infoC.family()
             << ", Size=" << infoC.pointSize();


    window.setLayout(layout);
    window.setWindowTitle("QFont::exactMatch()の例");
    window.resize(400, 200);
    window.show();

    return app.exec();
}

解説

• fontC (システムのデフォルトフォント)
  QApplication::font()で取得したデフォルトフォントは、通常システムに存在するフォントなので、exactMatch()はtrueを返すでしょう。
• fontB (Times New Roman Black)
  Times New Romanはよく使われるフォントですが、QFont::Black (非常に太い) という特定のウェイトのバリアントがシステムにインストールされていない場合があります。その場合、exactMatch()はfalseを返し、Qtは利用可能な最も近い太さ（例: QFont::Bold）を適用しようとします。
• fontA (Arial Bold Italic)
  Arialは通常、BoldとItalicのバリアントを持つため、exactMatch()はtrueを返す可能性が高いです。

例3: フォントが見つからない場合の代替処理

exactMatch()がfalseを返した場合に、ユーザーにメッセージを表示したり、代替フォントを設定したりする例です。

#include <QApplication>
#include <QFont>
#include <QFontInfo>
#include <QDebug>
#include <QLabel>
#include <QVBoxLayout>
#include <QWidget>
#include <QMessageBox> // メッセージボックス用

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    QWidget window;
    QVBoxLayout *layout = new QVBoxLayout(&window);

    QString desiredFontFamily = "Comic Sans MS"; // 存在しない可能性のあるフォント（Windows以外など）
    int desiredPointSize = 16;
    QFont desiredFont(desiredFontFamily, desiredPointSize);

    QLabel *displayLabel = new QLabel("表示されるテキスト");
    layout->addWidget(displayLabel);

    if (desiredFont.exactMatch()) {
        qDebug() << "要求されたフォントが完全に一致しました: " << desiredFont.family();
        displayLabel->setFont(desiredFont);
        displayLabel->setText(QString("フォント: %1 (%2pt) - 完全に一致").arg(desiredFont.family()).arg(desiredFont.pointSize()));
    } else {
        qDebug() << "要求されたフォントが完全に一致しませんでした: " << desiredFont.family();
        // ユーザーにフォントが見つからないことを通知
        QMessageBox::warning(&window, "フォントが見つかりません",
                             QString("要求されたフォント '%1' はシステムに完全には一致しませんでした。代替フォントが使用されます。").arg(desiredFontFamily));

        // 実際にQtが選択したフォントの情報を取得
        QFontInfo actualFontInfo(desiredFont);
        qDebug() << "実際に使用されるフォントファミリー:" << actualFontInfo.family();
        qDebug() << "実際に使用されるサイズ:" << actualFontInfo.pointSize();

        // 別の代替フォントを明示的に設定することも可能
        QFont fallbackFont("Noto Sans CJK JP", desiredPointSize); // 日本語環境向けの代替フォント
        if (fallbackFont.exactMatch()) {
            displayLabel->setFont(fallbackFont);
            displayLabel->setText(QString("フォント: %1 (%2pt) - 代替フォントを使用").arg(fallbackFont.family()).arg(fallbackFont.pointSize()));
        } else {
            // 代替フォントも厳密には見つからなかった場合（しかし表示はされる）
            displayLabel->setFont(desiredFont); // 元の要求フォント（Qtが最善を尽くす）
            displayLabel->setText(QString("フォント: %1 (%2pt) - システムのデフォルトで表示").arg(actualFontInfo.family()).arg(actualFontInfo.pointSize()));
        }
    }

    window.setLayout(layout);
    window.setWindowTitle("フォント可用性チェック");
    window.resize(400, 150);
    window.show();

    return app.exec();
}

• さらに、"Noto Sans CJK JP"のような、より一般的なフォントを代替として設定しようとしています。これにより、フォントが見つからない場合でも、ユーザーに適切な表示を提供できます。
• exactMatch()がfalseを返した場合、QMessageBox::warningを使ってユーザーに情報を提供します。
• この例では、まず"Comic Sans MS"というフォントを要求します。これはWindowsでは一般的ですが、LinuxやmacOSではデフォルトでインストールされていない場合があります。

---

QFontInfo クラスの使用

QFontInfoは、実際にQtが特定のQFontオブジェクトに対して選択したフォントの情報を提供します。exactMatch()が「要求されたフォントがシステムにそのまま存在するか」を問うのに対し、QFontInfoは「Qtが最終的に何のフォントを使ったか」を知るためのものです。