gtk.ScrolledWindow
Prev | The gtk Class Reference | Next

## gtk.ScrolledWindow

gtk.ScrolledWindow — adds scrollbars to its child widget.

## Synopsis

    class gtk.ScrolledWindow(gtk.Bin):
        gtk.ScrolledWindow(hadjustment=None, vadjustment=None)
        def set_hadjustment(hadjustment)
        def set_vadjustment(vadjustment)
        def get_hadjustment()
        def get_vadjustment()
        def get_hscrollbar()
        def get_vscrollbar()
        def set_policy(hscrollbar_policy, vscrollbar_policy)
        def get_policy(hscrollbar_policy, vscrollbar_policy)
        def set_placement(window_placement)
        def get_placement()
        def set_shadow_type(type)
        def get_shadow_type()
        def add_with_viewport(child)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.ScrolledWindow

## Implemented Interfaces

`gtk.ScrolledWindow` implements `gtk.Buildable`

## gtk.ScrolledWindow Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"hadjustment" | Read-Write-Construct | The `gtk.Adjustment` for the horizontal position.
hscrollbar-policy"" | Read-Write | The horizontal scrollbar display policy; one of: `gtk.POLICY_ALWAYS`, `gtk.POLICY_AUTOMATIC` or `gtk.POLICY_NEVER`.
"shadow-type" | Read-Write | The style of bevel around the contents; one of: `gtk.SHADOW_NONE`, `gtk.SHADOW_IN`, `gtk.SHADOW_OUT`, `gtk.SHADOW_ETCHED_IN`, `gtk.SHADOW_ETCHED_OUT`.
"vadjustment" | Read-Write-Construct | The `gtk.Adjustment` for the vertical position.
"vscrollbar-policy" | Read-Write | The vertical scrollbar display policy; one of: `gtk.POLICY_ALWAYS`, `gtk.POLICY_AUTOMATIC` or `gtk.POLICY_NEVER`.
"window-placement" | Read-Write | Where the contents are located with respect to the scrollbars; one of: `gtk.CORNER_TOP_LEFT`, `gtk.CORNER_BOTTOM_LEFT`, `gtk.CORNER_TOP_RIGHT`, `gtk.CORNER_BOTTOM_RIGHT`.
"window-placement-set" | Read-Write | If `True` "window-placement" should be used to determine the location of the contents with respect to the scrollbars.

## gtk.ScrolledWindow Style Properties

gtk.Widget Style Properties

"scrollbar-spacing" | Read | The number of pixels between the scrollbars and the scrolled window. Available in `GTK+` 2.2 and above.
"scrollbar-within-bevel" | Read | Whether to place scrollbars within the scrolled window's bevel. Default value: `False` Available in `GTK+` 2.12 and above.

## gtk.ScrolledWindow Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"move-focus-out" | `def callback(`scrolledwindow`, `direction`, `user_param1`, `...`)`
"scroll-child" | `def callback(`scrolledwindow`, `scrolltype`, `horizontal`, `user_param1`, `...`)`

## Description

A `gtk.ScrolledWindow` is a subclass of `gtk.Bin` that adds scrollbars to a single child widget and optionally draws a beveled frame around the child widget. The scrolled window can work in two ways:

- Some widgets have native scrolling support using "slots" to hold `gtk.Adjustment` objects. Widgets with native scroll support include `gtk.TreeView`, `gtk.TextView`, and `gtk.Layout`.
- Widgets that lack native scrolling support use the `gtk.Viewport` widget that acts as an adapter class, implementing scrollability for child widgets that lack their own scrolling capabilities. Use `gtk.Viewport` to scroll child widgets such as `gtk.Table`, `gtk.Box`, and so on.

If a widget has native scrolling abilities, it can be added to the `gtk.ScrolledWindow` with the `gtk.Container.add`() method. If a widget does not, you must first add the widget to a `gtk.Viewport`, then add the `gtk.Viewport` to the scrolled window. The convenience method `add_with_viewport`() does exactly this, so you can ignore the presence of the viewport.

The position of the scrollbars is controlled by the scroll adjustments. The `gtk.ScrolledWindow` uses the attributes in an adjustment (see `gtk.Adjustment`) as follows:

- the `adjustment.lower` attribute is the minimum value of the scroll region
- the `adjustment.upper` attribute is the maximum value of the scroll region
- the `adjustment.value` attribute represents the position of the scrollbar, which must be between `adjustment.lower` and `adjustment.upper` - `adjustment.page_size`
- the `adjustment.page_size` attribute represents the size of the visible scrollable area
- the `adjustment.step_increment` attribute is the distance to scroll when the small stepper arrows are clicked
- the `adjustment.page_increment` attribute is the distance to scroll when the Page Up or Page Down keys are pressed

