11.100Class GtkRange

Base class for widgets which visualize an adjustment

Class GtkRange

GtkRange is the common base class for widgets which visualize an adjustment, e.g scales or scrollbars.

Apart from signals for monitoring the parameters of the adjustment, GtkRange provides properties and methods for influencing the sensitivity of the "steppers". It also provides properties and methods for setting a "fill level" on range widgets. See gtk_range_set_fill_level().

Sets the adjustment to be used as the "model" object for this range widget.

GtkRange.set_adjustment( adjustment )

adjustment

a GtkAdjustment

The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for GtkScale and nonzero for GtkScrollbar, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider.

The "fill level" is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in a streaming media player. In that use case, the value of the range would indicate the current play position, and the fill level would be the position up to which the file/stream has been downloaded.

This amount of prebuffering can be displayed on the range's trough and is themeable separately from the trough. To enable fill level display, use gtk_range_set_show_fill_level(). The range defaults to not showing the fill level.

Additionally, it's possible to restrict the range's slider position to values which are smaller than the fill level. This is controller by gtk_range_set_restrict_to_fill_level() and is by default enabled.

GTK_UPDATE_CONTINUOUS means that anytime the range slider is moved, the range value will change and the value_changed signal will be emitted. GTK_UPDATE_DELAYED means that the value will be updated after a brief timeout where no slider motion occurs, so updates are spaced by a short time rather than continuous. GTK_UPDATE_DISCONTINUOUS means that the value will only be updated when the user releases the button and ends the slider drag operation.

The change-value signal is emitted when a scroll action is performed on a range.

GtkRange.signal_change_value()

It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can handle the event itself and return TRUE to prevent further processing. Or, by returning FALSE, it can pass the event to other handlers until the default GTK+ handler is reached.

The value parameter is unrounded. An application that overrides the change-value signal is responsible for clamping the value to the desired number of decimal digits; the default GTK+ handler clamps the value based on range->round_digits.

It is not possible to use delayed update policies in an overridden change-value handler.