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.
Shortcuts and Gestures
The following signals have default keybindings:
signal@Gtk.ScrolledWindow::scroll-child
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.
Skipped during bindings generation
parameter
hscrollbar_policy: hscrollbar_policy: Out parameter is not supportedmethod
hadjustment: Property TypeInfo of getter and setter do not matchmethod
hscrollbar-policy: Property has no getter nor settermethod
vadjustment: Property TypeInfo of getter and setter do not matchmethod
vscrollbar-policy: Property has no getter nor setter
Constructors
Properties
The accessible role of the given GtkAccessible implementation.
A list of css classes applied to this widget.
Whether the widget should grab focus when it is clicked with the mouse.
Enables or disables the emission of the ::query-tooltip signal on @widget.
Whether to use the hexpand property.
Whether kinetic scrolling is enabled or not.
The GtkLayoutManager instance to use to compute the preferred size of the widget, and allocate its children.
Margin on bottom side of widget.
Margin on start of widget, horizontally.
The maximum content height of @scrolled_window.
The maximum content width of @scrolled_window.
The minimum content height of @scrolled_window.
The minimum content width of @scrolled_window.
Whether overlay scrolling is enabled or not.
Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height.
Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width.
Whether the widget will receive the default action when it is focused.
The scale factor of the widget.
Sets the text of tooltip to be the given string, which is marked up with Pango markup.
Sets the text of tooltip to be the given string.
Whether to use the vexpand property.
Where the contents are located with respect to the scrollbars.
Functions
Enable or disable an action installed with gtk_widget_class_install_action().
Looks up the action in the action groups associated with
Activates the default.activate action from @widget.
For widgets that can be “activated” (buttons, menu items, etc.), this function activates them.
Adds @controller to @widget so that it will receive events.
Adds a style class to @widget.
Adds a widget to the list of mnemonic labels for this widget.
Queues an animation frame update and adds a callback to be called before each frame.
This function is only used by GtkWidget subclasses, to assign a size, position and (optionally) baseline to their child widgets.
Requests the user's screen reader to announce the given message.
Called by widgets as the user moves around the window using keyboard shortcuts.
Computes the bounds for @widget in the coordinate space of @target.
Computes whether a container should give this widget extra space when possible.
Translates the given @point in @widget's coordinates to coordinates relative to @target’s coordinate system.
Computes a matrix suitable to describe a transformation from
Signals that all holders of a reference to the widget should release the reference that they hold.
Emitted when the text direction of a widget changes.
Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation.
Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation.
Emitted when @widget is hidden.
Emitted if keyboard navigation fails.
Emitted when @widget is going to be mapped.
Emitted when a widget is activated via a mnemonic.
Emitted when the focus is moved.
Emitted when focus is moved away from the scrolled window by a keybinding.
Emitted when the widget’s tooltip is about to be shown.
Emitted when @widget is associated with a GdkSurface.
Emitted when a keybinding that scrolls is pressed.
Emitted when @widget is shown.
Emitted when the widget state changes.
Emitted when @widget is going to be unmapped.
Emitted when the GdkSurface associated with @widget is destroyed.
Creates a new PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget.
Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.
Clears the template children for the given widget.
Checks to see if a drag movement has passed the GTK drag threshold.
Retrieves the accessible parent for an accessible object.
Retrieves the accessible role of an accessible object.
Returns the baseline that has currently been allocated to @widget.
Returns the height that has currently been allocated to @widget.
Returns the width that has currently been allocated to @widget.
Gets the first ancestor of @widget with type @widget_type.
Retrieves the accessible implementation for the given GtkAccessible.
Returns the baseline that has currently been allocated to @widget.
Gets the ID of the @buildable object.
Gets the value set with gtk_widget_set_child_visible().
Gets the clipboard object for @widget.
Gets the reading direction for a particular widget.
Get the GdkDisplay for the toplevel window associated with this widget.
Retrieves the first accessible child of an accessible object.
Returns the widget’s first child.
Returns the current focus child of @widget.
Gets the font map of @widget.
Obtains the frame clock for a widget.
Returns the horizontal scrollbar’s adjustment.
Returns the horizontal scrollbar of @scrolled_window.
Returns the widget’s last child.
Retrieves the next accessible sibling of an accessible object
Returns the widget’s next sibling.
Gets a PangoContext with the appropriate font map, font description, and base direction for this widget.
Query a platform state, such as focus.
Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.
Returns the widget’s previous sibling.
Gets the primary clipboard of @widget.
Determines whether @widget is realized.
Gets whether the widget prefers a height-for-width layout or a width-for-height layout.
Returns the widget’s sensitivity.
Gets the settings object holding the settings used for this widget.
Returns the content width or height of the widget.
Returns the widget state as a flag set.
Returns the style context associated to @widget.
Fetch an object build from the template XML for @widget_type in this @widget instance.
Returns the vertical scrollbar’s adjustment.
Determines whether the widget is visible.
Returns the vertical scrollbar of @scrolled_window.
Returns whether @css_class is currently applied to @widget.
Determines whether @widget is the current default widget within its toplevel.
Determines if the widget should show a visible indication that it has the global input focus.
Returns whether the widget is currently being destroyed.
Creates and initializes child widgets defined in templates.
Inserts @group into @widget.
Inserts @widget into the child widget list of @parent.
Inserts @widget into the child widget list of @parent.
Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers.
Determines whether @widget can be drawn to.
Returns the widget’s effective sensitivity.
Emits the ::keynav-failed signal on the widget.
Returns the widgets for which this widget is the target of a mnemonic.
Emits the ::mnemonic-activate signal.
Returns a GListModel to track the children of @widget.
Returns a GListModel to track the class@Gtk.EventControllers of @widget.
Flags the widget for a rerun of the vfunc@Gtk.Widget.size_allocate function.
Flags a widget to have its size renegotiated.
Removes @controller from @widget, so that it doesn't process events anymore.
Removes a style from @widget.
Removes a widget from the list of mnemonic labels for this widget.
Removes a tick callback previously registered with gtk_widget_add_tick_callback().
Resets the accessible @property to its default value.
Resets the accessible @relation to its default value.
Resets the accessible @state to its default value.
Sets the parent and sibling of an accessible object.
Sets whether @widget should be mapped along with its parent.
Sets a named cursor to be shown when pointer devices point towards @widget.
Sets the reading direction on a particular widget.
Set @child as the current focus child of @widget.
Sets the font map to use for Pango rendering.
Sets the GtkAdjustment for the horizontal scrollbar.
Set all margins to the same value.
Set start and end margin to horizontal and top and bottom margin to vertical
Set margins.
Sets the scrollbar policy for the horizontal and vertical scrollbars.
Sets the sensitivity of a widget.
Sets the minimum size of a widget.
Turns on flag values in the current widget state.
Sets the GtkAdjustment for the vertical scrollbar.
Sets the visibility state of @widget.
Returns whether @widget should contribute to the measuring and allocation of its parent.
Triggers a tooltip query on the display where the toplevel of @widget is located.
Unsets the placement of the contents with respect to the scrollbars.
Turns off flag values for the current widget state.
Updates the next accessible sibling of @self.