開発者必見！Qtのフォント代替機能substitute()の活用術

QString QFont::substitute() は、Qtフレームワークにおけるフォント処理に関連する重要な関数です。この関数は、特定のフォントファミリ名に対して、そのファミリ名に最も近い、または代替として実際に使用される可能性のあるフォントファミリ名を返します。

どのような時に使うのか？

この関数は、主に以下のシナリオで役立ちます。

---

QFont::substitute() 自体が直接エラーメッセージを出すことは稀です。むしろ、この関数の戻り値が期待と異なることで、アプリケーションのフォント表示が意図しないものになる、といった形で問題が顕在化することがほとんどです。

期待するフォントが代替されない (または、意図しないフォントに代替される)

エラー/現象
setFont("MyCustomFont") と設定したが、font.substitute() が "MyCustomFont" を返さず、別のフォント名（例: "Arial", "Sans Serif", システムのデフォルトフォントなど）を返す。あるいは、逆にシステムに存在しないフォントを設定したのに、substitute() が設定したフォント名をそのまま返してしまう。

原因

• スタイルシート (Qt Style Sheets) の優先度
  Qt Style Sheetsを使用している場合、CSSのルールがウィジェットの setFont() よりも優先されるため、QFont オブジェクトの変更が反映されないことがあります。
• QApplication::setFont() の影響
  アプリケーション全体にデフォルトフォントが設定されている場合、個々のウィジェットのフォント設定が影響を受けることがあります。
• Qtが管理しないフォント
  一部のフォント、特にWebフォントなど、Qtが通常のシステムフォントとして直接管理しないものは、QFontの通常のメカニズムでは期待通りに動作しない場合があります。
• Qtのフォント解決ロジック
  Qtは内部的に複雑なフォント解決ロジックを持っています。特に異なるOS間では、同じフォント名でも実際には異なるフォントが使用されたり、エイリアスが解決されたりすることがあります。
• フォントキャッシュの問題
  Qtのフォントキャッシュが古くなっている、または破損している可能性があります。
• フォント名のスペルミス
  フォント名が正確でない場合、Qtはそれを認識できず、代替フォントを選択します。
• フォントが存在しない/アクセスできない
  最も一般的な原因です。指定したフォントがシステムにインストールされていない、またはアプリケーションがそのフォントファイルにアクセスする権限がない場合に発生します。

トラブルシューティング

• スタイルシートの影響を排除
  
  • 一時的にスタイルシートを無効にしてみて、問題が解決するかどうかを確認します。スタイルシートを使用する場合は、font-family プロパティを正しく設定しているか確認してください。
• QApplication::setFont() との競合確認
  
  • QApplication::setFont() で設定されているフォントが意図しない挙動を引き起こしていないか確認します。必要に応じて、個々のウィジェットで明示的に setFont() を呼び出してオーバーライドします。
• QFontDatabase の活用
  
  • 特定のフォントのスタイル（Regular, Bold, Italicなど）やウェイトを確認するには、QFontDatabase クラスが非常に役立ちます。QFontDatabase::addApplicationFont() を使って、アプリケーションにバンドルされたカスタムフォントをロードすることもできます。
• 代替フォントの確認
  
  • qDebug() << myFont.substitute(); で実際にどのフォント名が返されているかを常に確認し、デバッグに役立てます。
• フォントキャッシュのリフレッシュ
  
  • アプリケーションを再起動してみる。
  • OSのフォントキャッシュをクリアしてみる（OSによって手順が異なります）。
• 正確なフォント名を使用
  
  • フォントファミリ名は、大文字・小文字、スペース、特殊文字を含め、システム上の実際の名前と完全に一致させる必要があります。わずかな違いでも認識されません。QFontDatabase::families() で取得した名前をコピー＆ペーストするのが確実です。
• フォントの存在確認
  
  • システムに実際にフォントがインストールされているか確認します。
  • QFontDatabase::families() を使用して、システムが利用可能なフォントファミリのリストを取得し、目的のフォントが含まれているか確認します。
  • QFontDatabase::hasFamily(const QString &family) を使用して、特定のフォントファミリがシステムに存在するかどうかをプログラムで確認できます。

substitute() が常に同じ結果を返す

