Skip to content

QQuantity

A widget for editing a quantity: a magnitude, in a spin box, and a unit, in a combo box with the units of the same dimension (for meters: millimeters, kilometers, and so on). The value is a pint.Quantity.

Requires pint

Install pint with the quantity extra:

pip install "superqt[quantity]"
QQuantity QQuantity
from qtpy.QtWidgets import QApplication

from superqt import QQuantity

app = QApplication([])
w = QQuantity("1m")
w.show()

app.exec()

Only one dimension

QQuantity supports units of a single dimension, with an exponent, such as meter ** 2 or 1 / second. Units that combine dimensions, such as meter / second or newton, raise a NotImplementedError.

QQuantity

QQuantity(
    value: str | Quantity | Number = 0,
    units: UnitsContainer | str | Quantity | None = None,
    ureg: UnitRegistry | None = None,
    parent: QWidget | None = None,
)

A combination QDoubleSpinBox and QComboBox for entering quantities.

For this widget, value() returns a pint.Quantity object, while setValue() accepts either a number, pint.Quantity, a string that can be parsed by pint.

Parameters:

  • value (Union[str, Quantity, Number], default: 0 ) –

    The initial value to display. If a string, it will be parsed by pint.

  • units (Union[UnitsContainer, str, Quantity], default: None ) –

    The units to use if value is a number. If a string, it will be parsed by pint. If a pint.Quantity, the units will be extracted from it.

  • ureg (UnitRegistry, default: None ) –

    The unit registry to use. If not provided, the registry will be extracted from value if it is a pint.Quantity, otherwise the default registry will be used.

  • parent (QWidget, default: None ) –

    The parent widget, by default None

Subclass of QWidget

QQuantity inherits all of QWidget's methods, signals, and properties. Only those that superqt adds or changes are listed here.

Signals

  • valueChanged(Quantity)
  • unitsChanged(Unit)
  • dimensionalityChanged(UnitsContainer)

Methods

A combination QDoubleSpinBox and QComboBox for entering quantities.

For this widget, value() returns a pint.Quantity object, while setValue() accepts either a number, pint.Quantity, a string that can be parsed by pint.

Parameters:

  • value (Union[str, Quantity, Number], default: 0 ) –

    The initial value to display. If a string, it will be parsed by pint.

  • units (Union[UnitsContainer, str, Quantity], default: None ) –

    The units to use if value is a number. If a string, it will be parsed by pint. If a pint.Quantity, the units will be extracted from it.

  • ureg (UnitRegistry, default: None ) –

    The unit registry to use. If not provided, the registry will be extracted from value if it is a pint.Quantity, otherwise the default registry will be used.

  • parent (QWidget, default: None ) –

    The parent widget, by default None

dimensionality

dimensionality() -> UnitsContainer

Return the current dimensionality (cast to str for nice repr).

isDimensionless

isDimensionless() -> bool

Return True if the current value is dimensionless.

magnitude

magnitude() -> float | int

Return the magnitude of the current value.

magnitudeSpinBox

magnitudeSpinBox() -> QDoubleSpinBox

Return the QSpinBox widget used to edit the magnitude.

setDecimals

setDecimals(decimals: int) -> None

Set the number of decimals to display in the spinbox.

setMagnitude

setMagnitude(magnitude: Number) -> None

Set the magnitude of the current value.

setUnits

setUnits(units: str | Unit | Quantity | None) -> None

Set the units of the current value.

If units is None, will convert to a dimensionless quantity. Otherwise, units must be compatible with the current dimensionality.

setValue

setValue(
    value: str | Quantity | Number,
    units: UnitsContainer | str | Quantity | None = None,
) -> None

Set the current value (will cast to a pint Quantity).

text

text() -> str

unitRegistry

unitRegistry() -> UnitRegistry

Return the pint UnitRegistry used by this widget.

units

units() -> Unit

Return the current units.

unitsComboBox

unitsComboBox() -> QComboBox

Return the QCombBox widget used to edit the units.

value

value() -> Quantity

Return the current value as a pint.Quantity.