Gtk.ScrolledWindow¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`get_child` ()
	`get_hadjustment` ()
	`get_has_frame` ()
	`get_hscrollbar` ()
	`get_kinetic_scrolling` ()
	`get_max_content_height` ()
	`get_max_content_width` ()
	`get_min_content_height` ()
	`get_min_content_width` ()
	`get_overlay_scrolling` ()
	`get_placement` ()
	`get_policy` ()
	`get_propagate_natural_height` ()
	`get_propagate_natural_width` ()
	`get_vadjustment` ()
	`get_vscrollbar` ()
	`set_child` (child)
	`set_hadjustment` (hadjustment)
	`set_has_frame` (has_frame)
	`set_kinetic_scrolling` (kinetic_scrolling)
	`set_max_content_height` (height)
	`set_max_content_width` (width)
	`set_min_content_height` (height)
	`set_min_content_width` (width)
	`set_overlay_scrolling` (overlay_scrolling)
	`set_placement` (window_placement)
	`set_policy` (hscrollbar_policy, vscrollbar_policy)
	`set_propagate_natural_height` (propagate)
	`set_propagate_natural_width` (propagate)
	`set_vadjustment` (vadjustment)
	`unset_placement` ()

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`child`	`Gtk.Widget`	r/w/en
`hadjustment`	`Gtk.Adjustment`	r/w/c/en
`has-frame`	`bool`	r/w/en
`hscrollbar-policy`	`Gtk.PolicyType`	r/w/en
`kinetic-scrolling`	`bool`	r/w/en
`max-content-height`	`int`	r/w/en
`max-content-width`	`int`	r/w/en
`min-content-height`	`int`	r/w/en
`min-content-width`	`int`	r/w/en
`overlay-scrolling`	`bool`	r/w/en
`propagate-natural-height`	`bool`	r/w/en
`propagate-natural-width`	`bool`	r/w/en
`vadjustment`	`Gtk.Adjustment`	r/w/c/en
`vscrollbar-policy`	`Gtk.PolicyType`	r/w/en
`window-placement`	`Gtk.CornerType`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`edge-overshot`	Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation.
`edge-reached`	Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation.
`move-focus-out`	Emitted when focus is moved away from the scrolled window by a keybinding.
`scroll-child`	Emitted when a keybinding that scrolls is pressed.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.ScrolledWindow(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No

GtkScrolledWindow is a container that makes its child scrollable.

It does so using either internally added scrollbars or externally associated adjustments, and optionally draws a frame around the child.

Widgets with native scrolling support, i.e. those whose classes implement the [iface`Gtk`.Scrollable] interface, are added directly. For other types of widget, the class [class`Gtk`.Viewport] acts as an adaptor, giving scrollability to other widgets. [method`Gtk`.ScrolledWindow.set_child] intelligently accounts for whether or not the added child is a GtkScrollable. If it isn’t, then it wraps the child in a GtkViewport. Therefore, you can just add any child widget and not worry about the details.

If [method`Gtk`.ScrolledWindow.set_child] has added a GtkViewport for you, it will be automatically removed when you unset the child. Unless [property`Gtk`.ScrolledWindow:hscrollbar-policy] and [property`Gtk`.ScrolledWindow:vscrollbar-policy] are Gtk.PolicyType.NEVER or Gtk.PolicyType.EXTERNAL, GtkScrolledWindow adds internal GtkScrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the [property`Gtk`.ScrolledWindow:hadjustment] and [property`Gtk`.ScrolledWindow:vadjustment] that are associated with the GtkScrolledWindow. See the docs on [class`Gtk`.Scrollbar] for the details, but note that the “step_increment” and “page_increment” fields are only effective if the policy causes scrollbars to be present.

If a GtkScrolledWindow 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 GtkScrollbar and for example a GtkGrid.

Touch support

GtkScrolledWindow has built-in support for touch devices. When a touchscreen is used, swiping will move the scrolled window, and will expose ‘kinetic’ behavior. This can be turned off with the [property`Gtk`.ScrolledWindow:kinetic-scrolling] property if it is undesired.

GtkScrolledWindow also displays visual ‘overshoot’ indication when the content is pulled beyond the end, and this situation can be captured with the [signal`Gtk`.ScrolledWindow::edge-overshot] signal.

If no mouse device is present, the scrollbars will overlaid as narrow, auto-hiding indicators over the content. If traditional scrollbars are desired although no mouse is present, this behaviour can be turned off with the [property`Gtk`.ScrolledWindow:overlay-scrolling] property.

CSS nodes

GtkScrolledWindow has a main CSS node with name scrolledwindow. It gets a .frame style class added when [property`Gtk`.ScrolledWindow:has-frame] is True.

It uses subnodes with names overshoot and undershoot to draw the overflow and underflow indications. These nodes get the .left, .right, .top or .bottom style class added depending on where the indication is drawn.

GtkScrolledWindow also sets the positional style classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering) on its scrollbars.

