9.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 on 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 in <gtk/gtkrange.h> and will work on all range widgets.

9.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 in <gtk/gtkenums.h> as type enum GtkUpdateType, are:

GTK_UPDATE_CONTINUOUS

This is the default. The "value_changed" signal is emitted continuously, i.e., whenever the slider is moved by even the tiniest amount.

GTK_UPDATE_DISCONTINUOUS

The "value_changed" signal is only emitted once the slider has stopped moving and the user has released the mouse button.

GTK_UPDATE_DELAYED

The "value_changed" signal is emitted when the user releases the mouse button, or if the slider stops moving for a short period of time.

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

void gtk_range_set_update_policy( GtkRange      *range,
	                          GtkUpdateType  policy);

9.3.2. Getting and Setting Adjustments

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

GtkAdjustment* gtk_range_get_adjustment( GtkRange *range );

void gtk_range_set_adjustment( GtkRange      *range,
                               GtkAdjustment *adjustment );

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:

g_signal_emit_by_name (G_OBJECT (adjustment), "changed");