GtkSpinButton
<!-- ##### SECTION Short_Description ##### -->
-retrieve an integer or floating-point number from the user.
+Retrieve an integer or floating-point number from the user
<!-- ##### SECTION Long_Description ##### -->
<para>
-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.
+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.
</para>
<para>
-The main properties of a #GtkSpinButton are through a #GtkAdjustment. See the #GtkAdjustment section for more details about an adjustment's properties.
-</para>
-<para>
-#GtkSpinButton widgets are created with a call to gtk_spin_button_new().
-</para>
-<para>
-The #GtkAdjustment of a spin button can be set or retrieved with a call to gtk_spin_button_set_adjustment() or gtk_spin_button_get_adjustment(), respectively.
-</para>
-<para>
-The number of digits after the decimal point of a spin button can be altered with gtk_spin_button_set_digits().
-</para>
-<para>
-To retrieve values from a spin button, use gtk_spin_button_get_value_as_float() if you require a floating point number, or gtk_spin_button_get_value_as_int() if you require an integer.
-</para>
-<para>
-To set the value of a #GtkSpinButton, use gtk_spin_button_set_value(). To change the update behaviour of a spin button, use gtk_spin_button_set_update_policy().
-</para>
-<para>
-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 gtk_spin_button_set_wrap().
-</para>
-<para>
-A border around a spin button's arrows can be created using gtk_spin_button_set_shadow_type().
-</para>
-<para>
-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 gtk_spin_button_snap_to_ticks(), which will alter the current value to the nearest step increment. (See #GtkAdjustment for step increments).
-</para>
-<para>
-Because a spin contains a #GtkEntry, alphabetic characters may be entered. These can be ignored by using gtk_spin_button_set_numeric() with a value of TRUE. Then only numeric values, '-' and a decimal point will be accepted.
-</para>
-<para>
-To manually increment or decrement the spin button, use gtk_spin_button_spin(), and to force an update (refresh), use gtk_spin_button_update().
+The main properties of a #GtkSpinButton are through a #GtkAdjustment. See the
+#GtkAdjustment section for more details about an adjustment's properties.
</para>
<para>
<example>
-<title>Using a GtkSpinButton to get an integer.</title>
+<title>Using a <structname>GtkSpinButton</structname> to get an integer.</title>
<programlisting>
/* Provides a function to retrieve an integer value from a GtkSpinButton
return gtk_spin_button_get_value_as_int (a_spinner);
}
-void create_integer_spin_button(void) {
+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);
+ 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);
+ 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_container_add (GTK_CONTAINER (window), spinner);
gtk_widget_show_all (window);
return;
<para>
<example>
-<title>Using a GtkSpinButton to get a floating point value.</title>
+<title>Using a <structname>GtkSpinButton</structname> to get a floating point value.</title>
<programlisting>
/* Provides a function to retrieve a floating point value from a
*/
gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
- return gtk_spin_button_get_value_as_float (a_spinner);
+ return gtk_spin_button_get_value (a_spinner);
}
-void create_floating_spin_button(void) {
+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);
+ 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);
+ 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_container_add (GTK_CONTAINER (window), spinner);
gtk_widget_show_all (window);
return;
</variablelist>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT GtkSpinButton ##### -->
<para>
-<structfield>entry</structfield> 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.
+<structfield>entry</structfield> 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.
</para>
-@entry:
-@adjustment:
-@panel:
-@shadow_type:
-@timer:
-@ev_time:
-@climb_rate:
-@timer_step:
-@update_policy:
-@in_child:
-@click_child:
-@button:
-@need_timer:
-@timer_calls:
-@digits:
-@numeric:
-@wrap:
-@snap_to_ticks:
+
+<!-- ##### SIGNAL GtkSpinButton::change-value ##### -->
+<para>
+
+</para>
+
+@spinbutton: the object which received the signal.
+@arg1:
+
+<!-- ##### SIGNAL GtkSpinButton::input ##### -->
+<para>
+
+</para>
+
+@spinbutton: the object which received the signal.
+@arg1:
+@Returns:
+
+<!-- ##### SIGNAL GtkSpinButton::output ##### -->
+<para>
+
+</para>
+
+@spinbutton: the object which received the signal.
+@Returns:
+
+<!-- ##### SIGNAL GtkSpinButton::value-changed ##### -->
+<para>
+
+</para>
+
+@spinbutton: the object which received the signal.
+
+<!-- ##### SIGNAL GtkSpinButton::wrapped ##### -->
+<para>
+
+</para>
+
+@spinbutton: the object which received the signal.
+
+<!-- ##### ARG GtkSpinButton:adjustment ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:climb-rate ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:digits ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:numeric ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:snap-to-ticks ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:update-policy ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:value ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:wrap ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkSpinButton:shadow-type ##### -->
+<para>
+the type of border that surrounds the arrows of a spin button.
+</para>
<!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
<para>
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<informaltable pgwide="1" frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry>GTK_UPDATE_ALWAYS</entry>
<!-- ##### ENUM GtkSpinType ##### -->
<para>
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<informaltable pgwide="1" frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry>GTK_SPIN_STEP_FORWARD,
<row>
<entry>GTK_SPIN_HOME,
GTK_SPIN_END</entry>
-<entry>These set the spin button's value to the minimum or maxmimum possible values, (set by it's #GtkAdjustment), respectively.</entry>
+<entry>These set the spin button's value to the minimum or maxmimum possible values, (set by its #GtkAdjustment), respectively.</entry>
</row>
<row>
<entry>GTK_SPIN_USER_DEFINED</entry>
@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.
+@Returns: The new spin button as a #GtkWidget.
+
+
+<!-- ##### FUNCTION gtk_spin_button_new_with_range ##### -->
+<para>
+
+</para>
+
+@min:
+@max:
+@step:
+@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_adjustment ##### -->
<para>
-Changes which #GtkAdjustment is associated with a spin button.
+
</para>
-@spin_button: a #GtkSpinButton.
-@adjustment: a #GtkAdjustment.
+@spin_button:
+@adjustment:
<!-- ##### FUNCTION gtk_spin_button_get_adjustment ##### -->
<para>
-Retrieves the #GtkAdjustment used by a given spin button.
+
</para>
-@spin_button: a #GtkSpinButton.
-@Returns: a #GtkAdjustment.
+@spin_button:
+@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_digits ##### -->
<para>
-Alters the number of decimal places that are displayed in a spin button.
+
</para>
-@spin_button: a #GtkSpinButton.
-@digits: the number of decimal places.
+@spin_button:
+@digits:
+
+
+<!-- ##### FUNCTION gtk_spin_button_set_increments ##### -->
+<para>
+
+</para>
+
+@spin_button:
+@step:
+@page:
+
+
+<!-- ##### FUNCTION gtk_spin_button_set_range ##### -->
+<para>
+
+</para>
+
+@spin_button:
+@min:
+@max:
-<!-- ##### FUNCTION gtk_spin_button_get_value_as_float ##### -->
+<!-- ##### MACRO gtk_spin_button_get_value_as_float ##### -->
<para>
-Retrieves the current value of a #GtkSpinButton. If the number has no decimal places, it is converted to a float before the function returns.
+Gets the value in the @spin_button. This function is deprecated,
+use gtk_spin_button_get_value() instead.
</para>
+@Returns: the value of @spin_button.
+<!-- # Unused Parameters # -->
@spin_button: a #GtkSpinButton.
-@Returns: the value of @spin_button as a #gfloat.
<!-- ##### FUNCTION gtk_spin_button_get_value_as_int ##### -->
<para>
-Retrieves the current integer value of a #GtkSpinButton.
+
</para>
-@spin_button: a #GtkSpinButton.
-@Returns: the value of @spin_button as a #gint.
+@spin_button:
+@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_value ##### -->
<para>
-Sets the value of a spin button.
+
</para>
-@spin_button: a #GtkSpinButton.
-@value: the new floating point value.
+@spin_button:
+@value:
<!-- ##### FUNCTION gtk_spin_button_set_update_policy ##### -->
<para>
-Changes the way a spin button refreshes and updates itself. See %GtkSpinButtonUpdatePolicy for more information.
+
</para>
-@spin_button: a #GtkSpinButton.
-@policy: the new update policy.
+@spin_button:
+@policy:
<!-- ##### FUNCTION gtk_spin_button_set_numeric ##### -->
<para>
-Sets how the spin button's #GtkEntry reacts to alphabetic characters. A value of TRUE to @numeric means that all non-numeric characters (except '-' and a decimal point) are ignored.
+
</para>
-@spin_button: a #GtkSpinButton.
-@numeric: whether letters should be ignored.
+@spin_button:
+@numeric:
<!-- ##### FUNCTION gtk_spin_button_spin ##### -->
<para>
-Performs an explicit 'spin' on a spin button.
+
</para>
-@spin_button: a #GtkSpinButton.
-@direction: the type of spin to perform.
-@increment: the amount to spin.
+@spin_button:
+@direction:
+@increment:
<!-- ##### FUNCTION gtk_spin_button_set_wrap ##### -->
<para>
-Sets a spin button's value to the lower limit when it's upper limit is reached, and vice versa.
-</para>
-
-@spin_button: a #GtkSpinButton.
-@wrap: defaults to FALSE, set to TRUE to make the spin button wrap.
-
-<!-- ##### FUNCTION gtk_spin_button_set_shadow_type ##### -->
-<para>
-Creates a border around the arrows of a #GtkSpinButton. The type of border is determined by @shadow_type.
</para>
-@spin_button: a #GtkSpinButton
-@shadow_type: the new border type.
+@spin_button:
+@wrap:
<!-- ##### FUNCTION gtk_spin_button_set_snap_to_ticks ##### -->
<para>
-Sets whether a number typed into a spin button should be snapped to the nearest step increment.
+
</para>
-@spin_button: a #GtkButton.
-@snap_to_ticks: TRUE or FALSE.
+@spin_button:
+@snap_to_ticks:
<!-- ##### FUNCTION gtk_spin_button_update ##### -->
<para>
-Refreshes a spin button. The behaviour of the update is determined by gtk_spin_button_set_update_policy().
+
</para>
-@spin_button: a #GtkSpinButton.
+@spin_button:
-<!-- ##### ARG GtkSpinButton:adjustment ##### -->
+<!-- ##### FUNCTION gtk_spin_button_get_digits ##### -->
<para>
-the #GtkAdjustment that defines a spin button's main properties.
+
</para>
-<!-- ##### ARG GtkSpinButton:climb_rate ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_increments ##### -->
<para>
-the amount a spin button changes when an arrow is clicked.
+
</para>
-<!-- ##### ARG GtkSpinButton:digits ##### -->
+@spin_button:
+@step:
+@page:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_numeric ##### -->
<para>
-the number of decimal places to display.
+
</para>
-<!-- ##### ARG GtkSpinButton:snap_to_ticks ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_range ##### -->
<para>
-whether erroneous values are automatically changed to a spin button's nearest step increment.
+
</para>
-<!-- ##### ARG GtkSpinButton:numeric ##### -->
+@spin_button:
+@min:
+@max:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_snap_to_ticks ##### -->
<para>
-whether non-numeric characters should be ignored.
+
</para>
-<!-- ##### ARG GtkSpinButton:wrap ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_update_policy ##### -->
<para>
-whether a spin button should wrap upon reaching its limits.
+
</para>
-<!-- ##### ARG GtkSpinButton:update_policy ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_value ##### -->
<para>
-how a spin button should be updated.
+
</para>
-<!-- ##### ARG GtkSpinButton:shadow_type ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_spin_button_get_wrap ##### -->
<para>
-the type of border that surrounds the arrows of a spin button.
+
</para>
-<!-- ##### ARG GtkSpinButton:value ##### -->
+@spin_button:
+@Returns:
+
+
+<!-- ##### MACRO GTK_INPUT_ERROR ##### -->
<para>
-reads the current value, or sets a new value.
+
</para>
+
+
projects / ~andy / gtk / blobdiff