gtk.ScrolledWindow

gtk.ScrolledWindow
Prev	The gtk Class Reference	Next

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

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.

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