Class: Gtk::ScrolledWindow

Inherits:
Widget
  • Object
show all
Defined in:
(unknown)

Overview

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 [ifaceGtk.Scrollable] interface, are added directly. For other types of widget, the class [classGtk.Viewport] acts as an adaptor, giving scrollability to other widgets. [methodGtk.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 [methodGtk.ScrolledWindow.set_child] has added a GtkViewport for you, it will be automatically removed when you unset the child. Unless [propertyGtk.ScrolledWindow:hscrollbar-policy] and [propertyGtk.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 [propertyGtk.ScrolledWindow:hadjustment] and [propertyGtk.ScrolledWindow:vadjustment] that are associated with the GtkScrolledWindow. See the docs on [classGtk.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 [propertyGtk.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 [signalGtk.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 [propertyGtk.ScrolledWindow:overlay-scrolling] property.

CSS nodes

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

Instance Method Summary collapse

Methods inherited from Widget

#accessible_role, #accessible_role=, #action_set_enabled, #activate, #activate_action, #activate_action_variant, #activate_default, #activate_signal, #activate_signal=, #activate_signal_from_name=, #add_binding, #add_binding_action, #add_binding_signal, #add_controller, #add_css_class, #add_mnemonic_label, #add_shortcut, #add_tick_callback, #allocate, #allocated_baseline, #allocated_height, #allocated_width, #baseline, #bind_template_callback_full, #bind_template_child_full, #can_focus, #can_focus=, #can_focus?, #can_target, #can_target=, #can_target?, #child_focus, #child_visible, #child_visible=, #clipboard, #compute_bounds, #compute_expand, #compute_point, #compute_transform, #contains, #create_pango_context, #create_pango_layout, #css_classes, #css_classes=, #css_name, #css_name=, #cursor, #cursor=, #cursor_from_name=, default_direction, default_direction=, #direction, #direction=, #display, #dispose_template, #drag_check_threshold, #error_bell, #first_child, #focus_child, #focus_child=, #focus_on_click, #focus_on_click=, #focus_on_click?, #focusable, #focusable=, #focusable?, #font_map, #font_map=, #font_options, #font_options=, #frame_clock, #get_allocation, #get_ancestor, #get_color, #get_preferred_size, #get_size, #get_size_request, #get_template_child, #grab_focus, #halign, #halign=, #has_css_class, #has_default, #has_default=, #has_default?, #has_focus, #has_focus=, #has_focus?, #has_tooltip, #has_tooltip=, #has_tooltip?, #has_visible_focus, #height, #height_request, #height_request=, #hexpand, #hexpand=, #hexpand?, #hexpand_set, #hexpand_set=, #hexpand_set?, #hide, #in_destruction, #init_template, #insert_action_group, #insert_after, #insert_before, #install_action, #install_property_action, #is_ancestor, #is_drawable, #is_focus, #is_sensitive, #is_visible, #keynav_failed, #last_child, #layout_manager, #layout_manager=, #layout_manager_type, #layout_manager_type=, #list_mnemonic_labels, #map, #mapped, #margin_bottom, #margin_bottom=, #margin_end, #margin_end=, #margin_start, #margin_start=, #margin_top, #margin_top=, #measure, #mnemonic_activate, #name, #name=, #native, #next_sibling, #observe_children, #observe_controllers, #opacity, #opacity=, #overflow, #overflow=, #pango_context, #parent, #parent=, #pick, #prev_sibling, #primary_clipboard, #query_action, #queue_allocate, #queue_draw, #queue_resize, #realize, #realized, #receives_default, #receives_default=, #receives_default?, #remove_controller, #remove_css_class, #remove_mnemonic_label, #remove_tick_callback, #request_mode, #root, #root=, #scale_factor, #scale_factor=, #sensitive, #sensitive=, #sensitive?, #set_size_request, #set_state_flags, #settings, #should_layout, #show, #size_allocate, #snapshot_child, #state_flags, #style_context, #template=, #template_from_resource=, #template_scope=, #tooltip_markup, #tooltip_markup=, #tooltip_text, #tooltip_text=, #translate_coordinates, #trigger_tooltip_query, #unmap, #unparent, #unrealize, #unset_state_flags, #valign, #valign=, #vexpand, #vexpand=, #vexpand?, #vexpand_set, #vexpand_set=, #vexpand_set?, #visible, #visible=, #visible?, #width, #width_request, #width_request=

Constructor Details

#initialize ⇒ Gtk::Widget

Creates a new scrolled window.

Instance Method Details

#child ⇒ Gtk::Widget

The child widget.

When setting this property, if the child widget does not implement [ifaceGtk.Scrollable], the scrolled window will add the child to a [classGtk.Viewport] and then set the viewport as the child.

Returns:

#child=(child) ⇒ Gtk::Widget

The child widget.

When setting this property, if the child widget does not implement [ifaceGtk.Scrollable], the scrolled window will add the child to a [classGtk.Viewport] and then set the viewport as the child.

Parameters:

Returns:

#get_policy(hscrollbar_policy, vscrollbar_policy) ⇒ nil

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

See [methodGtk.ScrolledWindow.set_policy].

Parameters:

  • hscrollbar_policy (Gtk::PolicyType) —

    location to store the policy for the horizontal scrollbar

  • vscrollbar_policy (Gtk::PolicyType) —

    location to store the policy for the vertical scrollbar

Returns:

  • (nil)

#hadjustment ⇒ Gtk::Adjustment

Returns hadjustment.

Returns:

#hadjustment=(hadjustment) ⇒ Gtk::Adjustment

Parameters:

Returns:

#has_frame ⇒ Boolean

Gets whether the scrolled window draws a frame.

Returns:

  • (Boolean) —

    true if the scrolled_window has a frame

#has_frame=(has_frame) ⇒ Boolean

Whether to draw a frame around the contents.

Parameters:

  • has_frame (Boolean)

Returns:

  • (Boolean) —

    has-frame

  • (Boolean) —

    has-frame

#has_frame? ⇒ Boolean

Whether to draw a frame around the contents.

Returns:

  • (Boolean) —

    has-frame

#hscrollbar ⇒ Gtk::Widget

Returns the horizontal scrollbar of scrolled_window.

Returns:

  • (Gtk::Widget) —

    the horizontal scrollbar of the scrolled window.

#hscrollbar_policy ⇒ Gtk::PolicyType

When the horizontal scrollbar is displayed.

Use [methodGtk.ScrolledWindow.set_policy] to set this property.

Returns:

#hscrollbar_policy=(hscrollbar_policy) ⇒ Gtk::PolicyType

When the horizontal scrollbar is displayed.

Use [methodGtk.ScrolledWindow.set_policy] to set this property.

Parameters:

Returns:

#kinetic_scrolling ⇒ Boolean

Returns the specified kinetic scrolling behavior.

Returns:

  • (Boolean) —

    the scrolling behavior flags.

#kinetic_scrolling=(kinetic_scrolling) ⇒ Boolean

Whether kinetic scrolling is enabled or not.

Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN.

Parameters:

  • kinetic_scrolling (Boolean)

Returns:

  • (Boolean) —

    kinetic-scrolling

  • (Boolean) —

    kinetic-scrolling

#kinetic_scrolling? ⇒ Boolean

Whether kinetic scrolling is enabled or not.

Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN.

Returns:

  • (Boolean) —

    kinetic-scrolling

#max_content_height ⇒ Integer

The maximum content height of scrolled_window.

Returns:

  • (Integer) —

    max-content-height

#max_content_height=(max_content_height) ⇒ Integer

The maximum content height of scrolled_window.

Parameters:

  • max_content_height (Integer)

Returns:

  • (Integer) —

    max-content-height

  • (Integer) —

    max-content-height

#max_content_width ⇒ Integer

The maximum content width of scrolled_window.

Returns:

  • (Integer) —

    max-content-width

#max_content_width=(max_content_width) ⇒ Integer

The maximum content width of scrolled_window.

Parameters:

  • max_content_width (Integer)

Returns:

  • (Integer) —

    max-content-width

  • (Integer) —

    max-content-width

#min_content_height ⇒ Integer

The minimum content height of scrolled_window.

Returns:

  • (Integer) —

    min-content-height

#min_content_height=(min_content_height) ⇒ Integer

The minimum content height of scrolled_window.

Parameters:

  • min_content_height (Integer)

Returns:

  • (Integer) —

    min-content-height

  • (Integer) —

    min-content-height

#min_content_width ⇒ Integer

The minimum content width of scrolled_window.

Returns:

  • (Integer) —

    min-content-width

#min_content_width=(min_content_width) ⇒ Integer

The minimum content width of scrolled_window.

Parameters:

  • min_content_width (Integer)

Returns:

  • (Integer) —

    min-content-width

  • (Integer) —

    min-content-width

#overlay_scrolling ⇒ Boolean

Returns whether overlay scrolling is enabled for this scrolled window.

Returns:

  • (Boolean) —

    true if overlay scrolling is enabled

#overlay_scrolling=(overlay_scrolling) ⇒ Boolean

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 [propertyGtk.Settings:gtk-overlay-scrolling] setting.

Parameters:

  • overlay_scrolling (Boolean)

Returns:

  • (Boolean) —

    overlay-scrolling

  • (Boolean) —

    overlay-scrolling

#overlay_scrolling? ⇒ Boolean

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 [propertyGtk.Settings:gtk-overlay-scrolling] setting.

Returns:

  • (Boolean) —

    overlay-scrolling

#placement ⇒ Gtk::CornerType

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

Returns:

#placement=(window_placement) ⇒ nil

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 [enumGtk.CornerType] are %GTK_CORNER_TOP_RIGHT, %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT.

See also [methodGtk.ScrolledWindow.get_placement] and [methodGtk.ScrolledWindow.unset_placement].

Parameters:

Returns:

  • (nil)

#propagate_natural_height ⇒ Boolean

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

Returns:

  • (Boolean) —

    whether natural height propagation is enabled.

#propagate_natural_height=(propagate_natural_height) ⇒ Boolean

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.

Parameters:

  • propagate_natural_height (Boolean)

Returns:

  • (Boolean) —

    propagate-natural-height

  • (Boolean) —

    propagate-natural-height

#propagate_natural_height? ⇒ Boolean

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.

Returns:

  • (Boolean) —

    propagate-natural-height

#propagate_natural_width ⇒ Boolean

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

Returns:

  • (Boolean) —

    whether natural width propagation is enabled.

#propagate_natural_width=(propagate_natural_width) ⇒ Boolean

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.

Parameters:

  • propagate_natural_width (Boolean)

Returns:

  • (Boolean) —

    propagate-natural-width

  • (Boolean) —

    propagate-natural-width

#propagate_natural_width? ⇒ Boolean

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.

Returns:

  • (Boolean) —

    propagate-natural-width

#set_policy(hscrollbar_policy, vscrollbar_policy) ⇒ nil

Sets the scrollbar policy for the horizontal and vertical scrollbars.

The policy determines when the scrollbar should appear; it is a value from the [enumGtk.PolicyType] 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).

Parameters:

Returns:

  • (nil)

#unset_placement ⇒ nil

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.

Returns:

  • (nil)

#vadjustment ⇒ Gtk::Adjustment

Returns vadjustment.

Returns:

#vadjustment=(vadjustment) ⇒ Gtk::Adjustment

Parameters:

Returns:

#vscrollbar ⇒ Gtk::Widget

Returns the vertical scrollbar of scrolled_window.

Returns:

  • (Gtk::Widget) —

    the vertical scrollbar of the scrolled window.

#vscrollbar_policy ⇒ Gtk::PolicyType

When the vertical scrollbar is displayed.

Use [methodGtk.ScrolledWindow.set_policy] to set this property.

Returns:

#vscrollbar_policy=(vscrollbar_policy) ⇒ Gtk::PolicyType

When the vertical scrollbar is displayed.

Use [methodGtk.ScrolledWindow.set_policy] to set this property.

Parameters:

Returns:

#window_placement ⇒ Gtk::CornerType

Where the contents are located with respect to the scrollbars.

Returns:

#window_placement=(window_placement) ⇒ Gtk::CornerType

Where the contents are located with respect to the scrollbars.

Parameters:

Returns: