NAME
    `Tickit::Widget::FloatBox' - manage a collection of floating widgets

SYNOPSIS
     TODO

DESCRIPTION
    This container widget maintains a collection of floating widgets that
    can be displayed over the top of a single base widget. The box itself is
    entirely occupied by the base widget, and by default when no floats are
    created or displayed it will behave essentially invisibly, as though the
    box were not there and the base widget was an immediate child of the
    container the floatbox is inside.

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

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

    base_child => Tickit::Widget
            The main Tickit::Widget instance to use as the base.

ACCESSORS
  $base_child = $floatbox->base_child
  $floatbox->set_base_child( $base_child )
    Returns or sets the base widget to use.

  $float = $floatbox->add_float( %args )
    Adds a widget as a floating child and returns a new `Float' object.
    Takes the following arguments:

    child => Tickit::Widget
            The child widget

    top, bottom, left, right => INT
            The initial geometry of the floating area. These follow the same
            behaviour as the `move' method on the Float object.

    hidden => BOOL
            Optional. If true, the float starts off hidden initally, and
            must be shown by the `show' method before it becomes visible.

FLOATS
    The following objects represent a floating region as returned by the
    `add_float' method.

  $child = $float->child
    Returns the child widget in the region.

  $float->move( %args )
    Redefines the area geometry of the region. Takes arguments named `top',
    `bottom', `left' and `right', each of which should either be a numeric
    value, or `undef'.

    The region must have at least one of `top' or `bottom' and at least one
    of `left' or `right' defined, which will then fix the position of one
    corner of the region. If the size is not otherwise determined by the
    geometry, it will use the preferred size of the child widget. Any
    geometry argument may be negative to count backwards from the limits of
    the parent.

    For example,

     # top-left corner
     $float->move( top => 0, left => 0 )

     # top-right corner
     $float->move( top => 0, right => -1 )

     # bottom 3 lines, flush left
     $float->move( left => 0, top => -3, bottom => -1 )

    Any arguments not passed will be left unchanged; to specifically clear
    the current value pass a value of `undef'.

  $float->remove
    Removes the float from the FloatBox.

  $float->hide
    Hide the float by hiding the window of its child widget.

  $float->show
    Show the float by showing the window of its child widget. Undoes the
    effect of `hide'.

  $visible = $float->is_visible
    Return true if the float is currently visible.

TODO
    *   Support adjusting stacking order of floats.

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