QSpinBox::suffix

2025-05-31

簡単に言うと、ユーザーがスピンボックスで選択・入力した数値の後ろに表示される文字列を設定するために使われます。

例えば、QSpinBox で数値を設定する際に、その数値が「個数」を表すのであれば、「5 個」のように「個」という単位を表示したい場合があります。このような場合に suffix プロパティを使用します。

具体的に、suffix の設定は以下のようになります。

  • suffix() const: 現在設定されているサフィックスの文字列を取得する関数です。
  • setSuffix(const QString &suffix): スピンボックスのサフィックスを設定する関数です。QString で指定した文字列が数値の後ろに表示されます。

使用例

#include <QApplication>
#include <QSpinBox>
#include <QVBoxLayout>
#include <QWidget>

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

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

    QSpinBox *spinBox = new QSpinBox(&window);
    spinBox->setRange(0, 100); // 0から100までの範囲を設定
    spinBox->setValue(10);    // 初期値を10に設定

    // ここが QSpinBox::suffix の設定です
    spinBox->setSuffix(" kg"); // 数値の後ろに " kg" を表示する

    layout->addWidget(spinBox);
    window.setLayout(layout);
    window.setWindowTitle("QSpinBox Suffix Example");
    window.show();

    return a.exec();
}

このコードを実行すると、スピンボックスには「10 kg」のように表示されます。ユーザーが数値を変更しても、「11 kg」や「9 kg」のように、常に数値の後に「 kg」が表示されます。

  • 表示専用
    suffix はあくまで表示のためのものであり、スピンボックスが持つ実際の数値データ(value() で取得できる値)には影響を与えません。例えば、「10 kg」と表示されていても、value()10 を返します。
  • ユーザーエクスペリエンスの向上
    ユーザーは数値の意味をすぐに理解でき、誤解を減らすことができます。


サフィックスが表示されない/意図しない表示になる

よくある間違い

  • Qt Designer で設定したが、コードで上書きされている
    Qt Designer でサフィックスを設定した場合でも、コード内で setSuffix() を呼び出すと、コードの設定が優先されます。
  • サフィックスが長すぎる、または他のウィジェットと重なっている
    サフィックスの文字列が長すぎると、スピンボックスの幅が足りずに一部が隠れてしまったり、隣接するウィジェットと重なったりすることがあります。
  • 空の文字列を設定している
    setSuffix("") とすると、サフィックスは非表示になります。意図的に非表示にしたい場合は問題ありませんが、表示させたいのに空文字列を設定していると表示されません。
  • setSuffix() を呼び忘れている、または間違った場所で呼び出している
    QSpinBox オブジェクトを作成した後、setSuffix() を呼び出してサフィックスを設定する必要があります。例えば、UIファイル(.ui)で設定しているつもりでも、コードから動的に作成している場合は忘れがちです。

トラブルシューティング

  • レイアウトを確認する
    スピンボックスのサイズヒント(sizeHint())や、親ウィジェットのレイアウト(QHBoxLayout, QVBoxLayout, QGridLayout など)が適切に設定されているか確認し、十分なスペースがあるか確認します。必要に応じて、スピンボックスの最小幅を設定したり、レイアウトのストレッチファクターを調整したりします。
  • サフィックスの文字列を確認する
    qDebug() << spinBox->suffix(); のようにして、現在設定されているサフィックスの文字列を確認し、意図した通りになっているか確認します。
  • setSuffix() が呼ばれていることを確認する
    デバッグモードで実行し、setSpinBox->setSuffix("単位"); のような行が実際に実行されているか確認してください。

数値とサフィックスの間にスペースがない/多すぎる

よくある間違い

  • スペースを含めずにサフィックスを設定している
    setSuffix("kg") とすると、「10kg」のように数値とサフィックスがくっついて表示されます。多くの場合、「10 kg」のように間にスペースを入れたいでしょう。

トラブルシューティング

  • サフィックス文字列にスペースを含める
    setSuffix(" kg") のように、文字列の先頭にスペースを含めることで、数値との間に適切な間隔ができます。

