org.gicentre.treemappa
Class TreeMappa

java.lang.Object
  org.gicentre.treemappa.TreeMappa

public class TreeMappa
extends java.lang.Object

Class to read tree data and create treemaps and treemap output files.

Version:

3.0.1, 4th April, 2011.

Author:

Jo Wood, giCentre.

Constructor Summary

TreeMappa(TreeMapProperties props)
Creates an object capable of creating a treemap from the hierarchical data identified in the given properties.

Method Summary

boolean	buildTreeMap() Builds the treemap from the hierarchical data stored in this object.
TreeMapPanel	createPanel() Creates a panel in which the treemap is displayed.
TreeFrame	createWindow() Creates a window in which the treemap is displayed.
TreeMapProperties	getConfig() Provides the configuration options used to create the treemap.
boolean	getNeedsRebuilding() Reports whether or not the treemap needs building.
TreeMapNode	getRoot() Provides the root node of the treeMap.
javax.swing.tree.TreeModel	getTreeModel() Provides a TreeModel tree model view of this treemap object.
boolean	readData() Reads in the data from the file identified in the treemap configuration file provided to the constructor.
boolean	readData(PTreeMappa pTreeMappa) Reads in the data from the file identified in the given PTreeMappa object.
boolean	setAlignment(int level, java.lang.String alignment) Sets the alignment setting for the given level of the treemap.
boolean	setAlignments(java.lang.String alignment) Sets the alignment settings for all levels within the treemap.
boolean	setBorder(int level, float borderSize) Sets the border size of the nodes at the given level in the treemap.
boolean	setBorders(double borderSize) Sets the border size of the treemap.
boolean	setHeight(float height) Sets the new height of the treemap.
boolean	setLayout(int level, java.lang.String layout) Sets the new layout for the given level in the treemap.
boolean	setLayouts(java.lang.String layout) Sets the a new default layout for the treemap.
void	setRoot(TreeMapNode root) Sets the new tree data to be represented by the treemap.
boolean	setWidth(float width) Sets the new width of the treemap.
boolean	showStatistics() Display the summary statistics describing the treemap.
boolean	writeImage() Saves the treeMap displayed in the treeMap window as an image file.
boolean	writeOutput() Saves the current treeMap as a file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreeMappa

public TreeMappa(TreeMapProperties props)

Creates an object capable of creating a treemap from the hierarchical data identified in the given properties. These properties can also specify the appearance and output format of the treemap.

Parameters:

props - Properties defining the data and appearance associated with the treemap.

Method Detail

readData

public boolean readData()

Reads in the data from the file identified in the treemap configuration file provided to the constructor.

Returns:

True if data read without problems.

readData

public boolean readData(PTreeMappa pTreeMappa)

Reads in the data from the file identified in the given PTreeMappa object. This version is used when reading data from a Processing applet and avoids security exceptions by assuming data are stored in the Processing applet location.

Parameters:

pTreeMappa - Processing interface to treemappa that handles files.

Returns:

True if data read without problems.

buildTreeMap

public boolean buildTreeMap()

Builds the treemap from the hierarchical data stored in this object. The size of the treemap is determined by configuration properties supplied to the constructor. This method should only be called after readData() has been called to store the hierarchical data to map.

Returns:

True if the tree has been built without problems.

writeOutput

public boolean writeOutput()

Saves the current treeMap as a file. This might be a shapefile or text file depending on options specified by the configuration properties supplied to the constructor.

Returns:

True if output written successfully.

createWindow

public TreeFrame createWindow()

Creates a window in which the treemap is displayed.

Returns:

New window created or null if there was a problem creating treeMap window.

createPanel

public TreeMapPanel createPanel()

Creates a panel in which the treemap is displayed. This method can be used if you wish to incorporate a treemap display inside its own GUI.

Returns:

Panel in which the treemap is displayed or null if problem creating treemap panel.

getRoot

