view release on metacpan or  search on metacpan

lib/Data/Page/Viewport.pm  view on Meta::CPAN

	my(@bound);

	for (-2, 1, 4, 4, 1, 3, 3, -2, 1, 2, 1, -4, -4,
		-1, 1, 2, -1, -2, -2, -1, -4, 4, 4, 4)
	{
		print "Offset: $_. \n";

		@bound = $page -> offset($_) -> bounds();

		print "Page bounds: $bound[0] .. $bound[1]. \n";
		print 'Page data:   ',
			join(', ', @data[$bound[0] .. $bound[1] ]),
			". \n";
		print '-' x 50, "\n";
	}

=head1 Description

C<Data::Page::Viewport> is a pure Perl module.

This module keeps track of what items are on the 'current' page,
when you scroll forwards or backwards within a data set.

Similarly to Data::Page, you can call C<sub offset(N)>, for + or - N, to
scroll thru the data a page at a time.

And, like Set::Window, you can call C<sub offset(N)>, for + or - 1,
to scroll thru the data an item at a time.

Clearly, N does not have to be fixed.

The viewport provides access to the 'current' page, and the code shifts
indexes into and out of the viewport, according to the parameter passed
to C<sub offset()>.

Note that the data is I<not> passed into this module. The module only keeps
track of the indexes within the viewport, i.e. indexes on the 'current'
page.

You call C<sub bounds()> on the object (of type C<Set::Window>) returned by
C<sub offset()>, to determine what indexes are on the 'current' page at any
particular point in time.

Also note that, unlike Set::Window, the boundaries of the viewport are
rigid, so that changes to the indexes caused by C<sub offset()> are
limited by the size of the data set.

This means, if you do this:

	my($page) = Data::Page::Viewport -> new
	(
	    data_size => $#data,     # 0 .. $#data.
	    page_size => $page_size, # 1 .. N.
	);

	my(@bound) = $page -> offset(- 1) -> bounds();

the call to C<sub offset(- 1)> will have no effect.

That is, when trying to go back past the beginning of the data set, the
bounds will be locked to values within 0 .. data_size.

Similarly, a call which would go beyond the other end of the data set,
will lock the bounds to the same range.

In short, you can't fall off the edge by calling C<sub offset()>.

This in turn means that the values returned by C<sub bounds()> will
always be valid indexes within the range 0 .. data_size.

The module implements this by building 2 objects of type Set::Window,
one for the original data set (which never changes), and one for the
'current' page, which changes each time C<sub offset()> is called
(until the boundaries are hit, of course).

Note: No range checking is performed on the parameters to C<sub new()>.

Note: It should be obvious by now that this module differs from Data::Page,
and indeed all such modules, in that they never change the items which are
on a given page. They only allow you to change the page known as the
'current' page. This module differs, in that, by calling
C<sub offset(+ or - N)>, you are effectively changing the items which are
deemed to be on the 'current' page.

=head1 Distributions

This module is available both as a Unix-style distro (*.tgz) and an
ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for
help on unpacking and installing each type of distro.

=head1 Constructor and initialization

new(...) returns a C<Data::Page::Viewport> object.

This is the class's contructor.

Parameters:

=over 4

=item data_size

This is the upper limit on the indexes controlled by the viewport.

The lower limit is assumed to be 0.

This parameter is mandatory.

=item old_style

This controls whether you get the old style or new style scrolling.

The two types of scrolling are explained next, assuming you have tied the
up and down arrow keys to scrolling via user input, and assuming you highlight
the 'current' record. This just makes it easier to explain.

=over 4