`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 [[email protected]] interface, are added directly. For
other types of widget, the class [[email protected]] acts as an adaptor, giving scrollability to other widgets. [
[email protected]_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 [[email protected]_child] has added a `GtkViewport` for you, you can remove both your added child widget from the
`GtkViewport`, and the `GtkViewport` from the `GtkScrolledWindow`, like this:
```c GtkWidget *scrolled_window = gtk_scrolled_window_new (); GtkWidget *child_widget = gtk_button_new ();
// GtkButton is not a GtkScrollable, so GtkScrolledWindow will automatically // add a GtkViewport. gtk_box_append (GTK_BOX (
scrolled_window), child_widget);
// Either of these will result in child_widget being unparented: gtk_box_remove (GTK_BOX (scrolled_window), child_widget); // or
gtk_box_remove (GTK_BOX (scrolled_window), gtk_bin_get_child (GTK_BIN (scrolled_window))); ```
Unless [[email protected]:hscrollbar-policy] and [[email protected]: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
[[email protected]:hadjustment] and [[email protected]:vadjustment] that are associated with the `GtkScrolledWindow`.
See the docs on [[email protected]] 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 [[email protected]: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 [[email protected]:GtkScrolledWindow: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 [[email protected]:overlay-scrolling]
property.
CSS nodes
`GtkScrolledWindow` has a main CSS node with name scrolledwindow. It gets a .frame style class added when [
[email protected]: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
`GtkScrolledWindow` uses the gtk_accessible_role_group role.
- public unowned Widget? get_child ()
Gets the child widget of this.
- public unowned Adjustment get_hadjustment ()
Returns the horizontal scrollbar’s adjustment.
- public bool get_has_frame ()
Gets whether the scrolled window draws a frame.
- public unowned Widget get_hscrollbar ()
Returns the horizontal scrollbar of this
.
- public bool get_kinetic_scrolling ()
Returns the specified kinetic scrolling behavior.
- public int get_max_content_height ()
Returns the maximum content height set.
- public int get_max_content_width ()
Returns the maximum content width set.
- public int get_min_content_height ()
Gets the minimal content height of this
.
- public int get_min_content_width ()
Gets the minimum content width of this
.
- public bool get_overlay_scrolling ()
Returns whether overlay scrolling is enabled for this scrolled window.
- public CornerType get_placement ()
Gets the placement of the contents with respect to the scrollbars.
- public void get_policy (out PolicyType hscrollbar_policy, out PolicyType vscrollbar_policy)
Retrieves the current policy values for the horizontal and vertical
scrollbars.
- public bool 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.
- public bool 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.
- public unowned Adjustment get_vadjustment ()
Returns the vertical scrollbar’s adjustment.
- public unowned Widget get_vscrollbar ()
Returns the vertical scrollbar of this
.
- public void set_child (Widget? child)
Sets the child widget of this.
- public void set_hadjustment (Adjustment? hadjustment)
Sets the `GtkAdjustment` for the horizontal scrollbar.
- public void set_has_frame (bool has_frame)
Changes the frame drawn around the contents of
this.
- public void set_kinetic_scrolling (bool kinetic_scrolling)
Turns kinetic scrolling on or off.
- public void set_max_content_height (int height)
Sets the maximum height that this
should keep visible.
- public void set_max_content_width (int width)
Sets the maximum width that this
should keep visible.
- public void set_min_content_height (int height)
Sets the minimum height that this
should keep visible.
- public void set_min_content_width (int width)
Sets the minimum width that this
should keep visible.
- public void set_overlay_scrolling (bool overlay_scrolling)
Enables or disables overlay scrolling for this scrolled window.
- public void set_placement (CornerType window_placement)
Sets the placement of the contents with respect to the scrollbars for
the scrolled window.
- public void set_policy (PolicyType hscrollbar_policy, PolicyType vscrollbar_policy)
Sets the scrollbar policy for the horizontal and vertical scrollbars.
- public void set_propagate_natural_height (bool propagate)
Sets whether the natural height of the child should be calculated and
propagated through the scrolled window’s requested natural height.
- public void set_propagate_natural_width (bool propagate)
Sets whether the natural width of the child should be calculated and
propagated through the scrolled window’s requested natural width.
- public void set_vadjustment (Adjustment? vadjustment)
Sets the `GtkAdjustment` for the vertical scrollbar.
- public void unset_placement ()
Unsets the placement of the contents with respect to the scrollbars.