サフィックスが編集中に消える

よくある間違い

  • これは「間違い」ではありませんが、QSpinBox の標準的な挙動です。ユーザーがスピンボックスの値を直接編集するためにテキストエディタ部分をクリックすると、サフィックスは一時的に非表示になり、数値だけが表示されます。入力が完了してフォーカスが外れると、再びサフィックスが表示されます。

トラブルシューティング

  • 常にサフィックスを表示したい場合(稀なケース)
    もし、何らかの理由で編集時もサフィックスを常に表示したい場合は、QAbstractSpinBox を継承して textFromValue() メソッドをオーバーライドし、カスタムの表示ロジックを実装する必要があります。しかし、これは複雑になりがちで、ユーザーエクスペリエンスを損なう可能性もあるため、通常は推奨されません。
  • これは期待される動作であると理解する
    Qt のデザイン哲学に基づいた挙動であり、通常は問題ありません。ユーザーは数値の入力に集中できます。

QDoubleSpinBox での小数点以下の精度とサフィックス

よくある間違い

  • QDoubleSpinBox で小数点以下の精度を設定しているが、サフィックスと組み合わせると表示が崩れる。

トラブルシューティング

  • 丸め誤差に注意する
    浮動小数点数の計算には丸め誤差がつきものです。表示される数値が期待と異なる場合は、setDecimals() の設定を確認するとともに、数値の内部的な表現に注意を払う必要があります。
  • setDecimals() で小数点以下の桁数を適切に設定する
    QDoubleSpinBox の場合は setDecimals() を使用して、表示したい小数点以下の桁数を明示的に指定します。これにより、数値の表示が適切にフォーマットされ、サフィックスとの組み合わせも自然になります。

サフィックスを動的に変更したい

よくある間違い

  • サフィックスの文字列を変更する際に、スピンボックスの表示が即座に更新されないと勘違いする。
  • setSuffix() を呼び出すと、スピンボックスの表示は自動的に更新されます。もし更新されない場合は、Qt のイベントループが正しく動作していないか、UIスレッド以外から更新を試みているなどの、より根本的な問題が考えられます。
  • qDebug() を活用する
    重要な箇所に qDebug() を挿入し、プログラムの実行フローや変数の値を確認します。
  • デバッガを使用する
    ブレークポイントを設定して、変数の値や関数の呼び出し順序を確認します。
  • Qt のドキュメントを参照する
    QSpinBoxQAbstractSpinBox の公式ドキュメントには、詳細な情報や使用例が記載されています。
  • 最小限の再現コードを作成する
    問題が発生した場合、関係ない部分をすべて削ぎ落とし、QSpinBoxsuffix の設定だけに絞った最小限のコードを作成してみてください。これにより、問題の原因を特定しやすくなります。


例1:基本的なサフィックスの設定(単位の表示)

最も一般的な使用例です。数値の後に単位を表示します。

#include <QApplication>
#include <QSpinBox>
#include <QVBoxLayout>
#include <QWidget>

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

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

    // QSpinBox を作成
    QSpinBox *spinBoxWeight = new QSpinBox(&window);
    spinBoxWeight->setRange(0, 500); // 0から500までの範囲
    spinBoxWeight->setValue(75);     // 初期値

    // ★ ここで suffix を設定 ★
    spinBoxWeight->setSuffix(" kg"); // " kg" をサフィックスとして追加 (先頭にスペース)

    // 別の QSpinBox の例
    QSpinBox *spinBoxQuantity = new QSpinBox(&window);
    spinBoxQuantity->setRange(1, 100);
    spinBoxQuantity->setValue(5);
    spinBoxQuantity->setSuffix(" 個"); // " 個" をサフィックスとして追加

    layout->addWidget(spinBoxWeight);
    layout->addWidget(spinBoxQuantity);

    window.setLayout(layout);
    window.setWindowTitle("QSpinBox Suffix Examples (Basic)");
    window.show();

    return app.exec();
}

