Qtプログラマー必見！フォント代替の仕組みと制御方法

2025-06-06

以下に詳しく説明します。

QStringList QFont::substitutions() とは？

この関数は、現在のフォIントが代替されたフォントのリストを返します。具体的には、元のフォントがシステム上で利用できない場合や、特定の文字グリフが元のフォントに存在しない場合などに、Qtが自動的に代替フォントを探して使用します。substitutions()は、この「代替されたフォント」のリストを文字列のリスト（QStringList）として返します。

戻り値

QStringList: フォントの代替リストを格納する文字列のリスト。リストの各要素は、代替フォントの名前を表すQStringです。もし代替が行われていない場合、このリストは空になります。

利用シーン

フォントの互換性チェック
異なるシステムや環境でアプリケーションを実行する際に、フォントの表示に問題がないかを確認するために使用できます。特定のフォントが利用できない環境で、どのような代替フォントが使われているかを把握できます。
デバッグ/情報取得
現在使用されているフォントがどのようにレンダリングされているか、どのフォントが実際に使用されているかを確認したい場合に役立ちます。例えば、特定の文字が表示されない問題がある場合、この関数を使って代替フォントを確認し、そのフォントが原因であるかどうかを調べることができます。

注意点

フォントの代替は、オペレーティングシステムやQtのフォント設定、利用可能なフォントによって動的に決定されます。したがって、同じコードでも実行環境によってsubstitutions()の結果が異なる場合があります。
この関数が返すリストは、実際にレンダリングに使用されたフォントの代替を示すものであり、ユーザーが明示的に設定したフォントの代替ルールではありません。

#include <QApplication>
#include <QFont>
#include <QFontDatabase>
#include <QDebug>

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

    // 存在しない可能性のあるフォントを設定してみる
    QFont font("NonExistentFontName");
    font.setPointSize(24);

    qDebug() << "設定したフォントファミリー:" << font.family();
    qDebug() << "実際に使用されるフォントファミリー (resolved):" << font.resolvedFont().family();

    // 代替フォントのリストを取得
    QStringList substitutions = font.substitutions();

    if (substitutions.isEmpty()) {
        qDebug() << "代替フォントはありません。";
    } else {
        qDebug() << "代替フォントリスト:";
        foreach (const QString &sub, substitutions) {
            qDebug() << "  - " << sub;
        }
    }

    // 別の例：特定の日本語フォントを設定し、代替を確認
    QFont japaneseFont("メイリオ"); // または "MS ゴシック", "ヒラギノ角ゴ ProN W3" など
    japaneseFont.setPointSize(20);

    qDebug() << "\n日本語フォント設定:";
    qDebug() << "設定したフォントファミリー:" << japaneseFont.family();
    qDebug() << "実際に使用されるフォントファミリー (resolved):" << japaneseFont.resolvedFont().family();

    QStringList japaneseSubstitutions = japaneseFont.substitutions();
    if (japaneseSubstitutions.isEmpty()) {
        qDebug() << "日本語フォントに代替フォントはありません。";
    } else {
        qDebug() << "日本語フォントの代替フォントリスト:";
        foreach (const QString &sub, japaneseSubstitutions) {
            qDebug() << "  - " << sub;
        }
    }

    return 0;
}

このコードでは、存在しないフォント名を設定した場合にsubstitutions()がどのような代替フォントを返すか、また、システムに存在するフォント（例: メイリオ）を設定した場合に代替が行われるか（通常は行われないはずです）を確認しています。

QStringList QFont::substitutions() は、Qtアプリケーションでフォントの代替が行われた場合に、どのフォントが代替として使用されたかを示すリストを返す便利な関数ですが、これ自体が直接エラーを発生させることは稀です。多くの場合、substitutions() が返す結果が期待と異なることが問題となり、それはフォントのレンダリングや表示に関する問題の兆候であることが多いです。

ここでは、QStringList QFont::substitutions() に関連してよくある問題とそのトラブルシューティングについて説明します。

よくある問題と原因

