NAME

       "Tickit::Widget::GridBox" - lay out a set of child widgets in a grid

SYNOPSIS

          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;

DESCRIPTION

       This container widget holds a set of child widgets distributed in a regular grid shape across rows and
       columns.

STYLE

       The default style pen is used as the widget pen.

       The following style keys are used:

       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 new "Tickit::Widget::GridBox" object.

METHODS

   rowcount
   colcount
          $count = $gridbox->rowcount;

          $count = $gridbox->colcount;

       Returns the number of rows or columns in the grid.

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

       Sets  the child widget to display in the given grid cell. Cells do not need to be explicitly constructed;
       the grid will automatically expand to the size required. This method can  also  be  used  to  replace  an
       existing child at the given cell location. To remove a cell entirely, use the "remove" method.

       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.

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

       Removes the child widget on display in the given cell. May shrink the grid if this  was  the  last  child
       widget in the given row or column.

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

       Returns  the child widget at the given cell in the grid. If the row or column index are beyond the bounds
       of the grid, or if there is no widget in the given cell, returns "undef".

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

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

       Convenient shortcut to call "get" on an entire row or column of the grid.

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

       Inserts a new row into the grid by moving 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 an column corresponding to its index in  the
       array. A child of "undef" will be skipped over.

       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.

       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.

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

       Shortcut to inserting a new column after the end of the current grid.

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

   delete_row
          $gridbox->delete_row( $row );

       Deletes a row of the grid by moving the existing rows after it higher up.

   delete_col
          $gridbox->delete_col( $col );

       Deletes a column of the grid by moving the existing columns after it to the left.

TODO

       •   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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.36.0                                       2024-01-02                       Tickit::Widget::GridBox(3pm)