GTK#

Miscellaneous Widgets

Spin Buttons

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.

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.

The Spin Button uses an Adjustment object to hold information about the range of values that the spin button can take. This makes for a powerful Spin Button widget.

Recall that an adjustment widget is created with the following function, which illustrates the information that it holds:

Adjustment adjustment1 = new Adjustment( double value,
                                         double lower,
                                         double upper,
                                         double step_increment,
                                         double page_increment,
                                         double page_size );
These attributes of an Adjustment are used by the Spin Button in the following way:

value: initial value for the Spin Button

lower: lower range value

upper: upper range value

step_increment: value to increment/decrement when pressing mouse button 1 on a button

page_increment: value to increment/decrement when pressing mouse button 2 on a button

page_size: unused

Additionally, mouse button 3 can be used to jump directly to the upper or lower values when used to select one of the buttons. Lets look at how to create a Spin Button:

SpinButton spinbutton1 = new SpinButton(Adjustment adjustment,
                                        double     climb_rate,
                                        uint       digits );
The climb_rate argument take a value between 0.0 and 1.0 and indicates the amount of acceleration that the Spin Button has. The digits argument specifies the number of decimal places to which the value will be displayed.

A Spin Button can be reconfigured after creation using the following function:

spinbutton1.Configure(Adjustment adjustment,
                      double     climb_rate,
                      uint       digits);
The spin_button argument specifies the Spin Button widget that is to be reconfigured. The other arguments are as specified above.

The adjustment can be set and retrieved independantly using the following two functions:

spinbutton1.Adjustment = Adjustment adjustment;
Adjustment adjustment1 = spinbutton1.Adjustment;
The number of decimal places can also be altered using:
spinbutton1.Digits = uint digits;
The value that a Spin Button is currently displaying can be changed using the following function:
spinbutton1.Value = double value;
The current value of a Spin Button can be retrieved as either a floating point or integer value with the following functions:
double value = spinbutton1.Value;
If you want to alter the value of a Spin Button relative to its current value, then the following function can be used:
spinbutton1.Spin(SpinType    direction,
                 double      increment );
The direction parameter can take one of the following values:
  Gtk.Spin.StepForward
  Gtk.Spin.StepBackward
  Gtk.Spin.PageForward
  Gtk.Spin.PageBackward
  Gtk.Spin.Home
  Gtk.Spin.End
  Gtk.Spin.UserDefined
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.

Gtk.Spin.StepForward and Gtk.Spin.StepBackward change the value of the Spin Button by the amount specified by increment, unless increment is equal to 0, in which case the value is changed by the value of step_increment in theAdjustment.

Gtk.Spin.PageForward and Gtk.Spin.PageBackward simply alter the value of the Spin Button by increment.

Gtk.Spin.Home sets the value of the Spin Button to the bottom of the Adjustments range.

Gtk.Spin.End sets the value of the Spin Button to the top of the Adjustments range.

Gtk.Spin.UserDefined simply alters the value of the Spin Button by the specified amount.

We move away from functions for setting and retreving the range attributes of the Spin Button now, and move onto functions that effect the appearance and behaviour of the Spin Button widget itself.

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:

spinbutton1.Numeric = boolean numeric;
You can set whether a Spin Button will wrap around between the upper and lower range values with the following function:
spinbutton.Wrap = bool wrap;
You can set a Spin Button to round the value to the nearest step_increment, which is set within the Adjustment object used with the Spin Button. This is accomplished with the following function:
spinbutton1.SnapToTicks = boole snap_to_ticks);
The update policy of a Spin Button can be changed with the following function:
spinbutton1.UpdatePolicy = SpinButtonUpdatePolicy policy;
The possible values of policy are either Gtk.UpdateAlways or Gtk.UpdateIfValid.

These policies affect the behavior of a Spin Button when parsing inserted text and syncing its value with the values of the Adjustment.

In the case of Gtk.UpdateIfValid In case of Gtk.UpdateAlways we ignore errors while converting text into a numeric value.

Finally, you can explicitly request that a Spin Button update itself:

spinbutton1.Update();
It's example time again.

#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 (G_OBJECT (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 (G_OBJECT (adj), "value_changed",
                    G_CALLBACK (change_digits),
                    (gpointer) 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 (G_OBJECT (button), "clicked",
                    G_CALLBACK (toggle_snap),
                    (gpointer) 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 (G_OBJECT (button), "clicked",
                    G_CALLBACK (toggle_numeric),
                    (gpointer) 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 (G_OBJECT (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 (G_OBJECT (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 (G_OBJECT (button), "clicked",
                            G_CALLBACK (gtk_widget_destroy),
                            G_OBJECT (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;
}