解説

  • " kg" のように、数値との間にスペースを入れることで、表示がより自然になります。
  • spinBoxWeight->setSuffix(" kg"); のように、文字列を setSuffix() に渡すだけで簡単に設定できます。

例2:サフィックスの動的な変更

ユーザーのアクションやプログラムの状態に応じて、サフィックスを動的に変更する例です。

#include <QApplication>
#include <QSpinBox>
#include <QComboBox> // 単位選択のために使用
#include <QVBoxLayout>
#include <QHBoxLayout>
#include <QWidget>
#include <QLabel>

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

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

    // 重量入力用のスピンボックス
    QSpinBox *spinBoxValue = new QSpinBox(&window);
    spinBoxValue->setRange(0, 1000);
    spinBoxValue->setValue(100);

    // 単位選択用のコンボボックス
    QComboBox *unitComboBox = new QComboBox(&window);
    unitComboBox->addItem("kg");
    unitComboBox->addItem("g");
    unitComboBox->addItem("lb");

    // コンボボックスの選択が変更されたときに、spinBoxValue の suffix を更新する
    QObject::connect(unitComboBox, &QComboBox::currentTextChanged,
                     spinBoxValue, [spinBoxValue](const QString &text){
        spinBoxValue->setSuffix(" " + text); // 選択された単位をサフィックスに設定
    });

    // 初期サフィックスを設定 (コンボボックスの初期選択に合わせて)
    spinBoxValue->setSuffix(" " + unitComboBox->currentText());

    QHBoxLayout *inputLayout = new QHBoxLayout();
    inputLayout->addWidget(new QLabel("重さ:", &window));
    inputLayout->addWidget(spinBoxValue);
    inputLayout->addWidget(unitComboBox);

    mainLayout->addLayout(inputLayout);
    window.setLayout(mainLayout);
    window.setWindowTitle("QSpinBox Suffix Dynamic Change");
    window.show();

    return app.exec();
}

解説

  • これにより、コンボボックスで「g」を選択するとスピンボックスが「100 g」と表示されるように、サフィックスが動的に変わります。
  • QObject::connect() を使用し、unitComboBox の選択が変更されるたびに、ラムダ関数が実行され、spinBoxValue->setSuffix() が呼び出されます。
  • QComboBox を使用して、ユーザーが単位(kg, g, lb)を選択できるようにしています。

Qt Creator の統合開発環境を使っている場合、UI ファイル(.ui)内で suffix を直接設定することもできます。これはコードを書く手間を省き、GUI デザインの段階で視覚的に確認できる利点があります。

手順

  1. Qt Creator を開き、「新しいプロジェクト」→「Qt Widgets Application」を作成します。
  2. Forms フォルダ内の mainwindow.ui をダブルクリックして Qt Designer を開きます。
  3. ウィジェットボックスから Spin Box をドラッグ&ドロップして、フォームに配置します。
  4. 配置した Spin Box を選択します。
  5. プロパティエディタ(通常は右側に表示される)で、QSpinBox のセクションを探します。
  6. suffix プロパティを見つけ、その右側のフィールドに希望のサフィックス文字列(例: %)を入力します。
  7. ファイルを保存し、プロジェクトをビルドして実行します。

コード(UIファイルから生成されるもの、手動で書く必要なし)

Qt Designer で設定すると、C++コード側では通常、以下のように自動的に生成されたUIクラスの setupUi メソッド内で設定されます。(直接書くわけではありませんが、内部でこのように解釈されます)

// ui_mainwindow.h (mocによって自動生成されるコードの一部)
// mainwindow.cpp のコンストラクタで ui->setupUi(this); が呼び出されると実行される

