qudi.util.widgets.scientific_spinbox

This file contains a wrapper to display the SpinBox in scientific way

Classes

ScienDSpinBox(*args, **kwargs)	Wrapper Class from PyQt5 (or QtPy) to display a QDoubleSpinBox in Scientific way.
ScienSpinBox(*args, **kwargs)	Wrapper Class from PyQt5 (or QtPy) to display a QSpinBox in Scientific way.

class qudi.util.widgets.scientific_spinbox.ScienDSpinBox(*args, **kwargs)

Bases: PySide2.QtWidgets.QAbstractSpinBox

Wrapper Class from PyQt5 (or QtPy) to display a QDoubleSpinBox in Scientific way. Fully supports prefix and suffix functionality of the QDoubleSpinBox. Has built-in functionality to invoke the displayed number precision from the user input.

This class can be directly used in Qt Designer by promoting the QDoubleSpinBox to ScienDSpinBox. State the path to this file (in python style, i.e. dots are separating the directories) as the header file and use the name of the present class.

property assumed_unit_prefix

Default unit prefix for text input.

Returns:

str or None

The default unit prefix string if set, otherwise None.

check_range(value)

Helper method to check if the passed value is within the set minimum and maximum value bounds.

If outside of bounds, the returned value will be clipped to the nearest boundary.

Parameters:

valuefloat or Decimal

Number to be checked.

Returns:

Decimal

The corrected value.

bool

Flag indicating if the value has been changed (True) or not (False).

cleanText()

Compliance method from Qt SpinBoxes.

Returns the currently shown text from the QLineEdit without prefix and suffix and stripped from leading or trailing whitespaces.

Returns:

str

Currently shown text stripped from suffix and prefix.

decimals()

property dynamic_precision

Flag indicating whether dynamic decimal precision should be used based on user input.

Returns:

bool

True to use dynamic decimal precision, False to use fixed precision.

property dynamic_stepping

Flag indicating whether dynamic (logarithmic) stepping should be used or fixed steps.

Returns:

bool

True if dynamic stepping is enabled, False otherwise.

fixup(text)

Takes an invalid string and tries to fix it in order to pass validation. The returned string is not guaranteed to pass validation.

Parameters:

textstr

A string that has not passed validation and needs to be fixed.

Returns:

str

The resulting string from the fix attempt.

focusInEvent(self, event: PySide2.QtGui.QFocusEvent) → None

focusOutEvent(self, event: PySide2.QtGui.QFocusEvent) → None

property is_valid

Flag indicating if the currently available value is valid.

Returns:

bool

True if the current value is valid, False otherwise. Returns False if there has been an attempt to set NaN as the current value; True after a valid value has been set.

keyPressEvent(event)

This method catches all keyboard press events triggered by the user.

Can be used to alter the behaviour of certain key events from the default implementation of QAbstractSpinBox.

Parameters:

eventQKeyEvent

A Qt QKeyEvent instance holding the event information

maximum()

minimalStep()

minimum()

paintEvent(ev)

Add drawing of a red frame around the spinbox if the is_valid flag is False

prefix()

selectAll(self) → None

setDecimals(decimals, dynamic_precision=True)

Set the number of displayed digits after the decimal point and specify dynamic precision.

Parameters:

decimalsint

The number of decimals to be displayed.

dynamic_precisionbool

Flag indicating whether dynamic precision functionality should be used: - If True, the number of decimals will be determined dynamically from user input until

explicitly set by calling this method or entering user text.

• If False, the specified number of decimals will be fixed and will not change automatically.

Returns:

None

setMaximum(maximum)

Setter method to set the maximum value allowed in the SpinBox.

Parameters:

maximumfloat

The maximum value to be set. Input will be converted to float before being stored.

setMinimalStep(step)

Method used to set a minimal step size.

When the absolute step size has been calculated in either dynamic or constant step mode, this value is checked against the minimal step size. If it is smaller then the minimal step size is chosen over the calculated step size. This ensures that no step taken can be smaller than minimalStep.

