gtk.Adjustment
Prev | The gtk Class Reference | Next

## gtk.Adjustment

gtk.Adjustment — an object representing an adjustable bounded value

## Synopsis

    class gtk.Adjustment(gtk.Object):
        gtk.Adjustment(value=0, lower=0, upper=0, step_incr=0, page_incr=0, page_size=0)
        def set_all(value, lower, upper, step_increment, page_increment, page_size)
        def changed()
        def value_changed()
        def clamp_page(lower, upper)
        def get_value()
        def set_value(value)
        def configure(value, lower, upper, step_increment, page_increment, page_size)
        def get_lower()
        def set_lower(lower)
        def get_page_increment()
        def set_page_increment(page_increment)
        def get_page_size()
        def set_page_size(page_size)
        def get_step_increment()
        def set_step_increment(step_increment)
        def get_upper()
        def set_upper(upper)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Adjustment

## gtk.Adjustment Properties

gtk.Object Properties

### Note

These properties are available in GTK+ 2.4 and above. The GTK+ version is contained in the 3-tuple gtk.gtk_version.

"lower" | Read-Write | The minimum value of the adjustment. (float)
"page-increment" | Read-Write | The page increment of the adjustment. (float)
"page-size" | Read-Write | The page size of the adjustment. (float)
"step-increment" | Read-Write | The step increment of the adjustment. (float)
"upper" | Read-Write | The maximum value of the adjustment. (float)
"value" | Read-Write | The value of the adjustment. (float)

## Attributes

"value" | Read-Write | the current value (float)
"lower" | Read-Write | the minimum value (float)
"upper" | Read-Write | the maximum value (float)
"step_increment" | Read-Write | the increment to use to make minor changes to the value. In a `gtk.Scrollbar` this increment is used when the mouse is clicked on the arrows at the top and bottom of the scrollbar, to scroll by a small amount. (float)
"page_increment" | Read-Write | the increment to use to make major changes to the value. In a `gtk.Scrollbar` this increment is used when the mouse is clicked in the trough, to scroll by a large amount. (float)
"page_size" | Read-Write | a widget specific size. In a `gtk.Scrollbar` this is the size of the area which is currently visible. (float)

## gtk.Adjustment Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

"changed" | `def callback(`adjustment`, `user_param1`, `...`)`
"value-changed" | `def callback(`adjustment`, `user_param1`, `...`)`

## Description

The `gtk.Adjustment` object contains a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used in conjunction with several PyGTK widgets, including `gtk.SpinButton`, `gtk.Viewport`, and `gtk.Range` (which is a base class for `gtk.HScrollbar`, `gtk.VScrollbar`, `gtk.HScale`, and `gtk.VScale`).

A `gtk.Adjustment` can be shared by multiple widgets. The `gtk.Adjustment` object does not update the value itself. Instead it is left up to the associated widget(s) that use the `gtk.Adjustment` to control the value.

The widget using the `gtk.Adjustment` typically calls the `value_changed`() or `changed`() methods after changing the value or its bounds. This results in the emission of the "value_changed" or "changed" signal respectively.

A `gtk.Adjustment` object contains several attributes that provide access to its value and bounds:

- value
- lower
- upper
- step_increment
- page_increment
- page_size

The attribute values can be retrieved and set similar to:

      adjustment.upper = 25.0
      lower = adjustment.lower

## Constructor

        gtk.Adjustment(value=0, lower=0, upper=0, step_incr=0, page_incr=0, page_size=0)

`value` : | the initial value.
`lower` : | the minimum value.
`upper` : | the maximum value.
`step_incr` : | the step increment.
`page_incr` : | the page increment.
`page_size` : | the page size.
Returns : | a new gtk.Adjustment object

`gtk.Adjustment`() creates a new `gtk.Adjustment` object with the specified attributes. Any attributes not specified are set to 0.0 by default.

## Methods

### gtk.Adjustment.set_all

        def set_all(value, lower, upper, step_increment, page_increment, page_size)

`value` : | the new value.
`lower` : | the new minimum value.
`upper` : | the new maximum value.
`step_increment` : | the new step increment.
`page_increment` : | the new page increment.
`page_size` : | the new page size.

The `set_all`() method sets the attributes of the adjustment to the specified values.

### gtk.Adjustment.changed

        def changed()

The `changed`() method emits a "changed" signal from the adjustment. This must typically be called if any of the adjustment attributes other than value has changed so that the widget(s) using the adjustment can reflect the changes. Applications usually will not need to use this method since setting the attributes directly will automatically invoke this method.

### gtk.Adjustment.value_changed

        def value_changed()

The `value_changed`() method emits a "value_changed" signal from the adjustment. This must typically be called after the value attribute of the adjustment has changed. Applications usually will not need to use this method since setting the attribute directly will automatically invoke this method as will using the `set_value`() method.

