GtkSpinButton

GtkSpinButton

Properties

GtkAdjustment * adjustment Read / Write
gdouble climb-rate Read / Write
guint digits Read / Write
gboolean numeric Read / Write
gboolean snap-to-ticks Read / Write
GtkSpinButtonUpdatePolicy update-policy Read / Write
gdouble value Read / Write
gboolean wrap Read / Write

Style Properties

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GtkEntry
                    ╰── GtkSpinButton

Implemented Interfaces

GtkSpinButton implements AtkImplementorIface, GtkBuildable, GtkEditable and GtkCellEditable.

Includes

#include <gtk/gtk.h>

Description

Functions

gtk_spin_button_configure ()

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.

Parameters

spin_button

a GtkSpinButton

 

adjustment

a GtkAdjustment.

[allow-none]

climb_rate

the new climb rate.

 

digits

the number of decimal places to display in the spin button.

 

gtk_spin_button_new ()

GtkWidget *
gtk_spin_button_new (GtkAdjustment *adjustment,
                     gdouble climb_rate,
                     guint digits);

gtk_spin_button_new_with_range ()

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.

Parameters

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.


gtk_spin_button_set_adjustment ()

void
gtk_spin_button_set_adjustment (GtkSpinButton *spin_button,
                                GtkAdjustment *adjustment);

Replaces the GtkAdjustment associated with spin_button .

Parameters

spin_button

a GtkSpinButton

 

adjustment

a GtkAdjustment to replace the existing adjustment

 

gtk_spin_button_get_adjustment ()

GtkAdjustment *
gtk_spin_button_get_adjustment (GtkSpinButton *spin_button);

Get the adjustment associated with a GtkSpinButton

Parameters

spin_button

a GtkSpinButton

 

Returns

the GtkAdjustment of spin_button .

[transfer none]


gtk_spin_button_set_digits ()

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.

Parameters

spin_button

a GtkSpinButton

 

digits

the number of digits after the decimal point to be displayed for the spin button's value

 

gtk_spin_button_set_increments ()

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.

Parameters

spin_button

a GtkSpinButton

 

step

increment applied for a button 1 press.

 

page

increment applied for a button 2 press.

 

gtk_spin_button_set_range ()

void
gtk_spin_button_set_range (GtkSpinButton *spin_button,
                           gdouble min,
                           gdouble max);

Sets the minimum and maximum allowable values for spin_button

Parameters

spin_button

a GtkSpinButton

 

min

minimum allowable value

 

max

maximum allowable value

 

gtk_spin_button_get_value_as_int ()

gint
gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button);

Get the value spin_button represented as an integer.

Parameters

spin_button

a GtkSpinButton

 

Returns

the value of spin_button


gtk_spin_button_set_value ()

void
gtk_spin_button_set_value (GtkSpinButton *spin_button,
                           gdouble value);

Set the value of spin_button .

Parameters

spin_button

a GtkSpinButton

 

value

the new value

 

gtk_spin_button_set_update_policy ()

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.

Parameters

spin_button

a GtkSpinButton

 

policy

a GtkSpinButtonUpdatePolicy value

 

gtk_spin_button_set_numeric ()

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.

Parameters

spin_button

a GtkSpinButton

 

numeric

flag indicating if only numeric entry is allowed.

 

gtk_spin_button_spin ()

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.

Parameters

spin_button

a GtkSpinButton

 

direction

a GtkSpinType indicating the direction to spin.

 

increment

step increment to apply in the specified direction.

 

gtk_spin_button_set_wrap ()

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.

Parameters

spin_button

a GtkSpinButton

 

wrap

a flag indicating if wrapping behavior is performed.

 

gtk_spin_button_set_snap_to_ticks ()

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.

Parameters

spin_button

a GtkSpinButton

 

snap_to_ticks

a flag indicating if invalid values should be corrected.

 

gtk_spin_button_update ()

void
gtk_spin_button_update (GtkSpinButton *spin_button);

Manually force an update of the spin button.

Parameters

spin_button

a GtkSpinButton

 

gtk_spin_button_get_digits ()

guint
gtk_spin_button_get_digits (GtkSpinButton *spin_button);

Fetches the precision of spin_button . See gtk_spin_button_set_digits().

Parameters

spin_button

a GtkSpinButton

 

Returns

the current precision


gtk_spin_button_get_increments ()

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().

Parameters

spin_button

a GtkSpinButton

 

step

location to store step increment, or NULL.

[out][allow-none]

page

