Description
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 a GtkAdjustment. See the GtkAdjustment section for more details about an adjustment's properties.
Example 1. Using a GtkSpinButton to get an integer.
/* 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 *a_spinner, gpointer user_data) {
return gtk_spin_button_get_value_as_int (a_spinner);
}
void create_integer_spin_button(void) {
GtkWidget *window, *spinner;
GtkAdjustment *spinner_adj;
spinner_adj = (GtkAdjustment *) gtk_adjustment_new(50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
/* creates the spinner, with no decimal places */
spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
gtk_container_add (GTK_CONTAINER(window), spinner);
gtk_widget_show_all (window);
return;
}
|
Example 2. Using a GtkSpinButton to get a floating point value.
/* Provides a function to retrieve a floating point value from a
* GtkSpinButton, and creates a high precision spin button.
*/
gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
return gtk_spin_button_get_value_as_float (a_spinner);
}
void create_floating_spin_button(void) {
GtkWidget *window, *spinner;
GtkAdjustment *spinner_adj;
spinner_adj = (GtkAdjustment *) gtk_adjustment_new(2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
/* creates the spinner, with three decimal places */
spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
gtk_container_add (GTK_CONTAINER(window), spinner);
gtk_widget_show_all (window);
return;
}
|
Details
struct GtkSpinButton
entry is the GtkEntry part of the GtkSpinButton widget, and can be used accordingly. All other fields contain private data and should only be modified using the functions below.
enum GtkSpinButtonUpdatePolicy
typedef enum
{
GTK_UPDATE_ALWAYS,
GTK_UPDATE_IF_VALID
} GtkSpinButtonUpdatePolicy; |
enum GtkSpinType
typedef enum
{
GTK_SPIN_STEP_FORWARD,
GTK_SPIN_STEP_BACKWARD,
GTK_SPIN_PAGE_FORWARD,
GTK_SPIN_PAGE_BACKWARD,
GTK_SPIN_HOME,
GTK_SPIN_END,
GTK_SPIN_USER_DEFINED
} GtkSpinType; |
gtk_spin_button_configure ()
Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call.
gtk_spin_button_new_with_range ()
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.
gtk_spin_button_set_adjustment ()
Replaces the GtkAdjustment associated with spin_button.
gtk_spin_button_get_adjustment ()
Get the adjustment associated with a GtkSpinButton
gtk_spin_button_set_digits ()
Set the precision to be displayed by spin_button. Up to 20 digit precision
is allowed.
gtk_spin_button_set_increments ()
Sets the step and page increments for spin_button. This affects how
quickly the value changes when the spin button's arrows are activated.
gtk_spin_button_set_range ()
Sets the minimum and maximum allowable values for spin_button
gtk_spin_button_get_value_as_float
#define gtk_spin_button_get_value_as_float gtk_spin_button_get_value |
Warning |
gtk_spin_button_get_value_as_float is deprecated and should not be used in newly-written code. |
gtk_spin_button_get_value_as_int ()
Get the value spin_button represented as an integer.
gtk_spin_button_set_value ()
Set the value of spin_button.
gtk_spin_button_set_update_policy ()
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.
gtk_spin_button_set_numeric ()
Sets the flag that determines if non-numeric text can be typed into
the spin button.
gtk_spin_button_spin ()
Increment or decrement a spin button's value in a specified direction
by a specified amount.
gtk_spin_button_set_wrap ()
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.
gtk_spin_button_set_snap_to_ticks ()
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.
gtk_spin_button_update ()
Manually force an update of the spin button.
GTK_INPUT_ERROR
#define GTK_INPUT_ERROR -1 |