エラー/現象
存在しないフォントを設定しても、substitute() が常にデフォルトのフォント名（例: "Sans Serif"）を返す。

原因
これは通常エラーではありません。Qtは、要求されたフォントが見つからない場合に、最も適切なデフォルトのフォントにフォールバックします。そのため、多くの「存在しないフォント」に対しては、同じ「最も適切な」代替フォントが返される可能性が高いです。

トラブルシューティング
これが期待通りの動作であるかを確認し、もし異なる代替を期待している場合は、より具体的なフォントを設定するか、QFontDatabase を使ってフォントの利用可能性をより詳細に制御する必要があります。

マルチスレッド環境でのフォント操作

エラー/現象
複数のスレッドで QFont オブジェクトを操作したり、substitute() を呼び出したりすると、クラッシュや予期せぬ動作が発生する。

原因
QtのGUI関連のクラス（QWidget, QFont など）は、基本的にメインスレッドからのみアクセスされることを想定して設計されています。フォントの解決やレンダリングはOSのリソースに依存することが多いため、スレッドセーフではない場合があります。

トラブルシューティング

• QMetaObject::invokeMethod の使用
  バックグラウンドスレッドからフォント関連の処理をトリガーする必要がある場合は、QMetaObject::invokeMethod を使用して、メインスレッドで実行されるスロットを呼び出すようにします。
• メインスレッドでのGUI操作
  QFont オブジェクトの生成、設定、および substitute() の呼び出しは、可能な限りメインスレッドで行うようにします。

パフォーマンスの問題

エラー/現象
substitute() を頻繁に呼び出すと、アプリケーションのパフォーマンスが低下する。

原因
substitute() は、フォントの解決のためにシステムリソースに問い合わせを行う場合があります。特に多数のフォントオブジェクトに対して頻繁に呼び出すと、オーバーヘッドが発生する可能性があります。

• フォントの事前ロード
  アプリケーション起動時に必要なフォントをすべてロードし、QFontDatabase に登録しておくことで、実行時のフォント解決のコストを削減できます。
• 必要な時のみ呼び出す
  フォントの代替名が必要な場合のみ substitute() を呼び出すようにします。
• 結果のキャッシュ
  substitute() の結果は、フォントが変更されない限り通常は安定しています。同じ QFont オブジェクトに対して何度も substitute() を呼び出すのではなく、一度結果を取得したらそれをキャッシュして再利用することを検討します。

---

QString QFont::substitute() は、Qtが実際にどのフォントファミリ名をテキストのレンダリングに使用しているかを調べるために使われます。特に、要求されたフォントがシステムに存在しない場合の代替フォントの確認や、クロスプラットフォームでのフォント名の解決状況のデバッグに非常に役立ちます。

以下に、いくつかの使用例を挙げます。

例1: 存在しないフォントと存在するフォントの代替状況を確認する

この例では、システムに存在しない可能性のあるフォント名と、一般的に存在するフォント名を設定し、それぞれ substitute() の結果がどうなるかを確認します。

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

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

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

    // --- 例1a: 存在しない可能性のあるフォント ---
    // システムにインストールされていないであろうフォント名
    QFont fontNonExisting("NonExistingFontFamily123");
    QLabel *labelNonExisting = new QLabel("これは存在しないかもしれないフォントです。");
    labelNonExisting->setFont(fontNonExisting);

    QString substitutedNonExisting = fontNonExisting.substitute();
    labelNonExisting->setText(labelNonExisting->text() +
                              "\n(設定: " + fontNonExisting.family() +
                              ", 実際: " + substitutedNonExisting + ")");

    qDebug() << "設定フォント (存在しない可能性):" << fontNonExisting.family();
    qDebug() << "代替フォント (存在しない可能性):" << substitutedNonExisting;
    layout->addWidget(labelNonExisting);

    // --- 例1b: 一般的に存在するフォント ---
    // 例えば、Windowsなら"Meiryo"、macOSなら"Hiragino Kaku Gothic ProN"、Linuxなら"Noto Sans CJK JP"など
    // ここでは、クロスプラットフォームで比較的存在するであろう"Arial"を使用します。
    QFont fontExisting("Arial");
    QLabel *labelExisting = new QLabel("これはArialフォントです。");
    labelExisting->setFont(fontExisting);

    QString substitutedExisting = fontExisting.substitute();
    labelExisting->setText(labelExisting->text() +
                           "\n(設定: " + fontExisting.family() +
                           ", 実際: " + substitutedExisting + ")");

    qDebug() << "設定フォント (存在する):" << fontExisting.family();
    qDebug() << "代替フォント (存在する):" << substitutedExisting;
    layout->addWidget(labelExisting);

    // --- 例1c: 別名を持つフォント ---
    // 例: "Helvetica" はmacOSでは"Helvetica"として認識されるが、Windowsでは"Arial"などに代替されることが多い。
    // 環境によって結果が変わる興味深い例です。
    QFont fontAlias("Helvetica");
    QLabel *labelAlias = new QLabel("これはHelveticaフォント（別名あり？）です。");
    labelAlias->setFont(fontAlias);

    QString substitutedAlias = fontAlias.substitute();
    labelAlias->setText(labelAlias->text() +
                        "\n(設定: " + fontAlias.family() +
                        ", 実際: " + substitutedAlias + ")");

    qDebug() << "設定フォント (別名を持つ可能性):" << fontAlias.family();
    qDebug() << "代替フォント (別名を持つ可能性):" << substitutedAlias;
    layout->addWidget(labelAlias);


    window->setWindowTitle("QFont::substitute() の例");
    window->resize(400, 300);
    window->show();

    return a.exec();
}

