callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move GtkSpinButton docs inline

Browse Source 
...and modernize the examples at the same time.

This fixes a problem pointed out in bug 638193.
This commit is contained in:
Matthias Clasen
2011-01-02 23:30:02 -05:00
parent 1a87dfdf6d
commit 85fe6cb2c4
3 changed files with 669 additions and 993 deletions
Download Patch File Download Diff File Expand all files Collapse all files

482
docs/reference/gtk/tmpl/gtkspinbutton.sgml
View File

@ -1,482 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkSpinButton
<!-- ##### SECTION Short_Description ##### -->
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.
</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>
<example>
<title>Using a <structname>GtkSpinButton</structname> to get an integer.</title>
<programlisting>
/* 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 = 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;
}
</programlisting>
</example>
</para>
<para>
<example>
<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
* 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 = 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;
}
</programlisting>
</example>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkEntry</term>
<listitem><para>retrieve text rather than numbers.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### 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.
</para>
<!-- ##### 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*"/>
<tbody>
<row>
<entry>GTK_UPDATE_ALWAYS</entry>
<entry>When refreshing your #GtkSpinButton, the value is always displayed.</entry>
</row>
<row>
<entry>GTK_UPDATE_IF_VALID</entry>
<entry>When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's #GtkAdjustment.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GTK_UPDATE_ALWAYS:
@GTK_UPDATE_IF_VALID:
<!-- ##### ENUM GtkSpinType ##### -->
<para>
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry>GTK_SPIN_STEP_FORWARD,
GTK_SPIN_STEP_BACKWARD,
GTK_SPIN_PAGE_FORWARD,
GTK_SPIN_PAGE_BACKWARD</entry>
<entry>These values spin a #GtkSpinButton by the relevant values of the spin button's #GtkAdjustment.</entry>
</row>
<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 its #GtkAdjustment), respectively.</entry>
</row>
<row>
<entry>GTK_SPIN_USER_DEFINED</entry>
<entry>The programmer must specify the exact amount to spin the #GtkSpinButton.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@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:
<!-- ##### FUNCTION gtk_spin_button_configure ##### -->
<para>
</para>
@spin_button:
@adjustment:
@climb_rate:
@digits:
<!-- ##### FUNCTION gtk_spin_button_new ##### -->
<para>
Creates a new #GtkSpinButton.
</para>
@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.
<!-- ##### FUNCTION gtk_spin_button_new_with_range ##### -->
<para>
</para>
@min:
@max:
@step:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_adjustment ##### -->
<para>
</para>
@spin_button:
@adjustment:
<!-- ##### FUNCTION gtk_spin_button_get_adjustment ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_digits ##### -->
<para>
</para>
@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_int ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_set_value ##### -->
<para>
</para>
@spin_button:
@value:
<!-- ##### FUNCTION gtk_spin_button_set_update_policy ##### -->
<para>
</para>
@spin_button:
@policy:
<!-- ##### FUNCTION gtk_spin_button_set_numeric ##### -->
<para>
</para>
@spin_button:
@numeric:
<!-- ##### FUNCTION gtk_spin_button_spin ##### -->
<para>
</para>
@spin_button:
@direction:
@increment:
<!-- ##### FUNCTION gtk_spin_button_set_wrap ##### -->
<para>
</para>
@spin_button:
@wrap:
<!-- ##### FUNCTION gtk_spin_button_set_snap_to_ticks ##### -->
<para>
</para>
@spin_button:
@snap_to_ticks:
<!-- ##### FUNCTION gtk_spin_button_update ##### -->
<para>
</para>
@spin_button:
<!-- ##### FUNCTION gtk_spin_button_get_digits ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_get_increments ##### -->
<para>
</para>
@spin_button:
@step:
@page:
<!-- ##### FUNCTION gtk_spin_button_get_numeric ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_get_range ##### -->
<para>
</para>
@spin_button:
@min:
@max:
<!-- ##### FUNCTION gtk_spin_button_get_snap_to_ticks ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_get_update_policy ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_get_value ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### FUNCTION gtk_spin_button_get_wrap ##### -->
<para>
</para>
@spin_button:
@Returns:
<!-- ##### MACRO GTK_INPUT_ERROR ##### -->
<para>
</para>

224
gtk/gtkspinbutton.c
View File

@ -50,6 +50,95 @@
#define MIN_ARROW_WIDTH 6 #define MIN_ARROW_WIDTH 6
/**
* SECTION:gtkspinbutton
* @Title: GtkSpinButton
* @Short_description: Retrieve an integer or floating-point number from
* the user
* @See_also: #GtkEntry
*
* 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>
* <title>Using a GtkSpinButton to get an integer</title>
* <programlisting>
* /&ast; Provides a function to retrieve an integer value from a
* &ast; GtkSpinButton and creates a spin button to model percentage
* &ast; values.
* &ast;/
*
* 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 *adj;
*
* adj = 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);
*
* /&ast; creates the spinbutton, with no decimal places &ast;/
* button = gtk_spin_button_new (adj, 1.0, 0);
* gtk_container_add (GTK_CONTAINER (window), button);
*
* gtk_widget_show_all (window);
* }
* </programlisting>
* </example>
*
* <example>
* <title>Using a GtkSpinButton to get a floating point value</title>
* <programlisting>
* /&ast; Provides a function to retrieve a floating point value from a
* &ast; GtkSpinButton, and creates a high precision spin button.
* &ast;/
*
* 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 *adj;
*
* adj = 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);
*
* /&ast; creates the spinbutton, with three decimal places &ast;/
* button = gtk_spin_button_new (adj, 0.001, 3);
* gtk_container_add (GTK_CONTAINER (window), button);
*
* gtk_widget_show_all (window);
* }
* </programlisting>
* </example>
*/
struct _GtkSpinButtonPrivate struct _GtkSpinButtonPrivate
{ {
GtkSpinButtonUpdatePolicy update_policy; GtkSpinButtonUpdatePolicy update_policy;
@ -302,6 +391,22 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class)
GTK_SHADOW_IN, GTK_SHADOW_IN,
GTK_PARAM_READABLE), GTK_PARAM_READABLE),
gtk_rc_property_parse_enum); gtk_rc_property_parse_enum);
/**
* GtkSpinButton::input:
* @spin_button: the object on which the signal was emitted
* @new_value: return location for the new value
*
* The ::input signal can be used to influence the conversion of
* the users input into a double value. The signal handler is
* expected to use gtk_entry_get_text() to retrieve the text of
* the entry and set @new_value to the new value.
*
* The default conversion uses g_strtod().
*
* Returns: %TRUE for a successful conversion, %FALSE if the input
* was not handled, and %GTK_INPUT_ERROR if the conversion failed.
*/
spinbutton_signals[INPUT] = spinbutton_signals[INPUT] =
g_signal_new (I_("input"), g_signal_new (I_("input"),
G_TYPE_FROM_CLASS (gobject_class), G_TYPE_FROM_CLASS (gobject_class),
@ -338,7 +443,7 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class)
* } * }
* ]| * ]|
* *
* Returns: %TRUE if the value has been displayed. * Returns: %TRUE if the value has been displayed
*/ */
spinbutton_signals[OUTPUT] = spinbutton_signals[OUTPUT] =
g_signal_new (I_("output"), g_signal_new (I_("output"),
@ -1756,12 +1861,13 @@ gtk_spin_button_default_output (GtkSpinButton *spin_button)
/** /**
* gtk_spin_button_configure: * gtk_spin_button_configure:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @adjustment: (allow-none): a #GtkAdjustment. * @adjustment: (allow-none): a #GtkAdjustment
* @climb_rate: the new climb rate. * @climb_rate: the new climb rate
* @digits: the number of decimal places to display in the spin button. * @digits: the number of decimal places to display in the spin button
* *
* Changes the properties of an existing spin button. The adjustment, climb rate, * Changes the properties of an existing spin button. The adjustment,
* and number of decimal places are all changed accordingly, after this function call. * climb rate, and number of decimal places are all changed accordingly,
* after this function call.
*/ */
void void
gtk_spin_button_configure (GtkSpinButton *spin_button, gtk_spin_button_configure (GtkSpinButton *spin_button,
@ -1797,6 +1903,18 @@ gtk_spin_button_configure (GtkSpinButton *spin_button,
gtk_adjustment_value_changed (adjustment); gtk_adjustment_value_changed (adjustment);
} }
/**
* gtk_spin_button_new:
* @adjustment: (allow-none): the #GtkAdjustment object that this spin
* button should use, or %NULL
* @climb_rate: specifies how much the spin button changes when an arrow
* is clicked on
* @digits: the number of decimal places to display
*
* Creates a new #GtkSpinButton.
*
* Returns: The new spin button as a #GtkWidget
*/
GtkWidget * GtkWidget *
gtk_spin_button_new (GtkAdjustment *adjustment, gtk_spin_button_new (GtkAdjustment *adjustment,
gdouble climb_rate, gdouble climb_rate,
@ -1830,8 +1948,8 @@ gtk_spin_button_new (GtkAdjustment *adjustment,
* is a power of ten. If the resulting precision is not suitable for your * is a power of ten. If the resulting precision is not suitable for your
* needs, use gtk_spin_button_set_digits() to correct it. * needs, use gtk_spin_button_set_digits() to correct it.
* *
* Return value: The new spin button as a #GtkWidget. * Return value: The new spin button as a #GtkWidget
**/ */
GtkWidget * GtkWidget *
gtk_spin_button_new_with_range (gdouble min, gtk_spin_button_new_with_range (gdouble min,
gdouble max, gdouble max,
@ -1863,8 +1981,9 @@ gtk_spin_button_new_with_range (gdouble min,
return GTK_WIDGET (spin); return GTK_WIDGET (spin);
} }
/* Callback used when the spin button's adjustment changes. We need to redraw /* Callback used when the spin button's adjustment changes.
* the arrows when the adjustment's range changes, and reevaluate our size request. * We need to redraw the arrows when the adjustment's range
* changes, and reevaluate our size request.
*/ */
static void static void
adjustment_changed_cb (GtkAdjustment *adjustment, gpointer data) adjustment_changed_cb (GtkAdjustment *adjustment, gpointer data)
@ -1882,7 +2001,7 @@ adjustment_changed_cb (GtkAdjustment *adjustment, gpointer data)
* @adjustment: a #GtkAdjustment to replace the existing adjustment * @adjustment: a #GtkAdjustment to replace the existing adjustment
* *
* Replaces the #GtkAdjustment associated with @spin_button. * Replaces the #GtkAdjustment associated with @spin_button.
**/ */
void void
gtk_spin_button_set_adjustment (GtkSpinButton *spin_button, gtk_spin_button_set_adjustment (GtkSpinButton *spin_button,
GtkAdjustment *adjustment) GtkAdjustment *adjustment)
@ -2041,8 +2160,8 @@ gtk_spin_button_get_increments (GtkSpinButton *spin_button,
* @min: minimum allowable value * @min: minimum allowable value
* @max: maximum allowable value * @max: maximum allowable value
* *
* Sets the minimum and maximum allowable values for @spin_button * Sets the minimum and maximum allowable values for @spin_button.
**/ */
void void
gtk_spin_button_set_range (GtkSpinButton *spin_button, gtk_spin_button_set_range (GtkSpinButton *spin_button,
gdouble min, gdouble min,
@ -2074,9 +2193,9 @@ gtk_spin_button_set_range (GtkSpinButton *spin_button,
* @min: (allow-none): location to store minimum allowed value, or %NULL * @min: (allow-none): location to store minimum allowed value, or %NULL
* @max: (allow-none): location to store maximum allowed value, or %NULL * @max: (allow-none): location to store maximum allowed value, or %NULL
* *
* Gets the range allowed for @spin_button. See * Gets the range allowed for @spin_button.
* gtk_spin_button_set_range(). * See gtk_spin_button_set_range().
**/ */
void void
gtk_spin_button_get_range (GtkSpinButton *spin_button, gtk_spin_button_get_range (GtkSpinButton *spin_button,
gdouble *min, gdouble *min,
@ -2101,7 +2220,7 @@ gtk_spin_button_get_range (GtkSpinButton *spin_button,
* Get the value in the @spin_button. * Get the value in the @spin_button.
* *
* Return value: the value of @spin_button * Return value: the value of @spin_button
**/ */
gdouble gdouble
gtk_spin_button_get_value (GtkSpinButton *spin_button) gtk_spin_button_get_value (GtkSpinButton *spin_button)
{ {
@ -2117,7 +2236,7 @@ gtk_spin_button_get_value (GtkSpinButton *spin_button)
* Get the value @spin_button represented as an integer. * Get the value @spin_button represented as an integer.
* *
* Return value: the value of @spin_button * Return value: the value of @spin_button
**/ */
gint gint
gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button) gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button)
{ {
@ -2140,8 +2259,8 @@ gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button)
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @value: the new value * @value: the new value
* *
* Set the value of @spin_button. * Sets the value of @spin_button.
**/ */
void void
gtk_spin_button_set_value (GtkSpinButton *spin_button, gtk_spin_button_set_value (GtkSpinButton *spin_button,
gdouble value) gdouble value)
@ -2168,9 +2287,10 @@ gtk_spin_button_set_value (GtkSpinButton *spin_button,
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @policy: a #GtkSpinButtonUpdatePolicy value * @policy: a #GtkSpinButtonUpdatePolicy value
* *
* Sets the update behavior of a spin button. This determines whether the * Sets the update behavior of a spin button.
* spin button is always updated or only when a valid value is set. * This determines wether the spin button is always updated
**/ * or only when a valid value is set.
*/
void void
gtk_spin_button_set_update_policy (GtkSpinButton *spin_button, gtk_spin_button_set_update_policy (GtkSpinButton *spin_button,
GtkSpinButtonUpdatePolicy policy) GtkSpinButtonUpdatePolicy policy)
@ -2192,11 +2312,11 @@ gtk_spin_button_set_update_policy (GtkSpinButton *spin_button,
* gtk_spin_button_get_update_policy: * gtk_spin_button_get_update_policy:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* *
* Gets the update behavior of a spin button. See * Gets the update behavior of a spin button.
* gtk_spin_button_set_update_policy(). * See gtk_spin_button_set_update_policy().
* *
* Return value: the current update policy * Return value: the current update policy
**/ */
GtkSpinButtonUpdatePolicy GtkSpinButtonUpdatePolicy
gtk_spin_button_get_update_policy (GtkSpinButton *spin_button) gtk_spin_button_get_update_policy (GtkSpinButton *spin_button)
{ {
@ -2208,11 +2328,11 @@ gtk_spin_button_get_update_policy (GtkSpinButton *spin_button)
/** /**
* gtk_spin_button_set_numeric: * gtk_spin_button_set_numeric:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @numeric: flag indicating if only numeric entry is allowed. * @numeric: flag indicating if only numeric entry is allowed
* *
* Sets the flag that determines if non-numeric text can be typed into * Sets the flag that determines if non-numeric text can be typed
* the spin button. * into the spin button.
**/ */
void void
gtk_spin_button_set_numeric (GtkSpinButton *spin_button, gtk_spin_button_set_numeric (GtkSpinButton *spin_button,
gboolean numeric) gboolean numeric)
@ -2240,7 +2360,7 @@ gtk_spin_button_set_numeric (GtkSpinButton *spin_button,
* See gtk_spin_button_set_numeric(). * See gtk_spin_button_set_numeric().
* *
* Return value: %TRUE if only numeric text can be entered * Return value: %TRUE if only numeric text can be entered
**/ */
gboolean gboolean
gtk_spin_button_get_numeric (GtkSpinButton *spin_button) gtk_spin_button_get_numeric (GtkSpinButton *spin_button)
{ {
@ -2252,11 +2372,12 @@ gtk_spin_button_get_numeric (GtkSpinButton *spin_button)
/** /**
* gtk_spin_button_set_wrap: * gtk_spin_button_set_wrap:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @wrap: a flag indicating if wrapping behavior is performed. * @wrap: a flag indicating if wrapping behavior is performed
* *
* Sets the flag that determines if a spin button value wraps around to the * Sets the flag that determines if a spin button value wraps
* opposite limit when the upper or lower limit of the range is exceeded. * around to the opposite limit when the upper or lower limit
**/ * of the range is exceeded.
*/
void void
gtk_spin_button_set_wrap (GtkSpinButton *spin_button, gtk_spin_button_set_wrap (GtkSpinButton *spin_button,
gboolean wrap) gboolean wrap)
@ -2271,7 +2392,7 @@ gtk_spin_button_set_wrap (GtkSpinButton *spin_button,
if (priv->wrap != wrap) if (priv->wrap != wrap)
{ {
priv->wrap = (wrap != 0); priv->wrap = wrap;
g_object_notify (G_OBJECT (spin_button), "wrap"); g_object_notify (G_OBJECT (spin_button), "wrap");
} }
@ -2286,7 +2407,7 @@ gtk_spin_button_set_wrap (GtkSpinButton *spin_button,
* exceeded. See gtk_spin_button_set_wrap(). * exceeded. See gtk_spin_button_set_wrap().
* *
* Return value: %TRUE if the spin button wraps around * Return value: %TRUE if the spin button wraps around
**/ */
gboolean gboolean
gtk_spin_button_get_wrap (GtkSpinButton *spin_button) gtk_spin_button_get_wrap (GtkSpinButton *spin_button)
{ {
@ -2316,11 +2437,12 @@ spin_button_get_arrow_size (GtkSpinButton *spin_button)
/** /**
* gtk_spin_button_set_snap_to_ticks: * gtk_spin_button_set_snap_to_ticks:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @snap_to_ticks: a flag indicating if invalid values should be corrected. * @snap_to_ticks: a flag indicating if invalid values should be corrected
* *
* Sets the policy as to whether values are corrected to the nearest step * Sets the policy as to whether values are corrected to the
* increment when a spin button is activated after providing an invalid value. * nearest step increment when a spin button is activated after
**/ * providing an invalid value.
*/
void void
gtk_spin_button_set_snap_to_ticks (GtkSpinButton *spin_button, gtk_spin_button_set_snap_to_ticks (GtkSpinButton *spin_button,
gboolean snap_to_ticks) gboolean snap_to_ticks)
@ -2348,11 +2470,11 @@ gtk_spin_button_set_snap_to_ticks (GtkSpinButton *spin_button,
* gtk_spin_button_get_snap_to_ticks: * gtk_spin_button_get_snap_to_ticks:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* *
* Returns whether the values are corrected to the nearest step. See * Returns whether the values are corrected to the nearest step.
* gtk_spin_button_set_snap_to_ticks(). * See gtk_spin_button_set_snap_to_ticks().
* *
* Return value: %TRUE if values are snapped to the nearest step. * Return value: %TRUE if values are snapped to the nearest step
**/ */
gboolean gboolean
gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button) gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button)
{ {
@ -2364,12 +2486,12 @@ gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button)
/** /**
* gtk_spin_button_spin: * gtk_spin_button_spin:
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* @direction: a #GtkSpinType indicating the direction to spin. * @direction: a #GtkSpinType indicating the direction to spin
* @increment: step increment to apply in the specified direction. * @increment: step increment to apply in the specified direction
* *
* Increment or decrement a spin button's value in a specified direction * Increment or decrement a spin button's value in a specified
* by a specified amount. * direction by a specified amount.
**/ */
void void
gtk_spin_button_spin (GtkSpinButton *spin_button, gtk_spin_button_spin (GtkSpinButton *spin_button,
GtkSpinType direction, GtkSpinType direction,
@ -2447,7 +2569,7 @@ gtk_spin_button_spin (GtkSpinButton *spin_button,
* @spin_button: a #GtkSpinButton * @spin_button: a #GtkSpinButton
* *
* Manually force an update of the spin button. * Manually force an update of the spin button.
**/ */
void void
gtk_spin_button_update (GtkSpinButton *spin_button) gtk_spin_button_update (GtkSpinButton *spin_button)
{ {

38
gtk/gtkspinbutton.h
View File

@ -48,14 +48,45 @@ G_BEGIN_DECLS
#define GTK_IS_SPIN_BUTTON_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_SPIN_BUTTON)) #define GTK_IS_SPIN_BUTTON_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_SPIN_BUTTON))
#define GTK_SPIN_BUTTON_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_SPIN_BUTTON, GtkSpinButtonClass)) #define GTK_SPIN_BUTTON_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_SPIN_BUTTON, GtkSpinButtonClass))
/**
* GTK_INPUT_ERROR:
*
* Constant to return from a signal handler for the #GtkSpinButton::input
* signal in case of conversion failure.
*/
#define GTK_INPUT_ERROR -1 #define GTK_INPUT_ERROR -1
/**
* 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
* adjustment
*
* 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().
*/
typedef enum typedef enum
{ {
GTK_UPDATE_ALWAYS, GTK_UPDATE_ALWAYS,
GTK_UPDATE_IF_VALID GTK_UPDATE_IF_VALID
} GtkSpinButtonUpdatePolicy; } GtkSpinButtonUpdatePolicy;
/**
* GtkSpinType:
* @GTK_SPIN_STEP_FORWARD: Increment by the adjustments step increment.
* @GTK_SPIN_STEP_BACKWARD: Decrement by the adjustments step increment.
* @GTK_SPIN_PAGE_FORWARD: Increment by the adjustments page increment.
* @GTK_SPIN_PAGE_BACKWARD: Decrement by the adjustments page increment.
* @GTK_SPIN_HOME: Go to the adjustments lower bound.
* @GTK_SPIN_END: Go to the adjustments upper bound.
* @GTK_SPIN_USER_DEFINED: Change by a specified amount.
*
* The values of the GtkSpinType enumeration are used to specify the
* change to make in gtk_spin_button_spin().
*/
typedef enum typedef enum
{ {
GTK_SPIN_STEP_FORWARD, GTK_SPIN_STEP_FORWARD,
@ -72,7 +103,12 @@ typedef struct _GtkSpinButton GtkSpinButton;
typedef struct _GtkSpinButtonPrivate GtkSpinButtonPrivate; typedef struct _GtkSpinButtonPrivate GtkSpinButtonPrivate;
typedef struct _GtkSpinButtonClass GtkSpinButtonClass; typedef struct _GtkSpinButtonClass GtkSpinButtonClass;
/**
* GtkSpinButton:
*
* The #GtkSpinButton struct contains only private data and should
* not be directly modified.
*/
struct _GtkSpinButton struct _GtkSpinButton
{ {
GtkEntry entry; GtkEntry entry;