public TreeMapNode getRoot()

Provides the root node of the treeMap. The root should contain links to all its children and therefore the entire treemap.

Returns:

Root of the treemap or null if the treemap has not yet been built.

setRoot

public void setRoot(TreeMapNode root)

Sets the new tree data to be represented by the treemap. Note that the new treemap will not be created until a call to buildTreeMap() is made.

Parameters:

root - Root of the tree to be represented as a treemap.

writeImage

public boolean writeImage()

Saves the treeMap displayed in the treeMap window as an image file. The name of the file should be specified in the configuration properties supplied to the constructor.

Returns:

True if image written successfully.

showStatistics

public boolean showStatistics()

Display the summary statistics describing the treemap.

Returns:

True if summary statistics were able to be calculated.

getConfig

public TreeMapProperties getConfig()

Provides the configuration options used to create the treemap. Note that these properties will reflect any programmatic changes that have been made that affect the treemap. For example, if setWidth() or setBorder() have been called, the configuration options will reflect these new properties.

Returns:

Configuration options used to create the treemap.

getTreeModel

public javax.swing.tree.TreeModel getTreeModel()

Provides a TreeModel tree model view of this treemap object. Can be used for Swing components that require a TreeModel.

Returns:

TreeModel view of this tree, or null if the treemap has not yet been created.

getNeedsRebuilding

public boolean getNeedsRebuilding()

Reports whether or not the treemap needs building. It will need rebuilding if (a) it has not yet been created, or (b) some property that affects layout has been changed, such as the layout algorithm or the border size. The treemap can be rebuilt with a call to buildTreeMap(). Note that if you make changes to one or more of the TreeMapNodes dirctly (ie not via one of the methods in this class) this may require a rebuilding of the tree before they come into effect even if this method returns false.

Returns:

True if the treemap needs rebuilding.

setAlignments

public boolean setAlignments(java.lang.String alignment)

Sets the alignment settings for all levels within the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

alignment - Alignment setting to use. Valid values are 'horizontal', 'vertical' and 'free'.

Returns:

True if new property is updated successfully.

setAlignment

public boolean setAlignment(int level,
                            java.lang.String alignment)

Sets the alignment setting for the given level of the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

level - Level of the hierarchy at which the given border setting is to apply.

alignment - Alignment setting to use. Valid values are 'horizontal', 'vertical' and 'free'.

Returns:

True if new property is updated successfully.

setBorders

public boolean setBorders(double borderSize)

Sets the border size of the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

borderSize - Border size used to separate treemap nodes.

Returns:

True if new property is updated successfully.

setBorder

public boolean setBorder(int level,
                         float borderSize)

Sets the border size of the nodes at the given level in the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

level - Level of the hierarchy at which the given border setting is to apply.

borderSize - Border size used to separate treemap nodes.

Returns:

True if new property is updated successfully.

setLayouts

public boolean setLayouts(java.lang.String layout)

Sets the a new default layout for the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

layout - Name of new layout algorithm to use.

Returns:

True if new property is updated successfully.

setLayout

public boolean setLayout(int level,
                         java.lang.String layout)

Sets the new layout for the given level in the treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

level - Level of the hierarchy at which the given layout setting is to apply.

layout - Name of new layout algorithm to use.

Returns:

True if new property is updated successfully.

setWidth

public boolean setWidth(float width)

Sets the new width of the treemap. This may or may not correspond to real pixel coordinates depending on whether a TreeMapPanel has been created to display this treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

width - New width of of the treemap.

Returns:

True if new property is updated successfully.

setHeight

public boolean setHeight(float height)

Sets the new height of the treemap. This may or may not correspond to real pixel coordinates depending on whether a TreeMapPanel has been created to display this treemap. Note that since this operation requires the recalculation of the treemap layout, no changes will be made until buildTreeMap() is called.

Parameters:

height - New height of of the treemap.

Returns:

True if new property is updated successfully.