- 原因: フォントファイルが欠落しているか、適切に配置されていない
  - 開発環境では問題なく動作するのに、ターゲット環境で問題が発生する場合、その環境に表示に必要なフォントファイルがインストールされていない、またはQtがフォントファイルを見つけられないパスに配置されている可能性が高いです。組み込みシステムでは、必要なフォントを手動で組み込む必要があることがよくあります。
- 原因: フォントレンダリングエンジンの違い
  - 異なるプラットフォームでは、Qtが使用するフォントレンダリングエンジンや、基盤となるグラフィックライブラリ（例: FreeType, FontConfig, DirectWrite, Core Text）が異なります。これらの違いが、フォントの表示に影響を与えることがあります。

フォントの存在確認とインストール
- システムのフォントを確認する
  QFont::substitutions() が空を返す場合、まず指定したフォントがシステムにインストールされているか確認します。
  - Windows: コントロールパネルの「フォント」
  - macOS: Font Book.app
  - Linux: fc-list コマンドなど
- 必要なフォントをインストールする
  もしフォントが不足している場合は、それをシステムにインストールします。特に多言語対応が必要な場合は、対応する文字セットを含むフォント（例: Noto Sans CJK, メイリオ、游ゴシックなど）をインストールします。
- アプリケーションにフォントを組み込む
  システム全体にフォントをインストールできない場合や、特定のフォントを必ず使用したい場合は、QFontDatabase::addApplicationFont() や QFontDatabase::addApplicationFontFromData() を使用して、アプリケーション実行時にフォントをロードします。
QFont::resolvedFont() を使用する
- QFont::substitutions() は代替フォントのリストを返しますが、実際にQtがレンダリングに使用する最終的なフォントは、QFont::resolvedFont() で取得できます。
- qDebug() << "実際に使用されるフォントファミリー (resolved):" << myFont.resolvedFont().family();
- この情報と substitutions() の結果を比較することで、何が実際に起こっているかをより深く理解できます。
代替フォントのリストを調べる
- substitutions() が何かを返した場合、そのリストに期待するフォントが含まれているか、または問題のあるフォントが含まれていないかを確認します。リスト内のフォントが適切でない場合、それが表示問題の原因である可能性があります。
フォントキャッシュのクリア
- 一部のシステムでは、フォントキャッシュをクリアすることで問題が解決することがあります。
  - Linux: fc-cache -fv を実行し、システムを再起動する。
  - Qtアプリケーションのフォントキャッシュは、アプリケーションが実行されるたびに更新されることがありますが、開発中に何度もフォントを変更する場合は、一時的にキャッシュを無効にするか、Qtのバージョンアップ時にキャッシュが破損していないか確認します。
環境変数の確認
- Linux環境では、QT_QPA_FONTDIR などのQt関連の環境変数がフォントの検索パスに影響を与えることがあります。これらの変数が正しく設定されているか確認します。
- fontconfig が使用されている場合、その設定ファイル（/etc/fonts/fonts.conf やユーザーごとの設定ファイル）が正しいか確認します。
デバッグ出力の活用
- qDebug() を使って、設定したフォント、resolvedFont() の結果、substitutions() の結果などを詳細に出力し、問題の切り分けを行います。
- 特に、フォントのファミリー名やスタイルが正確に指定されているか確認します。
最小限の再現コードを作成する
- 問題が複雑な場合、問題の発生する最小限のコードスニペットを作成します。これにより、問題の原因がフォント設定にあるのか、他のQtウィジェットやレイアウトの問題にあるのかを切り分けることができます。
Qtのバージョンとプラットフォームの確認
- 使用しているQtのバージョンやターゲットプラットフォーム（Windows, macOS, Linux, 組み込みなど）によって、フォントの扱いに違いがある場合があります。公式ドキュメントやQtフォーラムで、特定のバージョンやプラットフォームにおける既知の問題がないか確認します。

例1: 存在しないフォントを設定した場合の代替フォントの確認

この例では、意図的にシステムに存在しないと思われるフォント名を設定し、QFont::substitutions() が何を返すかを確認します。

