SpinButton

open class SpinButton : Entry, SpinButtonProtocol

A GtkSpinButton is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a GtkEntry, GtkSpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range.

The main properties of a GtkSpinButton are through an adjustment. See the GtkAdjustment section for more details about an adjustment’s properties. Note that GtkSpinButton will by default make its entry large enough to accomodate the lower and upper bounds of the adjustment, which can lead to surprising results. Best practice is to set both the GtkEntry:width-chars and GtkEntry:max-width-chars poperties to the desired number of characters to display in the entry.

CSS nodes

(plain Language Example):

spinbutton.horizontal
├── undershoot.left
├── undershoot.right
├── entry
│   ╰── ...
├── button.down
╰── button.up

(plain Language Example):

spinbutton.vertical
├── undershoot.left
├── undershoot.right
├── button.up
├── entry
│   ╰── ...
╰── button.down

GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes for the entry and the two buttons, with these names. The button nodes have the style classes .up and .down. The GtkEntry subnodes (if present) are put below the entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node.

Using a GtkSpinButton to get an integer

(C Language Example):

// Provides a function to retrieve an integer value from a GtkSpinButton
// and creates a spin button to model percentage values.

gint
grab_int_value (GtkSpinButton *button,
                gpointer       user_data)
{
  return gtk_spin_button_get_value_as_int (button);
}

void
create_integer_spin_button (void)
{

  GtkWidget *window, *button;
  GtkAdjustment *adjustment;

  adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 5);

  // creates the spinbutton, with no decimal places
  button = gtk_spin_button_new (adjustment, 1.0, 0);
  gtk_container_add (GTK_CONTAINER (window), button);

  gtk_widget_show_all (window);
}

Using a GtkSpinButton to get a floating point value

(C Language Example):

// Provides a function to retrieve a floating point value from a
// GtkSpinButton, and creates a high precision spin button.

gfloat
grab_float_value (GtkSpinButton *button,
                  gpointer       user_data)
{
  return gtk_spin_button_get_value (button);
}

void
create_floating_spin_button (void)
{
  GtkWidget *window, *button;
  GtkAdjustment *adjustment;

  adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 5);

  // creates the spinbutton, with three decimal places
  button = gtk_spin_button_new (adjustment, 0.001, 3);
  gtk_container_add (GTK_CONTAINER (window), button);

  gtk_widget_show_all (window);
}

The SpinButton type acts as a reference-counted owner of an underlying GtkSpinButton instance. It provides the methods that can operate on this data type through SpinButtonProtocol conformance. Use SpinButton as a strong reference or owner of a GtkSpinButton instance.

  • Designated initialiser from the underlying `C` data type.
    

    This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafeMutablePointer<GtkSpinButton>)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafePointer<GtkSpinButton>)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a non-mutating gpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    override public init!(gpointer op: gpointer?)

    Parameters

    op

    gpointer to the underlying object

  • Optional initialiser from a non-mutating gconstpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    override public init!(gconstpointer op: gconstpointer?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafePointer<GtkSpinButton>?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafeMutablePointer<GtkSpinButton>?)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from the underlying C data type. Will retain GtkSpinButton. i.e., ownership is transferred to the SpinButton instance.

    Declaration

    Swift

    @inlinable
    public init(retaining op: UnsafeMutablePointer<GtkSpinButton>)

    Parameters

    op

    pointer to the underlying object

  • Reference intialiser for a related type that implements SpinButtonProtocol Will retain GtkSpinButton.

    Declaration

    Swift

    @inlinable
    public init<T>(spinButton other: T) where T : SpinButtonProtocol

    Parameters

    other

    an instance of a related type that implements SpinButtonProtocol

  • Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init<T>(cPointer p: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe typed, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init<T>(retainingCPointer cPointer: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init(raw p: UnsafeRawPointer)

    Parameters

    p

    raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init(retainingRaw raw: UnsafeRawPointer)
  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    public required init(raw p: UnsafeMutableRawPointer)

    Parameters

    p

    mutable raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    required public init(retainingRaw raw: UnsafeMutableRawPointer)

    Parameters

    raw

    mutable raw pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init(opaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to SpinButtonProtocol.

    Declaration

    Swift

    @inlinable
    override public init(retainingOpaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying object

  • Creates a new GtkSpinButton.

    Declaration

    Swift

    @inlinable
    public init<AdjustmentT>(adjustment: AdjustmentT?, climbRate: Double, digits: Int) where AdjustmentT : AdjustmentProtocol
  • 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 gtk_spin_button_set_digits() to correct it.

    Declaration

    Swift

    @inlinable
    public init(range min: Double, max: Double, step: Double)
  • 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 gtk_spin_button_set_digits() to correct it.

    Declaration

    Swift

    @inlinable
    public static func newWith(range min: Double, max: Double, step: Double) -> Widget!