If both scrollbars are visible, the area where they meet is drawn with a subnode named junction.

Accessibility

Until GTK 4.10, GtkScrolledWindow used the GTK_ACCESSIBLE_ROLE_GROUP role.

Starting from GTK 4.12, GtkScrolledWindow uses the GTK_ACCESSIBLE_ROLE_GENERIC role.

classmethod new()[source]¶

Returns:: a new scrolled window
Return type:: Gtk.Widget

Creates a new scrolled window.

get_child()[source]¶

Returns:: the child widget of self
Return type:: Gtk.Widget or None

Gets the child widget of self.

If the scrolled window automatically added a [class`Gtk`.Viewport], this function will return the viewport widget, and you can retrieve its child using [method`Gtk`.Viewport.get_child].

get_hadjustment()[source]¶

Returns:: the horizontal GtkAdjustment
Return type:: Gtk.Adjustment

Returns the horizontal scrollbar’s adjustment.

This is the adjustment used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality.

get_has_frame()[source]¶

Returns:: True if the self has a frame
Return type:: bool

Gets whether the scrolled window draws a frame.

get_hscrollbar()[source]¶

Returns:: the horizontal scrollbar of the scrolled window.
Return type:: Gtk.Widget

Returns the horizontal scrollbar of self.

get_kinetic_scrolling()[source]¶

Returns:: the scrolling behavior flags.
Return type:: bool

Returns the specified kinetic scrolling behavior.

get_max_content_height()[source]¶

Returns:: the maximum content height, or -1
Return type:: int

Returns the maximum content height set.

get_max_content_width()[source]¶

Returns:: the maximum content width, or -1
Return type:: int

Returns the maximum content width set.

get_min_content_height()[source]¶

Returns:: the minimal content height
Return type:: int

Gets the minimal content height of self.

get_min_content_width()[source]¶

Returns:: the minimum content width
Return type:: int

Gets the minimum content width of self.

get_overlay_scrolling()[source]¶

Returns:: True if overlay scrolling is enabled
Return type:: bool

Returns whether overlay scrolling is enabled for this scrolled window.

get_placement()[source]¶

Returns:: the current placement value.
Return type:: Gtk.CornerType

Gets the placement of the contents with respect to the scrollbars.

get_policy()[source]¶

Returns:

hscrollbar_policy:: location to store the policy for the horizontal scrollbar
vscrollbar_policy:: location to store the policy for the vertical scrollbar

Return type:

(hscrollbar_policy: Gtk.PolicyType, vscrollbar_policy: Gtk.PolicyType)

Retrieves the current policy values for the horizontal and vertical scrollbars.

See [method`Gtk`.ScrolledWindow.set_policy].

get_propagate_natural_height()[source]¶

Returns:: whether natural height propagation is enabled.
Return type:: bool

Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height.

get_propagate_natural_width()[source]¶

Returns:: whether natural width propagation is enabled.
Return type:: bool

Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width.

get_vadjustment()[source]¶

Returns:: the vertical GtkAdjustment
Return type:: Gtk.Adjustment

Returns the vertical scrollbar’s adjustment.

This is the adjustment used to connect the vertical scrollbar to the child widget’s vertical scroll functionality.

get_vscrollbar()[source]¶

Returns:: the vertical scrollbar of the scrolled window.
Return type:: Gtk.Widget

Returns the vertical scrollbar of self.