#include <QApplication>
#include <QFont>
#include <QDebug>
#include <QLabel> // UIに表示する場合のためにインクルード

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

    // 1. 存在しないフォント名でQFontオブジェクトを作成
    //    多くのシステムでは、「NonExistentFont」という名前のフォントは通常インストールされていません。
    QFont myFont("NonExistentFont");
    myFont.setPointSize(24); // フォントサイズを設定

    qDebug() << "--- 例1: 存在しないフォントの場合 ---";
    qDebug() << "設定したフォントファミリー:" << myFont.family();

    // 2. QFont::substitutions() を呼び出して代替フォントのリストを取得
    QStringList substitutions = myFont.substitutions();

    // 3. 代替フォントのリストを表示
    if (substitutions.isEmpty()) {
        qDebug() << "代替フォントはありません。";
        qDebug() << "おそらく、Qtは設定したフォントを見つけられず、システムのデフォルトフォントを使用しています。";
    } else {
        qDebug() << "代替フォントリスト:";
        foreach (const QString &sub, substitutions) {
            qDebug() << "  - " << sub;
        }
        qDebug() << "これは、設定したフォントの代わりにこれらのフォントが使われた可能性を示します。";
    }

    // 4. 実際に解決された（使用される）フォントファミリーも確認
    //    substitutions() は代替の候補ですが、最終的にどのフォントが使われるかは resolvedFont() で確認できます。
    qDebug() << "実際に解決されたフォントファミリー:" << myFont.resolvedFont().family();

    // UIにテキストを表示して視覚的に確認
    QLabel label1("Hello World and こんにちは");
    label1.setFont(myFont);
    label1.setWindowTitle("NonExistentFont Example");
    label1.show();

    return app.exec();
}

出力例（Windows環境の場合）

--- 例1: 存在しないフォントの場合 ---
設定したフォントファミリー: "NonExistentFont"
代替フォントはありません。
おそらく、Qtは設定したフォントを見つけられず、システムのデフォルトフォントを使用しています。
実際に解決されたフォントファミリー: "Segoe UI" // または別のシステムデフォルトフォント

この結果から、NonExistentFont が見つからなかったため substitutions() は空を返し、Qtがシステムのデフォルトフォント（ここでは "Segoe UI"）にフォールバックしたことがわかります。

例2: 特定の言語文字を含むフォントを設定した場合の代替フォントの確認

#include <QApplication>
#include <QFont>
#include <QDebug>
#include <QLabel>
#include <QFontDatabase> // 利用可能なフォントを調べるためにインクルード

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

    // 1. 日本語フォントを設定（システムにインストールされている可能性のあるフォント名を使用）
    //    あなたのシステムにインストールされている可能性のある日本語フォント名に置き換えてください。
    //    例: "メイリオ", "MS ゴシック", "Yu Gothic", "Hiragino Sans GB" など
    QString japaneseFontName = "メイリオ"; // 例: Windowsの場合

    // システムに「メイリオ」がインストールされているか確認する（オプション）
    if (!QFontDatabase::families().contains(japaneseFontName)) {
        qDebug() << QString("警告: フォント '%1' がシステムにインストールされていない可能性があります。").arg(japaneseFontName);
        // 代わりに別のフォントを試すか、デフォルトのフォントを使用させる
        japaneseFontName = "Arial"; // デフォルトフォントに変更
    }

    QFont japaneseFont(japaneseFontName);
    japaneseFont.setPointSize(20);

    qDebug() << "\n--- 例2: 日本語フォントの場合 ---";
    qDebug() << "設定したフォントファミリー:" << japaneseFont.family();

    // 2. QFont::substitutions() を呼び出して代替フォントのリストを取得
    QStringList substitutions = japaneseFont.substitutions();

    // 3. 代替フォントのリストを表示
    if (substitutions.isEmpty()) {
        qDebug() << "代替フォントはありません。";
        qDebug() << "設定したフォントが適切に適用されているか、またはQtが代替を必要としなかったことを示します。";
    } else {
        qDebug() << "代替フォントリスト:";
        foreach (const QString &sub, substitutions) {
            qDebug() << "  - " << sub;
        }
        qDebug() << "これは、特定の文字グリフのためにこれらのフォントが使われた可能性を示します。";
    }

    // 4. 実際に解決された（使用される）フォントファミリーも確認
    qDebug() << "実際に解決されたフォントファミリー:" << japaneseFont.resolvedFont().family();

    // UIに日本語テキストを表示して視覚的に確認
    QLabel label2("こんにちは世界！ Qt プログラミング。");
    label2.setFont(japaneseFont);
    label2.setWindowTitle("Japanese Font Example");
    label2.show();

    return app.exec();
}

