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>