Class gtk-scrolled-window

Package: gtk

Superclasses

gtk-bin, gtk-container, gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk-places-sidebar

Direct Slots

hadjustment

The hadjustment property of type gtk-adjustment (Read / Write / Construct)
The adjustment for the horizontal position.

hscrollbar-policy

The hscrollbar-policy property of type gtk-policy-type (Read / Write)
When the horizontal scrollbar is displayed.
Default value: :automatic

kinetic-scrolling

The kinetic-scrolling property of type :boolean (Read / Write)
Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to input devices of :touchscreen type.
Default value: true

max-content-height

The max-content-height property of type :int (Read / Write)
The maximum content height of the scrolled window, or -1 if not set. Since 3.22
Allowed values: >= -1
Default value: -1

max-content-width

The max-content-width property of type :int (Read / Write)
The maximum content width of the scrolled window, or -1 if not set. Since 3.22
Allowed values: >= -1
Default value: -1

min-content-height

The min-content-height property of type :int (Read / Write)
The minimum content height of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1

min-content-width

The min-content-width property of type :int (Read / Write)
The minimum content width of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1

overlay-scrolling

The overlay-scrolling property of type :boolean (Read / Write)
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 overlayed on top of the content, as narrow indicators.
Default value: true

propagate-natural-height

The propagate-natural-height property of type :boolean (Read / Write)
Whether the natural height of the child should be calculated and propagated through the requested natural height of the scrolled window. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. Since 3.22
Default value: false

propagate-natural-width

The propagate-natural-width property of type :boolean (Read / Write)
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. Since 3.22
Default value: false

shadow-type

The shadow-type property of type gtk-shadow-type (Read / Write)
Style of bevel around the contents.
Default value: :none

vadjustment

The vadjustment property of type gtk-adjustment (Read / Write / Construct)
The adjustment for the vertical position.

vscrollbar-policy

The vscrollbar-policy property of type gtk-policy-type (Read / Write)
When the vertical scrollbar is displayed.
Default value: :automatic

window-placement

The window-placement property of type gtk-corner-type (Read / Write)
Where the contents are located with respect to the scrollbars.
Default value: :left

window-placement-set

The window-placement-set property of type :boolean (Read / Write)
Whether the window-placement property should be used to determine the location of the contents with respect to the scrollbars.
Warning: The window-placement-set property has been deprecated since version 3.10 and should not be used in newly written code. This value is ignored and the value of the window-placement property is always honored.
Default value: true

Details

The gtk-scrolled-window widget is a container that accepts a single child widget, makes that child scrollable 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 gtk-scrollable interface, are added directly. For other types of widgets, the gtk-viewport class acts as an adaptor, giving scrollability to other widgets. The gtk-scrolled-window widgets implementation of the gtk-container-add function intelligently accounts for whether or not the added child is a gtk-scrollable widget. If it is not, the gtk-scrolled-window widget wraps the child in a gtk-viewport widget and adds that for you. Therefore, you can just add any child widget and not worry about the details.

If the gtk-container-add function has added a gtk-viewport widget for you, you can remove both your added child widget from the gtk-viewport widget, and the gtk-viewport widget from the gtk-scrolled-window widget, like this:

(let ((window (make-instance 'gtk-scrolled-window))
      (child (make-instance 'gtk-button)))


  ;; GtkButton is not a GtkScrollable, so GtkScrolledWindow will automatically
  ;; add a GtkViewport.
  (gtk-container-add window child)


  ;; Either of these will result in child being unparented:
  (gtk-container-remove window child)
  ;; or
  (gtk-container-remove window (gtk-bin-child window))
  ... )

Unless the hscrollbar-policy and vscrollbar-policy properties are :never or :external, the gtk-scrolled-window widget adds internal gtk-scrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the hadjustment and vadjustment properties that are associated with the gtk-scrolled-window widget. See the docs on the gtk-scrollbar widget for the details, but note that the step-increment and page-increment properties are only effective if the policy causes scrollbars to be present.

If a gtk-scrolled-window widget does not behave quite as you would like, or does not have exactly the right layout, it is very possible to set up your own scrolling with the gtk-scrollbar widget and for example a gtk-grid widget.

Touch support

The gtk-scrolled-window widget 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.

The gtk-scrolled-window widget 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 overlayed 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

The gtk-scrolled-window implementation has a main CSS node with name scrolledwindow. 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.

The gtk-scrolled-window implementation 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.

Style Property Details

scrollbar-spacing: The scrollbar-spacing style property of type :int (Read)
Number of pixels between the scrollbars and the scrolled window.
Allowed values: >= 0
Default value: 3
scrollbars-within-bevel: The scrollbars-within-bevel style property of type :boolean (Read)
Whether to place scrollbars within the scrolled bevel of the window.
Warning: The scrollbars-within-bevel style property has been deprecated since version 3.20 and should not be used in newly written code. The value of this style property is ignored.
Default value: false

Signal Details

The "edge-overshot" signal

 lambda (window pos)    :run-last

The signal is emitted whenever user initiated scrolling makes the scrolled window firmly surpass, i.e. with some edge resistance, the lower or upper 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.

window: The gtk-scrolled-window widget which received the signal.
pos: Edge side as a value of the gtk-position-type enumeration that was hit.

The "edge-reached" signal

 lambda (window pos)    :run-last

The signal is 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.

window: The gtk-scrolled-window widget which received the signal.
pos: Edge side as a value of the gtk-position-type enumeration that was hit.

The "move-focus-out" signal

 lambda (window direction)    :action

The signal is a keybinding signal which gets emitted when focus is moved away from the scrolled window by a keybinding. The "move-focus" signal is emitted with the direction value on this scrolled windows toplevel parent in the container hierarchy. The default bindings for this signal are the Tab+Ctrl and Tab+Ctrl+Shift keys.

window: The gtk-scrolled-window widget which received the signal.
direction: Either the :tab-forward or :tab-backward value of the gtk-direction-type enumeration.

The "scroll-child" signal

 lambda (window scroll horizontal)    :action

The signal is a keybinding signal which gets emitted when a keybinding that scrolls is pressed. The horizontal or vertical adjustment is updated which triggers a signal that the scrolled windows child may listen to and scroll itself.

window: The gtk-scrolled-window widget which received the signal.
scroll: A value of the gtk-scroll-type enumeration describing how much to scroll.
horizontal: A boolean whether the keybinding scrolls the child horizontally or not.