--- 例2: 日本語フォントの場合 ---
設定したフォントファミリー: "メイリオ"
代替フォントはありません。
設定したフォントが適切に適用されているか、またはQtが代替を必要としなかったことを示します。
実際に解決されたフォントファミリー: "メイリオ"

特に多言語対応のアプリケーションを開発する際には、対象となる言語の文字が正しく表示されるように、適切なフォントが設定され、必要に応じて代替フォントが正しく機能しているかを確認するために、この関数が活用できます。
フォントの表示問題をデバッグする際には、substitutions() の結果と、QFont::resolvedFont().family() の結果を合わせて確認することが非常に役立ちます。これにより、期待しているフォントが実際に使われているか、あるいは意図しない代替フォントが使われていないかを判断できます。
空のリストが返される場合、それは必ずしも問題ではありません。設定したフォントがそのまま使用されたか、Qtがデフォルトのフォントに静かにフォールバックしたことを意味します。

したがって、「QStringList QFont::substitutions() に関連する代替方法」というよりは、「フォントの代替が発生しないようにする」「フォントの代替を制御する」「代替が発生した場合に情報を得る他の方法」という観点からのプログラミング手法を説明することになります。

以下に、いくつかの代替的・関連するプログラミング手法を説明します。

アプリケーションにフォントを埋め込む (Fonts in Application)

システムに特定のフォントがインストールされていない場合、Qtは代替フォントを探します。この代替を防ぎ、特定のフォントを必ず使用したい場合は、アプリケーション自身にフォントファイルを埋め込むことができます。

方法: QFontDatabase::addApplicationFont() または QFontDatabase::addApplicationFontFromData() を使用します。
- addApplicationFont(const QString &fileName): アプリケーションのリソースに含めたフォントファイル（例: .ttf, .otf）のパスを指定してロードします。
- addApplicationFontFromData(const QByteArray &fontData): フォントファイルのバイナリデータを直接渡してロードします。
目的: ユーザーのシステム環境に依存せず、常に同じフォントを使用する。

コード例

#include <QApplication>
#include <QFont>
#include <QFontDatabase>
#include <QLabel>
#include <QDebug>
#include <QFile> // ファイルから読み込む場合

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

    // リソースにフォントを追加する例 (プロジェクトファイルにRSCファイルを追加する必要があります)
    // 例えば、プロジェクトの .qrc ファイルに <file>fonts/MyCustomFont.ttf</file> を追加
    int fontId = QFontDatabase::addApplicationFont(":/fonts/MyCustomFont.ttf");
    QStringList fontFamilies = QFontDatabase::applicationFontFamilies(fontId);

    QFont customFont;
    if (!fontFamilies.isEmpty()) {
        customFont.setFamily(fontFamilies.at(0));
        qDebug() << "埋め込まれたフォントをロードしました:" << fontFamilies.at(0);
    } else {
        qDebug() << "埋め込まれたフォントのロードに失敗しました。";
        customFont.setFamily("Arial"); // フォールバック
    }
    customFont.setPointSize(24);

    QLabel label("Embedded Font Test");
    label.setFont(customFont);
    label.show();

    // ここで substitutions() を確認しても、意図的に代替を発生させていなければ空になるはずです
    qDebug() << "埋め込みフォントの代替リスト:" << customFont.substitutions();
    qDebug() << "解決されたフォントファミリー:" << customFont.resolvedFont().family();

    return app.exec();
}

フォントエイリアスの設定 (Font Aliases)

Qtは、特定のフォントファミリー名を別のフォントファミリー名にマッピングするフォントエイリアス（別名）を設定できます。これにより、特定のフォントが利用できない場合に、開発者が指定した代替フォントを使用させることができます。