void Ui_MainWindow::setupUi(QMainWindow *MainWindow)
{
    // ... 他のウィジェットの設定 ...

    spinBox = new QSpinBox(this);
    spinBox->setObjectName(QStringLiteral("spinBox"));
    spinBox->setSuffix(QStringLiteral(" %")); // ★ ここが Designer で設定した内容 ★

    // ... レイアウトへの追加など ...
}
  • ただし、プログラムの実行中に動的にサフィックスを変更したい場合は、例2のようにコードで setSuffix() を呼び出す必要があります。
  • 特に複雑な UI をデザインする際に、WYSIWYG(What You See Is What You Get)で確認できるため便利です。
  • Qt Designer を使うことで、コーディングなしに suffix を設定できます。


QAbstractSpinBox::textFromValue() / valueFromText() をオーバーライドする

これは最も強力で柔軟な方法であり、QSpinBoxQDoubleSpinBox の親クラスである QAbstractSpinBox の仮想関数をオーバーライドすることで実現します。これにより、数値とテキスト間の変換ロジックを完全に制御できます。

  • double QAbstractSpinBox::valueFromText(const QString &text) (QDoubleSpinBoxの場合)
    • ユーザーがスピンボックスのテキストエディタに直接入力したテキスト(QString)を、内部的な数値(int または double)に変換するために呼び出されます。textFromValue() で追加したサフィックスなどをここできちんと取り除き、数値部分だけをパースする必要があります。
  • int QAbstractSpinBox::valueFromText(const QString &text) (QSpinBoxの場合)
  • QString QAbstractSpinBox::textFromValue(int value) (QSpinBoxの場合)

利点

  • 編集時の挙動も制御可能
    ユーザーが値を編集する際も、このロジックを通じてテキストが処理されます。suffix と異なり、編集時にもサフィックスの一部を表示し続けるといったことも理論的には可能です。
  • 完全な制御
    数値の表示形式を完全にカスタマイズできます。サフィックスだけでなく、プレフィックス、単位の位置、複数の単位の切り替え、特殊な丸め処理なども実装可能です。

欠点

  • suffix のシンプルさに欠ける
    単純にサフィックスを追加するだけであれば、setSuffix() の方がはるかに簡単です。
  • 実装が複雑
    新しいクラスを定義し、これらの仮想関数を適切にオーバーライドする必要があります。valueFromText() の実装は特に慎重に行う必要があり、パースエラーの処理も考慮しなければなりません。

使用例(QSpinBoxのサブクラス化)

#include <QApplication>
#include <QSpinBox>
#include <QVBoxLayout>
#include <QWidget>
#include <QLabel> // for demonstration

// CustomSpinBox クラスを QSpinBox から継承
class CustomSpinBox : public QSpinBox
{
public:
    explicit CustomSpinBox(QWidget *parent = nullptr)
        : QSpinBox(parent)
    {
    }

protected:
    // 数値から表示テキストへの変換をカスタマイズ
    QString textFromValue(int value) const override
    {
        // 単位を日本語の「個」に固定して表示
        // ここで任意の表示形式を構築できる
        return QString::number(value) + " 個";
    }

    // 表示テキストから数値への変換をカスタマイズ
    int valueFromText(const QString &text) const override
    {
        // " 個" の部分を取り除いて数値に変換
        // もし入力が不正な場合は、現在の値を返すなどのエラー処理が必要
        QString strippedText = text;
        strippedText.remove(" 個"); // サフィックスを取り除く
        bool ok;
        int value = strippedText.toInt(&ok);
        if (ok) {
            return value;
        }
        return this->value(); // パース失敗時は現在の値を返す
    }
};

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

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

    CustomSpinBox *spinBox = new CustomSpinBox(&window);
    spinBox->setRange(0, 100);
    spinBox->setValue(10);
    // setSuffix() は使用しない

    layout->addWidget(new QLabel("CustomSpinBox (Units always '個'):", &window));
    layout->addWidget(spinBox);

    window.setLayout(layout);
    window.setWindowTitle("Custom SpinBox with textFromValue/valueFromText");
    window.show();

    return app.exec();
}

QLineEdit と QLabel を組み合わせる

QSpinBox を直接使用せず、テキスト入力用の QLineEdit と、その隣に単位などを表示するための QLabel を配置する方法です。

