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>

cpanm Tickit::Widgets

perl -MCPAN -e shell
install Tickit::Widgets