| GTK+ Reference Manual | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> | 
| "adjustment" GtkAdjustment : Read / Write "climb-rate" gdouble : Read / Write "digits" guint : Read / Write "snap-to-ticks" gboolean : Read / Write "numeric" gboolean : Read / Write "wrap" gboolean : Read / Write "update-policy" GtkSpinButtonUpdatePolicy : Read / Write "value" gdouble : Read / Write | 
| "change-value" void user_function (GtkSpinButton *spinbutton, GtkScrollType arg1, gpointer user_data); "input" gint user_function (GtkSpinButton *spinbutton, gpointer arg1, gpointer user_data); "output" gboolean user_function (GtkSpinButton *spinbutton, gpointer user_data); "value-changed" void user_function (GtkSpinButton *spinbutton, gpointer user_data); | 
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 (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;
}
 | 
| 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.
| typedef enum
{
  GTK_UPDATE_ALWAYS,
  GTK_UPDATE_IF_VALID
} GtkSpinButtonUpdatePolicy; | 
| GTK_UPDATE_ALWAYS | When refreshing your GtkSpinButton, the value is always displayed. | 
| GTK_UPDATE_IF_VALID | When refreshing your GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's GtkAdjustment. | 
| 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_STEP_FORWARD, GTK_SPIN_STEP_BACKWARD, GTK_SPIN_PAGE_FORWARD, GTK_SPIN_PAGE_BACKWARD | These values spin a GtkSpinButton by the relevant values of the spin button's GtkAdjustment. | 
| GTK_SPIN_HOME, GTK_SPIN_END | These set the spin button's value to the minimum or maxmimum possible values, (set by it's GtkAdjustment), respectively. | 
| GTK_SPIN_USER_DEFINED | The programmer must specify the exact amount to spin the GtkSpinButton. | 
| void gtk_spin_button_configure (GtkSpinButton *spin_button, GtkAdjustment *adjustment, gdouble climb_rate, guint digits); | 
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.
| spin_button : | a GtkSpinButton. | 
| adjustment : | a GtkAdjustment. | 
| climb_rate : | the new climb rate. | 
| digits : | the number of decimal places to display in the spin button. | 
| GtkWidget* gtk_spin_button_new (GtkAdjustment *adjustment, gdouble climb_rate, guint digits); | 
Creates a new GtkSpinButton.
| adjustment : | the GtkAdjustment 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. | 
| Returns : | The new spin button as a GtkWidget. | 
| GtkWidget* gtk_spin_button_new_with_range (gdouble min, gdouble max, gdouble step); | 
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.
| min : | Minimum allowable value | 
| max : | Maximum allowable value | 
| step : | Increment added or subtracted by spinning the widget | 
| Returns : | The new spin button as a GtkWidget. | 
| void gtk_spin_button_set_adjustment (GtkSpinButton *spin_button, GtkAdjustment *adjustment); | 
Replaces the GtkAdjustment associated with spin_button.
| spin_button : | a GtkSpinButton | 
| adjustment : | a GtkAdjustment to replace the existing adjustment | 
| GtkAdjustment* gtk_spin_button_get_adjustment (GtkSpinButton *spin_button); | 
Get the adjustment associated with a GtkSpinButton
| spin_button : | |
| Returns : | the GtkAdjustment of spin_button | 
| void gtk_spin_button_set_digits (GtkSpinButton *spin_button, guint digits); | 
Set the precision to be displayed by spin_button. Up to 20 digit precision is allowed.
| spin_button : | a GtkSpinButton | 
| digits : | the number of digits to be displayed for the spin button's value | 
| void gtk_spin_button_set_increments (GtkSpinButton *spin_button, gdouble step, gdouble page); | 
Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button's arrows are activated.
| spin_button : | a GtkSpinButton | 
| step : | increment applied for a button 1 press. | 
| page : | increment applied for a button 2 press. | 
| void gtk_spin_button_set_range (GtkSpinButton *spin_button, gdouble min, gdouble max); | 
Sets the minimum and maximum allowable values for spin_button
| spin_button : | a GtkSpinButton | 
| min : | minimum allowable value | 
| max : | maximum allowable value | 
| #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. | 
Gets the value in the spin_button. This function is deprecated, use gtk_spin_button_get_value() instead.
| gint gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button); | 
Get the value spin_button represented as an integer.
| spin_button : | a GtkSpinButton | 
| Returns : | the value of spin_button | 
| void gtk_spin_button_set_value (GtkSpinButton *spin_button, gdouble value); | 
Set the value of spin_button.
| spin_button : | a GtkSpinButton | 
| value : | the new value | 
| void        gtk_spin_button_set_update_policy
                                            (GtkSpinButton *spin_button,
                                             GtkSpinButtonUpdatePolicy 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.
| spin_button : | a GtkSpinButton | 
| policy : | a GtkSpinButtonUpdatePolicy value | 
| void gtk_spin_button_set_numeric (GtkSpinButton *spin_button, gboolean numeric); | 
Sets the flag that determines if non-numeric text can be typed into the spin button.
| spin_button : | a GtkSpinButton | 
| numeric : | flag indicating if only numeric entry is allowed. | 
| void gtk_spin_button_spin (GtkSpinButton *spin_button, GtkSpinType direction, gdouble increment); | 
Increment or decrement a spin button's value in a specified direction by a specified amount.
| spin_button : | a GtkSpinButton | 
| direction : | a GtkSpinType indicating the direction to spin. | 
| increment : | step increment to apply in the specified direction. | 
| void gtk_spin_button_set_wrap (GtkSpinButton *spin_button, gboolean 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.
| spin_button : | a GtkSpinButton | 
| wrap : | a flag indicating if wrapping behavior is performed. | 
| void        gtk_spin_button_set_snap_to_ticks
                                            (GtkSpinButton *spin_button,
                                             gboolean 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.
| spin_button : | a GtkSpinButton | 
| snap_to_ticks : | a flag indicating if invalid values should be corrected. | 
| void gtk_spin_button_update (GtkSpinButton *spin_button); | 
Manually force an update of the spin button.
| spin_button : | a GtkSpinButton | 
| guint gtk_spin_button_get_digits (GtkSpinButton *spin_button); | 
Fetches the precision of spin_button. See gtk_spin_button_set_digits().
| spin_button : | a GtkSpinButton | 
| Returns : | the current precision | 
| void gtk_spin_button_get_increments (GtkSpinButton *spin_button, gdouble *step, gdouble *page); | 
Gets the current step and page the increments used by spin_button. See gtk_spin_button_set_increments().
| spin_button : | a GtkSpinButton | 
| step : | location to store step increment, or NULL | 
| page : | location to store page increment, or NULL | 
| gboolean gtk_spin_button_get_numeric (GtkSpinButton *spin_button); | 
Returns whether non-numeric text can be typed into the spin button. See gtk_spin_button_set_numeric().
| spin_button : | a GtkSpinButton | 
| Returns : | TRUE if only numeric text can be entered | 
| void gtk_spin_button_get_range (GtkSpinButton *spin_button, gdouble *min, gdouble *max); | 
Gets the range allowed for spin_button. See gtk_spin_button_set_range().
| spin_button : | a GtkSpinButton | 
| min : | location to store minimum allowed value, or NULL | 
| max : | location to store maximum allowed value, or NULL | 
| gboolean gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button); | 
Returns whether the values are corrected to the nearest step. See gtk_spin_button_set_snap_to_ticks().
| spin_button : | a GtkSpinButton | 
| Returns : | TRUE if values are snapped to the nearest step. | 
| GtkSpinButtonUpdatePolicy gtk_spin_button_get_update_policy (GtkSpinButton *spin_button); | 
Gets the update behavior of a spin button. See gtk_spin_button_set_update_policy().
| spin_button : | a GtkSpinButton | 
| Returns : | the current update policy | 
| gdouble gtk_spin_button_get_value (GtkSpinButton *spin_button); | 
Get the value in the spin_button.
| spin_button : | a GtkSpinButton | 
| Returns : | the value of spin_button | 
| gboolean gtk_spin_button_get_wrap (GtkSpinButton *spin_button); | 
Returns whether the spin button's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. See gtk_spin_button_set_wrap().
| spin_button : | a GtkSpinButton | 
| Returns : | TRUE if the spin button wraps around | 
the GtkAdjustment that defines a spin button's main properties.
the amount a spin button changes when an arrow is clicked.
the number of decimal places to display.
whether erroneous values are automatically changed to a spin button's nearest step increment.
whether non-numeric characters should be ignored.
whether a spin button should wrap upon reaching its limits.
how a spin button should be updated.
reads the current value, or sets a new value.
| void user_function (GtkSpinButton *spinbutton, GtkScrollType arg1, gpointer user_data); | 
| gint user_function (GtkSpinButton *spinbutton, gpointer arg1, gpointer user_data); |