方法: QFontDatabase::addApplicationFont() でフォントをロードした後、QFontDatabase::addApplicationFont() の戻り値である fontId を使用して QFontDatabase::removeAllApplicationFonts() で削除し、新しい名前で再度追加することでエイリアスとして機能させることができます。しかし、より直接的な方法としては、Qtのフォント設定ファイル（qt.conf や環境変数 QT_FONT_FALLBACKS など）を利用したり、プラットフォーム固有のフォント設定を操作したりすることが一般的です。
目的: ユーザーのシステムに依存せず、特定のフォントが利用できない場合にフォールバックとして使用するフォントを明示的に指定する。

QtのAPIで直接フォントエイリアスを設定する直接的な関数は提供されていませんが、QFont コンストラクタで複数のフォントファミリーをカンマ区切りで指定することで、フォールバックの優先順位を設定できます。

コード例 (フォールバック優先順位の設定)

#include <QApplication>
#include <QFont>
#include <QLabel>
#include <QDebug>

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

    // 優先順位を指定してフォントを設定
    // "MyCustomFont" が見つからなければ "Arial", それも見つからなければ "Sans Serif"
    QFont preferredFont("MyCustomFont, Arial, Sans Serif");
    preferredFont.setPointSize(20);

    qDebug() << "設定したフォントファミリー（優先順位付き）:" << preferredFont.family();
    qDebug() << "代替リスト:" << preferredFont.substitutions();
    qDebug() << "解決されたフォントファミリー:" << preferredFont.resolvedFont().family();

    QLabel label("Preferred Font Test");
    label.setFont(preferredFont);
    label.show();

    return app.exec();
}

この場合、substitutions() は MyCustomFont が見つからなかった場合に Arial や Sans Serif が代替として機能したことを報告する可能性があります。

フォントフォールバックの制御 (Font Fallback Control)

特にLinux環境では、Fontconfigライブラリがフォントの選択とフォールバックを管理しています。Qtは通常、システムにインストールされているFontconfigの設定を尊重します。

方法:
- Fontconfig設定ファイル: /etc/fonts/fonts.conf やユーザーの ~/.config/fontconfig/fonts.conf を編集して、フォントの優先順位や代替ルールを定義します。これはQtアプリケーションだけでなく、システム全体のフォント挙動に影響します。
- 環境変数: FC_DEBUG などの環境変数を使ってFontconfigのデバッグ情報を取得したり、QT_QPA_FONTDIR を使って追加のフォントディレクトリを指定したりできます。
目的: よりきめ細かいフォントフォールバックルールを定義する。

コード例 (Fontconfigの設定はC++コードでは直接行いませんが、概念として)

<fontconfig>
  <alias>
    <family>sans-serif</family>
    <prefer>
      <family>Noto Sans CJK JP</family> <family>Arial</family>
    </prefer>
  </alias>
  <match target="pattern">
    <test name="family">
      <string>MyCustomFont</string>
    </test>
    <edit name="family" mode="append" binding="strong">
      <string>Arial</string> </edit>
  </match>
</fontconfig>

このようなシステムレベルの設定変更は、QFont::substitutions() の結果に影響を与えます。

利用可能なフォントの探索と選択 (Exploring Available Fonts)

方法: QFontDatabase::families() や QFontDatabase::styles()、QFontDatabase::font() などを利用します。
目的: アプリケーション実行時に、システムで利用可能なフォントのリストを取得し、ユーザーに選択させたり、適切なフォントをプログラムで決定したりする。

コード例

#include <QApplication>
#include <QFont>
#include <QFontDatabase>
#include <QDebug>
#include <QComboBox> // フォント選択UIの例

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

    qDebug() << "--- 利用可能なフォントファミリー ---";
    QStringList availableFamilies = QFontDatabase::families();
    foreach (const QString &family, availableFamilies) {
        qDebug() << family;
    }

    // UIでフォントを選択させる例
    QComboBox *fontComboBox = new QComboBox();
    fontComboBox->addItems(availableFamilies);
    fontComboBox->setWindowTitle("Font Selector");
    fontComboBox->show();

    // 特定のフォントが bold スタイルを持っているか確認
    if (QFontDatabase::bold("Arial")) {
        qDebug() << "\nArial は太字スタイルをサポートしています。";
    }

    return app.exec();
}

