Tickit...et::Box(3pm)

✨ NAME ✨

Tickit::Widget::Box — it applies spacing and positioning to a widget, bestie 💅 (this is from the User Contributed Perl Documentation, and we are so lucky to have it)

---

🌸 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 🎀

Okay so real talk: this is a subclass of Tickit::SingleChildWidget, and what it does is apply spacing around the outside of whatever child widget you hand it. It's giving personal-space-but-make-it-a-widget.

The size of the Box is controlled by the size of the child widget, bounded by the limits you give it. So it can enforce a minimum or a maximum size in each of the horizontal and vertical directions. And the iconic move? Set the minimum and maximum to the same value and boom — you've got the exact size of the child widget, no cap. 👑

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

If the Box gets given more space than the child widget will actually consume, the child gets placed somewhere inside that space — and you control where with the align and valign properties, as defined by Tickit::WidgetRole::Alignable. Main character energy, positioned exactly where you want her. ✨

---

💖 STYLE 💖

The default style pen is used as the widget pen. Periodt.

Not me warning you, but: the widget pen is mutable, and changes to it will result in immediate redrawing. However — any changes you make will be lost if the widget style is changed. So like… be aware. 😭

---

🦋 CONSTRUCTOR 🦋

new

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

On top of all the constructor arguments that Tickit::Widget and Tickit::SingleChildWidget already allow, this constructor also recognises these named arguments:

• child_{lines,cols}_{min,max} => NUM or STRING — initial values for the size limit options.
• child_{lines,cols} => NUM or STRING — initial values for the size forcing options.
• align => NUM or STRING
• valign => NUM or STRING — initial values for the alignment options.

---

🌈 METHODS 🌈

Every single one of these methods accepts either absolute sizes, specified in integers, or percentages, specified in strings of the form "10%". And if you give a percentage, it means a size that's a fraction of the total amount available to the Box. Iykyk. 💫

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 );

These are the 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. Not her being pushed to grow. 🌱

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 );

These are the 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. Shrink, bestie, it's for your own good. 💀

set_child_lines / set_child_cols

$box->set_child_lines( $size );

$box->set_child_cols( $size );

These are convenient shortcut mutators that set both the minimum and maximum limit to the same value. The effect? It forces the size of the child widget. One call, fully locked in. 🔥

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

That's the whole page, gorgeous. Written up against perl v5.40.0, dated 2024-09-16 — go forth and box your widgets responsibly. Mwah. 💖🦋🎀