gtk.Range
Prev | The gtk Class Reference | Next

## gtk.Range

gtk.Range — a base class for widgets that allow a user to set a value in a range.

## Synopsis

    class gtk.Range(gtk.Widget):
        def set_update_policy(policy)
        def get_update_policy()
        def set_adjustment(adjustment)
        def get_adjustment()
        def set_inverted(setting)
        def get_inverted()
        def set_increments(step, page)
        def set_range(min, max)
        def set_value(value)
        def get_value()
        def get_fill_level()
        def set_fill_level(fill_level)
        def get_restrict_to_fill_level()
        def set_restrict_to_fill_level(restrict_to_fill_level)
        def get_show_fill_level()
        def set_show_fill_level(show_fill_level)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Range

## Implemented Interfaces

`gtk.Range` implements `gtk.Buildable`

## gtk.Range Properties

gtk.Object Properties

gtk.Widget Properties

"adjustment" | Read-Write | The `gtk.Adjustment` that contains the current value of this range object
"fill-level" | Read-Write | The fill level (e.g. prebuffering of a network stream). See `gtk.Range.set_fill_level`(). Default value: 1.79769e+308. Available in GTK+ 2.12.
"inverted" | Read-Write | If `True`, the slider movement is reversed e.g right-to-left instead of left-to-right
"lower-stepper-sensitivity" | Read-Write | The sensitivity policy for the stepper that points to the adjustment's lower side
"restrict-to-fill-level" | Read-Write | The restrict-to-fill-level property controls whether slider movement is restricted to an upper boundary set by the fill level. See `gtk.Range.get_restrict_to_fill_level`(). Default value: True. Available in GTK+ 2.12.
"update-policy" | Read-Write | How the range should be updated on the screen: `gtk.UPDATE_CONTINUOUS`, `gtk.UPDATE_DISCONTINUOUS`, `gtk.UPDATE_DELAYED`.
"show-fill-level" | Read-Write | The show-fill-level property controls whether fill level indicator graphics are displayed on the trough. See gtk_range_set_show_fill_level(). `gtk.Range.set_show_fill_level`(). Default value: False. Available in GTK+ 2.12.

## gtk.Range Style Properties

gtk.Widget Style Properties

"activate-slider" | Read | With this option set to `True`, sliders will be drawn `ACTIVE` and with shadow `IN` while they are dragged
"arrow-displacement-x" | Read | The distance horizontally to move the arrow when the button is depressed
"arrow-displacement-y" | Read | The distance vertically to move the arrow when the button is depressed
"arrow-scaling" | Read | The arrow size proportion relative to the scroll button size. Allowed values: [0,1]. Default value: 0.5. Available from GTK+ 2.14.
"slider-width" | Read | The width of scrollbar or scale thumb
"stepper-size" | Read | The length of step buttons at ends
"stepper-spacing" | Read | The spacing between step buttons and thumb
"trough-border" | Read | The spacing between thumb or steppers and outer trough bevel
"trough-side-details" | Read | This property is available in GTK+ 2.10 and above.
"trough-under-steppers" | Read | if `True` draw the trough across the full length of the range or to exclude the steppers and their spacing. Note that setting the "stepper-spacing" style property to any value > 0 will automatically enable "trough-under-steppers" too. This property is available in GTK+ 2.10 and above.

## gtk.Range Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

"adjust-bounds" | `def callback(`range`, `value`, `user_param1`, `...`)`
"change-value | `def callback(`range`, `scroll`, `value`, `arg1`, `arg2`, `user_param1`, `...`)`
"move-slider" | `def callback(`range`, `scrolltype`, `user_param1`, `...`)`
"value-changed" | `def callback(`range`, `user_param1`, `...`)`

## Description

The `gtk.Range` is the base class for the `gtk.Scale` and `gtk.Scrollbar` widgets. The `gtk.Range` provides the common functionality for these widgets that allow a user to set a value in a range of values. The `gtk.Scale` works in conjunction with a `gtk.Adjustment` which provides the range information.

## Methods

### gtk.Range.set_update_policy

        def set_update_policy(policy)

`policy` : | the update policy: `gtk.UPDATE_CONTINUOUS`, `gtk.UPDATE_DISCONTINUOUS`, `gtk.UPDATE_DELAYED`

The `set_update_policy`() method sets the "update-policy" property to the value specified by `policy`. The update policy has the following values and effects:

`gtk.UPDATE_CONTINUOUS` | anytime the range slider is moved, the range value will change and the "value_changed" signal will be emitted.
`gtk.UPDATE_DELAYED` | the value will be updated after a brief timeout where no slider motion occurs, so value changes are delayed slightly rather than continuously updated.
`gtk.UPDATE_DISCONTINUOUS` | the value will only be updated when the user releases the button and ends the slider drag operation.

### gtk.Range.get_update_policy

        def get_update_policy()

Returns : | the current update policy

The `get_update_policy`() method gets the value of the "update-policy" property. The update policy is one of: `gtk.UPDATE_CONTINUOUS`, `gtk.UPDATE_DISCONTINUOUS` or `gtk.UPDATE_DELAYED`. See the `set_update_policy`() method for details.

