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

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.40.0                                       2024-09-16                           Tickit::Widget::Box(3pm)

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.

       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.

       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_minset_child_lines_minchild_cols_minset_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_maxset_child_lines_maxchild_cols_maxset_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_linesset_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.

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

       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.

          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;