8. Range Widgets

The category of range widgets includes the ubiquitous scrollbar widget and the less common scale widget. Though these two types of widgets are generally used for different purposes, they are quite similar in function and implementation. All range widgets share a set of common graphic elements, each of which has its own X window and receives events. They all contain a trough (if English isn't your mother-tongue you may need to know that this is pronounced troff) and a slider (what is sometimes called a thumbwheel in other GUI environments). Dragging the slider with the pointer moves it back and forth within the trough, while clicking in the trough advances the slider towards the location of the click, either completely, or by a designated amount, depending on which mouse button is used.

As mentioned in Adjustments above, all range widgets are associated with an adjustment object, from which they calculate the length of the slider and its position within the trough. When the user manipulates the slider, the range widget will change the value of the adjustment.

8.1 Scrollbar Widgets

These are your standard, run-of-the-mill scrollbars. These should be used only for scrolling some other widget, such as a list, a text box, or a viewport (and it's generally easier to use the scrolled window widget in most cases). For other purposes, you should use scale widgets, as they are friendlier and more featureful.

There are separate types for horizontal and vertical scrollbars. There really isn't much to say about these. You create them with the following functions:

and that's about it. The adjustment argument can either be a pointer to an existing Adjustment, or NIL, in which case one will be created for you. Specifying NIL might actually be useful in this case, if you wish to pass the newly-created adjustment to the constructor function of some other widget which will configure it for you, such as a text widget.

8.2 Scale Widgets

Scale widgets are used to allow the user to visually select and manipulate a value within a specific range. You might want to use a scale widget, for example, to adjust the magnification level on a zoomed preview of a picture, or to control the brightness of a colour, or to specify the number of minutes of inactivity before a screensaver takes over the screen.

8.2.1 Creating Scale Widgets

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:

The adjustment argument can either be an adjustment which has already been created with gtk_adjustment_new(), or NIL, 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. (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:

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 GtkAdjustment. You can change this with:

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:

The argument pos can take one of the following values:

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.

8.3 Common Range Functions

The Range widget class is fairly complicated internally, but, like all the base class widgets, most of its complexity is only interesting if you want to hack it. Also, almost all of the functions and signals it defines are only really used in writing derived widgets. There are, however, a few useful functions that are defined that will work on all range widgets.

8.3.1 Setting the Update Policy

The  update policy" of a range widget defines at what points during user interaction it will change the value field of its Adjustment and emit the "value_changed" signal on this Adjustment. The update policies, defined as GtkUpdateType, are:

The update policy of a range widget can be set by casting it using the GTK_RANGE(widget) macro and passing it to this procedure:

8.3.2 Getting and Setting Adjustments

Getting and setting the adjustment for a range widget "on the fly" is done, predictably, with:

gtk_range_get_adjustment() returns a pointer to the adjustment to which range is connected. gtk_range_set_adjustment() does absolutely nothing if you pass it the adjustment that range is already using, regardless of whether you changed any of its fields or not. If you pass it a new Adjustment, it will unreference the old one if it exists (possibly destroying it), connect the appropriate signals to the new one, and call the private function gtk_range_adjustment_changed(), which will (or at least, is supposed to...) recalculate the size and/or position of the slider and redraw if necessary. As mentioned in the section on adjustments, if you wish to reuse the same Adjustment, when you modify its values directly, you should emit the changed signal on it, like this:

8.4 Key and Mouse bindings

All of the GTK range widgets react to mouse clicks in more or less the same way. Clicking button-1 in the trough will cause its adjustment's page_increment to be added or subtracted from its value, and the slider to be moved accordingly. Clicking mouse button-2 in the trough will jump the slider to the point at which the button was clicked. Clicking any button on a scrollbar's arrows will cause its adjustment's value to change step_increment each time.

It may take a little while to get used to, but by default, scrollbars as well as scale widgets can take the keyboard focus in GTK. If you think your users will find this too confusing, you can always disable this by unsetting the GTK_CAN_FOCUS flag on the scrollbar, like this:

The key bindings (which are, of course, only active when the widget has focus) are slightly different between horizontal and vertical range widgets, for obvious reasons. They are also not quite the same for scale widgets as they are for scrollbars, for somewhat less obvious reasons (possibly to avoid confusion between the keys for horizontal and vertical scrollbars in scrolled windows, where both operate on the same area).

All vertical range widgets can be operated with the up and down arrow keys, as well as with the Page Up and Page Down keys. The arrows move the slider up and down by step_increment, while Page Up and Page Down move it by page_increment.

The user can also move the slider all the way to one end or the other of the trough using the keyboard. With the VScale widget, this is done with the Home and End keys, whereas with the VScrollbar widget, this is done by pressing Control + Page Up and Control + Page Down.

The left and right arrow keys work as you might expect in these widgets, moving the slider back and forth by step_increment. The Home and End keys move the slider to the ends of the trough. For the HScale widget, moving the slider by page_increment is accomplished with Control + Left Arrow and Control + Right Arrow, while for HScrollbar, it's done with Control + Home and Control + End.

8.5 Range Controls Example

This example is a somewhat modified version of the range controls test from testgtk.c. It basically puts up a window with three range widgets all connected to the same adjustment, and a couple of controls for adjusting some of the parameters mentioned above and in the section on adjustments, so you can see how they affect the way these widgets work for the user. This is a long example, but is well worth going through.

You will notice that the program does not call gtk_signal_connect() for the delete_event, but only for the destroy signal. This will still perform the desired function, because an unhandled delete_event will result in a destroy signal being given to the window.