### gtk.Adjustment.clamp_page

        def clamp_page(lower, upper)

`lower` : | the lower value
`upper` : | the upper value

The `clamp_page`() method updates the adjustment value to ensure that the range between `lower` and `upper` is in the current page (i.e. between value and value + page_size). If the range is larger than the page size, then only the start of it will be in the current page. A "changed" signal will be emitted if the value is changed.

### gtk.Adjustment.get_value

        def get_value()

Returns : | The current value of the adjustment.

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

### gtk.Adjustment.set_value

        def set_value(value)

`value` : | the new value

The `set_value`() method sets the value of the adjustment to the specified `value`.

### gtk.Adjustment.configure

        def configure(value, lower, upper, step_increment, page_increment, page_size)

`value` : | the new value.
`lower` : | the new minimum value.
`upper` : | the new maximum value.
`step_increment` : | the new step increment.
`page_increment` : | the new page increment.
`page_size` : | the new page size.

### Note

This method is available in PyGTK 2.14 and above.

The `configure`() method sets all properties of the adjustment at once.

This method is an alternative to avoid multiple emissions of the "changed" signal. When setting multiple adjustment properties via their individual setters, multiple "changed" signals will be emitted. However, since the emission of the "changed" signal is tied to the emission of the "GObject::notify" signals of the changed properties, it's possible to compress the "changed" signals into one by calling `gobject.Gobject.freeze_notify`() and `gobject.Gobject.thaw_notify`() around the calls to the individual setters.

### gtk.Adjustment.get_lower

        def get_lower()

Returns : | The current minimum value of the adjustment.

### Note

This method is available in PyGTK 2.14 and above.

The `get_lower`() method gets the current minimum value of the adjustment.

### gtk.Adjustment.set_lower

        def set_lower(lower)

`lower` : | the new minimum value

### Note

This method is available in PyGTK 2.14 and above.

The `set_lower`() method sets the minimum value of the adjustment.

When setting multiple adjustment properties via their individual setters, multiple "changed" signals will be emitted. However, since the emission of the "changed" signal is tied to the emission of the "GObject::notify" signals of the changed properties, it's possible to compress the "changed" signals into one by calling gobject.Gobject.freeze_notify() and gobject.Gobject.thaw_notify() around the calls to the individual setters.

Alternatively, using gtk.Adjustment.configure() has the same effect of compressing "changed" emissions.

### gtk.Adjustment.get_page_increment

        def get_page_increment()

Returns : | The current page increment of the adjustment.

### Note

This method is available in PyGTK 2.14 and above.

The `get_page_increment`() method gets the current page increment of the adjustment.

### gtk.Adjustment.set_page_increment

        def set_page_increment(page_increment)

`page_increment` : | the new page increment value

### Note

This method is available in PyGTK 2.14 and above.

The `set_page_increment`() method sets the page increment of the adjustment.

See gtk.Adjustment.get_lower() about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.

### gtk.Adjustment.get_page_size

        def get_page_size()

Returns : | The current page size of the adjustment.

### Note

This method is available in PyGTK 2.14 and above.

The `get_page_size`() method gets the current page size of the adjustment.

### gtk.Adjustment.set_page_size

        def set_page_size(page_size)

`page_size` : | the new page size value

### Note

This method is available in PyGTK 2.14 and above.

The `set_page_size`() method sets the page size of the adjustment.

See gtk.Adjustment.get_lower() about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.

### gtk.Adjustment.get_step_increment

        def get_step_increment()

Returns : | The current step increment of the adjustment.

### Note

This method is available in PyGTK 2.14 and above.

The `get_step_increment`() method gets the current step increment of the adjustment.

### gtk.Adjustment.set_step_increment

        def set_step_increment(step_increment)

`step_increment` : | the new step increment value

### Note

This method is available in PyGTK 2.14 and above.

The `set_step_increment`() method sets the step increment of the adjustment.

See gtk.Adjustment.get_lower() about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.

### gtk.Adjustment.get_upper

        def get_upper()

Returns : | The current minimum value of the adjustment.

### Note

This method is available in PyGTK 2.14 and above.

The `get_upper`() method gets the current minimum value of the adjustment.

### gtk.Adjustment.set_upper

        def set_upper(upper)

`upper` : | the new maximum value

### Note

This method is available in PyGTK 2.14 and above.

The `set_upper`() method sets the maximum value of the adjustment.

Note that values will be restricted by upper - page-size if the page-size property is nonzero.

See gtk.Adjustment.get_lower() about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.

## Signals

### The "changed" gtk.Adjustment Signal

        def callback(adjustment, user_param1, ...)

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

The "changed" signal is emitted when one (or more) of the adjustment attributes (except the value attribute) has changed.

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

        def callback(adjustment, user_param1, ...)

`adjustment` : | the object 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 adjustment value attribute has changed.

Prev | Up | Next
gtk.Activatable | Home | gtk.Alignment