Description

Gnome::Gtk4::ScrolledWindow 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 Gnome::Gtk4::R-Scrollable interface, are added directly. For other types of widget, the class Gnome::Gtk4::Viewport acts as an adaptor, giving scrollability to other widgets. .set-child() intelligently accounts for whether or not the added child is a Gnome::Gtk4::R-Scrollable. If it isn’t, then it wraps the child in a Gnome::Gtk4::Viewport. Therefore, you can just add any child widget and not worry about the details.

If .set-child() has added a Gnome::Gtk4::Viewport for you, it will be automatically removed when you unset the child. Unless hscrollbar-policy and vscrollbar-policy are GTK_POLICY_NEVER or GTK_POLICY_EXTERNAL, Gnome::Gtk4::ScrolledWindow adds internal Gnome::Gtk4::Scrollbar 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 Gnome::Gtk4::ScrolledWindow. See the docs on Gnome::Gtk4::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 Gnome::Gtk4::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 Gnome::Gtk4::Scrollbar and for example a Gnome::Gtk4::Grid.

Touch support

Gnome::Gtk4::ScrolledWindow 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.

Gnome::Gtk4::ScrolledWindow 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

Gnome::Gtk4::ScrolledWindow 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.

Gnome::Gtk4::ScrolledWindow 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, Gnome::Gtk4::ScrolledWindow used the GTK_ACCESSIBLE_ROLE_GROUP role.

Starting from GTK 4.12, Gnome::Gtk4::ScrolledWindow uses the GTK_ACCESSIBLE_ROLE_GENERIC role.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-scrolledwindow

Creates a new scrolled window.

method new-scrolledwindow ( --> Gnome::Gtk4::ScrolledWindow \)

Methods

get-child

Gets the child widget of $scrolled-window.

If the scrolled window automatically added a Gnome::Gtk4::Viewport, this function will return the viewport widget, and you can retrieve its child using .get-child() in class Gnome::Gtk4::Viewport.

method get-child (--> N-Object )

Return value; the child widget of $scrolled-window.

get-hadjustment

Returns the horizontal scrollbar’s adjustment.

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

method get-hadjustment (--> N-Object )

Return value; the horizontal Gnome::Gtk4::Adjustment.

get-has-frame

Gets whether the scrolled window draws a frame.

method get-has-frame (--> Bool )

Return value; True if the $scrolled-window has a frame.

get-hscrollbar

Returns the horizontal scrollbar of $scrolled-window.

method get-hscrollbar (--> N-Object )

Return value; the horizontal scrollbar of the scrolled window..

get-kinetic-scrolling

Returns the specified kinetic scrolling behavior.

method get-kinetic-scrolling (--> Bool )

Return value; the scrolling behavior flags..

get-max-content-height

Returns the maximum content height set.

method get-max-content-height (--> Int )

Return value; the maximum content height, or -1.

get-max-content-width

Returns the maximum content width set.

method get-max-content-width (--> Int )

Return value; the maximum content width, or -1.

get-min-content-height

Gets the minimal content height of $scrolled-window.

method get-min-content-height (--> Int )

Return value; the minimal content height.

get-min-content-width

Gets the minimum content width of $scrolled-window.

method get-min-content-width (--> Int )

Return value; the minimum content width.

get-overlay-scrolling

Returns whether overlay scrolling is enabled for this scrolled window.

method get-overlay-scrolling (--> Bool )

Return value; True if overlay scrolling is enabled.

get-placement

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

method get-placement (--> GtkCornerType )

Return value; the current placement value..

get-policy

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

See .set-policy().

method get-policy ( GtkPolicyType $hscrollbar-policy, GtkPolicyType $vscrollbar-policy )

• $hscrollbar-policy; (transfer ownership: full) location to store the policy for the horizontal scrollbar.

• $vscrollbar-policy; (transfer ownership: full) location to store the policy for the vertical scrollbar.

get-propagate-natural-height

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

method get-propagate-natural-height (--> Bool )

Return value; whether natural height propagation is enabled..

get-propagate-natural-width

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

method get-propagate-natural-width (--> Bool )

Return value; whether natural width propagation is enabled..

get-vadjustment

Returns the vertical scrollbar’s adjustment.

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

method get-vadjustment (--> N-Object )

Return value; the vertical Gnome::Gtk4::Adjustment.

get-vscrollbar

Returns the vertical scrollbar of $scrolled-window.

method get-vscrollbar (--> N-Object )

Return value; the vertical scrollbar of the scrolled window..