If a `gtk.ScrolledWindow` doesn't behave quite as you would like, or doesn't have exactly the right layout, it's very possible to set up your own scrolling with `gtk.Scrollbar` and for example a `gtk.Table`.

## Constructor

        gtk.ScrolledWindow(hadjustment=None, vadjustment=None)

`hadjustment` : | the horizontal `gtk.Adjustment` or None
`vadjustment` : | a vertical `gtk.Adjustment` or None
Returns : | a new `gtk.ScrolledWindow` widget

Creates a new scrolled window with the horizontal and vertical `gtk.Adjustment` specified by `hadjustment` and `vadjustment` respectively. These will be shared with the scrollbars and the child widget to keep the bars in sync with the child. If `hadjustment` and `vadjustment` are `None` or not specified the scrolled window will create them for you.

## Methods

### gtk.ScrolledWindow.set_hadjustment

        def set_hadjustment(hadjustment)

`hadjustment` : | the horizontal `gtk.Adjustment`

The `set_hadjustment`() method sets the horizontal adjustment (and the "hadjustment" property) to the value of `hadjustment`. `hadjustment` must be a `gtk.Adjustment`.

### gtk.ScrolledWindow.set_vadjustment

        def set_vadjustment(vadjustment)

`vadjustment` : | the vertical `gtk.Adjustment`

The `set_vadjustment`() method sets the vertical adjustment (and the "vadjustment" property) to the value of `vadjustment`. `vadjustment` must be a `gtk.Adjustment`.

### gtk.ScrolledWindow.get_hadjustment

        def get_hadjustment()

Returns : | the horizontal `gtk.Adjustment`

The `get_hadjustment`() method returns the value of the "hadjustment" property which is a reference to the horizontal adjustment.

### gtk.ScrolledWindow.get_vadjustment

        def get_vadjustment()

Returns : | the vertical `gtk.Adjustment`

The `get_vadjustment`() method returns the value of the "vadjustment" property which is a reference to the vertical adjustment.

### gtk.ScrolledWindow.get_hscrollbar

        def get_hscrollbar()

Returns : | The horizontal scrollbar of the scrolled window or `None` if it does not exist.

### Note

This method is available in PyGTK 2.8 and above.

The `get_hscrollbar`() method returns the `gtk.HScrollbar` for the scrolled window or `None` if there is no horizontal scrollbar.

### gtk.ScrolledWindow.get_vscrollbar

        def get_vscrollbar()

Returns : | The vertical scrollbar of the scrolled window or `None` if it does not exist.

### Note

This method is available in PyGTK 2.8 and above.

The `get_vscrollbar`() method returns the `gtk.VScrollbar` for the scrolled window or `None` if there is no vertical scrollbar.

### gtk.ScrolledWindow.set_policy

        def set_policy(hscrollbar_policy, vscrollbar_policy)

`hscrollbar_policy` : | the policy for the horizontal scrollbar
`vscrollbar_policy` : | the policy for the vertical scrollbar

The `set_policy`() method sets the "hscrollbar_policy" and "vscrollbar_policy" properties to the value of `hscrollbar_policy` and `vscrollbar_policy` respectively. The policy determines when the scrollbar should be displayed. The policy value is one of:

gtk.POLICY_ALWAYS | the scrollbar is always present
gtk.POLICY_AUTOMATIC | the scrollbar is present only if needed i.e. the contents are larget than the window
gtk.POLICY_NEVER | the scrollbar is never present

### gtk.ScrolledWindow.get_policy

        def get_policy()

Returns> : | a tuple containing the horizontal and vertical scrollbar policies

The `get_policy`() method returns a tuple containing the horizontal and vertical scrollbar policies. See the `set_policy`() method for more detail.

### gtk.ScrolledWindow.set_placement

        def set_placement(window_placement)

`window_placement` : | the placement of the contents with respect to the scrollbars

The `set_placement`() method sets the "window-placement" property to the value specified by `window_placement`. The window placement determines the location of the child widget with respect to the scrollbars. `window_placement` must be one of:

gtk.CORNER_TOP_LEFT | Place the scrollbars on the right and bottom of the widget (default behavior).
gtk.CORNER_BOTTOM_LEFT | Place the scrollbars on the top and right of the widget.
gtk.CORNER_TOP_RIGHT | Place the scrollbars on the left and bottom of the widget.
gtk.CORNER_BOTTOM_RIGHT | Place the scrollbars on the top and left of the widget.