利点

  • シンプルな構造
    QSpinBox のサブクラス化が不要です。
  • 視覚的な柔軟性
    QLabel にはフォント、色、背景などを自由に設定できるため、サフィックスの表示スタイルを細かく制御できます。

欠点

  • 編集時の統一感がない
    ユーザーが QLineEdit を編集している間も QLabel は常に表示されますが、QSpinBox のような「編集モード」の概念はありません。
  • データの同期
    QLineEdit のテキスト変更と、内部的な数値データの同期を自分で行う必要があります。
  • 機能の再現が必要
    QSpinBox が提供するアップ/ダウンボタン、値の範囲チェック、キーボード操作(↑↓キーでの増減)といった機能を独自に実装する必要があります。これは非常に手間がかかります。

使用例(概念のみ、完全なQSpinBoxの機能再現は省略)

#include <QApplication>
#include <QLineEdit>
#include <QLabel>
#include <QHBoxLayout>
#include <QWidget>
#include <QPushButton> // For simple up/down buttons

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

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

    QLineEdit *lineEdit = new QLineEdit(&window);
    lineEdit->setValidator(new QIntValidator(0, 100, &window)); // 数値入力に制限
    lineEdit->setText("10"); // 初期値

    QLabel *suffixLabel = new QLabel(" kg", &window); // 単位を表示するラベル

    // QSpinBoxのアップダウンボタンの代わり
    QVBoxLayout *buttonLayout = new QVBoxLayout();
    QPushButton *upButton = new QPushButton("▲", &window);
    QPushButton *downButton = new QPushButton("▼", &window);
    buttonLayout->addWidget(upButton);
    buttonLayout->addWidget(downButton);
    buttonLayout->setContentsMargins(0,0,0,0); // 余分なマージンを削除

    // 数値の増減ロジック(非常に単純化)
    QObject::connect(upButton, &QPushButton::clicked, lineEdit, [lineEdit](){
        int value = lineEdit->text().toInt();
        lineEdit->setText(QString::number(value + 1));
    });
    QObject::connect(downButton, &QPushButton::clicked, lineEdit, [lineEdit](){
        int value = lineEdit->text().toInt();
        lineEdit->setText(QString::number(value - 1));
    });


    layout->addWidget(lineEdit);
    layout->addWidget(suffixLabel);
    layout->addLayout(buttonLayout); // ボタンを追加

    window.setLayout(layout);
    window.setWindowTitle("QLineEdit + QLabel (Alternative to QSpinBox::suffix)");
    window.show();

    return app.exec();
}

イベントフィルタリング(あまり推奨されないが、可能性として)

QSpinBox の内部にある QLineEditfindChild<QLineEdit*>() などで取得できる)に対してイベントフィルターを設定し、表示をカスタマイズするという方法も考えられます。例えば、paintEvent を監視して直接描画を調整したり、keyPressEvent をインターセプトして特定のキー入力を処理したりできます。

利点

  • 既存の QSpinBox のインスタンスに対して、その場でカスタマイズを適用できる。
  • 通常は過剰な手段
    単純なサフィックス表示のためにここまでする必要はありません。
  • デバッグが困難
    予期せぬ副作用が発生しやすいです。
  • 非常に複雑で脆い
    Qt の内部実装に依存することになるため、Qt のバージョンアップで挙動が変わる可能性があります。
  • QSpinBox の機能を全く必要とせず、単なる数値入力と固定された単位表示で十分な場合
    QLineEditQLabel の組み合わせも選択肢になります。ただし、スピンボックスの基本的な機能(ボタンでの増減、範囲チェックなど)が必要ない場合に限ります。
  • 表示形式を細かく制御したい、または編集時の挙動もカスタマイズしたい
    QAbstractSpinBox::textFromValue() / valueFromText() をオーバーライドするのが適切です。カスタムクラスを定義する手間はかかりますが、最も堅牢で柔軟な方法です。
  • 最もシンプルで一般的なケース(単位など)
    QSpinBox::setSuffix() を使うべきです。これが最も簡単で、Qt の意図した使い方です。