Gtk-- Reference: Gtk::SpinButton

Class Index | Cross Index | Namespace Index

# Class Gtk::SpinButton

Retrieve an integer or floating-point number from the user.
Contained in: Gtk
Derived from: Gtk::Entry
Derived by: none

#include <gtk--/spinbutton.h>

### public function member index:
`` | `SpinButton` | `(`gfloat` `climb_rate`=0, `gint` `digits`=0)`;
`` | `SpinButton` | `(`Adjustment`& `adjustment`, `gfloat` `climb_rate`=0, `gint` `digits`=0)`;
``Adjustment`*` | `get_adjustment` | `() `const``;
``guint`` | `get_digits` | `() `const``;
``bool`` | `get_numeric` | `() `const``;
``GtkShadowType`` | `get_shadow_type` | `() `const``;
``bool`` | `get_snap_to_ticks` | `() `const``;
``GtkSpinButtonUpdatePolicy`` | `get_update_policy` | `() `const``;
``gfloat`` | `get_value_as_float` | `() `const``;
``gint`` | `get_value_as_int` | `() `const``;
``bool`` | `get_wrap` | `() `const``;
``GtkSpinButton`*` | `gtkobj` | `()`;
``const` `GtkSpinButton`*` | `gtkobj` | `() `const``;
``static` `bool`` | `isA` | `(`Object`* `object`)`;
``void`` | `set_adjustment` | `(`Adjustment`& `adjustment`)`;
``void`` | `set_adjustment` | `(`Adjustment`* `adjustment`)`;
``void`` | `set_digits` | `(`gint` `digits`)`;
``void`` | `set_numeric` | `(`bool` `numeric`)`;
``void`` | `set_shadow_type` | `(`GtkShadowType` `shadow_type`)`;
``void`` | `set_snap_to_ticks` | `(`bool` `snap_to_ticks`)`;
``void`` | `set_update_policy` | `(`GtkSpinButtonUpdatePolicy` `policy`)`;
``void`` | `set_value` | `(`gfloat` `value`)`;
``void`` | `set_wrap` | `(`bool` `wrap`)`;
``void`` | `spin` | `(`GtkSpinType` `direction`, `gfloat` `step`)`;
``void`` | `update` | `()`;
``virtual`` | `~SpinButton` | `()`;

## Description:

A `Gtk::SpinButton` 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 ``Gtk`::`Entry``, `Gtk::SpinButton` 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 `Gtk::SpinButton` are through a ``Gtk`::`Adjustment``. See the ``Gtk`::`Adjustment`` section for more details about an adjustment's properties.

The ``Gtk`::`Adjustment`` of a spin button can be set or retrieved with a call to `set_adjustment` or `get_adjustment`, respectively.

The number of digits after the decimal point of a spin button can be altered with `set_digits`.

To retrieve values from a spin button, use `get_value_as_float` if you require a floating point number, or `get_value_as_int` if you require an integer.

To set the value of a `Gtk::SpinButton`, use `set_value`. To change the update behaviour of a spin button, use `set_update_policy`.

When a spin button reaches it's upper or lower limit, it can either stop spinning, or wrap around and continue spinning from the opposite limit. For example, if five is the upper limit and the lower limit is zero, upon reaching the value five, the spin button can change it's value back to zero and continue spinning upwards. This behaviour is set with `set_wrap`.

A border around a spin button's arrows can be created using `set_shadow_type`.

A number may be entered that is invalid, given a spin button's range. An erroneous number can be corrected as soon as the spin button is 'activated' using `set_snap_to_ticks`, which will alter the current value to the nearest step increment. (See ``Gtk`::`Adjustment`` for step increments).

Because a spin contains a ``Gtk`::`Entry``, alphabetic characters may be entered. These can be ignored by using `set_numeric` with a value of TRUE. Then only numeric values, '-' and a decimal point will be accepted.

To manually increment or decrement the spin button, use `spin`, and to force an update (refresh), use `update`.

## Function Member Descriptions:

Gtk::SpinButton::SpinButton - Creates a new `Gtk::SpinButton`.

`` `SpinButton``(`gfloat` `climb_rate`=0, `gint` `digits`=0)`;