Set this value to 0 for no minimal step size.

For maximum roboustness and consistency it is strongly recommended to pass step as Decimal or string in order to be converted lossless to Decimal.

Parameters:

stepDecimal|str

The minimal step size to be set.

Returns:

None

setMinimum(minimum)

Setter method to set the minimum value allowed in the SpinBox.

Parameters:

minimumfloat

The minimum value to be set. Input will be converted to float before being stored.

setPrefix(prefix)

Set a string to be shown as non-editable prefix in the spinbox.

Parameters:

prefixstr

The prefix string to be displayed.

Returns:

None

setProperty(prop, val)

For compatibility with QtDesigner. Initializes the value through this method.

Parameters:

proptype

Description of the parameter ‘prop’.

valtype

Description of the parameter ‘val’.

setRange(minimum, maximum)

Convenience method for compliance with Qt SpinBoxes. Essentially a wrapper to call both self.setMinimum and self.setMaximum.

Parameters:

minimumfloat

The minimum value to be set.

maximumfloat

The maximum value to be set.

setSingleStep(step, dynamic_stepping=True)

Set the stepping behavior of the spinbox (e.g., when using the mouse wheel).

When dynamic_stepping=True, the spinbox will perform logarithmic steps according to the current order of magnitude of the values. The step parameter then specifies the step size relative to the value’s order of magnitude. For example, step=0.1 would increment the second most significant digit by one.

When dynamic_stepping=False, the step parameter specifies an absolute step size. This means that each time a step is performed, this value is added or subtracted from the current value.

For maximum robustness and consistency, it is strongly recommended to pass step as a Decimal or string to ensure lossless conversion to Decimal.

Parameters:

stepDecimal or str

The (relative) step size to set. For dynamic_stepping=True, this is relative to the order of magnitude of the current value. For dynamic_stepping=False, this is an absolute step size.

dynamic_steppingbool

Flag indicating the use of dynamic stepping (True) or constant stepping (False).

Returns:

None

setSuffix(suffix)

Set a string to be shown as non-editable suffix in the spinbox. This suffix will come right after the si-prefix.

Parameters:

suffixstr

The suffix string to be displayed after the si-prefix.

Returns:

None

setValue(value)

Setter method to programmatically set the current value. For best robustness pass the value as string or Decimal in order to be lossless cast into Decimal. Will perform range checking and ignore NaN values. Will emit valueChanged if the new value is different from the old one. When using dynamic decimals precision, this method will also try to invoke the optimal display precision by checking for a change in the displayed text.

singleStep()

staticMetaObject = <PySide2.QtCore.QMetaObject object>

stepBy(steps)

This method is responsible for incrementing the value of the SpinBox when the user triggers a step (by pressing PgUp/PgDown/Up/Down, MouseWheel movement or clicking on the arrows). It should handle the case when the new to-set value is out of bounds. Also, the absolute value of a single step increment should be handled here. It is essential to avoid accumulating rounding errors and/or discrepancies between self.value and the displayed text.

Parameters:

stepsint

Number of steps to increment (NOT the absolute step size).

stepEnabled()

Enables stepping (mouse wheel, arrow up/down, clicking, PgUp/Down) by default.

suffix()

textFromValue(value)

This method is responsible for the mapping of the underlying value to a string to display in the SpinBox. Suffix and Prefix must not be handled here, just the si-Prefix.

The main problem here is, that a scaled float with a suffix is represented by a different machine precision than the total value. This method is so complicated because it represents the actual precision of the value as float and not the precision of the scaled si float. ‘{:.20f}’.format(value) shows different digits than ‘{:.20f} {}’.format(scaled_value, si_prefix)

Parameters:

valuefloat or decimal.Decimal

The numeric value to be formatted into a string.

Returns:

str

The formatted string representing the input value.

update_display()

This helper method updates the shown text based on the current value. Because this method is only called upon finishing an editing procedure, the eventually cached value gets deleted.

update_value()

