adwaita-swift/Documentation/Reference/structs/ScrolledWindow.md

STRUCT

ScrolledWindow

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_POLICY_NEVER or %GTK_POLICY_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.

Properties

updateFunctions

Additional update functions for type extensions.

appearFunctions

Additional appear functions for type extensions.

accessibleRole

The accessible role of the given GtkAccessible implementation.

The accessible role cannot be changed once set.

child

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.

hasFrame

Whether to draw a frame around the contents.

kineticScrolling

Whether kinetic scrolling is enabled or not.

Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN.

maxContentHeight

The maximum content height of @scrolled_window.

maxContentWidth

The maximum content width of @scrolled_window.

minContentHeight

The minimum content height of @scrolled_window.

minContentWidth

The minimum content width of @scrolled_window.

overlayScrolling

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.

propagateNaturalHeight

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.

propagateNaturalWidth

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.

edgeOvershot

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.

edgeReached

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.

moveFocusOut

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.

scrollChild

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.

app

The application.

window

The window.

Methods

init()

Initialize ScrolledWindow.

container(modifiers:)

Get the widget's view storage.

• Parameter modifiers: The view modifiers.
• Returns: The view storage.

update(_:modifiers:updateProperties:)

Update the widget's view storage.

• Parameters:
  • storage: The view storage.
  • modifiers: The view modifiers.
  • updateProperties: Whether to update the view's properties.

accessibleRole(_:)

The accessible role of the given GtkAccessible implementation.

The accessible role cannot be changed once set.

child(_:)

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.

hasFrame(_:)

Whether to draw a frame around the contents.

kineticScrolling(_:)

Whether kinetic scrolling is enabled or not.

Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN.

maxContentHeight(_:)

The maximum content height of @scrolled_window.

maxContentWidth(_:)

The maximum content width of @scrolled_window.

minContentHeight(_:)

The minimum content height of @scrolled_window.

minContentWidth(_:)

The minimum content width of @scrolled_window.

overlayScrolling(_:)

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.

propagateNaturalHeight(_:)

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.

propagateNaturalWidth(_:)

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.

edgeOvershot(_:)

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.

edgeReached(_:)

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.

moveFocusOut(_:)

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.

scrollChild(_:)

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.