:right-sidebar: True SpinButton =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: SpinButton(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.AccessibleRange`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.CellEditable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Editable`, :class:`~gi.repository.Gtk.Orientable` :Constructors: :: SpinButton(**properties) new(adjustment:Gtk.Adjustment=None, climb_rate:float, digits:int) -> Gtk.Widget new_with_range(min:float, max:float, step:float) -> Gtk.Widget Constructors ------------ .. rst-class:: interim-class .. class:: SpinButton :no-index: .. classmethod:: new(adjustment: ~gi.repository.Gtk.Adjustment | None, climb_rate: float, digits: int) -> ~gi.repository.Gtk.Widget Creates a new ``GtkSpinButton``. :param adjustment: the ``GtkAdjustment`` that this spin button should use :param climb_rate: specifies by how much the rate of change in the value will accelerate if you continue to hold down an up/down button or arrow key :param digits: the number of decimal places to display .. classmethod:: new_with_range(min: float, max: float, step: float) -> ~gi.repository.Gtk.Widget Creates a new ``GtkSpinButton`` with the given properties. This is a convenience constructor that allows creation of a numeric ``GtkSpinButton`` without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * ``step`` is the default. The precision of the spin button is equivalent to the precision of ``step``. Note that the way in which the precision is derived works best if ``step`` is a power of ten. If the resulting precision is not suitable for your needs, use :obj:`~gi.repository.Gtk.SpinButton.set_digits` to correct it. :param min: Minimum allowable value :param max: Maximum allowable value :param step: Increment added or subtracted by spinning the widget Methods ------- .. rst-class:: interim-class .. class:: SpinButton :no-index: .. method:: configure(adjustment: ~gi.repository.Gtk.Adjustment | None, climb_rate: float, digits: int) -> None Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. :param adjustment: a ``GtkAdjustment`` to replace the spin button’s existing adjustment, or :const:`None` to leave its current adjustment unchanged :param climb_rate: the new climb rate :param digits: the number of decimal places to display in the spin button .. method:: get_activates_default() -> bool Retrieves the value set by :obj:`~gi.repository.Gtk.SpinButton.set_activates_default`. .. versionadded:: 4.14 .. method:: get_adjustment() -> ~gi.repository.Gtk.Adjustment Get the adjustment associated with a ``GtkSpinButton``. .. method:: get_climb_rate() -> float Returns the acceleration rate for repeated changes. .. method:: get_digits() -> int Fetches the precision of ``spin_button``. .. method:: get_increments() -> tuple[float, float] Gets the current step and page the increments used by ``spin_button``. See :obj:`~gi.repository.Gtk.SpinButton.set_increments`. .. method:: get_numeric() -> bool Returns whether non-numeric text can be typed into the spin button. .. method:: get_range() -> tuple[float, float] Gets the range allowed for ``spin_button``. See :obj:`~gi.repository.Gtk.SpinButton.set_range`. .. method:: get_snap_to_ticks() -> bool Returns whether the values are corrected to the nearest step. .. method:: get_update_policy() -> ~gi.repository.Gtk.SpinButtonUpdatePolicy Gets the update behavior of a spin button. See :obj:`~gi.repository.Gtk.SpinButton.set_update_policy`. .. method:: get_value() -> float Get the value in the ``spin_button``. .. method:: get_value_as_int() -> int Get the value ``spin_button`` represented as an integer. .. method:: get_wrap() -> bool Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. .. method:: set_activates_default(activates_default: bool) -> None Sets whether activating the spin button will activate the default widget for the window containing the spin button. See :obj:`~gi.repository.Gtk.SpinButton.signals.activate` for what counts as activation. .. versionadded:: 4.14 :param activates_default: :const:`True` to activate window’s default widget on activation .. method:: set_adjustment(adjustment: ~gi.repository.Gtk.Adjustment) -> None Replaces the ``GtkAdjustment`` associated with ``spin_button``. :param adjustment: a ``GtkAdjustment`` to replace the existing adjustment .. method:: set_climb_rate(climb_rate: float) -> None Sets the acceleration rate for repeated changes when you hold down a button or key. :param climb_rate: the rate of acceleration, must be >= 0 .. method:: set_digits(digits: int) -> None Set the precision to be displayed by ``spin_button``. Up to 20 digit precision is allowed. :param digits: the number of digits after the decimal point to be displayed for the spin button’s value .. method:: set_increments(step: float, page: float) -> None Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. :param step: increment applied for a button 1 press. :param page: increment applied for a button 2 press. .. method:: set_numeric(numeric: bool) -> None Sets the flag that determines if non-numeric text can be typed into the spin button. :param numeric: flag indicating if only numeric entry is allowed .. method:: set_range(min: float, max: float) -> None Sets the minimum and maximum allowable values for ``spin_button``. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. :param min: minimum allowable value :param max: maximum allowable value .. method:: set_snap_to_ticks(snap_to_ticks: bool) -> None Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value. :param snap_to_ticks: a flag indicating if invalid values should be corrected .. method:: set_update_policy(policy: ~gi.repository.Gtk.SpinButtonUpdatePolicy) -> None Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set. :param policy: a ``GtkSpinButtonUpdatePolicy`` value .. method:: set_value(value: float) -> None Sets the value of ``spin_button``. :param value: the new value .. method:: set_wrap(wrap: bool) -> None Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. :param wrap: a flag indicating if wrapping behavior is performed .. method:: spin(direction: ~gi.repository.Gtk.SpinType, increment: float) -> None Increment or decrement a spin button’s value in a specified direction by a specified amount. :param direction: a ``GtkSpinType`` indicating the direction to spin :param increment: step increment to apply in the specified direction .. method:: update() -> None Manually force an update of the spin button. Properties ---------- .. rst-class:: interim-class .. class:: SpinButton :no-index: .. attribute:: props.activates_default :type: bool Whether to activate the default widget when the spin button is activated. See :obj:`~gi.repository.Gtk.SpinButton.signals.activate` for what counts as activation. .. versionadded:: 4.14 .. attribute:: props.adjustment :type: ~gi.repository.Gtk.Adjustment The adjustment that holds the value of the spin button. .. attribute:: props.climb_rate :type: float The acceleration rate when you hold down a button or key. .. attribute:: props.digits :type: int The number of decimal places to display. .. attribute:: props.numeric :type: bool Whether non-numeric characters should be ignored. .. attribute:: props.snap_to_ticks :type: bool Whether erroneous values are automatically changed to the spin buttons nearest step increment. .. attribute:: props.update_policy :type: ~gi.repository.Gtk.SpinButtonUpdatePolicy Whether the spin button should update always, or only when the value is acceptable. .. attribute:: props.value :type: float The current value. .. attribute:: props.wrap :type: bool Whether a spin button should wrap upon reaching its limits. Signals ------- .. rst-class:: interim-class .. class:: SpinButton.signals :no-index: .. method:: activate() -> None Emitted when the spin button is activated. The keybindings for this signal are all forms of the :kbd:`Enter` key. If the :kbd:`Enter` key results in the value being committed to the spin button, then activation does not occur until :kbd:`Enter` is pressed again. .. versionadded:: 4.14 .. method:: change_value(scroll: ~gi.repository.Gtk.ScrollType) -> None Emitted when the user initiates a value change. This is a `keybinding signal `_. Applications should not connect to it, but may emit it with :func:`~gi.repository.GObject.signal_emit_by_name` if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp/PageDown. :param scroll: a ``GtkScrollType`` to specify the speed and amount of change .. method:: input() -> tuple[int, float] Emitted to convert the users input into a double value. The signal handler is expected to use :obj:`~gi.repository.Gtk.Editable.get_text` to retrieve the text of the spinbutton and set ``new_value`` to the new value. The default conversion uses :func:`~gi.repository.GLib.strtod`. .. method:: output() -> bool Emitted to tweak the formatting of the value for display. .. code-block:: c :dedent: // show leading zeros static gboolean on_output (GtkSpinButton *spin, gpointer data) { char *text; int value; value = gtk_spin_button_get_value_as_int (spin); text = g_strdup_printf ("``%02d``", value); gtk_editable_set_text (GTK_EDITABLE (spin), text): g_free (text); return TRUE; } .. method:: value_changed() -> None Emitted when the value is changed. Also see the :obj:`~gi.repository.Gtk.SpinButton.signals.output` signal. .. method:: wrapped() -> None Emitted right after the spinbutton wraps from its maximum to its minimum value or vice-versa.