gtk.Scale
Prev | The gtk Class Reference | Next

## gtk.Scale

gtk.Scale — a base class for the scale widgets.

## Synopsis

    class gtk.Scale(gtk.Range):
        def set_digits(digits)
        def get_digits()
        def set_draw_value(draw_value)
        def get_draw_value()
        def set_value_pos(pos)
        def get_value_pos()
        def get_layout()
        def get_layout_offsets()
        def add_mark(value, position, markup)
        def clear_marks()

## Ancestry

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

## Implemented Interfaces

`gtk.Scale` implements `gtk.Buildable`

## gtk.Scale Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Range Properties

"digits" | Read-Write | The number of decimal places that are displayed in the value
"draw-value" | Read-Write | If `True` the current value is displayed as a string next to the slider
"value-pos" | Read-Write | The position in which the current value is displayed: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP` or `gtk.POS_BOTTOM`

## gtk.Scale Style Properties

gtk.Widget Style Properties

gtk.Range Style Properties

"slider-length" | Read | The length of scale's slider
"value-spacing" | Read | The space between value text and the slider or trough area

## gtk.Scale Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Range Signal Prototypes

"format-value" | `def callback(`scale`, `user_param1`, `...`)`

## Description

The `gtk.Scale` widget is an abstract base class, used only for deriving the subclasses `gtk.HScale` and `gtk.VScale`. A `gtk.Scale` is a slider control used to select a numeric value. Since `gtk.Scale` is a subclass of `gtk.Range`, see the `gtk.Range` methods for additional methods. To set the value of a scale, you would normally use `set_value`(). To detect changes to the value, you would normally use the "value_changed" signal.

## Methods

### gtk.Scale.set_digits

        def set_digits(digits)

`digits` : | the number of decimal places to display

The `set_digits`() method sets the "digits" property to the value specified by `digits`. The value of `digits` specifies the number of decimal places that are displayed in the value. The value of the adjustment is also rounded off to this number of digits if "draw-value" is `True`, so the retrieved value matches the value the user sees. If the "draw-value" property has been set to `False` by using the `set_draw_value`() method, the adjustment value will not be rounded at all.

### gtk.Scale.get_digits

        def get_digits()

Returns : | the number of decimal places that are displayed.

The `get_digits`() method returns the value of the "digits" property that indicates the number of decimal places that are displayed in the value.

### gtk.Scale.set_draw_value

        def set_draw_value(draw_value)

`draw_value` : | If `True` draw the current value next to the slider

The `set_draw_value`() method sets the "draw-value" property to the value specified by `draw_value`. If `draw_value` is `True` the current value is displayed next to the slider.

### gtk.Scale.get_draw_value

        def get_draw_value()

Returns : | `True` if the current value is to be drawn next to the slider

The `get_draw_value`() method returns the value of the "draw-value" property. If "draw-value" is `True` the current scale value is drawn next to the slider.

### gtk.Scale.set_value_pos

        def set_value_pos(pos)

`pos` : | the position where the current value is displayed.

The `set_value_pos`() method sets the value of the "value-pos" property to the value specified by `pos`. The value of `pos` must be one of: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP` or `gtk.POS_BOTTOM`.

### gtk.Scale.get_value_pos

        def get_value_pos()

Returns : | the position where the current value is displayed.

The `get_value_pos`() method returns the value of the "value-pos" property. See the `set_value_pos`() method.

### gtk.Scale.get_layout

        def get_layout()

Returns : | the `pango.Layout` for this scale or `None` if the draw_value property is `False`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_layout`() method returns the `pango.Layout` used to display the scale.

### gtk.Scale.get_layout_offsets

        def get_layout_offsets()

Returns : | a 2-tuple containing the coordinates where the scale will draw the `pango.Layout` representing the text in the scale

### Note

This method is available in PyGTK 2.4 and above.

The `get_layout_offsets`() method returns a 2-tuple containing the coordinates where the scale will draw the `pango.Layout` representing the text in the scale. Remember when using the `pango.Layout` function you need to convert to and from pixels using the `pango.PIXELS`() function or `pango.SCALE`. If the "draw-value" property is `False`, the return values are undefined.

### gtk.Scale.add_mark

        def add_mark(value, position, markup)

`value` : | the value at which the mark is placed, must be between the lower and upper limits of the scales' adjustment.
`position` : | where to draw the mark. For a horizontal scale, `gtk.POS_TOP` is drawn above the scale, anything else below. For a vertical scale, `gtk.POS_LEFT` is drawn to the left of the scale, anything else to the right.
`markup` : | text to be shown at the mark, using Pango markup, or `None`.

### Note

This method is available in PyGTK 2.16 and above.

The `add_mark`() method adds a mark at value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK+ makes it easy for the user to position the scale exactly at the marks value. If markup is not `None`, text is shown next to the tick mark. To remove marks from a scale, use `clear_marks`().

### gtk.Scale.clear_marks

        def clear_marks()

### Note

This method is available in PyGTK 2.16 and above.

The `clear_marks`() method removes any marks that have been added with `add_mark`().

## Signals

### The "format-value" gtk.Scale Signal

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

`scale` : | the scale that received the signal
`value` : | the value to be formatted
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | a string representing `value` for display

The "format-value" signal is emitted when the scale is being redrawn with a value displayed. The "format-value" signal handler should return a formatted string containing `value`.

Prev | Up | Next
gtk.Ruler | Home | gtk.ScaleButton