set-child

Sets the child widget of $scrolled-window.

If $child does not implement the Gnome::Gtk4::R-Scrollable interface, the scrolled window will add $child to a Gnome::Gtk4::Viewport instance and then add the viewport as its child widget.

method set-child ( N-Object() $child )

• $child; the child widget.

set-hadjustment

Sets the Gnome::Gtk4::Adjustment for the horizontal scrollbar.

method set-hadjustment ( N-Object() $hadjustment )

• $hadjustment; the Gnome::Gtk4::Adjustment to use, or undefined to create a new one.

set-has-frame

Changes the frame drawn around the contents of $scrolled-window.

method set-has-frame ( Bool() $has-frame )

• $has-frame; whether to draw a frame around scrolled window contents.

set-kinetic-scrolling

Turns kinetic scrolling on or off.

Kinetic scrolling only applies to devices with source GDK_SOURCE_TOUCHSCREEN.

method set-kinetic-scrolling ( Bool() $kinetic-scrolling )

• $kinetic-scrolling; True to enable kinetic scrolling.

set-max-content-height

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.

method set-max-content-height ( Int() $height )

• $height; the maximum content height.

set-max-content-width

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.

method set-max-content-width ( Int() $width )

• $width; the maximum content width.

set-min-content-height

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.

method set-min-content-height ( Int() $height )

• $height; the minimal content height.

set-min-content-width

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.

method set-min-content-width ( Int() $width )

• $width; the minimal content width.

set-overlay-scrolling

Enables or disables overlay scrolling for this scrolled window.

method set-overlay-scrolling ( Bool() $overlay-scrolling )

• $overlay-scrolling; whether to enable overlay scrolling.

set-placement

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

The default is GTK_CORNER_TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in enumeration CornerType from Gnome::Gtk4::T-scrolledwindow are GTK_CORNER_TOP_RIGHT, GTK_CORNER_BOTTOM_LEFT, and GTK_CORNER_BOTTOM_RIGHT.

See also .get-placement() and .unset-placement().

method set-placement ( GtkCornerType $window-placement )

• $window-placement; position of the child window.

set-policy

Sets the scrollbar policy for the horizontal and vertical scrollbars.

The policy determines when the scrollbar should appear; it is a value from the enumeration PolicyType from Gnome::Gtk4::T-scrolledwindow enumeration. If GTK_POLICY_ALWAYS, the scrollbar is always present; if GTK_POLICY_NEVER, the scrollbar is never present; if GTK_POLICY_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).

method set-policy ( GtkPolicyType $hscrollbar-policy, GtkPolicyType $vscrollbar-policy )

• $hscrollbar-policy; policy for horizontal bar.

• $vscrollbar-policy; policy for vertical bar.

set-propagate-natural-height

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

method set-propagate-natural-height ( Bool() $propagate )

• $propagate; whether to propagate natural height.

set-propagate-natural-width

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

method set-propagate-natural-width ( Bool() $propagate )

• $propagate; whether to propagate natural width.

set-vadjustment

Sets the Gnome::Gtk4::Adjustment for the vertical scrollbar.

method set-vadjustment ( N-Object() $vadjustment )

• $vadjustment; the Gnome::Gtk4::Adjustment to use, or undefined to create a new one.

unset-placement

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_CORNER_TOP_LEFT.

method unset-placement ( )

Signals

edge-overshot

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.

method handler (
   $pos,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ScrolledWindow :$_widget,
  *C<user>-options
)

• $pos; edge side that was hit.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ScrolledWindow object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

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.

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.

method handler (
   $pos,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ScrolledWindow :$_widget,
  *C<user>-options
)

• $pos; edge side that was reached.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ScrolledWindow object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

move-focus-out

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

This is a [keybinding signal](class.SignalAction.html).

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

method handler (
   $direction-type,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ScrolledWindow :$_widget,
  *C<user>-options
)

• $direction-type; either GTK_DIR_TAB_FORWARD or GTK_DIR_TAB_BACKWARD.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ScrolledWindow object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

scroll-child

Emitted when a keybinding that scrolls is pressed.

This is a [keybinding signal](class.SignalAction.html).

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

method handler (
   $scroll,
  gboolean $horizontal,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ScrolledWindow :$_widget,
  *C<user>-options
  --> gboolean
)

• $scroll; a enumeration GtkScrollType defined in Gnome::Gtk4::T-enums describing how much to scroll.

• $horizontal; whether the keybinding scrolls the child horizontally or not.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ScrolledWindow object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;