Struct gtk4::ScrolledWindow

pub struct ScrolledWindow(_);

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 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 Scrollable. If it isn’t, then it wraps the child in a Viewport. Therefore, you can just add any child widget and not worry about the details.

If set_child() has added a Viewport for you, you can remove both your added child widget from the Viewport, and the Viewport from the ScrolledWindow, like this:

⚠️ The following code is in 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 property::ScrolledWindow::hscrollbar-policy and property::ScrolledWindow::vscrollbar-policy are PolicyType::Never or PolicyType::External, ScrolledWindow adds internal Scrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the property::ScrolledWindow::hadjustment and property::ScrolledWindow::vadjustment that are associated with the ScrolledWindow. 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 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 Scrollbar and for example a Grid.

Touch support

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 property::ScrolledWindow::kinetic-scrolling property if it is undesired.

ScrolledWindow also displays visual ‘overshoot’ indication when the content is pulled beyond the end, and this situation can be captured with the signal::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::ScrolledWindow::overlay-scrolling property.

CSS nodes

ScrolledWindow has a main CSS node with name scrolledwindow. It gets a .frame style class added when property::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.

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

ScrolledWindow uses the AccessibleRole::Group role.

Implements

WidgetExt, glib::ObjectExt, AccessibleExt, BuildableExt, ConstraintTargetExt, WidgetExtManual, AccessibleExtManual

Implementations

impl ScrolledWindow

pub fn new() -> ScrolledWindow

Creates a new scrolled window.

Returns

a new scrolled window

pub fn builder() -> ScrolledWindowBuilder

Creates a new builder-pattern struct instance to construct ScrolledWindow objects.

This method returns an instance of ScrolledWindowBuilder which can be used to create ScrolledWindow objects.

pub fn child(&self) -> Option<Widget>

Gets the child widget of self.

Returns

the child widget of self

pub fn hadjustment(&self) -> Option<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.

Returns

the horizontal Adjustment

pub fn has_frame(&self) -> bool

Gets whether the scrolled window draws a frame.

Returns

true if the self has a frame

pub fn hscrollbar(&self) -> Option<Widget>

Returns the horizontal scrollbar of self.

Returns

the horizontal scrollbar of the scrolled window.

pub fn is_kinetic_scrolling(&self) -> bool

Returns the specified kinetic scrolling behavior.

Returns

the scrolling behavior flags.

pub fn max_content_height(&self) -> i32

Returns the maximum content height set.

Returns

the maximum content height, or -1

pub fn max_content_width(&self) -> i32

Returns the maximum content width set.

Returns

the maximum content width, or -1

pub fn min_content_height(&self) -> i32

Gets the minimal content height of self.

Returns

the minimal content height

pub fn min_content_width(&self) -> i32

Gets the minimum content width of self.

Returns

the minimum content width

pub fn is_overlay_scrolling(&self) -> bool

Returns whether overlay scrolling is enabled for this scrolled window.

Returns

true if overlay scrolling is enabled

pub fn placement(&self) -> CornerType

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

Returns

the current placement value.

pub fn policy(&self) -> (PolicyType, PolicyType)

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

See set_policy().

Returns

hscrollbar_policy

location to store the policy for the horizontal scrollbar

vscrollbar_policy

location to store the policy for the vertical scrollbar

pub fn propagates_natural_height(&self) -> bool

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

Returns

whether natural height propagation is enabled.

pub fn propagates_natural_width(&self) -> bool

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

Returns

whether natural width propagation is enabled.

pub fn vadjustment(&self) -> Option<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.

Returns

the vertical Adjustment

pub fn vscrollbar(&self) -> Option<Widget>

Returns the vertical scrollbar of self.

Returns

the vertical scrollbar of the scrolled window.

pub fn set_child<P: IsA<Widget>>(&self, child: Option<&P>)

Sets the child widget of self.

child

the child widget

pub fn set_hadjustment<P: IsA<Adjustment>>(&self, hadjustment: Option<&P>)

Sets the Adjustment for the horizontal scrollbar.

hadjustment

the Adjustment to use, or None to create a new one

pub fn set_has_frame(&self, has_frame: bool)

Changes the frame drawn around the contents of self.

has_frame

whether to draw a frame around scrolled window contents

pub fn set_kinetic_scrolling(&self, kinetic_scrolling: bool)

Turns kinetic scrolling on or off.

Kinetic scrolling only applies to devices with source GDK_SOURCE_TOUCHSCREEN.

kinetic_scrolling

true to enable kinetic scrolling

pub fn set_max_content_height(&self, height: i32)

Sets the maximum height that self should keep visible.

The self 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 property::ScrolledWindow::min-content-height.

