![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gtk/gtk.h> GtkSpinButton; enum GtkSpinButtonUpdatePolicy; enum GtkSpinType; void gtk_spin_button_configure (GtkSpinButton *spin_button
,GtkAdjustment *adjustment
,gdouble climb_rate
,guint digits
); GtkWidget* gtk_spin_button_new (GtkAdjustment *adjustment
,gdouble climb_rate
,guint digits
); GtkWidget* gtk_spin_button_new_with_range (gdouble min
,gdouble max
,gdouble step
); void gtk_spin_button_set_adjustment (GtkSpinButton *spin_button
,GtkAdjustment *adjustment
); GtkAdjustment* gtk_spin_button_get_adjustment (GtkSpinButton *spin_button
); void gtk_spin_button_set_digits (GtkSpinButton *spin_button
,guint digits
); void gtk_spin_button_set_increments (GtkSpinButton *spin_button
,gdouble step
,gdouble page
); void gtk_spin_button_set_range (GtkSpinButton *spin_button
,gdouble min
,gdouble max
); gint gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button
); void gtk_spin_button_set_value (GtkSpinButton *spin_button
,gdouble value
); void gtk_spin_button_set_update_policy (GtkSpinButton *spin_button
,GtkSpinButtonUpdatePolicy policy
); void gtk_spin_button_set_numeric (GtkSpinButton *spin_button
,gboolean numeric
); void gtk_spin_button_spin (GtkSpinButton *spin_button
,GtkSpinType direction
,gdouble increment
); void gtk_spin_button_set_wrap (GtkSpinButton *spin_button
,gboolean wrap
); void gtk_spin_button_set_snap_to_ticks (GtkSpinButton *spin_button
,gboolean snap_to_ticks
); void gtk_spin_button_update (GtkSpinButton *spin_button
); guint gtk_spin_button_get_digits (GtkSpinButton *spin_button
); void gtk_spin_button_get_increments (GtkSpinButton *spin_button
,gdouble *step
,gdouble *page
); gboolean gtk_spin_button_get_numeric (GtkSpinButton *spin_button
); void gtk_spin_button_get_range (GtkSpinButton *spin_button
,gdouble *min
,gdouble *max
); gboolean gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button
); GtkSpinButtonUpdatePolicy gtk_spin_button_get_update_policy (GtkSpinButton *spin_button
); gdouble gtk_spin_button_get_value (GtkSpinButton *spin_button
); gboolean gtk_spin_button_get_wrap (GtkSpinButton *spin_button
); #define GTK_INPUT_ERROR
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 an adjustment. See the GtkAdjustment section for more details about an adjustment's properties.
Example 52. Using a GtkSpinButton to get an integer
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
/* 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 *button, gpointer user_data) { return gtk_spin_button_get_value_as_int (button); } void create_integer_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_container_set_border_width (GTK_CONTAINER (window), 5); /* creates the spinbutton, with no decimal places */ button = gtk_spin_button_new (adjustment, 1.0, 0); gtk_container_add (GTK_CONTAINER (window), button); gtk_widget_show_all (window); } |
Example 53. Using a GtkSpinButton to get a floating point value
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
/* Provides a function to retrieve a floating point value from a * GtkSpinButton, and creates a high precision spin button. */ gfloat grab_float_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value (button); } void create_floating_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_container_set_border_width (GTK_CONTAINER (window), 5); /* creates the spinbutton, with three decimal places */ button = gtk_spin_button_new (adjustment, 0.001, 3); gtk_container_add (GTK_CONTAINER (window), button); gtk_widget_show_all (window); } |
typedef struct { GtkEntry entry; } GtkSpinButton;
The GtkSpinButton struct contains only private data and should not be directly modified.
typedef enum { GTK_UPDATE_ALWAYS, GTK_UPDATE_IF_VALID } GtkSpinButtonUpdatePolicy;
The spin button update policy determines whether the spin button displays
values even if they are outside the bounds of its adjustment.
See gtk_spin_button_set_update_policy()
.
When refreshing your GtkSpinButton, the value is always displayed | |
When refreshing your GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's adjustment |
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;
The values of the GtkSpinType enumeration are used to specify the
change to make in gtk_spin_button_spin()
.
Increment by the adjustments step increment. | |
Decrement by the adjustments step increment. | |
Increment by the adjustments page increment. | |
Decrement by the adjustments page increment. | |
Go to the adjustments lower bound. | |
Go to the adjustments upper bound. | |
Change by a specified amount. |
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.
|
a GtkSpinButton |
|
a GtkAdjustment. [allow-none] |
|
the new climb rate |
|
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.
|
the GtkAdjustment object that this spin
button should use, or NULL . [allow-none]
|
|
specifies how much the spin button changes when an arrow is clicked on |
|
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
.
Note that the way in which the precision is derived works best if step
is a power of ten. If the resulting precision is not suitable for your
needs, use gtk_spin_button_set_digits()
to correct it.
|
Minimum allowable value |
|
Maximum allowable value |
|
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
.
|
a GtkSpinButton |
|
a GtkAdjustment to replace the existing adjustment |
GtkAdjustment* gtk_spin_button_get_adjustment (GtkSpinButton *spin_button
);
Get the adjustment associated with a GtkSpinButton
|
a GtkSpinButton |
Returns : |
the GtkAdjustment of spin_button . [transfer none]
|
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.
|
a GtkSpinButton |
|
the number of digits after the decimal point 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.
|
a GtkSpinButton |
|
increment applied for a button 1 press. |
|
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
.
|
a GtkSpinButton |
|
minimum allowable value |
|
maximum allowable value |
gint gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button
);
Get the value spin_button
represented as an integer.
|
a GtkSpinButton |
Returns : |
the value of spin_button
|
void gtk_spin_button_set_value (GtkSpinButton *spin_button
,gdouble value
);
Sets the value of spin_button
.
|
a GtkSpinButton |
|
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 wether the spin button is always updated or only when a valid value is set.
|
a GtkSpinButton |
|
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.
|
a GtkSpinButton |
|
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.
|
a GtkSpinButton |
|
a GtkSpinType indicating the direction to spin |
|
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.
|
a GtkSpinButton |
|
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.
|
a GtkSpinButton |
|
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.
|
a GtkSpinButton |
guint gtk_spin_button_get_digits (GtkSpinButton *spin_button
);
Fetches the precision of spin_button
. See gtk_spin_button_set_digits()
.
|
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()
.
|
a GtkSpinButton |
|
location to store step increment, or NULL . [out][allow-none]
|
|
location to store page increment, or NULL . [out][allow-none]
|
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()
.
|
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()
.
|
a GtkSpinButton |
|
location to store minimum allowed value, or NULL . [out][allow-none]
|
|
location to store maximum allowed value, or NULL . [out][allow-none]
|
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()
.
|
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()
.
|
a GtkSpinButton |
Returns : |
the current update policy |
gdouble gtk_spin_button_get_value (GtkSpinButton *spin_button
);
Get the value in the 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()
.
|
a GtkSpinButton |
Returns : |
TRUE if the spin button wraps around
|