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 |
"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_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; } |
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 : | 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 5 digit precision is allowed.
spin_button : | a GtkSpinButton |
digits : | the number of digits to be displayed for the spin button's value |
gdouble gtk_spin_button_get_value_as_float (GtkSpinButton *spin_button); |
Get the value spin_button represented as a floating point number.
spin_button : | a GtkSpinButton |
Returns : | the value of spin_button |
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 |
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.
gint user_function (GtkSpinButton *spinbutton, gpointer arg1, gpointer user_data); |