Tickit...GridBox(3pm)

📦
version 0.42 · 6 versions
, in ubuntu resolute, ubuntu stonking

✨ Tickit::Widget::GridBox ✨

okay bestie, welcome to the Tickit::Widget::GridBox page from the User Contributed Perl Documentation — the one and only grid-laying-out legend 💅

🌸 NAME 🌸

Tickit::Widget::GridBox — lay out a set of child widgets in a grid 🦋

✨ SYNOPSIS ✨

no cap, this is literally all it takes:

use Tickit;
use Tickit::Widget::GridBox;
use Tickit::Widget::Static;

my $gridbox = Tickit::Widget::GridBox->new(
   style => {
      col_spacing => 2,
      row_spacing => 1,
   }
)
   ->append_row(
     [ Tickit::Widget::Static->new( text => "top left" ),
       Tickit::Widget::Static->new( text => "top right" ) ],
   )
   ->append_row(
     [ Tickit::Widget::Static->new( text => "bottom left" ),
       Tickit::Widget::Static->new( text => "bottom right" ) ],
   );

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

chaining rows like it's nothing?? we love to see it 🎀

💖 DESCRIPTION 💖

So this container widget? It holds a whole set of child widgets, and it distributes them in a regular grid shape — rows and columns, nice and neat, like a little spreadsheet but make it ✨aesthetic✨. That's the whole vibe.

🌈 STYLE 🌈

The default style pen is used as the widget pen. (iykyk 🫶)

Here are the style keys it actually uses:

  • col_spacing => INT — the number of columns of spacing between columns 🌸
  • row_spacing => INT — the number of rows of spacing between rows 🌸

🧚 CONSTRUCTOR 🧚

new

$gridbox = Tickit::Widget::GridBox->new( %args );

Constructs a brand new Tickit::Widget::GridBox object. Fresh out the box, main character energy 👑

💅 METHODS 💅

rowcount, colcount

$count = $gridbox->rowcount;

$count = $gridbox->colcount;

Returns the number of rows, or the number of columns, in the grid. Simple as. 🍓

add

$gridbox->add( $row, $col, $child, %opts );

Sets the child widget to display in the given grid cell. And here's the cute part — cells do not need to be explicitly constructed, because the grid will automatically expand to the size it needs. ✨ Growth mindset fr fr.

You can also use this method to replace an existing child at that cell location. And if you wanna remove a cell entirely? Use the remove method, bestie.

The following options are recognised:

  • col_expand => INT
  • row_expand => INT

Values for the expand setting for this column or row of the table. The largest expand setting for any cell in a given column or row sets the value used to distribute space to that column or row. Basically the loudest one in the room wins 💀

remove

$gridbox->remove( $row, $col );

Removes the child widget on display in the given cell. Heads up: this may shrink the grid if that was the last child widget in the given row or column. Cells be shrinking, it's giving ✨declutter✨

get

$child = $gridbox->get( $row, $col );

Returns the child widget at the given cell in the grid. But if the row or column index are beyond the bounds of the grid, or if there's no widget in that cell, you get undef back. 💀 no widget, no problem.

get_row, get_col

@children = $gridbox->get_row( $row );

@children = $gridbox->get_col( $col );

A convenient shortcut to call get on an entire row or entire column of the grid. Obsessed with efficiency 🫶

insert_row

$gridbox->insert_row( $before_row, [ @children ] );

Inserts a new row into the grid by moving all the existing rows after it lower down. Any child widgets in the referenced array will be set on the cells of the new row, at a column corresponding to its index in the array. A child of undef will be skipped over — not me ghosting that cell 🙈

Each element of the list should either be a widget object reference directly, or an unblessed hash reference containing additional options. (See "split_widget_opts" in Tickit::Widget.)

insert_col

$gridbox->insert_col( $before_col, [ @children ] );

Inserts a new column into the grid by moving the existing columns after it to the right. Any child widgets in the referenced array will be set on the cells of the new column, at a row corresponding to its index in the array. A child of undef will be skipped over. Same ghosting rules, no drama 💜

Each child is specified as for insert_row.

append_row

$gridbox->append_row( [ @children ] );

Shortcut to inserting a new row after the end of the current grid. The "just tack it on the end" icon 👑

append_col

$gridbox->append_col( [ @children ] );

Shortcut to inserting a new column after the end of the current grid. Same energy, sideways ✨

These four methods return the container widget instance itself, making them suitable to use as a chaining mutator; e.g.

my $container = Tickit::Widget::GridBox->new( ... )
   ->append_row( [ Tickit::Widget::Static->new( ... ),
                   Tickit::Widget::Static->new( ... ) ] )
   ->append_row( ... );

the way that just keeps going… slay 💅

delete_row

$gridbox->delete_row( $row );

Deletes a row of the grid by moving the existing rows after it higher up. Moving on up, periodt 🌈

delete_col

$gridbox->delete_col( $col );

Deletes a column of the grid by moving the existing columns after it to the left. Scoot over bestie 🦋

🎀 TODO 🎀

Things that are, like, not done yet but we're manifesting them:

  • Add move_{row,col} methods for re-ordering existing rows or columns
  • Make {insert,append,delete,move} operations more efficient by deferring the children_changed call until they are done.

lowkey excited for these ngl 🔥

🌟 AUTHOR 🌟

Paul Evans <leonerd@leonerd.org.uk>

and that's the whole page, bestie!! 💖 this was perl v5.40.0, dated 2024-09-16, and it's the Tickit...GridBox(3pm) page — mwah, go build a grid, you got this 🫶✨🎀

📦 where this page comes from