QSpinBox と QDoubleSpinBox は、数値の入力・調整を簡単に行える便利な GUI ウィジェットです。

本記事では、その基本的な使い方から主要プロパティ・メソッド、よくある質問、実用的な使い方まで詳しく解説します。整数・小数の入力UIを作りたい方、数値制御を行うアプリを作りたい方はぜひ最後までお読みください。

QSpinBox と QDoubleSpinBoxとは？（基本コード）

QSpinBox と QDoubleSpinBox は、数値の入力や調整を簡単に行えるPySide の標準ウィジェットです。

QSpinBox は整数値、QDoubleSpinBox は小数値の入力に対応しており、上下の矢印ボタンやキーボード操作で値を変更できます。これらはフォームの数値入力欄、パラメータ調整、設定画面など幅広い用途に活用されます。小数点以下の桁数指定、接頭辞・接尾辞の付与、値の範囲指定、循環設定など便利な機能が豊富です。

基本コード

from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout, QSpinBox, QDoubleSpinBox
import sys

app = QApplication(sys.argv)
window = QWidget()
layout = QVBoxLayout()

# QSpinBox
spinbox = QSpinBox()
spinbox.setMinimum(0) #最小値
spinbox.setMaximum(100) #最大値
spinbox.setValue(10) #現在値

# QDoubleSpinBox
doublespinbox = QDoubleSpinBox()
doublespinbox.setMinimum(0.0) #最小値
doublespinbox.setMaximum(100.0) #最大値
doublespinbox.setDecimals(2) #桁数設定
doublespinbox.setValue(10.5) #現在値

#============================
#ここにコードを追加してください
#============================

layout.addWidget(spinbox)
layout.addWidget(doublespinbox)
window.setLayout(layout)
window.show()
app.exec()

主なプロパティとメソッド一覧（全解説）

QSpinBoxのメソッド

QDoubleSpinBoxのメソッド

各プロパティ・メソッド 詳細解説

【1】入力できる最小値を設定・取得

• 概要：入力できる最小値を設定・取得します。
• メソッド：setMinimum(int or float) / minimum()
• 使い方：

spinbox.setMinimum(0)
print(spinbox.minimum())

doublespinbox.setMinimum(0.0)
print(doublespinbox.minimum())

# 0
# 0.0

【2】入力できる最大値を設定・取得

• 概要：入力できる最大値を設定・取得します。
• メソッド：setMaximum(int or float) / maximum()
• 使い方：

spinbox.setMaximum(100)
print(spinbox.maximum())

doublespinbox.setMaximum(100.0)
print(doublespinbox.maximum())

# 100
# 100.0

【3】現在の値を設定・取得

• 概要：現在の値を設定・取得します。
• メソッド：setValue(int or float) / value()
• 使い方：

spinbox.setValue(10)
print(spinbox.value())

doublespinbox.setValue(10.5)
print(doublespinbox.value())

# 10
# 10.5

【4】増減のステップ幅を設定・取得

• 概要：増減のステップ幅を設定・取得します。
• メソッド：setSingleStep(int or float) / singleStep()
• 使い方：

spinbox.setSingleStep(2)
print(spinbox.singleStep())

doublespinbox.setSingleStep(0.2)
print(doublespinbox.singleStep())

# 2
# 0.2

【5】値の前に表示する文字列を設定・取得

• 概要：値の前に表示する文字列を設定・取得します。
• メソッド：setPrefix(str) / prefix()
• 使い方：

spinbox.setPrefix("¥")
print(spinbox.prefix())

doublespinbox.setPrefix("$")
print(doublespinbox.prefix())

# ¥
# $

【6】値の後に表示する文字列を設定・取得

• 概要：値の後に表示する文字列を設定・取得します。
• メソッド：setSuffix(str) / suffix()
• 使い方：

spinbox.setSuffix(" kg")
print(spinbox.suffix())

doublespinbox.setSuffix(" m")
print(doublespinbox.suffix())

#  kg
#  m

【7】循環動作の設定・確認

• 概要：最大値を超えると最小値に戻る、または逆にする循環動作の設定・確認をします。
• メソッド：setWrapping(bool) / wrapping()
• 使い方：

spinbox.setWrapping(True)
print(spinbox.wrapping())

doublespinbox.setWrapping(True)
print(doublespinbox.wrapping())

# True
# True

【8】値変更シグナル

• 概要：値が変わったときにシグナルが発生します。
• メソッド：valueChanged(int or float)
• 使い方：

spinbox.valueChanged.connect(lambda v: print(f"SpinBox 値: {v}"))
doublespinbox.valueChanged.connect(lambda v: print(f"DoubleSpinBox 値: {v}"))

# SpinBox 値: 12
# DoubleSpinBox 値: 10.7
# SpinBox 値: 14
# DoubleSpinBox 値: 10.899999999999999

【9】10進数、16進数を設定・取得（QSpinBox）

• 概要：表示する値の進数（例：10進数、16進数）を設定・取得します。
• メソッド：setDisplayIntegerBase(int) / displayIntegerBase()
• 使い方：

spinbox.setDisplayIntegerBase(16)  # 16進数表示
print(spinbox.displayIntegerBase())

【10】小数点以下の表示桁数を設定・取得（QDoubleSpinBox）

• 概要：小数点以下の表示桁数を設定・取得します。
• メソッド：setDecimals(int) / decimals()
• 使い方：

doublespinbox.setDecimals(3)
print(doublespinbox.decimals())

よくある質問（FAQ）

QSpinBox の値が上限を超えたときに自動的に最小値に戻せますか？

setWrapping(True) を使うと上限・下限で循環します。

小数点以下を3桁まで入力したいのですが？

QDoubleSpinBox.setDecimals(3) で設定可能です。

値の変更イベントはどう拾えばいいですか？

valueChanged シグナルを使います。

spinbox.valueChanged.connect(lambda v: print(f"値: {v}"))

接頭辞・接尾辞は途中で変更できますか？

可能です。setPrefix / setSuffix をいつでも呼び出せます。

入力の幅を変えたい場合は？

setMinimumWidth など QWidget のメソッドを使えます。

まとめ

QSpinBox と QDoubleSpinBox は数値入力の標準ウィジェットで、簡単な設定で多様な入力UIが作れます。接頭辞・接尾辞、小数設定、循環などの便利な機能を組み合わせて、実用的なインターフェースを作ってみてください。

次回は、「QPlainTextEdit と QTextEdit の使い方」 を予定しています。テキスト入力UIをさらに強化したい方はぜひご覧ください！

使える.py

PySide超入門【第9回】高機能なテキスト入力フィールドを操る！QPlainTextEditとQTextEdit | 使える.py テキスト入力を扱うGUIアプリでは、QLineEdit では足りない場面が出てきます。そんなときに活躍するのが QPlainTextEdit と QTextEdit です。 この2つは多行のテキスト入力…