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


This document refers to verion 1.5 of Graph::Timeline::DiagonalGD, September 29, 2009


This class is used to clear charts where earliest starting event is at the top of the page and the next event to start follows it (and so on). For each event a box is drawn relative to the length of the event. You get something like this:

 first event      : XX
 second event     :  XXXXX
 third event      :    XX
 fourth event:    :     XXXXXX

Optionally a client side imagemap can be generated for the events that have a url defined.

An example of usage follows. Note that the labels down the left hand side are based on the id attribute and the colour of the event box on the label.


 use strict;
 use warnings;

 use Graph::Timeline::DiagonalGD;

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

 while ( my $line = <> ) {

      next if $line =~ m/^\s*$/;
      next if $line =~ m/^\s*#/;
      my ( $id, $label, $start, $end, $url ) = split( ',', $line );
      $x->add_interval( label => $label, start => $start, end => $end, id => $id, url => $url );

 my %render = (
   'graph-width' => 400,
   'label-width' => 150,
   'border'      => 10,
   'colours'     => {
      'Ended_Successfully' => [ 128, 128, 128 ],
      'Failed'             => [ 255, 0,   0 ]

 open( FILE, '>test_diagonal1.png' );
 print FILE $x->render(%render);

 open( FILE, '>' );
 print FILE $x->map( 'box', 'image1' );


Render a diagonal event graph based on the input data.


The render method controls the display. This is inturn controlled by the parameters that are passed in to it.

Constructors and initialisation

new( )

Inherited from Graph::Timeline

Public methods

render( HASH )

The hight of the image created will be 20 pixels per event reported plus 40 pixels for the title, plus an additional 2 * border. The width of the image will be 2 * border + label-width + graph-width.


The number of pixels to use as a border around the graph. If omitted will be set to 0.


The number of pixels used to display the id of the event.


The number of pixels within which the events will be drawn.


When an event is rendered the label is used as a key to this hash to return a list of values to use for the colour for that event:

  'colours' => {
    'Ended_Successfully' => [ 128, 128, 128 ],
    'Failed'             => [ 255, 0,   0 ]

The values are for the RGB triplet, if no value is supplied for a label the event will be draw in black.

map( style, name )

Produce a client side imagemap for the data that has a url defined.


There are two styles available. 'line' or 'box'. For line the clickable area is the whole line that the event occurs on. For box the clickable area is the box drawn for the event plus 5 pixels to the left and right.


This is the name that will be used for the imagemap

Private methods


A method to calculate the duration of an event in seconds.


The the events are within one day return just a day to use as the title, if they span more than one day return a string 'start TO end' to display as the title.




Timeline->new() takes no arguments

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

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

Render expects a hash and did not get one

Timeline::DiagonalGD->render() 'graph-width' and 'label-width' must be defined

Both of these parameters must be defined.

Timeline::DiagonalGD->render() there is not enough data to render

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

Timeline::DiagonalGD->render() Date range spans into months or years. No can do

It is assumed that the data will span, at best, a few days. More than that and we can't realy draw this graph.

Timeline::DiagonalGD->map() Unknown map style, use 'line' or 'box'

Maps come in type styles, 'line' or 'box'. You tried to use something else

Timeline::DiagonalGD->map() The map requires a name

You must supply a name for the map




See the diagonal script in the examples directory


Graph::Timeline - The core timeline class


Peter Hickman (


Copyright (c) 2007, 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.