Package: gtk

Class gtk-scrolled-window

Superclasses

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

Documented Subclasses

Direct Slots

hadjustment
The hadjustment property of type gtk-adjustment (Read / Write / Construct)
The gtk-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]
The kinetic scrolling behavior flags. Kinetic scrolling only applies to devices with source :touchscreen
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.
Allowed values: >= -1
Default value: -1
Since 3.22
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.
Allowed values: >= -1
Default value: -1
Since 3.22
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: >= G_MAXULONG
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: >= G_MAXULONG
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
Since 3.16
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 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.
Default value: nil
Since 3.22
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.
Default value: nil
Since 3.22
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 gtk-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. This property only takes effect if window-placement-set is true.
Default value: :left
window-placement-set
The window-placement-set property of type :boolean (Read / Write)
Whether window-placement should be used to determine the location of the contents with respect to the scrollbars.
Warning: window-placement-set has been deprecated since version 3.10 and should not be used in newly-written code. This value is ignored and window-placement value is always honored.
Default value: true

Details

gtk-scrolled-window is a gtk-bin subclass: it is a container the accepts a single child widget. gtk-scrolled-window adds scrollbars to the child widget and optionally draws a beveled frame around the child widget.

The scrolled window can work in two ways. Some widgets have native scrolling support; these widgets implement the gtk-scrollable interface. Widgets with native scroll support include gtk-tree-view, gtk-text-view, and gtk-layout.

For widgets that lack native scrolling support, the gtk-viewport widget acts as an adaptor class, implementing scrollability for child widgets that lack their own scrolling capabilities. Use gtk-viewport to scroll child widgets such as gtk-grid, gtk-box, and so on.

If a widget has native scrolling abilities, it can be added to the gtk-scrolled-window with the function gtk-container-add. If a widget does not, you must first add the widget to a gtk-viewport, then add the gtk-viewport to the scrolled window. The convenience function gtk-scrolled-window-add-with-viewport does exactly this, so you can ignore the presence of the viewport.

The position of the scrollbars is controlled by the scroll adjustments. See the function gtk-adjustment for the fields in an adjustment - for gtk-scrollbar, used by gtk-scrolled-window, the value slot represents the position of the scrollbar, which must be between the lower slot and upper - page-size. The page-size slot represents the size of the visible scrollable area. The step-increment and page-increment slot are used when the user asks to step down (using the small stepper arrows) or page down (using for example the PageDown key).

If a gtk-scrolled-window 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 gtk-scrollbar and for example a gtk-grid.

Touch support gtk-scrolled-window 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.

gtk-scrolled-window 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

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

gtk-scrolled-window 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 window's bevel.
Warning: scrollbars-within-bevel 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: nil

Signal Details

The "edge-overshot" signal
 lambda (scolled-window pos)    : Run Last      
The "edge-overshot" 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.
scrolled-window
A gtk-scrolled-window object.
pos
Edge side of type gtk-position-type that was hit.
Since 3.16

The "edge-reached" signal
lambda (scrolled-window pos) : Run Last The "edge-reached" 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.
scrolled-window
A gtk-scrolled-window object.
pos
Edge side of type gtk-position-type that was hit.
Since 3.16

The "move-focus-out" signal
 lambda (scrolled-window direction-type)    : Action      
The "move-focus-out" 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 direction-type on this scrolled windows toplevel parent in the container hierarchy. The default bindings for this signal are Tab+Ctrl and Tab+Ctrl+Shift.
scrolled-window
A gtk-scrolled-window.
direction-type
Either :forward or :backward.
The "scroll-child" signal
 lambda (scrolled-window scroll horizontal)    : Action        
The "scroll-child" 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.
scrolled-window
a gtk-scrolled-window.
scroll
A gtk-scroll-type describing how much to scroll.
horizontal
Whether the keybinding scrolls the child horizontally or not.
 

Slot Access Functions

Inherited Slot Access Functions

See also

2013-6-20