location to store page increment, or NULL.

[out][allow-none]

gtk_spin_button_get_numeric ()

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().

Parameters

spin_button

a GtkSpinButton

 

Returns

TRUE if only numeric text can be entered


gtk_spin_button_get_range ()

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().

Parameters

spin_button

a GtkSpinButton

 

min

location to store minimum allowed value, or NULL.

[out][allow-none]

max

location to store maximum allowed value, or NULL.

[out][allow-none]

gtk_spin_button_get_snap_to_ticks ()

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().

Parameters

spin_button

a GtkSpinButton

 

Returns

TRUE if values are snapped to the nearest step.


gtk_spin_button_get_update_policy ()

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().

Parameters

spin_button

a GtkSpinButton

 

Returns

the current update policy


gtk_spin_button_get_value ()

gdouble
gtk_spin_button_get_value (GtkSpinButton *spin_button);

Get the value in the spin_button .

Parameters

spin_button

a GtkSpinButton

 

Returns

the value of spin_button


gtk_spin_button_get_wrap ()

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().

Parameters

spin_button

a GtkSpinButton

 

Returns

TRUE if the spin button wraps around

Types and Values

struct GtkSpinButton

struct GtkSpinButton;

enum GtkSpinButtonUpdatePolicy

Members

GTK_UPDATE_ALWAYS

   

GTK_UPDATE_IF_VALID

   

enum GtkSpinType

Members

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

   

gtk_spin_button_get_value_as_float

#define gtk_spin_button_get_value_as_float gtk_spin_button_get_value

gtk_spin_button_get_value_as_float is deprecated and should not be used in newly-written code.


GTK_INPUT_ERROR

#define GTK_INPUT_ERROR -1

Property Details

The “adjustment” property

  “adjustment”               GtkAdjustment *

The adjustment that holds the value of the spinbutton.

Flags: Read / Write


The “climb-rate” property

  “climb-rate”               gdouble

The acceleration rate when you hold down a button.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “digits” property

  “digits”                   guint

The number of decimal places to display.

Flags: Read / Write

Allowed values: <= 20

Default value: 0


The “numeric” property

  “numeric”                  gboolean

Whether non-numeric characters should be ignored.

Flags: Read / Write

Default value: FALSE


The “snap-to-ticks” property

  “snap-to-ticks”            gboolean

Whether erroneous values are automatically changed to a spin button's nearest step increment.

Flags: Read / Write

Default value: FALSE


The “update-policy” property

  “update-policy”            GtkSpinButtonUpdatePolicy

Whether the spin button should update always, or only when the value is legal.

Flags: Read / Write

Default value: GTK_UPDATE_ALWAYS


The “value” property

  “value”                    gdouble

Reads the current value, or sets a new value.

Flags: Read / Write

Default value: 0


The “wrap” property

  “wrap”                     gboolean

Whether a spin button should wrap upon reaching its limits.

Flags: Read / Write

Default value: FALSE

Style Property Details

The “shadow-type” style property

  “shadow-type”              GtkShadowType

Style of bevel around the spin button.

Flags: Read

Default value: GTK_SHADOW_IN

Signal Details

The “change-value” signal

void
user_function (GtkSpinButton *spinbutton,
               GtkScrollType  arg1,
               gpointer       user_data)

Flags: Action


The “input” signal

gint
user_function (GtkSpinButton *spinbutton,
               gpointer       arg1,
               gpointer       user_data)

Flags: Run Last


The “output” signal

gboolean
user_function (GtkSpinButton *spin_button,
               gpointer       user_data)

The ::output signal can be used to change to formatting of the value that is displayed in the spin buttons entry.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/* show leading zeros */
static gboolean
on_output (GtkSpinButton *spin,
           gpointer       data)
{
   GtkAdjustment *adj;
   gchar *text;
   int value;

   adj = gtk_spin_button_get_adjustment (spin);
   value = (int)gtk_adjustment_get_value (adj);
   text = g_strdup_printf ("%02d", value);
   gtk_entry_set_text (GTK_ENTRY (spin), text);
   g_free (text);

   return TRUE;
}

Parameters

spin_button

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the value has been displayed.

Flags: Run Last


The “value-changed” signal

void
user_function (GtkSpinButton *spinbutton,
               gpointer       user_data)

Flags: Run Last


The “wrapped” signal

void
user_function (GtkSpinButton *spinbutton,
               gpointer       user_data)

The wrapped signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa.

Parameters

spinbutton

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 2.10