8.2. Scale Widgets

8.2.1. Creating a Scale Widget

As with scrollbars, there are separate widget types for horizontal and vertical scale widgets. (Most programmers seem to favour horizontal scale widgets.) Since they work essentially the same way, there's no need to treat them separately here. The following functions create vertical and horizontal scale widgets, respectively:

GtkWidget *gtk_vscale_new( GtkAdjustment *adjustment );

GtkWidget *gtk_vscale_new_with_range( gdouble min,
                                      gdouble max,
                                      gdouble step );

GtkWidget *gtk_hscale_new( GtkAdjustment *adjustment );

GtkWidget *gtk_hscale_new_with_range( gdouble min,
                                      gdouble max,
                                      gdouble step );

The adjustment argument can either be an adjustment which has already been created with gtk_adjustment_new(), or NULL, in which case, an anonymous Adjustment is created with all of its values set to 0.0 (which isn't very useful in this case). In order to avoid confusing yourself, you probably want to create your adjustment with a page_size of 0.0 so that its upper value actually corresponds to the highest value the user can select. The _new_with_range() variants take care of creating a suitable adjustment. (If you're already thoroughly confused, read the section on Adjustments again for an explanation of what exactly adjustments do and how to create and manipulate them.)

8.2.2. Functions and Signals (well, functions, at least)

Scale widgets can display their current value as a number beside the trough. The default behaviour is to show the value, but you can change this with this function:

void gtk_scale_set_draw_value( GtkScale *scale,
                               gboolean draw_value );

As you might have guessed, draw_value is either TRUE or FALSE, with predictable consequences for either one.

The value displayed by a scale widget is rounded to one decimal point by default, as is the value field in its Adjustment. You can change this with:

void gtk_scale_set_digits( GtkScale *scale,
                            gint     digits );

where digits is the number of decimal places you want. You can set digits to anything you like, but no more than 13 decimal places will actually be drawn on screen.

Finally, the value can be drawn in different positions relative to the trough:

void gtk_scale_set_value_pos( GtkScale        *scale,
                              GtkPositionType  pos );

The argument pos is of type GtkPositionType, which can take one of the following values:

  GTK_POS_LEFT
  GTK_POS_RIGHT
  GTK_POS_TOP
  GTK_POS_BOTTOM

If you position the value on the "side" of the trough (e.g., on the top or bottom of a horizontal scale widget), then it will follow the slider up and down the trough.

All the preceding functions are defined in <gtk/gtkscale.h>. The header files for all GTK widgets are automatically included when you include <gtk/gtk.h>. But you should look over the header files of all widgets that interest you, in order to learn more about their functions and features.