=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Tickit::Widget::Table::Paged
at lib/Tickit/Widget/Table/Paged.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

Tickit::Widget::Table::Paged - table widget with support for scrolling/paging

=head1 VERSION

version 0.003

=head1 SYNOPSIS

 use Tickit;
 use Tickit::Widget::Table::Paged;

 my $tbl = Tickit::Widget::Table::Paged->new;
 $tbl->{row_offset} = 0;
 $tbl->add_column(
 	label => 'Left',
 	align => 'left',
 	width => 8,
 );
 $tbl->add_column(
 	label => 'Second column',
 	align => 'centre'
 );
 $tbl->add_row('left', 'middle') for 1..100;
 Tickit->new(root => $tbl)->run;

=head1 DESCRIPTION

B<WARNING>: This is a preview release. API is subject to change in future,
please get in contact if you're using this, or wait for version 1.000.

This widget provides a scrollable table implementation.

=begin HTML

<p><img src="http://tickit.perlsite.co.uk/cpan-screenshot/tickit-widget-table-paged1.gif" alt="Paged table widget in action" width="430" height="306"></p>

=end HTML

=head1 METHODS

=head2 new

Instantiate. Will attempt to take focus.

=head1 METHODS - Table content

=head2 clear

Clear all data in the table.

=head2 add_row

Add a row to the table. Data should be provided as a list with one item per
column.

Returns $self.

=head2 add_column

Add a new column. Takes the following named parameters:

=over 4

=item * width - (optional) number of columns

=item * type - (optional) data type, currently only supports 'text' (the default)

=item * align - (optional) align left, center or right

=back

Returns $self.

=head1 METHODS - Callbacks

=head2 on_activate

Accessor for the activation callback - if called without parameters,
will return the current coderef (if any), otherwise, will set the new
callback.

This callback will be triggered via L</key_activate>:

 $code->($row_index, $row_data_as_arrayref)

If multiselect is enabled, the callback will have the following:

 $code->(
   [$highlight_row_index, @selected_row_indices],
   $highlight_row_data_as_arrayref,
   @selected_rows_as_arrayrefs
 )

(the selected row data + index list could be empty here)

=head2 multi_select

Accessor for multi_select mode - when set, this allows multiple rows
to be selected.

=head1 METHODS - Other

=head2 lines

Number of lines to request.

=head2 cols

Number of columns to request.

=head2 vscroll

True if there's a vertical scrollbar.

=head2 hscroll

True if there's a horizontal scrollbar.

=head2 row_offset

Current row offset (vertical scroll position).

=head2 visible_lines

Returns the list of lines currently visible in the display.

=head2 header_rect

Returns the L<Tickit::Rect> representing the header area.

=head2 body_rect

Returns the L<Tickit::Rect> representing the body area.

=head2 scrollbar_rect

Returns the L<Tickit::Rect> representing the scroll bar.

=head2 render_header

Render the header area.

=head2 render_to_rb

Render the table.

=head2 render_body

Render the body area.

=head2 apply_column_widget

Add widgets for the column.

=head2 render_scrollbar

Render the scrollbar.

=head2 render_cell

Render a given cell.

=head2 reshape

Handle reshape requests.

=head2 distribute_columns

Distribute space between columns.

=head2 window_gained

Called when a window has been assigned to the widget.

=head2 expose_rows

Expose the given rows.

=head2 highlight_row

Returns the index of the currently-highlighted row.

=head2 highlight_visible_row

Returns the position of the highlighted row taking scrollbar into account.

=head2 scroll_highlight

Update scroll information after changing highlight position.

=head2 move_highlight

Change the highlighted row.

=head2 key_previous_row

Go to the previous row.

=head2 key_next_row

Move to the next row.

=head2 key_first_row

Move to the first row.

=head2 key_last_row

Move to the last row.

=head2 key_previous_page

Go up a page.

=head2 key_next_page

Go down a page.

=head2 scroll_position

Current vertical scrollbar position.

=head2 row_count

Total number of rows.

=head2 sb_height

Current scrollbar height.

=head2 scroll_rows

Positions of the scrollbar indicator.

=head2 active_scrollbar_rect

Rectangle representing the area covered by the current scrollbar.

=head2 scroll_dimension

Size of the vertical scrollbar.

=head2 key_next_column

Move to the next column.

=head2 key_previous_column

Move to the previous column.

=head2 key_first_column

Move to the first column.

=head2 key_last_column

Move to the last column.

=head2 key_activate

Activate the highlighted item.

=head2 key_select_toggle

Toggle selected row.

=head1 TODO

Current list of pending features:

=over 4

=item * Storage abstraction - the main difference between this widget and
L<Tickit::Widget::Table> is that this is designed to work with a storage
abstraction. The current abstraction implementation needs more work before
it's reliable enough for release, so this version only has basic arrayref
support.

=item * Column and cell highlighting modes

=item * Proper widget-in-cell support

=item * Formatters for converting raw cell data into printable format
(without having to go through a separate widget)

=item * Better header support (more than one row, embedded widgets)

=back

=head1 SEE ALSO

=over 4

=item * L<Tickit::Widget::Table> - older table implementation based on L<Tickit::Widget::HBox> and L<Tickit::Widget::VBox>
widgets. Does not support scrolling and performance isn't as good, so it will eventually be merged with this one.

=item * L<Text::ANSITable> - not part of L<Tickit> but has some impressive styling capabilities.

=back

=head1 INHERITED METHODS

=over 4

=item L<Tickit::Widget>

L<get_style_pen|Tickit::Widget/get_style_pen>, L<get_style_text|Tickit::Widget/get_style_text>, L<get_style_values|Tickit::Widget/get_style_values>, L<key_focus_next_after|Tickit::Widget/key_focus_next_after>, L<key_focus_next_before|Tickit::Widget/key_focus_next_before>, L<on_pen_changed|Tickit::Widget/on_pen_changed>, L<parent|Tickit::Widget/parent>, L<pen|Tickit::Widget/pen>, L<redraw|Tickit::Widget/redraw>, L<requested_cols|Tickit::Widget/requested_cols>, L<requested_lines|Tickit::Widget/requested_lines>, L<requested_size|Tickit::Widget/requested_size>, L<resized|Tickit::Widget/resized>, L<set_parent|Tickit::Widget/set_parent>, L<set_pen|Tickit::Widget/set_pen>, L<set_requested_size|Tickit::Widget/set_requested_size>, L<set_style|Tickit::Widget/set_style>, L<set_style_tag|Tickit::Widget/set_style_tag>, L<set_window|Tickit::Widget/set_window>, L<style_classes|Tickit::Widget/style_classes>, L<take_focus|Tickit::Widget/take_focus>, L<window|Tickit::Widget/window>, L<window_lost|Tickit::Widget/window_lost>

=back

=head1 AUTHOR

Tom Molesworth <cpan@entitymodel.com>

=head1 LICENSE

Copyright Tom Molesworth 2012-2013. Licensed under the same terms as Perl itself.