This method will grab the currently shown text from the QLineEdit and interpret it. Range checking is performed on the value afterwards. If a valid value can be derived, it will set this value as the current value (if it has changed) and emit the valueChanged signal. Note that the comparison between old and new value is done by comparing the float representations of both values and not by comparing them as Decimals. The valueChanged signal will only emit if the actual float representation has changed since Decimals are only internally used and the rest of the program won’t notice a slight change in the Decimal that can’t be resolved in a float. In addition it will cache the old value provided the cache is empty to be able to restore it later on.

validate(text, position)

Access method to the validator. See FloatValidator class for more information.

Parameters:

textstr

String to be validated.

positionint

Current text cursor position.

Returns:

QValidator::State

The returned validator state.

str

The input string.

int

The cursor position.

value()

Getter method to obtain the current value as float.

Returns:

float

The current value of the SpinBox as a float.

valueChanged

!! processed by numpydoc !!

valueFromText(text, use_assumed_unit_prefix=False)

Convert a string displayed in the SpinBox into a Decimal value.

The input string is already stripped of prefix and suffix. Only the si-prefix may be present.

Parameters:

textstr

The display string to be converted into a numeric value. This string must conform to the validator.

Returns:

Decimal

The numeric value converted from the input string.

wheelEvent(event)

Overwriting wheel event, such that with the class variable disable_wheel = True the stepping with the mouse wheel is turned off and the wheel event is passed to the parent widget. :param event:

class qudi.util.widgets.scientific_spinbox.ScienSpinBox(*args, **kwargs)

Bases: PySide2.QtWidgets.QAbstractSpinBox

Wrapper Class from PyQt5 (or QtPy) to display a QSpinBox in Scientific way. Fully supports prefix and suffix functionality of the QSpinBox.

This class can be directly used in Qt Designer by promoting the QSpinBox to ScienSpinBox. State the path to this file (in python style, i.e. dots are separating the directories) as the header file and use the name of the present class.

check_range(value)

Helper method to check if the passed value is within the set minimum and maximum value bounds. If outside of bounds, the returned value will be clipped to the nearest boundary.

Parameters:

valueint

Number to be checked.

Returns:

(int, bool)

The corrected value and a flag indicating if the value has been changed: - False: Value has been corrected (clipped). - True: Value remains unchanged.

cleanText()

Compliance method from Qt SpinBoxes. Returns the currently shown text from the QLineEdit without prefix and suffix and stripped from leading or trailing whitespaces.

Returns:

str

Currently shown text stripped from suffix and prefix.

property dynamic_stepping

Property indicating whether dynamic (logarithmic) stepping is enabled or fixed steps are used.

Returns:

bool

True if dynamic stepping is enabled, False if fixed steps are used.

fixup(text)

Takes an invalid string and tries to fix it in order to pass validation. The returned string is not guaranteed to pass validation.

Parameters:

textstr

A string that has not passed validation and needs to be fixed.

Returns:

str

The resulting string from the fix attempt.

focusInEvent(self, event: PySide2.QtGui.QFocusEvent) → None

focusOutEvent(self, event: PySide2.QtGui.QFocusEvent) → None

keyPressEvent(event)

This method catches all keyboard press events triggered by the user. It can be used to alter the behavior of certain key events from the default implementation of QAbstractSpinBox.

Parameters:

eventQKeyEvent

A Qt QKeyEvent instance holding the event information.

maximum()

minimalStep()

minimum()

prefix()

selectAll(self) → None

setMaximum(maximum)

Setter method to set the maximum value allowed in the SpinBox. Input will be converted to int before being stored.

Parameters:

maximumint

The maximum value to be set.

setMinimalStep(step)

Method used to set a minimal step size.

Parameters:

stepint

The minimal step size to be set.

Returns:

None

Notes

When the absolute step size has been calculated in either dynamic or constant step mode, this value is checked against the minimal step size. If it is smaller, then the minimal step size is chosen over the calculated step size. This ensures that no step taken can be smaller than minimalStep. Minimal step size can’t be smaller than 1 for integers.