解説

• Helvetica のようなフォントは、OSによって代替されるフォントが異なるため、substitute() の結果が環境依存となる面白い例です。
• Arial のような存在するフォントを設定した場合、labelExisting はArialで表示され、substitute() も通常 "Arial" を返します（OSによってはフォントエイリアスなどで異なる場合があります）。
• NonExistingFontFamily123 のような存在しないフォントを設定した場合、labelNonExisting のテキストはシステムのデフォルトフォント（例えば "Sans Serif" や "MS UI Gothic" など）で表示され、substitute() はそのデフォルトフォント名が返されます。

この例では、qDebug() を使ってコンソールにも結果を出力しており、実際の動作を追跡しやすくなっています。

例2: フォントが実際に適用されているかを確認し、ユーザーにフィードバックする

ユーザーが設定したフォントがシステムに存在するかどうかを確認し、存在しない場合はその旨をユーザーに伝えるUIの例です。

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

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

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

    QLabel *instructionLabel = new QLabel("設定したいフォント名を入力してください:");
    layout->addWidget(instructionLabel);

    QLineEdit *fontNameEdit = new QLineEdit;
    fontNameEdit->setPlaceholderText("例: Arial, Meiryo, Times New Roman, NonExistingFont");
    layout->addWidget(fontNameEdit);

    QPushButton *applyButton = new QPushButton("フォントを適用して確認");
    layout->addWidget(applyButton);

    QLabel *displayLabel = new QLabel("これは表示されるテキストです。");
    displayLabel->setFont(QFont("Arial", 16)); // 初期フォント
    layout->addWidget(displayLabel);

    QLabel *statusLabel = new QLabel("状態: フォント未確認");
    layout->addWidget(statusLabel);

    // ボタンがクリックされたときの処理
    QObject::connect(applyButton, &QPushButton::clicked, [&]() {
        QString requestedFontName = fontNameEdit->text().trimmed();

        if (requestedFontName.isEmpty()) {
            QMessageBox::warning(window, "入力エラー", "フォント名を入力してください。");
            return;
        }

        QFont newFont(requestedFontName, 16); // ユーザーが入力したフォント名でQFontを作成
        displayLabel->setFont(newFont); // QLabelにフォントを適用

        QString actualFontName = newFont.substitute(); // 実際に適用されたフォント名を取得

        statusLabel->setText(QString("状態: 設定フォント '%1' -> 実際のフォント '%2'")
                             .arg(requestedFontName)
                             .arg(actualFontName));

        // ユーザーにフィードバック
        if (requestedFontName.compare(actualFontName, Qt::CaseInsensitive) == 0) {
            // 大文字小文字を無視して比較し、同じであればフォントが適用されたと判断
            QMessageBox::information(window, "フォント適用成功",
                                     QString("フォント '%1' が正常に適用されました。").arg(actualFontName));
        } else {
            // 異なる場合、代替フォントが使用されたことを通知
            QMessageBox::warning(window, "フォント適用失敗 (代替)",
                                 QString("要求されたフォント '%1' は見つかりませんでした。\n"
                                         "代わりに '%2' が使用されます。").arg(requestedFontName).arg(actualFontName));
        }
    });

    window->setWindowTitle("フォント適用確認ツール");
    window->resize(500, 250);
    window->show();

    return a.exec();
}