この方法では、substitutions() は直接関係しませんが、代替フォントが発生しないように、利用可能なフォントを適切に選択する設計をする上で非常に重要です。

方法: QFontMetrics::inFont() や QFontDatabase::has Font() などのメソッドを利用します。
目的: 特定の文字がフォントでサポートされているか、グリフが存在するかを確認する。

コード例

#include <QApplication>
#include <QFont>
#include <QFontMetrics>
#include <QDebug>
#include <QLabel>

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

    QFont font("Arial"); // 英語フォント
    font.setPointSize(24);

    QFontMetrics fm(font);

    QChar japaneseChar(0x3042); // ひらがなの 'あ'
    QChar englishChar('A');     // 英語の 'A'

    qDebug() << "フォント:" << font.family();
    qDebug() << "'あ' がフォントに含まれているか:" << fm.inFont(japaneseChar);
    qDebug() << "'A' がフォントに含まれているか:" << fm.inFont(englishChar);

    // 日本語フォントの場合
    QFont japaneseFont("メイリオ"); // または "Yu Gothic" など
    japaneseFont.setPointSize(24);
    QFontMetrics jfm(japaneseFont);

    qDebug() << "\nフォント:" << japaneseFont.family();
    qDebug() << "'あ' がフォントに含まれているか (日本語フォント):" << jfm.inFont(japaneseChar);
    qDebug() << "'A' がフォントに含まれているか (日本語フォント):" << jfm.inFont(englishChar);

    return app.exec();
}

この情報は、substitutions() が空なのに文字化けする、というような状況で、特定のフォントが特定の文字をサポートしていないことが原因であることを特定するのに役立ちます。

QStringList QFont::substitutions() はフォントの代替に関する「結果」を示すものであり、それを「代替」するプログラミング手法というよりは、フォントの代替が発生しないようにするための「事前対策」や、代替が発生した場合に問題を診断するための「補完的な情報取得」と考えるのが適切です。

【Qt】QFont::StyleHintで実現する洗練されたUIデザイン - フォント選びのヒント

StyleHintには、以下のようないくつかの値があります。それぞれの値は、フォントの一般的な特性を表しており、Qtはこれらのヒントに基づいて最適なフォントを選択しようとします。QFont::Monospace: 等幅フォントを優先します。Typewriterと似ていますが、より一般的な等幅フォントを指す場合があります。

QFont::StyleStrategy によるフォントの外観とパフォーマンスの調整

Qt プログラミングにおける QFont::StyleStrategy は、フォントのレンダリング戦略を指定する列挙型です。この戦略は、特に異なるフォントサイズやスタイルを使用する場合に、フォントの外観を最適化するために使用されます。列挙型の値と意味

Qt でフォントの太さをカスタマイズする

Qt プログラミングにおける QFont::Weight は、フォントの太さを表す列挙型です。この列挙型を使うことで、フォントの太さを細かく指定することができます。主な列挙値QFont::Black 極太QFont::ExtraBold 超太字

QFont::bold()

QtプログラミングにおけるQFont::bold()は、QFontオブジェクトが現在、太字の設定になっているかどうかを調べるための関数です。具体的には、以下の特徴があります。関連関数: setBold(bool enable): フォントを太字にするか、通常（太字ではない）にするかを設定します。enableがtrueの場合、フォントのウェイトはQFont::Boldに設定され、falseの場合はQFont::Normalに設定されます。 weight(): フォントのウェイト（太さ）を数値で取得します。QFont::bold()はこのweight()の値がQFont::Normalより大きいかどうかをチェックして結果を返します。 QFontInfo::bold(): 実際に表示されるフォントが太字かどうかを調べたい場合は、QFontInfoクラスのbold()関数を使用します。QFontオブジェクトに設定した太字設定が、システムにインストールされているフォントで実際に適用されるかどうかは、QFontInfoで確認できます。