setMinimum(minimum)

Setter method to set the minimum value allowed in the SpinBox. Input will be converted to int before being stored.

Parameters:

minimumint

The minimum value to be set.

setPrefix(prefix)

Set a string to be shown as a non-editable prefix in the spinbox.

Parameters:

prefixstr

The prefix string to be set.

setProperty(prop, val)

For compatibility with QtDesigner. Initializes the value through this method.

Parameters:

propstr

Property name.

valobject

Value to set for the property.

setRange(minimum, maximum)

Convenience method for compliance with Qt SpinBoxes. Essentially a wrapper to call both self.setMinimum and self.setMaximum.

Parameters:

minimumint

The minimum value to be set.

maximumint

The maximum value to be set.

setSingleStep(step, dynamic_stepping=True)

Method to set the stepping behavior of the spinbox (e.g., when moving the mouse wheel).

Parameters:

stepint

The absolute step size to set. Ignored if dynamic_stepping=True.

dynamic_steppingbool

Flag indicating the stepping method: - True: Use dynamic stepping (logarithmic steps according to current order of magnitude). - False: Use constant stepping (step parameter specifies absolute step size).

Returns:

None

Notes

When dynamic_stepping=True, the step parameter is ignored. The spinbox will increment the second most significant digit by one.

setSuffix(suffix)

Set a string to be shown as a non-editable suffix in the spinbox. This suffix will come right after the SI-prefix.

Parameters:

suffixstr

The suffix string to be set.

setValue(value)

Setter method to programmatically set the current value. Will perform range checking and ignore NaN values. Will emit valueChanged if the new value is different from the old one.

singleStep()

staticMetaObject = <PySide2.QtCore.QMetaObject object>

stepBy(steps)

This method increments the value of the SpinBox when the user triggers a step (by pressing PgUp/PgDown/Up/Down, MouseWheel movement, or clicking on the arrows). It handles cases where the new value to be set is out of bounds. The absolute value of a single step increment is also managed here to avoid accumulating rounding errors or discrepancies between self.value and the displayed text.

Parameters:

stepsint

Number of steps to increment (NOT the absolute step size).

stepEnabled()

Enables stepping (mouse wheel, arrow up/down, clicking, PgUp/Down) by default.

suffix()

textFromValue(value)

This method is responsible for mapping the underlying value to a string to display in the SpinBox. Suffix and Prefix are not handled here, only the SI-prefix.

Parameters:

valueint

The numeric value to be formatted into a string.

Returns:

str

The formatted string representing the input value.

update_display()

This helper method updates the shown text based on the current value. Because this method is only called upon finishing an editing procedure, the eventually cached value gets deleted.

update_value()

This method will grab the currently shown text from the QLineEdit and interpret it. Range checking is performed on the value afterwards. If a valid value can be derived, it will set this value as the current value (if it has changed) and emit the valueChanged signal. In addition it will cache the old value provided the cache is empty to be able to restore it later on.

validate(text, position)

Access method to the validator. See IntegerValidator class for more information.

Parameters:

textstr

String to be validated.

positionint

Current text cursor position.

Returns:

(QValidator.State, str, int)

• The returned validator state.

• The input string.

• The cursor position.

value()

Getter method to obtain the current value as an integer.

Returns:

int

The current value of the SpinBox.

valueChanged

!! processed by numpydoc !!

valueFromText(text)

This method is responsible for converting a string displayed in the SpinBox into an integer value. The input string is already stripped of prefix and suffix. Only the SI-prefix may be present.

Parameters:

textstr

The display string to be converted into a numeric value. This string must conform to the validator.

Returns:

int

The numeric value converted from the input string.

wheelEvent(event)

Overwrites the wheel event. If the class variable disable_wheel = True, stepping with the mouse wheel is turned off and the wheel event is passed to the parent widget.

Parameters:

eventQWheelEvent

A Qt QWheelEvent instance holding the wheel event information.