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

 new

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

      This argument is now discouraged as it complicates the construction
      of subclasses; see instead the "set_base_child" method used as a
      chaining mutator.

ACCESSORS

 base_child

 set_base_child

       $base_child = $floatbox->base_child
    
       $floatbox->set_base_child( $base_child )

    Returns or sets the base widget to use.

    The mutator method returns the container widget instance itself making
    it suitable to use as a chaining mutator; e.g.

       my $container = Tickit::Widget::FloatBox->new( ... )
          ->set_base_child( Tickit::Widget::Box->new ... );

 add_float

       $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

       $child = $float->child

    Returns the child widget in the region.

 move

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

 remove

       $float->remove

    Removes the float from the FloatBox.

 hide

       $float->hide

    Hide the float by hiding the window of its child widget.

 show

       $float->show

    Show the float by showing the window of its child widget. Undoes the
    effect of hide.

 is_visible

       $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>