Next: , Previous: GtkVScrollbar, Up: Top

108 GtkScrolledWindow

Adds scrollbars to its child widget

108.1 Overview

<gtk-scrolled-window> is a <gtk-bin> subclass: it's 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 have "slots" for <gtk-adjustment> objects. Widgets with native scroll support include <gtk-tree-view>, <gtk-text-view>, and <gtk-layout>.

The scrolled window installs <gtk-adjustment> objects in the child window's slots using the set_scroll_adjustments_signal, found in <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 <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 <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-table>, <gtk-box>, and so on.

If a widget has native scrolling abilities, it can be added to the <gtk-scrolled-window> with 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 <gtk-adjustment> for the fields in an adjustment - for <gtk-scrollbar>, used by <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 <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 <gtk-scrollbar> and for example a <gtk-table>.

108.2 Usage

— Class: <gtk-scrolled-window>

Derives from <gtk-bin>.

This class defines the following slots:

hadjustment
The GtkAdjustment for the horizontal position
vadjustment
The GtkAdjustment for the vertical position
hscrollbar-policy
When the horizontal scrollbar is displayed
vscrollbar-policy
When the vertical scrollbar is displayed
window-placement
Where the contents are located with respect to the scrollbars. This property only takes effect if "window-placement-set" is TRUE.
window-placement-set
Whether "window-placement" should be used to determine the location of the contents with respect to the scrollbars.
shadow-type
Style of bevel around the contents
— Signal on <gtk-scrolled-window>: move-focus-out (arg0 <gtk-direction-type>)
— Signal on <gtk-scrolled-window>: scroll-child (arg0 <gtk-scroll-type>) (arg1 <gboolean>) ⇒ <gboolean>
— Function: gtk-scrolled-window-new (hadjustment <gtk-adjustment>) (vadjustment <gtk-adjustment>) ⇒  (ret <gtk-widget>)

Creates a new scrolled window. The two arguments are the scrolled window's adjustments; these will be shared with the scrollbars and the child widget to keep the bars in sync with the child. Usually you want to pass ‘#f’ for the adjustments, which will cause the scrolled window to create them for you.

hadjustment
Horizontal adjustment.
vadjustment
Vertical adjustment.
ret
New scrolled window.
— Function: gtk-scrolled-window-get-hadjustment (self <gtk-scrolled-window>) ⇒  (ret <gtk-adjustment>)
— Method: get-hadjustment

Returns the horizontal scrollbar's adjustment, used to connect the horizontal scrollbar to the child widget's horizontal scroll functionality.

scrolled-window
A <gtk-scrolled-window>.
ret
The horizontal <gtk-adjustment>.
— Function: gtk-scrolled-window-get-vadjustment (self <gtk-scrolled-window>) ⇒  (ret <gtk-adjustment>)
— Method: get-vadjustment

Returns the vertical scrollbar's adjustment, used to connect the vertical scrollbar to the child widget's vertical scroll functionality.

scrolled-window
A <gtk-scrolled-window>.
ret
The vertical <gtk-adjustment>.
— Function: gtk-scrolled-window-get-hscrollbar (self <gtk-scrolled-window>) ⇒  (ret <gtk-widget>)
— Method: get-hscrollbar

Returns the horizontal scrollbar of scrolled-window.

scrolled-window
a <gtk-scrolled-window>
ret
the horizontal scrollbar of the scrolled window, or ‘#f’ if it does not have one.

Since 2.8

— Function: gtk-scrolled-window-get-vscrollbar (self <gtk-scrolled-window>) ⇒  (ret <gtk-widget>)
— Method: get-vscrollbar

Returns the vertical scrollbar of scrolled-window.

scrolled-window
a <gtk-scrolled-window>
ret
the vertical scrollbar of the scrolled window, or ‘#f’ if it does not have one.

Since 2.8

— Function: gtk-scrolled-window-set-policy (self <gtk-scrolled-window>) (hscrollbar_policy <gtk-policy-type>) (vscrollbar_policy <gtk-policy-type>)
— Method: set-policy

Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the <gtk-policy-type> 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).

scrolled-window
A <gtk-scrolled-window>.
hscrollbar-policy
Policy for horizontal bar.
vscrollbar-policy
Policy for vertical bar.
— Function: gtk-scrolled-window-set-placement (self <gtk-scrolled-window>) (window_placement <gtk-corner-type>)
— Method: set-placement

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

See also gtk-scrolled-window-get-placement and gtk-scrolled-window-unset-placement.

Determines the location of the child widget with respect to the scrollbars. 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 <gtk-corner-type> are ‘GTK_CORNER_TOP_RIGHT’, ‘GTK_CORNER_BOTTOM_LEFT’, and ‘GTK_CORNER_BOTTOM_RIGHT’.

scrolled-window
a <gtk-scrolled-window>
window-placement
Position of the child window.
— Function: gtk-scrolled-window-unset-placement (self <gtk-scrolled-window>)
— Method: unset-placement

Unsets the placement of the contents with respect to the scrollbars for the scrolled window. If no window placement is set for a scrolled window, it obeys the "gtk-scrolled-window-placement" XSETTING.

See also gtk-scrolled-window-set-placement and gtk-scrolled-window-get-placement.

scrolled-window
a <gtk-scrolled-window>

Since 2.10

— Function: gtk-scrolled-window-set-shadow-type (self <gtk-scrolled-window>) (type <gtk-shadow-type>)
— Method: set-shadow-type

Changes the type of shadow drawn around the contents of scrolled-window.

scrolled-window
a <gtk-scrolled-window>
type
kind of shadow to draw around scrolled window contents
— Function: gtk-scrolled-window-set-hadjustment (self <gtk-scrolled-window>) (hadjustment <gtk-adjustment>)
— Method: set-hadjustment

Sets the <gtk-adjustment> for the horizontal scrollbar.

scrolled-window
A <gtk-scrolled-window>.
hadjustment
Horizontal scroll adjustment.
— Function: gtk-scrolled-window-set-vadjustment (self <gtk-scrolled-window>) (vadjustment <gtk-adjustment>)
— Method: set-vadjustment

Sets the <gtk-adjustment> for the vertical scrollbar.

scrolled-window
A <gtk-scrolled-window>.
vadjustment
Vertical scroll adjustment.
— Function: gtk-scrolled-window-get-placement (self <gtk-scrolled-window>) ⇒  (ret <gtk-corner-type>)
— Method: get-placement

Gets the placement of the contents with respect to the scrollbars for the scrolled window. See gtk-scrolled-window-set-placement.

scrolled-window
a <gtk-scrolled-window>
ret
the current placement value. See also gtk-scrolled-window-set-placement and gtk-scrolled-window-unset-placement.
— Function: gtk-scrolled-window-get-shadow-type (self <gtk-scrolled-window>) ⇒  (ret <gtk-shadow-type>)
— Method: get-shadow-type

Gets the shadow type of the scrolled window. See gtk-scrolled-window-set-shadow-type.

scrolled-window
a <gtk-scrolled-window>
ret
the current shadow type