
@c %start of fragment

@node GtkScrolledWindow
@chapter GtkScrolledWindow
Adds scrollbars to its child widget

@section Overview
@code{<gtk-scrolled-window>} is a @code{<gtk-bin>} subclass: it's a container
the accepts a single child widget. @code{<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 have "slots" for @code{<gtk-adjustment>} objects. Widgets
with native scroll support include @code{<gtk-tree-view>},
@code{<gtk-text-view>}, and @code{<gtk-layout>}.

The scrolled window installs @code{<gtk-adjustment>} objects in the child
window's slots using the set_scroll_adjustments_signal, found in
@code{<gtk-widget-class>}. (Conceptually, these widgets implement a "Scrollable"
interface; because GTK+ 1.2 lacked interface support in the object system, this
interface is hackily implemented as a signal in @code{<gtk-widget-class>}. The
GTK+ 2.0 object system would allow a clean implementation, but it wasn't worth
breaking the API.)

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

If a widget has native scrolling abilities, it can be added to the
@code{<gtk-scrolled-window>} with @code{gtk-container-add}. If a widget does
not, you must first add the widget to a @code{<gtk-viewport>}, then add the
@code{<gtk-viewport>} to the scrolled window. The convenience function
@code{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
@code{<gtk-adjustment>} for the fields in an adjustment - for
@code{<gtk-scrollbar>}, used by @code{<gtk-scrolled-window>}, the "value" field
represents the position of the scrollbar, which must be between the "lower"
field and "upper - page_size." The "page_size" field represents the size of the
visible scrollable area. The "step_increment" and "page_increment" fields 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 @code{<gtk-scrolled-window>} 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 @code{<gtk-scrollbar>} and for example a @code{<gtk-table>}.

@section Usage
@include defuns-gtkscrolledwindow.xml.texi

@c %end of fragment
