view release on metacpan or  search on metacpan

lib/Gtk2/Ex/TreeMaker.pm  view on Meta::CPAN

package Gtk2::Ex::TreeMaker;

our $VERSION = '0.11';

use strict;
use warnings;
use Glib qw(TRUE FALSE);
use Gtk2::Ex::TreeMaker::FlatInterface;
use Data::Dumper;

=head1 NAME

Gtk2::Ex::TreeMaker - A high level widget to represent a set of relational records in a hierarchical spreadsheet kinda display. This task is typical to most of the business application user interfaces.

=head1 DESCRIPTION

Typically in business applications, users like to view data in a spreadsheet kind of display. (Columns represent timeline(typically) and rows represent measures like sales/inventory/blah/blah).

The data itself is typically stored internally as relational records. For example, here is some sales info (stored internally in a relational database)

	-------------------------------------
	Region, City, Product, Date, Quantity
	-------------------------------------
	Texas, Dallas, Fruits, Dec-2003, 300
	Texas, Dallas, Veggies, Jan-2004, 120
	Texas, Austin, Fruits, Nov-2003, 310
	Texas, Austin, Veggies, Feb-2004, 20
	-------------------------------------

The user will typically want to view the same data in a hierarchical(/spreadsheet) kinda display.

	------------------------------------------------------
	Prod / Date   Nov-2003  Dec-2003  Jan-2004  Feb-2004 
	------------------------------------------------------
	Texas
	  Dallas
		Fruits                  300             
		Veggies                           120 
	  Austin
		Fruits        310
		Veggies                                     20
	------------------------------------------------------

With web-based business apps, similar views are created in the browser using lots of html/jsp coding.

The Gtk2::TreeView is an excellent widget to display a similar presentation of data in a desktop app. But creating a (hierarchical) TreeView from flat relational data can require some recursive function coding. It would be great if all this recursive...

This high level widget is designed with that purpose in mind. This module will accept a relational feed of records and automatically convert it into a hierarchical treeview using the Gtk2::TreeView. The process involves invoking some recursive functi...

Details on the widget including a screenshot can be found at: http://ofey.blogspot.com/2005/02/gtk2extreemaker.html

=head1 SYNOPSIS

	use Gtk2 -init;
	use Gtk2::Ex::TreeMaker;

	# Create an array to contain the column_names. These names appear as the header for each column.
	# The first entry should be the title of the left side of the FreezePane.
	my $column_names = [
		'Name',
		'Nov-2003', 'Dec-2003', 'Jan-2004', 'Feb-2004'
	];

	# This api will have to be cleaned soon...
	# All the attributes of the cell in the treeview are specified here
	# The value for these attributes are to be populated from the recordset
	# The assumption is that the attributes are contained in the data record
	# in the same order towards the **end** of the record. (the last few fields)
	# Since we are using CellRendererText in the TreeView, any of the properties
	# of the CellRendererText can be passed using this mechanism
	# In addition to the properties of the CellRendererText, I have also added a
	# custom property called 'hyperlinked'.
	my $data_attributes = [
		{'text' => 'Glib::String'},
		{'editable' => 'Glib::Boolean'},
		{'hyperlinked' => 'Glib::Boolean'}, 
		{'background' => 'Glib::String'}, 
	];

	# Here is the set of relational records to be displayed
	my $recordset = [
		['Texas','Dallas','Fruits','Dec-2003','300',0,1,'red'],
		['Texas','Dallas','Veggies','Jan-2004','120',1,0,'blue'],
		['Texas','Austin','Fruits','Nov-2003','310',1,1,'white'],
		['Texas','Austin','Veggies','Feb-2004','20',0,1,'green']
	];

	# Initialize our new widget
	# The constructor requires two attributes
	# This constitutes of the $column_name and the $data_attributes as described above
	my $treemaker = Gtk2::Ex::TreeMaker->new($column_names, $data_attributes);

	# We will inject our relational recordset into the new widget
	$treemaker->set_data_flat(\@recordset);

	# Build the model
	$treemaker->build_model;

	# Create a root window to display the widget
	my $window = Gtk2::Window->new;
	$window->signal_connect(destroy => sub { Gtk2->main_quit; });

	# Add the widget to the root window
	$window->add($treemaker->get_widget());

	$window->set_default_size(500, 300);