NAME

       "Tickit::Widget::Box" - apply spacing and positioning to a widget

SYNOPSIS

          use Tickit;
          use Tickit::Widget::Box;
          use Tickit::Widget::Static;

          my $box = Tickit::Widget::Box->new(
             bg => "green",
             child_lines => "80%",
             child_cols  => "80%",
          )
             ->set_child(
                Tickit::Widget::Static->new(
                  text   => "Hello, world!",
                  bg     => "black",
                  align  => "centre",
                  valign => "middle",
                )
             );

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

DESCRIPTION

       This subclass of Tickit::SingleChildWidget can apply spacing around the outside of a given
       child widget. The size of the Box is controlled by the size of the child widget bounded by
       the given limits, allowing it to enforce a given minimum or maximum size in each of the
       horizontal and vertical directions. By setting both the minimum and maximum size to the
       same value, the exact size of the child widget can be controlled.

       Limits can be specified either as absolute values, or as a percentage of the maxmium
       available space.

       If the Box is given more space to use than the child widget will consume, the child will
       be placed somewhere within the space, at a position that is controllable using the "align"
       and "valign" properties, as defined by Tickit::WidgetRole::Alignable.

STYLE

       The default style pen is used as the widget pen.

       Note that while the widget pen is mutable and changes to it will result in immediate
       redrawing, any changes made will be lost if the widget style is changed.

CONSTRUCTOR

   new
          $box = Tickit::Widget::Box->new( %args )

       In addition to the constructor arguments allowed by "Tickit::Widget" and
       "Tickit::SingleChildWidget", this constructor also recognises the following named
       arguments:

       child_{lines,cols}_{min,max} => NUM or STRING
               Initial values for size limit options.

       child_{lines,cols} => NUM or STRING
               Initial values for size forcing options.

       align => NUM or STRING
       valign => NUM or STRING
               Initial values for alignment options.

METHODS

       The following methods all accept either absolute sizes, specified in integers, or
       percentages, specified in strings of the form "10%". If a percentage is given it specifies
       a size that is a fraction of the total amount that is available to the Box.

   child_lines_min
   set_child_lines_min
   child_cols_min
   set_child_cols_min
          $min = $box->child_lines_min

          $box->set_child_lines_min( $min )

          $min = $box->child_cols_min

          $box->set_child_cols_min( $min )

       Accessors for the child size minimum limits. If the child widget requests a size smaller
       than these limits, the allocated Window will be resized up to at least these sizes.

   child_lines_max
   set_child_lines_max
   child_cols_max
   set_child_cols_max
          $max = $box->child_lines_max

          $box->set_child_lines_max( $max )

          $max = $box->child_cols_max

          $box->set_child_cols_max( $max )

       Accessors for the child size maximum limits. If the child widget requests a size larger
       than these limits, the allocated Window will be resized down to at most these sizes.

   set_child_lines
   set_child_cols
          $box->set_child_lines( $size )

          $box->set_child_cols( $size )

       Convenient shortcut mutators that set both the minimum and maximum limit to the same
       value. This has the effect of forcing the size of the child widget.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>