set_child(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child widget of self.

If child does not implement the [iface`Gtk`.Scrollable] interface, the scrolled window will add child to a [class`Gtk`.Viewport] instance and then add the viewport as its child widget.

set_hadjustment(hadjustment)[source]¶

Parameters:: hadjustment (Gtk.Adjustment or None) – the GtkAdjustment to use, or None to create a new one

Sets the GtkAdjustment for the horizontal scrollbar.

set_has_frame(has_frame)[source]¶

Parameters:: has_frame (bool) – whether to draw a frame around scrolled window contents

Changes the frame drawn around the contents of self.

set_kinetic_scrolling(kinetic_scrolling)[source]¶

Parameters:: kinetic_scrolling (bool) – True to enable kinetic scrolling

Turns kinetic scrolling on or off.

Kinetic scrolling only applies to devices with source Gdk.InputSource.TOUCHSCREEN.

set_max_content_height(height)[source]¶

Parameters:: height (int) – the maximum content height

Sets the maximum height that self should keep visible.

The self will grow up to this height before it starts scrolling the content.

It is a programming error to set the maximum content height to a value smaller than [property`Gtk`.ScrolledWindow:min-content-height].

set_max_content_width(width)[source]¶

Parameters:: width (int) – the maximum content width

Sets the maximum width that self should keep visible.

The self will grow up to this width before it starts scrolling the content.

It is a programming error to set the maximum content width to a value smaller than [property`Gtk`.ScrolledWindow:min-content-width].

set_min_content_height(height)[source]¶

Parameters:: height (int) – the minimal content height

Sets the minimum height that self should keep visible.

Note that this can and (usually will) be smaller than the minimum size of the content.

It is a programming error to set the minimum content height to a value greater than [property`Gtk`.ScrolledWindow:max-content-height].

set_min_content_width(width)[source]¶

Parameters:: width (int) – the minimal content width

Sets the minimum width that self should keep visible.

Note that this can and (usually will) be smaller than the minimum size of the content.

It is a programming error to set the minimum content width to a value greater than [property`Gtk`.ScrolledWindow:max-content-width].

set_overlay_scrolling(overlay_scrolling)[source]¶

Parameters:: overlay_scrolling (bool) – whether to enable overlay scrolling

Enables or disables overlay scrolling for this scrolled window.

set_placement(window_placement)[source]¶

Parameters:: window_placement (Gtk.CornerType) – position of the child window

Sets the placement of the contents with respect to the scrollbars for the scrolled window.

The default is Gtk.CornerType.TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in [enum`Gtk`.CornerType] are Gtk.CornerType.TOP_RIGHT, Gtk.CornerType.BOTTOM_LEFT, and Gtk.CornerType.BOTTOM_RIGHT.

See also [method`Gtk`.ScrolledWindow.get_placement] and [method`Gtk`.ScrolledWindow.unset_placement].

set_policy(hscrollbar_policy, vscrollbar_policy)[source]¶

Parameters:

hscrollbar_policy (Gtk.PolicyType) – policy for horizontal bar
vscrollbar_policy (Gtk.PolicyType) – policy for vertical bar

Sets the scrollbar policy for the horizontal and vertical scrollbars.

The policy determines when the scrollbar should appear; it is a value from the [enum`Gtk`.PolicyType] enumeration. If Gtk.PolicyType.ALWAYS, the scrollbar is always present; if Gtk.PolicyType.NEVER, the scrollbar is never present; if Gtk.PolicyType.AUTOMATIC, the scrollbar is present only if needed (that is, if the slider part of the bar would be smaller than the trough — the display is larger than the page size).

set_propagate_natural_height(propagate)[source]¶

Parameters:: propagate (bool) – whether to propagate natural height

Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height.

set_propagate_natural_width(propagate)[source]¶

Parameters:: propagate (bool) – whether to propagate natural width

Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width.

set_vadjustment(vadjustment)[source]¶

Parameters:: vadjustment (Gtk.Adjustment or None) – the GtkAdjustment to use, or None to create a new one

Sets the GtkAdjustment for the vertical scrollbar.

unset_placement()[source]¶

Unsets the placement of the contents with respect to the scrollbars.

If no window placement is set for a scrolled window, it defaults to Gtk.CornerType.TOP_LEFT.

Signal Details¶

Gtk.ScrolledWindow.signals.edge_overshot(scrolled_window, pos)¶

Signal Name:

edge-overshot

Flags:

RUN_LAST

Parameters:

scrolled_window (Gtk.ScrolledWindow) – The object which received the signal
pos (Gtk.PositionType) – edge side that was hit

Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation.

A similar behavior without edge resistance is provided by the [signal`Gtk`.ScrolledWindow::edge-reached] signal.

Note: The pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges.

Gtk.ScrolledWindow.signals.edge_reached(scrolled_window, pos)¶

Signal Name:

edge-reached

Flags:

RUN_LAST

Parameters:

scrolled_window (Gtk.ScrolledWindow) – The object which received the signal
pos (Gtk.PositionType) – edge side that was reached

Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation.

A similar behavior with edge resistance is provided by the [signal`Gtk`.ScrolledWindow::edge-overshot] signal.

Note: The pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges.

Gtk.ScrolledWindow.signals.move_focus_out(scrolled_window, direction_type)¶

Signal Name:

move-focus-out

Flags:

RUN_LAST, ACTION

Parameters:

scrolled_window (Gtk.ScrolledWindow) – The object which received the signal
direction_type (Gtk.DirectionType) – either Gtk.DirectionType.TAB_FORWARD or Gtk.DirectionType.TAB_BACKWARD

Emitted when focus is moved away from the scrolled window by a keybinding.

This is a keybinding signal.

The default bindings for this signal are Ctrl + Tab to move forward and Ctrl + Shift + Tab to move backward.

Gtk.ScrolledWindow.signals.scroll_child(scrolled_window, scroll, horizontal)¶

Signal Name:

scroll-child

Flags:

RUN_LAST, ACTION

Parameters:

scrolled_window (Gtk.ScrolledWindow) – The object which received the signal
scroll (Gtk.ScrollType) – a GtkScrollType describing how much to scroll
horizontal (bool) – whether the keybinding scrolls the child horizontally or not

Return type:

bool

Emitted when a keybinding that scrolls is pressed.

This is a keybinding signal.

The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself.

Property Details¶

Gtk.ScrolledWindow.props.child¶

Name:: child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

When setting this property, if the child widget does not implement [iface`Gtk`.Scrollable], the scrolled window will add the child to a [class`Gtk`.Viewport] and then set the viewport as the child.

Gtk.ScrolledWindow.props.hadjustment¶

Name:: hadjustment
Type:: Gtk.Adjustment
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Gtk.ScrolledWindow.props.has_frame¶

Name:: has-frame
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to draw a frame around the contents.

Gtk.ScrolledWindow.props.hscrollbar_policy¶

Name:: hscrollbar-policy
Type:: Gtk.PolicyType
Default Value:: Gtk.PolicyType.AUTOMATIC
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

When the horizontal scrollbar is displayed.

Use [method`Gtk`.ScrolledWindow.set_policy] to set this property.

Gtk.ScrolledWindow.props.kinetic_scrolling¶

Name:: kinetic-scrolling
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether kinetic scrolling is enabled or not.

Kinetic scrolling only applies to devices with source Gdk.InputSource.TOUCHSCREEN.

Gtk.ScrolledWindow.props.max_content_height¶

Name:: max-content-height
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The maximum content height of scrolled_window.

Gtk.ScrolledWindow.props.max_content_width¶

Name:: max-content-width
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The maximum content width of scrolled_window.

Gtk.ScrolledWindow.props.min_content_height¶

Name:: min-content-height
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The minimum content height of scrolled_window.

Gtk.ScrolledWindow.props.min_content_width¶

Name:: min-content-width
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The minimum content width of scrolled_window.

Gtk.ScrolledWindow.props.overlay_scrolling¶

Name:: overlay-scrolling
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether overlay scrolling is enabled or not.

If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlaid on top of the content, as narrow indicators.

Note that overlay scrolling can also be globally disabled, with the [property`Gtk`.Settings:gtk-overlay-scrolling] setting.

Gtk.ScrolledWindow.props.propagate_natural_height¶

Name:: propagate-natural-height
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height.

This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child.

Gtk.ScrolledWindow.props.propagate_natural_width¶

Name:: propagate-natural-width
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width.

This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child.

Gtk.ScrolledWindow.props.vadjustment¶

Name:: vadjustment
Type:: Gtk.Adjustment
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Gtk.ScrolledWindow.props.vscrollbar_policy¶

Name:: vscrollbar-policy
Type:: Gtk.PolicyType
Default Value:: Gtk.PolicyType.AUTOMATIC
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

When the vertical scrollbar is displayed.

Use [method`Gtk`.ScrolledWindow.set_policy] to set this property.

Gtk.ScrolledWindow.props.window_placement¶

Name:: window-placement
Type:: Gtk.CornerType
Default Value:: Gtk.CornerType.TOP_LEFT
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Where the contents are located with respect to the scrollbars.