> `adjustment`: The ``Gtk`::`Adjustment`` object that this spin button should use.

> `climb_rate`: Specifies how much the spin button changes when an arrow is clicked on.

> `digits`: The number of decimal places to display. Must be less than 6.

Gtk::SpinButton::get_adjustment - Retrieves the GtkAdjustment used by a given spin button.

``Adjustment`*` `get_adjustment``() `const``;

> `Returns`: A ``Gtk`::`Adjustment``.

Gtk::SpinButton::get_value_as_float - Retrieves the current value of a `Gtk::SpinButton`.

``gfloat`` `get_value_as_float``() `const``;

> If the number has no decimal places, it is converted to a float before the function returns. `Returns`: The value of the spin button as a gfloat.

Gtk::SpinButton::get_value_as_int - Retrieves the current integer value of a `Gtk::SpinButton`.

``gint`` `get_value_as_int``() `const``;

> `Returns`: The value of the spin button as a gint.

Gtk::SpinButton::gtkobj - Returns the underlaying gtk+ object.

``GtkSpinButton`*` `gtkobj``()`;
Gtk::SpinButton::isA - Returns true if object is this type.

``static` `bool`` `isA``(`Object`* `object`)`;
Gtk::SpinButton::set_adjustment - Changes which ``Gtk`::`Adjustment`` is associated with a spin button.

``void`` `set_adjustment``(`Adjustment`& `adjustment`)`;

> `adjustment`: A ``Gtk`::`Adjustment``.

Gtk::SpinButton::set_adjustment - Changes which ``Gtk`::`Adjustment`` is associated with a spin button.

``void`` `set_adjustment``(`Adjustment`* `adjustment`)`;

> `adjustment`: A ``Gtk`::`Adjustment``.

Gtk::SpinButton::set_digits - Alters the number of decimal places that are displayed in a spin button.

``void`` `set_digits``(`gint` `digits`)`;

> `digits`: The number of decimal places.

Gtk::SpinButton::set_numeric - Sets how the spin button's ``Gtk`::`Entry`` reacts to alphabetic characters.

``void`` `set_numeric``(`bool` `numeric`)`;

> A value of TRUE to numeric means that all non-numeric characters (except '-' and a decimal point) are ignored.

> `numeric`: Whether letters should be ignored.

Gtk::SpinButton::set_shadow_type - Creates a border around the arrows of a `Gtk::SpinButton`.

``void`` `set_shadow_type``(`GtkShadowType` `shadow_type`)`;

> The type of border is determined by shadow_type.

> `shadow_type`: The new border type. This is one of: `GTK_SHADOW_NONE`, `GTK_SHADOW_IN`, `GTK_SHADOW_OUT`, `GTK_SHADOW_ETCHED_IN`, or `GTK_SHADOW_ETCHED_OUT`.

Gtk::SpinButton::set_snap_to_ticks - Sets whether a number typed into a spin button should be snapped to the nearest step increment.

``void`` `set_snap_to_ticks``(`bool` `snap_to_ticks`)`;

> `snap_to_ticks`: TRUE or FALSE.

Gtk::SpinButton::set_update_policy - Changes the way a spin button refreshes and updates itself.

``void`` `set_update_policy``(`GtkSpinButtonUpdatePolicy` `policy`)`;

> `policy`: The new update policy. This is one of: `GTK_UPDATE_ALWAYS`, or `GTK_UPDATE_IF_VALID`.

Gtk::SpinButton::set_value - Sets the value of a spin button.

``void`` `set_value``(`gfloat` `value`)`;

> `value`: The new floating point value.

Gtk::SpinButton::set_wrap - Sets a spin button's value to the lower limit when it's upper limit is reached, and vice versa.

``void`` `set_wrap``(`bool` `wrap`)`;

> `wrap`: Defaults to FALSE, set to TRUE to make the spin button wrap.

Gtk::SpinButton::spin - Performs an explicit 'spin' on a spin button.

``void`` `spin``(`GtkSpinType` `direction`, `gfloat` `step`)`;

> `direction`: The type of spin to perform.

> `increment`: The amount to spin.

Gtk::SpinButton::update - Refreshes a spin button.

``void`` `update``()`;

> The behaviour of the update is determined `set_update_policy`.