NAME

Graph::Timeline::GD - Render timeline data with GD

VERSION

This document refers to verion 1.1 of Graph::Timeline::GD, released January 26, 2004

SYNOPSIS

This subclass produces the GD object of the timeline. The user has to subclass from this class if they want a GD rendering of the timeline data. By overriding the render_year( ), render_point( ) and render_interval( ) methods the user can supply a less garish and more pleasing display.

use Graph::Timeline::GD;

my $x = Graph::Timeline::GD->new();

while ( my $line = <> ) {
  chomp($line);

  my ( $label, $start, $end, $group ) = split ( ',', $line );
  if($end) {
    $x->add_interval( label => $label, start => $start, end => $end, group => $group );
  }
  else {
    $x->add_point( label => $label, start => $start, group => $group );
  }
}

$x->window(start=>'1900/01/01', end=>'1999/12/31');

open(FILE, '>test.png');
binmode(FILE);
print FILE $x->render( border => 2, pixelsperyear => 35 );
close(FILE);

All the user needs to do is create a package that subclasses Graph::Timeline::GD

package MyTimeLine;

use base Graph::Timeline::GD;

sub render_year { ... }

sub render_interval { ... }

sub render point { ... }

1;

The default methods in Graph::Timeline::GD will show you how to write your own methods and the timeline script in the examples directory will show you how read in data, set up the timeline and draw various graphs with it.

DESCRIPTION

Overview

Only three methods need to be overridden to create your own GD image of the data.

render_year( YEAR )

The years that form the axis of the graph are rendered by render_year( ). A scalar pointing to the data for the year to be rendered is passed to the method. All you have to do is create an image of the correct size and decorate it.

render_interval( RECORD )

To render an interval this method takes the record of the interval. RECORD is a pointer to a hash that contains the all the data you should require, the important ones are:

width

This the width of the required image.

label

The label that came from the data.

group

The group that the interval belongs to.

Additionally the following are also defined but you may have no need for them

end, end_start, end_end, width_post

End is the end date as defined in the data, end_start and end_end define a subinterval that the end of the data occured in. For example if the end date is 1980/12/15 then end, end_start and end_end will be the same and width_post will be 0. However should the end date be an interval like 1980/12 (something during December 1980) then end_start will be 1980/12/01 and end_end will be 1980/12/31. Width_post will contain the number of pixels that represent the width of the subinterval.

start, start_start, start_end, width_pre

The same subinterval messing about for the start date as for the end date (defined above).

render_point( RECORD )

Just the same as render_interval but with the addition of the sequence data, as points are rendered they are numbered sequentualy from 1.

Constructors and initialisation

new( )

Inherited from Graph::Timeline

Public methods

render( HASH )

The method called to return the rendered image. This takes a hash of configuration options however only one of the pixelsper* keys can be supplied (being as they are mutually exclusive) and border is optional.

border

The number of pixels to use as a border around the graph.

pixelsperyear

The number of pixels the year will be rendered in

pixelspermonth

The number of pixels to render a month in, the number of pixels a year will be this value times twelve

pixelsperday

The number of pixels to render a day in, the number of pixels in a year will be calculated from this

render_year( SCALAR )

Override this method to render a year.

render_interval( SCALAR )

Override this method to render an interval.

render_point( SCALAR )

Override this method to render a point.

Private methods

_calculate_width

A method to calculate the width in pixels of an interval

_calc_start_x

A method to calculate at what offset a year, interval or point should be placed in the final image

_get_start_and_end

A method to find the first and last date

ENVIRONMENT

None

DIAGNOSTICS

Timeline->new() takes no arguments

When the constructor is initialised it requires no arguments. This message is given if some arguments were supplied.

Timeline::GD->render() expected HASH as parameter

Render expects a hash and did not get one

Timeline::GD->render() one of 'pixelsperlday', 'pixelsperlmonth' or 'pixelsperyear' must be defined

One of the required parameters needs to be defined

Timeline::GD->render() only one of 'pixelsperlday', 'pixelsperlmonth' or 'pixelsperyear' can be defined

Only on parameter can be defined

Timeline::GD->render() key 'height' is not defined from render_year()

The method that renders the year has not set the height key, this is required

Timeline::GD->render() key 'height' is not defined from render_interval()

The method that renders an interval has not set the height key, this is required

Timeline::GD->render() there is no data to render

None of the input data got passed through the call to window()

BUGS

None

FILES

See the timeline script in the examples directory

SEE ALSO

Graph::Timeline - The core timeline class

AUTHORS

Peter Hickman (peterhi@ntlworld.com)

COPYRIGHT

Copyright (c) 2003, Peter Hickman. All rights reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

cpanm Graph::Timeline

perl -MCPAN -e shell
install Graph::Timeline