NAME

Gtk2::Ex::TreeMap - Implementation of TreeMap.

SYNOPSIS

        use Gtk2::Ex::TreeMap;
        my $values = [6,6,4,3,2,2,1];
        my $treemap = Gtk2::Ex::TreeMap->new([600,400]);
        $treemap->draw_map_simple($values);
        my $window = Gtk2::Window->new;
        $window->signal_connect(destroy => sub { Gtk2->main_quit; });
        $window->add($treemap->get_image);
        $window->show_all;
        Gtk2->main;

DESCRIPTION

Treemap is a space-constrained visualization of hierarchical structures. It is very effective in showing attributes of leaf nodes using size and color coding. http://www.cs.umd.edu/hcil/treemap/

The popular treemaps are;

        http://www.marumushi.com/apps/newsmap/newsmap.cfm
        http://codecubed.com/map.html the del.icio.us most popular treemap
        http://www.smartmoney.com/marketmap/

This module implements the TreeMap functionality in pure perl. Currently I have implemented only the Squarified TreeMap algorithm. Details of this algorithm can be found at http://www.win.tue.nl/~vanwijk/stm.pdf This algorithm was chosen because it produces aesthetically pleasing rectangles.

All the drawing is done using GD. But Gtk2 adds plenty of life, bells and whistles to the otherwise passive TreeMap png image.

METHODS

Gtk2::Ex::TreeMap->new([$width, $height]);

Just a plain old constructor. Accepts two arguments, $width and $height of the TreeMap.

        my $treemap = Gtk2::Ex::TreeMap->new([600,400]);

Gtk2::Ex::TreeMap->draw_map_simple($values);

Use this API to quickly build a treemap from a flat list of values. The colors of the rectangles are chosen internally. If you want to do anything serious, like specify colors, description etc, then use the draw_map($tree) api.

        my $values = [6,6,4,3,2,2,1];
        $treemap->draw_map_simple($values);

Gtk2::Ex::TreeMap->draw_map($tree);

This is the api that you will use most of the time. This one accepts a hierarchical tree structure as its input. I have chosen the tree format that is used by the XML::Simple module. This approach so that the tree can be easily constructed from an xml document.

Here is an example definition of the XML

        <Node>
                <Node>
                        <Node size="9" color="0,0,80" description="0 0"/>
                        <Node size="7" color="0,120,80" description="0 1"/>
                        <Node>
                                <Node size="9" color="0,0,100" description="0 2 0"/>
                                <Node size="9" color="0,0,110" description="0 2 1"/>
                                <Node>
                                        <Node size="8" color="0,0,100" description="0 2 2 0"/>
                                        <Node size="2" color="0,0,110" description="0 2 2 1"/>
                                </Node>
                        </Node>
                </Node>
                <Node>
                        <Node size="7" color="0,170,200" description="1 0"/>
                        <Node size="5" color="0,170,210" description="1 1"/>
                        <Node size="9" color="0,170,220" description="1 2"/>
                </Node>
        </Node> 

Now read this string using XML::Simple to derive the tree.

        my $tree = XMLin($xmlstr, ForceArray => 1);
        $treemap->draw_map($tree);

Note: It is very important to use the ForceArray option. Else you will end up with a variety of errors.

Gtk2::Ex::TreeMap->get_image

Returns the TreeMap image as a Gtk2::Image wrapped in a Gtk2::EventBox. You can add this to your own Gtk2 container

        my $window = Gtk2::Window->new;
        $window->add($treemap->get_image);
        $window->show_all;
        Gtk2->main;

TODO

  * Implement callback for mouse-over and clicked events
  * Implement popup box as a default option
  * Implement text in the rectangles
  * The boxes should probably be drawn with a black border
  * Build a new example using WWW::Google::News perhaps !
  * Once the module is done, may be I'll split it into a two; a pure GD module which 
    will be "used" by a Gtk2 module. That way, non-Gtk2 folks can use it, of course 
    without the popups and callbacks and all those bells and whistles.
  * More tests, more documentation.

AUTHOR

Ofey Aikon, <ofey_aikon at gmail dot com>

ACKNOWLEDGEMENTS

To the wonderful gtk-perl list.

COPYRIGHT & LICENSE

Copyright 2005 Ofey Aikon, All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.

cpanm Gtk2::Ex::TreeMap

perl -MCPAN -e shell
install Gtk2::Ex::TreeMap