### gtk.ScrolledWindow.get_placement

        def get_placement()

Returns : | the current placement value.

The `get_placement`() method returns the value of the "window-placement" property that determines the placement of the scrollbars with respect to the scrolled window. See the `set_placement`() method for more detail.

### gtk.ScrolledWindow.set_shadow_type

        def set_shadow_type(type)

`type` : | the kind of bevel shadow to draw around the scrolled window contents

The `set_shadow_type`() method sets the value of the "shadow-type" property to the value of `shadow_type`. `shadow_type` determines the type of bevel shadow drawn around the contents of the scrolled window. The shadow type must be one of:

gtk.SHADOW_NONE | No outline.
gtk.SHADOW_IN | The outline is beveled inward.
gtk.SHADOW_OUT | The outline is beveled outward.
gtk.SHADOW_ETCHED_IN | The outline is an inward etched bevel.
gtk.SHADOW_ETCHED_OUT | The outline is an outward etched bevel.

### gtk.ScrolledWindow.get_shadow_type

        def get_shadow_type()

Returns : | the current shadow type

The `get_shadow_type`() method returns the value of the "shadow-type" property that determines the shadow type of the scrolled window. See the `set_shadow_type`() method for more detail.

### gtk.ScrolledWindow.add_with_viewport

        def add_with_viewport(child)

`child` : | the widget to be scrolled

The `add_with_viewport`() method is used to add a widget (specified by `child`) without native scrolling capabilities to the scrolled window. This is a convenience function that is equivalent to adding `child` to a `gtk.Viewport`, then adding the viewport to the scrolled window. If a child has native scrolling (e.g. `gtk.TextView`, `gtk.TreeView`, `gtk.Layout`), use `gtk.Container.add`() instead of this method.

The viewport scrolls the child by moving its `gtk.gdk.Window`, and takes the size of the child to be the size of its toplevel `gtk.gdk.Window`. This will be wrong for most widgets that support native scrolling. For example, if you add a widget such as `gtk.TreeView` with a viewport, the whole widget will scroll, including the column headings.

## Signals

### The "move-focus-out" gtk.ScrolledWindow Signal

        def callback(scrolledwindow, direction, user_param1, ...)

`scrolledwindow` : | the scrolledwindow that received the signal
`direction` : | the direction that the focus is moving either `gtk.DIR_TAB_FORWARD` or `gtk.DIR_TAB_BACKWARD`.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "move-focus-out" signal is emitted when the user presses Control+Tab or Control+Shift+Tab to move the focus out of the scrolled window. The `direction` is either `gtk.DIR_TAB_FORWARD` or `gtk.DIR_TAB_BACKWARD`

### The "scroll-child" gtk.ScrolledWindow Signal

        def callback(scrolledwindow, scrolltype, horizontal, user_param1, ...)

`scrolledwindow` : | the scrolledwindow that received the signal
`scrolltype` : | the scroll type; one of: `gtk.SCROLL_STEP_BACKWARD`, `gtk.SCROLL_STEP_FORWARD`, `gtk.SCROLL_PAGE_BACKWARD`, `gtk.SCROLL_PAGE_FORWARD`, `gtk.SCROLL_PAGE_UP`, `gtk.SCROLL_PAGE_DOWN`, `gtk.SCROLL_START` or `gtk.SCROLL_END`.
`horizontal` : | if True scroll in the horizontal direction
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "scroll-child" signal is emitted when the child widget is being scrolled by a keyboard action. The default key bindings with resulting `scrolltype` and `horizontal` arguments are:

Control+Left Arrow | `gtk.SCROLL_STEP_BACKWARD` - horizontal
Control+Right Arrow | `gtk.SCROLL_STEP_FORWARD` - horizontal
Control+Up Arrow | `gtk.SCROLL_STEP_BACKWARD` - vertical
Control+Down Arrow | `gtk.SCROLL_STEP_FORWARD` - vertical
Control+Page Up | `gtk.SCROLL_PAGE_BACKWARD` - horizontal
Control+Page Down | `gtk.SCROLL_PAGE_FORWARD` - horizontal
Page Up | `gtk.SCROLL_PAGE_BACKWARD` - vertical
Page Down | `gtk.SCROLL_PAGE_FORWARD` - vertical
Control+Home | `gtk.SCROLL_START` - horizontal
Control+End | `gtk.SCROLL_END` - horizontal
Home | `gtk.SCROLL_START` - vertical
End | `gtk.SCROLL_END` - vertical

Prev | Up | Next
gtk.Scrollbar | Home | gtk.SelectionData