• 異なる場合は、要求されたフォントが見つからず、代替フォントが使用されたことをユーザーにメッセージボックスで通知します。
• 設定したフォント名と substitute() が返したフォント名を比較し、同じであればフォントが正常に適用されたと判断します。
• newFont.substitute() を呼び出し、実際にQtがどのフォントファミリ名を使用したかを取得します。
• 入力されたフォント名で QFont オブジェクトを作成し、QLabel に適用します。
• ユーザーが QLineEdit にフォント名を入力し、「適用して確認」ボタンをクリックします。

---

QFont::substitute() は非常に便利ですが、Qtのフォント管理には他にも多くのツールやアプローチがあります。特定の目的によっては、substitute() よりもこれらの代替手段の方が適している場合があります。

QFontDatabase クラスの利用

QFontDatabase は、システムにインストールされているフォントに関する情報を取得・管理するための最も強力なクラスです。フォントの存在確認、利用可能なスタイルやウェイトの取得、アプリケーションにカスタムフォントを追加する際などに使用します。

代替目的

• カスタムフォントをロードしたい
  アプリケーションにバンドルされたフォントファイルを使用したい場合。
• 利用可能なフォントのリストをユーザーに表示したい
  アプリケーション内でフォント選択ダイアログなどを実装する場合。
• フォントの存在を事前に確認したい
  テキストをレンダリングする前に、特定のフォントがシステムにインストールされているかどうかを確認したい場合。

主な関連メソッド

• QFontDatabase::addApplicationFont(const QString &fileName)
  アプリケーションにバンドルされたフォントファイル（例: .ttf, .otf）をロードし、Qtが利用できるようにします。これにより、ユーザーのシステムにフォントがインストールされていなくても、そのフォントを使用できます。

  // 例: アプリケーションにカスタムフォントを追加
  int fontId = QFontDatabase::addApplicationFont(":/fonts/MyCustomFont.ttf");
  if (fontId != -1) {
      QStringList loadedFamilies = QFontDatabase::applicationFontFamilies(fontId);
      if (!loadedFamilies.isEmpty()) {
          QString myFontName = loadedFamilies.first();
          qDebug() << "カスタムフォント '" << myFontName << "' をロードしました。";
          QFont font(myFontName);
          // ロードしたフォントを適用
      }
  } else {
      qDebug() << "カスタムフォントのロードに失敗しました。";
  }
  

• QFontDatabase::families()
  システムが認識しているすべてのフォントファミリ名のリスト (QStringList) を返します。

  // 例: 利用可能なフォントファミリのリストを取得
  QStringList availableFamilies = QFontDatabase::families();
  qDebug() << "利用可能なフォントファミリ:";
  for (const QString &family : availableFamilies) {
      qDebug() << "- " << family;
  }
  

• QFontDatabase::hasFamily(const QString &family)
  指定されたフォントファミリがシステムに存在するかどうかを bool で返します。substitute() が実際にフォント名を返すのに対し、こちらは単に存在するかどうかだけを確認します。

  // 例: 特定のフォントの存在確認
  QString myFontName = "MyCustomAppFont";
  if (QFontDatabase::hasFamily(myFontName)) {
      qDebug() << myFontName << " はシステムに存在します。";
      QFont font(myFontName);
      // フォントを適用
  } else {
      qDebug() << myFontName << " はシステムに存在しません。代替フォントが使用されます。";
      // 代替フォントの適用、またはユーザーへの通知
  }
  

QFontInfo クラスの利用

QFontInfo は、特定の QFont オブジェクトが実際にレンダリングされる際の物理的なフォントに関する情報を提供するクラスです。substitute() がフォントファミリ名のみを返すのに対し、QFontInfo はフォントのポイントサイズ、スタイル、ウェイト、斜体などの詳細な属性にアクセスできます。

代替目的