<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Spin Buttons</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="GTK+ 2.0 Tutorial"
HREF="book1.html"><LINK
REL="UP"
TITLE="Miscellaneous Widgets"
HREF="c753.html"><LINK
REL="PREVIOUS"
TITLE="Text Entries"
HREF="x939.html"><LINK
REL="NEXT"
TITLE="Combo Box"
HREF="x1063.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>GTK+ 2.0 Tutorial</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x939.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Miscellaneous Widgets</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x1063.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SEC-SPINBUTTONS"
>Spin Buttons</A
></H1
><P
>The Spin Button widget is generally used to allow the user to select a
value from a range of numeric values. It consists of a text
entry box with up and down arrow buttons attached to the
side. Selecting one of the buttons causes the value to "spin" up and
down the range of possible values. The entry box may also be edited
directly to enter a specific value.</P
><P
>The Spin Button allows the value to have zero or a number of decimal
places and to be incremented/decremented in configurable steps. The
action of holding down one of the buttons optionally results in an
acceleration of change in the value according to how long it is
depressed.</P
><P
>The Spin Button uses an <A
HREF="c563.html"
>Adjustment</A
>
object to hold information about the range of values that the spin
button can take. This makes for a powerful Spin Button widget.</P
><P
>Recall that an adjustment widget is created with the following
function, which illustrates the information that it holds:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GtkObject *gtk_adjustment_new( gdouble value,
gdouble lower,
gdouble upper,
gdouble step_increment,
gdouble page_increment,
gdouble page_size );</PRE
></TD
></TR
></TABLE
><P
>These attributes of an Adjustment are used by the Spin Button in the
following way:</P
><P
></P
><UL
><LI
><P
> <TT
CLASS="LITERAL"
>value</TT
>: initial value for the Spin Button</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>lower</TT
>: lower range value</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>upper</TT
>: upper range value</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>step_increment</TT
>: value to increment/decrement when pressing
mouse button 1 on a button</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>page_increment</TT
>: value to increment/decrement when pressing
mouse button 2 on a button</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>page_size</TT
>: unused</P
></LI
></UL
><P
>Additionally, mouse button 3 can be used to jump directly to the
<TT
CLASS="LITERAL"
>upper</TT
> or <TT
CLASS="LITERAL"
>lower</TT
> values when used to select one of the
buttons. Lets look at how to create a Spin Button:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GtkWidget *gtk_spin_button_new( GtkAdjustment *adjustment,
gdouble climb_rate,
guint digits );</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="LITERAL"
>climb_rate</TT
> argument take a value between 0.0 and 1.0 and
indicates the amount of acceleration that the Spin Button has. The
<TT
CLASS="LITERAL"
>digits</TT
> argument specifies the number of decimal places to which
the value will be displayed.</P
><P
>A Spin Button can be reconfigured after creation using the following
function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_configure( GtkSpinButton *spin_button,
GtkAdjustment *adjustment,
gdouble climb_rate,
guint digits );</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="LITERAL"
>spin_button</TT
> argument specifies the Spin Button widget that is
to be reconfigured. The other arguments are as specified above.</P
><P
>The adjustment can be set and retrieved independantly using the
following two functions:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_adjustment( GtkSpinButton *spin_button,
GtkAdjustment *adjustment );
GtkAdjustment *gtk_spin_button_get_adjustment( GtkSpinButton *spin_button );</PRE
></TD
></TR
></TABLE
><P
>The number of decimal places can also be altered using:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_digits( GtkSpinButton *spin_button,
guint digits) ;</PRE
></TD
></TR
></TABLE
><P
>The value that a Spin Button is currently displaying can be changed
using the following function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_value( GtkSpinButton *spin_button,
gdouble value );</PRE
></TD
></TR
></TABLE
><P
>The current value of a Spin Button can be retrieved as either a
floating point or integer value with the following functions:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>gdouble gtk_spin_button_get_value ( GtkSpinButton *spin_button );
gint gtk_spin_button_get_value_as_int( GtkSpinButton *spin_button );</PRE
></TD
></TR
></TABLE
><P
>If you want to alter the value of a Spin Button relative to its current
value, then the following function can be used:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_spin( GtkSpinButton *spin_button,
GtkSpinType direction,
gdouble increment );</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="LITERAL"
>direction</TT
> parameter can take one of the following values:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> 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</PRE
></TD
></TR
></TABLE
><P
>This function packs in quite a bit of functionality, which I will
attempt to clearly explain. Many of these settings use values from the
Adjustment object that is associated with a Spin Button.</P
><P
><TT
CLASS="LITERAL"
>GTK_SPIN_STEP_FORWARD</TT
> and <TT
CLASS="LITERAL"
>GTK_SPIN_STEP_BACKWARD</TT
> change the
value of the Spin Button by the amount specified by <TT
CLASS="LITERAL"
>increment</TT
>,
unless <TT
CLASS="LITERAL"
>increment</TT
> is equal to 0, in which case the value is
changed by the value of <TT
CLASS="LITERAL"
>step_increment</TT
> in theAdjustment.</P
><P
><TT
CLASS="LITERAL"
>GTK_SPIN_PAGE_FORWARD</TT
> and <TT
CLASS="LITERAL"
>GTK_SPIN_PAGE_BACKWARD</TT
> simply
alter the value of the Spin Button by <TT
CLASS="LITERAL"
>increment</TT
>.</P
><P
><TT
CLASS="LITERAL"
>GTK_SPIN_HOME</TT
> sets the value of the Spin Button to the bottom of
the Adjustments range.</P
><P
><TT
CLASS="LITERAL"
>GTK_SPIN_END</TT
> sets the value of the Spin Button to the top of the
Adjustments range.</P
><P
><TT
CLASS="LITERAL"
>GTK_SPIN_USER_DEFINED</TT
> simply alters the value of the Spin Button
by the specified amount.</P
><P
>We move away from functions for setting and retreving the range attributes
of the Spin Button now, and move onto functions that affect the
appearance and behaviour of the Spin Button widget itself.</P
><P
>The first of these functions is used to constrain the text box of the
Spin Button such that it may only contain a numeric value. This
prevents a user from typing anything other than numeric values into
the text box of a Spin Button:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_numeric( GtkSpinButton *spin_button,
gboolean numeric );</PRE
></TD
></TR
></TABLE
><P
>You can set whether a Spin Button will wrap around between the upper
and lower range values with the following function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_wrap( GtkSpinButton *spin_button,
gboolean wrap );</PRE
></TD
></TR
></TABLE
><P
>You can set a Spin Button to round the value to the nearest
<TT
CLASS="LITERAL"
>step_increment</TT
>, which is set within the Adjustment object used
with the Spin Button. This is accomplished with the following
function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_snap_to_ticks( GtkSpinButton *spin_button,
gboolean snap_to_ticks );</PRE
></TD
></TR
></TABLE
><P
>The update policy of a Spin Button can be changed with the following
function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_set_update_policy( GtkSpinButton *spin_button,
GtkSpinButtonUpdatePolicy policy );</PRE
></TD
></TR
></TABLE
><P
>The possible values of <TT
CLASS="LITERAL"
>policy</TT
> are either <TT
CLASS="LITERAL"
>GTK_UPDATE_ALWAYS</TT
> or
<TT
CLASS="LITERAL"
>GTK_UPDATE_IF_VALID</TT
>.</P
><P
>These policies affect the behavior of a Spin Button when parsing
inserted text and syncing its value with the values of the
Adjustment.</P
><P
>In the case of <TT
CLASS="LITERAL"
>GTK_UPDATE_IF_VALID</TT
> the Spin Button value only
gets changed if the text input is a numeric value that is within the
range specified by the Adjustment. Otherwise the text is reset to the
current value.</P
><P
>In case of <TT
CLASS="LITERAL"
>GTK_UPDATE_ALWAYS</TT
> we ignore errors while converting
text into a numeric value.</P
><P
>Finally, you can explicitly request that a Spin Button update itself:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_spin_button_update( GtkSpinButton *spin_button );</PRE
></TD
></TR
></TABLE
><P
>It's example time again.</P
><P
><SPAN
CLASS="INLINEMEDIAOBJECT"
><IMG
SRC="images/spinbutton.png"></SPAN
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> #include <stdio.h>
#include <gtk/gtk.h>
static GtkWidget *spinner1;
static void toggle_snap( GtkWidget *widget,
GtkSpinButton *spin )
{
gtk_spin_button_set_snap_to_ticks (spin, GTK_TOGGLE_BUTTON (widget)->active);
}
static void toggle_numeric( GtkWidget *widget,
GtkSpinButton *spin )
{
gtk_spin_button_set_numeric (spin, GTK_TOGGLE_BUTTON (widget)->active);
}
static void change_digits( GtkWidget *widget,
GtkSpinButton *spin )
{
gtk_spin_button_set_digits (GTK_SPIN_BUTTON (spinner1),
gtk_spin_button_get_value_as_int (spin));
}
static void get_value( GtkWidget *widget,
gpointer data )
{
gchar *buf;
GtkLabel *label;
GtkSpinButton *spin;
spin = GTK_SPIN_BUTTON (spinner1);
label = GTK_LABEL (g_object_get_data (G_OBJECT (widget), "user_data"));
if (GPOINTER_TO_INT (data) == 1)
buf = g_strdup_printf ("%d", gtk_spin_button_get_value_as_int (spin));
else
buf = g_strdup_printf ("%0.*f", spin->digits,
gtk_spin_button_get_value (spin));
gtk_label_set_text (label, buf);
g_free (buf);
}
int main( int argc,
char *argv[] )
{
GtkWidget *window;
GtkWidget *frame;
GtkWidget *hbox;
GtkWidget *main_vbox;
GtkWidget *vbox;
GtkWidget *vbox2;
GtkWidget *spinner2;
GtkWidget *spinner;
GtkWidget *button;
GtkWidget *label;
GtkWidget *val_label;
GtkAdjustment *adj;
/* Initialise GTK */
gtk_init (&argc, &argv);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
g_signal_connect (window, "destroy",
G_CALLBACK (gtk_main_quit),
NULL);
gtk_window_set_title (GTK_WINDOW (window), "Spin Button");
main_vbox = gtk_vbox_new (FALSE, 5);
gtk_container_set_border_width (GTK_CONTAINER (main_vbox), 10);
gtk_container_add (GTK_CONTAINER (window), main_vbox);
frame = gtk_frame_new ("Not accelerated");
gtk_box_pack_start (GTK_BOX (main_vbox), frame, TRUE, TRUE, 0);
vbox = gtk_vbox_new (FALSE, 0);
gtk_container_set_border_width (GTK_CONTAINER (vbox), 5);
gtk_container_add (GTK_CONTAINER (frame), vbox);
/* Day, month, year spinners */
hbox = gtk_hbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), hbox, TRUE, TRUE, 5);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (hbox), vbox2, TRUE, TRUE, 5);
label = gtk_label_new ("Day :");
gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5);
gtk_box_pack_start (GTK_BOX (vbox2), label, FALSE, TRUE, 0);
adj = (GtkAdjustment *) gtk_adjustment_new (1.0, 1.0, 31.0, 1.0,
5.0, 0.0);
spinner = gtk_spin_button_new (adj, 0, 0);
gtk_spin_button_set_wrap (GTK_SPIN_BUTTON (spinner), TRUE);
gtk_box_pack_start (GTK_BOX (vbox2), spinner, FALSE, TRUE, 0);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (hbox), vbox2, TRUE, TRUE, 5);
label = gtk_label_new ("Month :");
gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5);
gtk_box_pack_start (GTK_BOX (vbox2), label, FALSE, TRUE, 0);
adj = (GtkAdjustment *) gtk_adjustment_new (1.0, 1.0, 12.0, 1.0,
5.0, 0.0);
spinner = gtk_spin_button_new (adj, 0, 0);
gtk_spin_button_set_wrap (GTK_SPIN_BUTTON (spinner), TRUE);
gtk_box_pack_start (GTK_BOX (vbox2), spinner, FALSE, TRUE, 0);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (hbox), vbox2, TRUE, TRUE, 5);
label = gtk_label_new ("Year :");
gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5);
gtk_box_pack_start (GTK_BOX (vbox2), label, FALSE, TRUE, 0);
adj = (GtkAdjustment *) gtk_adjustment_new (1998.0, 0.0, 2100.0,
1.0, 100.0, 0.0);
spinner = gtk_spin_button_new (adj, 0, 0);
gtk_spin_button_set_wrap (GTK_SPIN_BUTTON (spinner), FALSE);
gtk_widget_set_size_request (spinner, 55, -1);
gtk_box_pack_start (GTK_BOX (vbox2), spinner, FALSE, TRUE, 0);
frame = gtk_frame_new ("Accelerated");
gtk_box_pack_start (GTK_BOX (main_vbox), frame, TRUE, TRUE, 0);
vbox = gtk_vbox_new (FALSE, 0);
gtk_container_set_border_width (GTK_CONTAINER (vbox), 5);
gtk_container_add (GTK_CONTAINER (frame), vbox);
hbox = gtk_hbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), hbox, FALSE, TRUE, 5);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (hbox), vbox2, TRUE, TRUE, 5);
label = gtk_label_new ("Value :");
gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5);
gtk_box_pack_start (GTK_BOX (vbox2), label, FALSE, TRUE, 0);
adj = (GtkAdjustment *) gtk_adjustment_new (0.0, -10000.0, 10000.0,
0.5, 100.0, 0.0);
spinner1 = gtk_spin_button_new (adj, 1.0, 2);
gtk_spin_button_set_wrap (GTK_SPIN_BUTTON (spinner1), TRUE);
gtk_widget_set_size_request (spinner1, 100, -1);
gtk_box_pack_start (GTK_BOX (vbox2), spinner1, FALSE, TRUE, 0);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (hbox), vbox2, TRUE, TRUE, 5);
label = gtk_label_new ("Digits :");
gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5);
gtk_box_pack_start (GTK_BOX (vbox2), label, FALSE, TRUE, 0);
adj = (GtkAdjustment *) gtk_adjustment_new (2, 1, 5, 1, 1, 0);
spinner2 = gtk_spin_button_new (adj, 0.0, 0);
gtk_spin_button_set_wrap (GTK_SPIN_BUTTON (spinner2), TRUE);
g_signal_connect (adj, "value_changed",
G_CALLBACK (change_digits),
spinner2);
gtk_box_pack_start (GTK_BOX (vbox2), spinner2, FALSE, TRUE, 0);
hbox = gtk_hbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), hbox, FALSE, TRUE, 5);
button = gtk_check_button_new_with_label ("Snap to 0.5-ticks");
g_signal_connect (button, "clicked",
G_CALLBACK (toggle_snap),
spinner1);
gtk_box_pack_start (GTK_BOX (vbox), button, TRUE, TRUE, 0);
gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (button), TRUE);
button = gtk_check_button_new_with_label ("Numeric only input mode");
g_signal_connect (button, "clicked",
G_CALLBACK (toggle_numeric),
spinner1);
gtk_box_pack_start (GTK_BOX (vbox), button, TRUE, TRUE, 0);
gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (button), TRUE);
val_label = gtk_label_new ("");
hbox = gtk_hbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), hbox, FALSE, TRUE, 5);
button = gtk_button_new_with_label ("Value as Int");
g_object_set_data (G_OBJECT (button), "user_data", val_label);
g_signal_connect (button, "clicked",
G_CALLBACK (get_value),
GINT_TO_POINTER (1));
gtk_box_pack_start (GTK_BOX (hbox), button, TRUE, TRUE, 5);
button = gtk_button_new_with_label ("Value as Float");
g_object_set_data (G_OBJECT (button), "user_data", val_label);
g_signal_connect (button, "clicked",
G_CALLBACK (get_value),
GINT_TO_POINTER (2));
gtk_box_pack_start (GTK_BOX (hbox), button, TRUE, TRUE, 5);
gtk_box_pack_start (GTK_BOX (vbox), val_label, TRUE, TRUE, 0);
gtk_label_set_text (GTK_LABEL (val_label), "0");
hbox = gtk_hbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (main_vbox), hbox, FALSE, TRUE, 0);
button = gtk_button_new_with_label ("Close");
g_signal_connect_swapped (button, "clicked",
G_CALLBACK (gtk_widget_destroy),
window);
gtk_box_pack_start (GTK_BOX (hbox), button, TRUE, TRUE, 5);
gtk_widget_show_all (window);
/* Enter the event loop */
gtk_main ();
return 0;
} </PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x939.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x1063.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Text Entries</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c753.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Combo Box</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>