ScrolledWindow
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, Buildable
, ConstraintTarget
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 Scrollable
interface, are added directly. For other types
of widget, the class Viewport
acts as an adaptor, giving
scrollability to other widgets. 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 set_child
has added a GtkViewport
for you,
it will be automatically removed when you unset the child.
Unless hscrollbar_policy
and
vscrollbar_policy
are NEVER
or
EXTERNAL
, GtkScrolledWindow
adds internal GtkScrollbar
widgets
around its child. The scroll position of the child, and if applicable the
scrollbars, is controlled by the hadjustment
and vadjustment
that are associated with the
GtkScrolledWindow
. See the docs on 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
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 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 overlay_scrolling
property.
CSS nodes
GtkScrolledWindow
has a main CSS node with name scrolledwindow.
It gets a .frame style class added when 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.
Constructors
Methods
- class ScrolledWindow
- get_child() Widget | None
Gets the child widget of
scrolled_window
.If the scrolled window automatically added a
Viewport
, this function will return the viewport widget, and you can retrieve its child usingget_child
.
- get_hadjustment() 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_overlay_scrolling() bool
Returns whether overlay scrolling is enabled for this scrolled window.
- get_placement() CornerType
Gets the placement of the contents with respect to the scrollbars.
- get_policy() tuple[PolicyType, PolicyType]
Retrieves the current policy values for the horizontal and vertical scrollbars.
See
set_policy
.
- get_propagate_natural_height() 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() bool
Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width.
- get_vadjustment() 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.
- set_child(child: Widget | None = None) None
Sets the child widget of
scrolled_window
.If
child
does not implement theScrollable
interface, the scrolled window will addchild
to aViewport
instance and then add the viewport as its child widget.- Parameters:
child – the child widget
- set_hadjustment(hadjustment: Adjustment | None = None) None
Sets the
GtkAdjustment
for the horizontal scrollbar.- Parameters:
hadjustment – the
GtkAdjustment
to use, orNone
to create a new one
- set_has_frame(has_frame: bool) None
Changes the frame drawn around the contents of
scrolled_window
.- Parameters:
has_frame – whether to draw a frame around scrolled window contents
- set_kinetic_scrolling(kinetic_scrolling: bool) None
Turns kinetic scrolling on or off.
Kinetic scrolling only applies to devices with source
%GDK_SOURCE_TOUCHSCREEN
.- Parameters:
kinetic_scrolling –
True
to enable kinetic scrolling
- set_max_content_height(height: int) None
Sets the maximum height that
scrolled_window
should keep visible.The
scrolled_window
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
min_content_height
.- Parameters:
height – the maximum content height
- set_max_content_width(width: int) None
Sets the maximum width that
scrolled_window
should keep visible.The
scrolled_window
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
min_content_width
.- Parameters:
width – the maximum content width
- set_min_content_height(height: int) None
Sets the minimum height that
scrolled_window
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
max_content_height
.- Parameters:
height – the minimal content height
- set_min_content_width(width: int) None
Sets the minimum width that
scrolled_window
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
max_content_width
.- Parameters:
width – the minimal content width
- set_overlay_scrolling(overlay_scrolling: bool) None
Enables or disables overlay scrolling for this scrolled window.
- Parameters:
overlay_scrolling – whether to enable overlay scrolling
- set_placement(window_placement: CornerType) None
Sets the placement of the contents with respect to the scrollbars for the scrolled window.
The default is
TOP_LEFT
, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values inCornerType
areTOP_RIGHT
,BOTTOM_LEFT
, andBOTTOM_RIGHT
.See also
get_placement
andunset_placement
.- Parameters:
window_placement – position of the child window
- set_policy(hscrollbar_policy: PolicyType, vscrollbar_policy: PolicyType) None
Sets the scrollbar policy for the horizontal and vertical scrollbars.
The policy determines when the scrollbar should appear; it is a value from the
PolicyType
enumeration. IfALWAYS
, the scrollbar is always present; ifNEVER
, the scrollbar is never present; ifAUTOMATIC
, 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).- Parameters:
hscrollbar_policy – policy for horizontal bar
vscrollbar_policy – policy for vertical bar
- set_propagate_natural_height(propagate: bool) None
Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height.
- Parameters:
propagate – whether to propagate natural height
- set_propagate_natural_width(propagate: bool) None
Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width.
- Parameters:
propagate – whether to propagate natural width
- set_vadjustment(vadjustment: Adjustment | None = None) None
Sets the
GtkAdjustment
for the vertical scrollbar.- Parameters:
vadjustment – the
GtkAdjustment
to use, orNone
to create a new one
Properties
- class ScrolledWindow
- props.child: Widget
The child widget.
When setting this property, if the child widget does not implement
Scrollable
, the scrolled window will add the child to aViewport
and then set the viewport as the child.
- props.hadjustment: Adjustment
- props.hscrollbar_policy: PolicyType
When the horizontal scrollbar is displayed.
Use
set_policy
to set this property.
- props.kinetic_scrolling: bool
Whether kinetic scrolling is enabled or not.
Kinetic scrolling only applies to devices with source
%GDK_SOURCE_TOUCHSCREEN
.
- props.overlay_scrolling: bool
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
gtk_overlay_scrolling
setting.
- props.propagate_natural_height: bool
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.
- props.propagate_natural_width: bool
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.
- props.vadjustment: Adjustment
- props.vscrollbar_policy: PolicyType
When the vertical scrollbar is displayed.
Use
set_policy
to set this property.
- props.window_placement: CornerType
Where the contents are located with respect to the scrollbars.
Signals
- class ScrolledWindow.signals
- edge_overshot(pos: PositionType) None
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
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.- Parameters:
pos – edge side that was hit
- edge_reached(pos: PositionType) None
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
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.- Parameters:
pos – edge side that was reached
- move_focus_out(direction_type: DirectionType) None
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 andCtrl + Shift + Tab
to move backward.- Parameters:
direction_type – either
TAB_FORWARD
orTAB_BACKWARD
- scroll_child(scroll: ScrollType, horizontal: bool) 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.
- Parameters:
scroll – a
GtkScrollType
describing how much to scrollhorizontal – whether the keybinding scrolls the child horizontally or not