gi-gtk-3.0.17: Gtk bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.ScrolledWindow

Contents

Description

GtkScrolledWindow 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 Scrollable interface, are added directly. For other types of widget, the class Viewport acts as an adaptor, giving scrollability to other widgets. GtkScrolledWindow’s implementation of containerAdd intelligently accounts for whether or not the added child is a Scrollable. If it isn’t, ScrolledWindow wraps the child in a Viewport and adds that for you. Therefore, you can just add any child widget and not worry about the details.

If containerAdd has added a Viewport for you, you can remove both your added child widget from the Viewport, and the Viewport from the GtkScrolledWindow, with either of these calls:

C code

gtk_container_remove (GTK_CONTAINER (scrolled_window),
                      child_widget);
// or
gtk_container_remove (GTK_CONTAINER (scrolled_window),
                      gtk_bin_get_child (GTK_BIN (scrolled_window)));

Unless ScrolledWindow:policy is GTK_POLICY_NEVER or GTK_POLICY_EXTERNAL, GtkScrolledWindow adds internal Scrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the ScrolledWindow:hadjustment and ScrolledWindow:vadjustment that are associated with the GtkScrolledWindow. See the docs on 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 Scrollbar and for example a Grid.

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 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 ScrolledWindow::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 ScrolledWindow:overlay-scrolling property.

CSS nodes

GtkScrolledWindow 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.

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.

Synopsis

Exported types

Methods

addWithViewport

scrolledWindowAddWithViewport Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a, IsWidget b) 
=> a

scrolledWindow: a ScrolledWindow

-> b

child: the widget you want to scroll

-> m () 

Deprecated: (Since version 3.8)containerAdd will automatically adda Viewport if the child doesn’t implement Scrollable.

Used to add children without native scrolling capabilities. This is simply a convenience function; it is equivalent to adding the unscrollable child to a viewport, then adding the viewport to the scrolled window. If a child has native scrolling, use containerAdd instead of this function.

The viewport scrolls the child by moving its Window, and takes the size of the child to be the size of its toplevel Window. This will be very wrong for most widgets that support native scrolling; for example, if you add a widget such as TreeView with a viewport, the whole widget will scroll, including the column headings. Thus, widgets with native scrolling support should not be used with the Viewport proxy.

A widget supports scrolling natively if it implements the Scrollable interface.

getCaptureButtonPress

scrolledWindowGetCaptureButtonPress Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Bool

Returns: True if button presses are captured during kinetic scrolling

Return whether button presses are captured during kinetic scrolling. See scrolledWindowSetCaptureButtonPress.

Since: 3.4

getHadjustment

scrolledWindowGetHadjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Adjustment

Returns: the horizontal Adjustment

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

getHscrollbar

scrolledWindowGetHscrollbar Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Widget

Returns: the horizontal scrollbar of the scrolled window.

Returns the horizontal scrollbar of scrolledWindow.

Since: 2.8

getKineticScrolling

scrolledWindowGetKineticScrolling Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Bool

Returns: the scrolling behavior flags.

Returns the specified kinetic scrolling behavior.

Since: 3.4

getMaxContentHeight

scrolledWindowGetMaxContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Int32

Returns: the maximum content height, or -1

Returns the maximum content height set.

Since: 3.22

getMaxContentWidth

scrolledWindowGetMaxContentWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Int32

Returns: the maximum content width, or -1

Returns the maximum content width set.

Since: 3.22

getMinContentHeight

scrolledWindowGetMinContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Int32

Returns: the minimal content height

Gets the minimal content height of scrolledWindow, or -1 if not set.

Since: 3.0

getMinContentWidth

scrolledWindowGetMinContentWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Int32

Returns: the minimum content width

Gets the minimum content width of scrolledWindow, or -1 if not set.

Since: 3.0

getOverlayScrolling

scrolledWindowGetOverlayScrolling Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Bool

Returns: True if overlay scrolling is enabled

Returns whether overlay scrolling is enabled for this scrolled window.

Since: 3.16

getPlacement

scrolledWindowGetPlacement Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m CornerType

Returns: the current placement value.

See also scrolledWindowSetPlacement and scrolledWindowUnsetPlacement.

Gets the placement of the contents with respect to the scrollbars for the scrolled window. See scrolledWindowSetPlacement.

getPolicy

scrolledWindowGetPolicy Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m (PolicyType, PolicyType) 

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

getPropagateNaturalHeight

scrolledWindowGetPropagateNaturalHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Bool

Returns: whether natural height propagation is enabled.

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

Since: 3.22

getPropagateNaturalWidth

scrolledWindowGetPropagateNaturalWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Bool

Returns: whether natural width propagation is enabled.

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

Since: 3.22

getShadowType

scrolledWindowGetShadowType Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m ShadowType

Returns: the current shadow type

Gets the shadow type of the scrolled window. See scrolledWindowSetShadowType.

getVadjustment

scrolledWindowGetVadjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Adjustment

Returns: the vertical Adjustment

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

getVscrollbar

scrolledWindowGetVscrollbar Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m Widget

Returns: the vertical scrollbar of the scrolled window.

Returns the vertical scrollbar of scrolledWindow.

Since: 2.8

new

scrolledWindowNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsAdjustment a, IsAdjustment b) 
=> Maybe a

hadjustment: horizontal adjustment

-> Maybe b

