NAME
    `Tickit::Widget::ScrollBox' - allow a single child widget to be scrolled

SYNOPSIS
     use Tickit;
     use Tickit::Widget::ScrollBox;
     use Tickit::Widget::Static;

     my $scrollbox = Tickit::Widget::ScrollBox->new(
        child => Tickit::Widget::Static->new(
           text => join( "\n", map { "The content for line $_" } 1 .. 100 ),
        ),
     );

     Tickit->new( root => $scrollbox )->run;

DESCRIPTION
    This container widget draws a scrollbar beside a single child widget and
    allows a portion of it to be displayed by scrolling.

STYLE
    Th following style pen prefixes are used:

    scrollbar => PEN
        The pen used to render the background of the scroll bar

    scrollmark => PEN
        The pen used to render the active scroll position in the scroll bar

    arrow => PEN
        The pen used to render the scrolling arrow buttons

    The following style keys are used:

    arrow_up => STRING
    arrow_down => STRING
    arrow_left => STRING
    arrow_right => STRING
        Each should be a single character to use for the scroll arrow
        buttons.

    The following style actions are used:

    up_1 (<Up>)
    down_1 (<Down>)
    left_1 (<Left>)
    right_1 (<Right>)
        Scroll by 1 line

    up_half (<PageUp>)
    down_half (<PageDown>)
    left_half (<C-Left>)
    right_half (<C-Right>)
        Scroll by half of the viewport

    to_top (<C-Home>)
    to_bottom (<C-End>)
    to_leftmost (<Home>)
    to_rightmost (<End>)
        Scroll to the edge of the area

CONSTRUCTOR
  $scrollbox = Tickit::Widget::ScrollBox->new( %args )
    Constructs a new `Tickit::Widget::ScrollBox' object.

    Takes the following named arguments in addition to those taken by the
    base Tickit::SingleChildWidget constructor:

    vertical => BOOL or "on_demand"
    horizontal => BOOL or "on_demand"
            Whether to apply a scrollbar in the vertical or horizontal
            directions. If not given, these default to vertical only.

            If given as the string `on_demand' then the scrollbar will be
            optionally be displayed only if needed; if the space given to
            the widget is smaller than the child content necessary to
            display.

ACCESSORS
  $vextent = $scrollbox->vextent
    Returns the Tickit::Widget::ScrollBox::Extent object representing the
    box's vertical scrolling extent.

  $hextent = $scrollbox->hextent
    Returns the Tickit::Widget::ScrollBox::Extent object representing the
    box's horizontal scrolling extent.

METHODS
  $scrollbox->scroll( $downward, $rightward )
    Requests the content be scrolled downward a number of lines and
    rightward a number of columns (either of which which may be negative).

  $scrollbox->scroll_to( $top, $left )
    Requests the content be scrolled such that the given line and column
    number of the child's content is the topmost visible in the container.

TODO
    *   Choice of left/right and top/bottom bar positions.

    *   Click-and-hold on arrow buttons for auto-repeat

    *   Allow smarter cooperation with a scrolling-aware child widget;
        likely by setting extent objects on the child if it declares to be
        supported, and use that instead of an offset child window.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>