### gtk.Range.set_adjustment

        def set_adjustment(adjustment)

`adjustment` : | a `gtk.Adjustment`

The `set_adjustment`() method sets the "adjustment" property to the value specified by `adjustment`. The `gtk.Adjustment` is used as the "model" object for this range widget. `adjustment` indicates the current range value, the minimum and maximum range values, the step and page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for `gtk.Scale` and nonzero for `gtk.Scrollbar`, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider.

### gtk.Range.get_adjustment

        def get_adjustment()

Returns : | a `gtk.Adjustment`

The `get_adjustment`() method returns the value of the "adjustment" property. See the `set_adjustment`() method for details.

### gtk.Range.set_inverted

        def set_inverted(setting)

`setting` : | if `True` invert the range

The `set_inverted`() method sets the "inverted" property to the value specified by `setting`. If `setting` is `True` the normal motion of the range widget is reversed. Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted ranges have higher values at the top or left rather than on the bottom or right.

### gtk.Range.get_inverted

        def get_inverted()

Returns : | `True` if the range is inverted

The `get_inverted`() method returns the value of the "inverted" property that was set by the `set_inverted`() method.

### gtk.Range.set_increments

        def set_increments(step, page)

`step` : | the step size
`page` : | the page size

The `set_increments`() method sets the step and page sizes for the range to the values specified by `step` and `page` respectively. The step size is used when the user clicks the `gtk.Scrollbar` arrows or moves `gtk.Scale` via the arrow keys. The page size is used for example when moving via Page Up or Page Down keys.

### gtk.Range.set_range

        def set_range(min, max)

`min` : | the minimum range value
`max` : | the maximum range value

The `set_range`() method sets the minimum and maximum allowable values for the `gtk.Range` to that values specified by `min` and `max` respectively. If the range has a non-zero page size, it is also forced to be between `min` and `max`.

### gtk.Range.set_value

        def set_value(value)

`value` : | the new value of the range

The `set_value`() method sets the current value of the range to the value specified by `value`. `value` will be forced inside the minimum or maximum range values. The range emits the "value_changed" signal if the value changes.

### gtk.Range.get_value

        def get_value()

Returns : | the current value of the range.

The `get_value`() method gets the current value of the range.

### gtk.Range.set_fill_level

        def set_fill_level(fill_level)

`fill_level` : | the new position of the fill level indicator.

The `set_fill_level`() method sets the new position of the fill level indicator.

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.Range.get_fill_level

        def get_fill_level()

Returns : | The current fill level.

The `get_fill_level`() method gets the current position of the fill level indicator.

### gtk.Range.set_restrict_to_fill_level

        def set_restrict_to_fill_level(restrict_to_fill_level)

`restrict_to_fill_level` : | Whether the fill level restricts slider movement.

The `set_restrict_to_fill_level`() method sets whether the slider is restricted to the fill level. See `gtk.Range.set_fill_level`() for a general description of the fill level concept.

### gtk.Range.get_restrict_to_fill_level

        def get_restrict_to_fill_level()

Returns : | `True` if range is restricted to the fill level.

The `get_restrict_to_fill_level`() method gets whether the range is restricted to the fill level.

### gtk.Range.set_show_fill_level

        def set_show_fill_level(show_fill_level)

`show_fill_level` : | Whether a fill level indicator graphics is shown.

The `set_show_fill_level`() method sets whether a graphical fill level is show on the trough. See `gtk.Range.set_fill_level`() for a general description of the fill level concept.

### gtk.Range.get_show_fill_level

        def get_show_fill_level()

Returns : | `True` if range shows the fill level.

The `get_show_fill_level`() method gets whether the range displays the fill level graphically.

## Signals

### The "adjust-bounds" gtk.Range Signal

        def callback(range, value, user_param1, ...)

`range` : | the range that received the signal
`value` : | the value
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "adjust-bounds" signal is emitted when the range is adjusted by user action. Note the value can be more or less than the range since it depends on the mouse position.

### The "change-value" gtk.Range Signal

        def callback(range, scroll, value, user_param1, ...)

`range` : | the range that received the signal. the object which received the signal.
`scroll` : | the type of scroll action that was performed - one of the GTK Scroll Type Constants..
`value` : | the new value resulting from the scroll action.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to prevent other handlers from being invoked for the signal or `False` to propagate the signal further.

### Note

This signal is available in GTK+ 2.6 and above.

The "change-value" signal is emitted when a scroll action is performed on a range. 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.

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

### The "move-slider" gtk.Range Signal

        def callback(range, scrolltype, user_param1, ...)

`range` : | the range that received the signal
`scrolltype` : | the scroll type issued because a key was pressed by the user; one of the GTK Scroll Type Constants.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "move-slider" signal is emitted when the user presses a key (e.g. Page Up, Home, Right Arrow) to move the slider.

### The "value-changed" gtk.Range Signal

        def callback(range, user_param1, ...)

`range` : | the range that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "value-changed" signal is emitted when the range value is changed either programmatically or by user action.

Prev | Up | Next
gtk.RadioToolButton | Home | gtk.RcStyle