vadjustment: vertical adjustment

-> m ScrolledWindow

Returns: a new scrolled window

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 Nothing for the adjustments, which will cause the scrolled window to create them for you.

setCaptureButtonPress

scrolledWindowSetCaptureButtonPress Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Bool

captureButtonPress: True to capture button presses

-> m () 

Changes the behaviour of scrolledWindow with regard to the initial event that possibly starts kinetic scrolling. When captureButtonPress is set to True, the event is captured by the scrolled window, and then later replayed if it is meant to go to the child widget.

This should be enabled if any child widgets perform non-reversible actions on Widget::button-press-event. If they don't, and handle additionally handle Widget::grab-broken-event, it might be better to set captureButtonPress to False.

This setting only has an effect if kinetic scrolling is enabled.

Since: 3.4

setHadjustment

scrolledWindowSetHadjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a, IsAdjustment b) 
=> a

scrolledWindow: a ScrolledWindow

-> b

hadjustment: horizontal scroll adjustment

-> m () 

Sets the Adjustment for the horizontal scrollbar.

setKineticScrolling

scrolledWindowSetKineticScrolling Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Bool

kineticScrolling: True to enable kinetic scrolling

-> m () 

Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source InputSourceTouchscreen.

Since: 3.4

setMaxContentHeight

scrolledWindowSetMaxContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Int32

height: the maximum content height

-> m () 

Sets the maximum height that scrolledWindow should keep visible. The scrolledWindow will grow up to this height before it starts scrolling the content.

It is a programming error to set the maximum content height to a value smaller than ScrolledWindow:min-content-height.

Since: 3.22

setMaxContentWidth

scrolledWindowSetMaxContentWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Int32

width: the maximum content width

-> m () 

Sets the maximum width that scrolledWindow should keep visible. The scrolledWindow will grow up to this width before it starts scrolling the content.

It is a programming error to set the maximum content width to a value smaller than ScrolledWindow:min-content-width.

Since: 3.22

setMinContentHeight

scrolledWindowSetMinContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Int32

height: the minimal content height

-> m () 

Sets the minimum height that scrolledWindow should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content.

It is a programming error to set the minimum content height to a value greater than ScrolledWindow:max-content-height.

Since: 3.0

setMinContentWidth

scrolledWindowSetMinContentWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Int32

width: the minimal content width

-> m () 

Sets the minimum width that scrolledWindow should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content.

It is a programming error to set the minimum content width to a value greater than ScrolledWindow:max-content-width.

Since: 3.0

setOverlayScrolling

scrolledWindowSetOverlayScrolling Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Bool

overlayScrolling: whether to enable overlay scrolling

-> m () 

Enables or disables overlay scrolling for this scrolled window.

Since: 3.16

setPlacement

scrolledWindowSetPlacement Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> CornerType

windowPlacement: position of the child window

-> m () 

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

The default is CornerTypeTopLeft, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in CornerType are CornerTypeTopRight, CornerTypeBottomLeft, and CornerTypeBottomRight.

See also scrolledWindowGetPlacement and scrolledWindowUnsetPlacement.

setPolicy

scrolledWindowSetPolicy Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> PolicyType

hscrollbarPolicy: policy for horizontal bar

-> PolicyType

vscrollbarPolicy: policy for vertical bar

-> m () 

Sets the scrollbar policy for the horizontal and vertical scrollbars.

The policy determines when the scrollbar should appear; it is a value from the PolicyType enumeration. If PolicyTypeAlways, the scrollbar is always present; if PolicyTypeNever, the scrollbar is never present; if PolicyTypeAutomatic, 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).

setPropagateNaturalHeight

scrolledWindowSetPropagateNaturalHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Bool

propagate: whether to propagate natural height

-> m () 

Sets whether the natural height of the child should be calculated and propagated through the scrolled windows requested natural height.

Since: 3.22

setPropagateNaturalWidth

scrolledWindowSetPropagateNaturalWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> Bool

propagate: whether to propagate natural width

-> m () 

Sets whether the natural width of the child should be calculated and propagated through the scrolled windows requested natural width.

Since: 3.22

setShadowType

scrolledWindowSetShadowType Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> ShadowType

type: kind of shadow to draw around scrolled window contents

-> m () 

Changes the type of shadow drawn around the contents of scrolledWindow.

setVadjustment

scrolledWindowSetVadjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a, IsAdjustment b) 
=> a

scrolledWindow: a ScrolledWindow

-> b

vadjustment: vertical scroll adjustment

-> m () 

Sets the Adjustment for the vertical scrollbar.

unsetPlacement

scrolledWindowUnsetPlacement Source #

Arguments

:: (HasCallStack, MonadIO m, IsScrolledWindow a) 
=> a

scrolledWindow: a ScrolledWindow

-> m () 

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 defaults to CornerTypeTopLeft.

See also scrolledWindowSetPlacement and scrolledWindowGetPlacement.

Since: 2.10

Properties

hadjustment

hscrollbarPolicy

kineticScrolling

maxContentHeight

maxContentWidth

minContentHeight

minContentWidth

overlayScrolling

propagateNaturalHeight

propagateNaturalWidth

shadowType

vadjustment

vscrollbarPolicy

windowPlacement

windowPlacementSet

Signals

edgeOvershot

edgeReached

moveFocusOut

scrollChild