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.