height

the maximum content height

pub fn set_max_content_width(&self, width: i32)

Sets the maximum width that self should keep visible.

The self 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 property::ScrolledWindow::min-content-width.

width

the maximum content width

pub fn set_min_content_height(&self, height: i32)

Sets the minimum height that self 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 property::ScrolledWindow::max-content-height.

height

the minimal content height

pub fn set_min_content_width(&self, width: i32)

Sets the minimum width that self 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 property::ScrolledWindow::max-content-width.

width

the minimal content width

pub fn set_overlay_scrolling(&self, overlay_scrolling: bool)

Enables or disables overlay scrolling for this scrolled window.

overlay_scrolling

whether to enable overlay scrolling

pub fn set_placement(&self, window_placement: CornerType)

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

The default is CornerType::TopLeft, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in CornerType are CornerType::TopRight, CornerType::BottomLeft, and CornerType::BottomRight.

See also placement() and unset_placement().

window_placement

position of the child window

pub fn set_policy(
    &self,
    hscrollbar_policy: PolicyType,
    vscrollbar_policy: PolicyType
)

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. If PolicyType::Always, the scrollbar is always present; if PolicyType::Never, the scrollbar is never present; if PolicyType::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).

hscrollbar_policy

policy for horizontal bar

vscrollbar_policy

policy for vertical bar

pub fn set_propagate_natural_height(&self, propagate: bool)

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

propagate

whether to propagate natural height

pub fn set_propagate_natural_width(&self, propagate: bool)

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

propagate

whether to propagate natural width

pub fn set_vadjustment<P: IsA<Adjustment>>(&self, vadjustment: Option<&P>)

Sets the Adjustment for the vertical scrollbar.

vadjustment

the Adjustment to use, or None to create a new one

pub fn unset_placement(&self)

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

If no window placement is set for a scrolled window, it defaults to CornerType::TopLeft.

pub fn hscrollbar_policy(&self) -> PolicyType

When the horizontal scrollbar is displayed.

Use set_policy() to set this property.

pub fn set_hscrollbar_policy(&self, hscrollbar_policy: PolicyType)

When the horizontal scrollbar is displayed.

Use set_policy() to set this property.

pub fn vscrollbar_policy(&self) -> PolicyType

When the vertical scrollbar is displayed.

Use set_policy() to set this property.

pub fn set_vscrollbar_policy(&self, vscrollbar_policy: PolicyType)

When the vertical scrollbar is displayed.

Use set_policy() to set this property.

pub fn window_placement(&self) -> CornerType

Where the contents are located with respect to the scrollbars.

pub fn set_window_placement(&self, window_placement: CornerType)

Where the contents are located with respect to the scrollbars.

pub fn connect_edge_overshot<F: Fn(&Self, PositionType) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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

pos

edge side that was hit

pub fn connect_edge_reached<F: Fn(&Self, PositionType) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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

pos

edge side that was reached

pub fn connect_move_focus_out<F: Fn(&Self, DirectionType) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

direction_type

either DirectionType::TabForward or DirectionType::TabBackward

pub fn emit_move_focus_out(&self, direction_type: DirectionType)

pub fn connect_scroll_child<F: Fn(&Self, ScrollType, bool) -> bool + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

scroll

a ScrollType describing how much to scroll

horizontal

whether the keybinding scrolls the child horizontally or not

pub fn emit_scroll_child(&self, scroll: ScrollType, horizontal: bool) -> bool

pub fn connect_child_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_hadjustment_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_has_frame_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_hscrollbar_policy_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_kinetic_scrolling_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_max_content_height_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_max_content_width_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_min_content_height_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_min_content_width_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_overlay_scrolling_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_propagate_natural_height_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_propagate_natural_width_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_vadjustment_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_vscrollbar_policy_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_window_placement_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Trait Implementations

impl Clone for ScrolledWindow

fn clone(&self) -> ScrolledWindow

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ScrolledWindow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ScrolledWindow

fn default() -> Self

Returns the “default value” for a type.

impl Display for ScrolledWindow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for ScrolledWindow

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for ScrolledWindow

fn cmp(&self, other: &ScrolledWindow) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl ParentClassIs for ScrolledWindow

type Parent = Widget

impl<T: ObjectType> PartialEq<T> for ScrolledWindow

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ObjectType> PartialOrd<T> for ScrolledWindow

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for ScrolledWindow

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for ScrolledWindow

impl IsA<Accessible> for ScrolledWindow

impl IsA<Buildable> for ScrolledWindow

impl IsA<ConstraintTarget> for ScrolledWindow

impl IsA<Widget> for ScrolledWindow

impl StructuralEq for ScrolledWindow