org.geotoolkit.gui.swing.tree
Class TreeFormat

Object
  Format
      TreeFormat

All Implemented Interfaces:

Serializable, Cloneable

public class TreeFormat
extends Format

A parser and formatter for a tree of nodes. This class can format any of the following types:

• TreeModel (more info)
• TreeNode as the root node of a tree (more info)
• Iterable as a collection of children nodes (not including the root) (more info)

The result is a tree in String form like the example below:

Node #1
├───Node #2
│   └───Node #4
└───Node #3

If the table format is enabled and the tree nodes are instances of TreeTableNode, then the output format will be like the example below:

Node #1……………………… More #1
├───Node #2…………… More #2
│   └───Node #4… More #4
└───Node #3…………… More #3

This representation can be printed to the standard output stream (for example) if it uses a monospaced font and supports unicode. Indentation and position of the vertical line can be modified by calls to the setter methods.

Since:

3.18 (derived from 2.0)

Version:

3.19

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Serialized Form

Module:

utility/geotk-utility (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class Format

Format.Field

Constructor Summary

TreeFormat()
Creates a new format.

Method Summary

void	format(Iterable<?> nodes, Appendable toAppendTo) Writes a graphical representation of the specified elements in the given buffer.
void	format(Iterable<?> nodes, StringBuilder toAppendTo) Convenience method which delegate to the above format(Iterable, Appendable) method, but without throwing IOException.
StringBuffer	format(Object tree, StringBuffer toAppendTo, FieldPosition pos) Writes a graphical representation of the specified tree in the given buffer.
void	format(TreeModel tree, Appendable toAppendTo) Writes a graphical representation of the specified tree model in the given buffer.
void	format(TreeModel tree, StringBuilder toAppendTo) Convenience method which delegate to the above format(TreeModel, Appendable) method, but without throwing IOException.
void	format(TreeNode node, Appendable toAppendTo) Writes a graphical representation of the specified tree in the given buffer.
void	format(TreeNode node, StringBuilder toAppendTo) Convenience method which delegate to the above format(TreeNode, Appendable) method, but without throwing IOException.
char	getColumnSeparator() Returns the character used as column separator.
int	getIndentation() Returns the number of spaces to add on the left margin for each indentation level.
String	getLineSeparator() Returns the current line separator.
int	getVerticalLinePosition() Returns the position of the vertical line, relative to the position of the root label.
boolean	isTableFormatEnabled() Returns true if this TreeFormat is allowed to format the tree using many columns.
MutableTreeNode	parse(LineReader input) Creates a tree from the lines read from the given input.
MutableTreeNode	parseObject(String text) Creates a tree from the given string representation.
MutableTreeNode	parseObject(String text, ParsePosition pos) Creates a tree from the given string representation, or returns null if an error occurred while parsing the tree.
void	setColumnSeparator(char separator) Sets the column character to insert between the columns in a TreeTableNode.
void	setIndentation(int indentation) Sets the number of spaces to add on the left margin for each indentation level.
void	setLineSeparator(String separator) Sets the line separator.
void	setTableFormatEnabled(boolean enabled) Sets whatever this TreeFormat is allowed to format the tree as a table.
void	setVerticalLinePosition(int verticalLinePosition) Sets the position of the vertical line, relative to the position of the root label.

Methods inherited from class Format

clone, format, formatToCharacterIterator

Methods inherited from class Object

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

Constructor Detail

TreeFormat

public TreeFormat()

Creates a new format.

Method Detail

getIndentation

public int getIndentation()

Returns the number of spaces to add on the left margin for each indentation level. The default value is 4.

Returns:

The current indentation.

setIndentation

public void setIndentation(int indentation)
                    throws IllegalArgumentException

Sets the number of spaces to add on the left margin for each indentation level. If the new indentation is smaller than the vertical line position, then the later is also set to the given indentation value.

Parameters:

indentation - The new indentation.

Throws:

IllegalArgumentException - If the given value is negative.

getVerticalLinePosition

public int getVerticalLinePosition()

Returns the position of the vertical line, relative to the position of the root label. The default value is 0, which means that the vertical line is drawn below the first letter of the root label.

Returns:

The current vertical line position.

setVerticalLinePosition

public void setVerticalLinePosition(int verticalLinePosition)
                             throws IllegalArgumentException

Sets the position of the vertical line, relative to the position of the root label. The given value can not be greater than the indentation.

Parameters:

verticalLinePosition - The new vertical line position.

Throws:

IllegalArgumentException - If the given value is negative or greater than the indentation.

getLineSeparator

public String getLineSeparator()

Returns the current line separator. The default value is system-dependent.

Returns:

The current line separator.

setLineSeparator

public void setLineSeparator(String separator)

Sets the line separator.

Parameters:

separator - The new line separator.

getColumnSeparator

public char getColumnSeparator()

Returns the character used as column separator. This character will be inserted between the columns only if the table format is enabled and the tree to format contains TreeTableNode elements.

The default value if '…'.

Returns:

The column separator.

Since:

3.19

setColumnSeparator

public void setColumnSeparator(char separator)

Sets the column character to insert between the columns in a TreeTableNode.

Parameters:

separator - The column separator.

Since:

3.19

isTableFormatEnabled

public boolean isTableFormatEnabled()

Returns true if this TreeFormat is allowed to format the tree using many columns. The default value is false. Setting this property to true is useful only if the tree to format contains TreeTableNode elements.

Returns:

true if this TreeFormat object is allowed to format many columns.

Since:

3.19

setTableFormatEnabled

public void setTableFormatEnabled(boolean enabled)

Sets whatever this TreeFormat is allowed to format the tree as a table.

NOTE: parsing of table format is not yet implemented.

Parameters:

enabled - true for enabling the table format.

Since:

3.19

parseObject

public MutableTreeNode parseObject(String text,
                                   ParsePosition pos)

Creates a tree from the given string representation, or returns null if an error occurred while parsing the tree.

The default implementation delegates to parseObject(String).

Specified by:

parseObject in class Format

Parameters:

text - The string representation of the tree to parse.

pos - The position when to start the parsing.

Returns:

The root of the parsed tree, or null if the given tree can not be parsed.

parseObject

public MutableTreeNode parseObject(String text)
                            throws ParseException

Creates a tree from the given string representation. This method can parse the trees created by the format(...) methods defined in this class.

The default implementation delegates to parse(LineReader).

Overrides:

parseObject in class Format

Parameters:

text - The string representation of the tree to parse.

Returns:

The root of the parsed tree.

Throws:

ParseException - If an error occurred while parsing the tree.

parse

public MutableTreeNode parse(LineReader input)
                      throws IOException

Creates a tree from the lines read from the given input. This method can parse the trees created by the format(...) methods defined in this class.

Parsing rules
Each node must have at least one '─' character (unicode 2500) in front of it. The number of spaces and drawing characters ('│', '├' or '└') before the node determines its indentation, and the indentation determines the parent of each node.

Parameters:

input - A LineReader for reading the lines.

Returns:

The root of the parsed tree.

Throws:

IOException - If an error occurred while parsing the tree.

format

public void format(TreeModel tree,
                   Appendable toAppendTo)
            throws IOException

Writes a graphical representation of the specified tree model in the given buffer. This method iterates recursively over all children. Each children is fetched by a call to TreeModel.getChild(Object, int) and its string representation (expected to uses a single line) is created by a call to String.valueOf(Object).

Parameters:

tree - The tree to format.

toAppendTo - Where to format the tree.

Throws:

IOException - If an error occurred while writing in the given appender.

See Also:

Trees.toString(TreeModel)

format

public final void format(TreeModel tree,
                         StringBuilder toAppendTo)

Convenience method which delegate to the above format(TreeModel, Appendable) method, but without throwing IOException. The I/O exception should never occur since we are writing in a StringBuilder.

Note: Strictly speaking, an IOException could still occur in the user overrides the above format method and performs some I/O operation outside the given StringBuilder. However this is not the intended usage of this class and implementors should avoid such unexpected I/O operation.

Parameters:

tree - The tree to format.

toAppendTo - Where to format the tree.

format

public void format(TreeNode node,
                   Appendable toAppendTo)
            throws IOException

Writes a graphical representation of the specified tree in the given buffer. The default implementation delegates to format(TreeModel, Appendable).

Parameters:

node - The root node of the tree to format.

toAppendTo - Where to format the tree.

Throws:

IOException - If an error occurred while writing in the given appender.

See Also:

Trees.toString(TreeNode)

format

public final void format(TreeNode node,
                         StringBuilder toAppendTo)

Convenience method which delegate to the above format(TreeNode, Appendable) method, but without throwing IOException. The I/O exception should never occur since we are writing in a StringBuilder.

Note: Strictly speaking, an IOException could still occur in the user overrides the above format method and performs some I/O operation outside the given StringBuilder. However this is not the intended usage of this class and implementors should avoid such unexpected I/O operation.

Parameters:

node - The root node of the tree to format.

toAppendTo - Where to format the tree.

format

public void format(Iterable<?> nodes,
                   Appendable toAppendTo)
            throws IOException

Writes a graphical representation of the specified elements in the given buffer. This method iterates over the given collection and invokes the String.valueOf(Object) method for each element. The String value can span multiple lines.

Root label
This method formats only the given child elements. It does not format anything for the root. It is up to the caller to format a root label on its own line before to invoke this method.

Recursivity
This method does not perform any check on the element types. In particular, elements of type TreeModel, TreeNode or inner Iterable are not processed recursively. It is up to the toString() implementation of each element to invoke this format method recursively if they wish (this method is safe for this purpose).

Parameters:

nodes - A collection of nodes to format.

toAppendTo - Where to format the tree.

Throws:

IOException - If an error occurred while writing in the given appender.

See Also:

Trees.toString(String, Iterable)

format

public final void format(Iterable<?> nodes,
                         StringBuilder toAppendTo)

Convenience method which delegate to the above format(Iterable, Appendable) method, but without throwing IOException. The I/O exception should never occur since we are writing in a StringBuilder.

Note: Strictly speaking, an IOException could still occur in the user overrides the above format method and performs some I/O operation outside the given StringBuilder. However this is not the intended usage of this class and implementors should avoid such unexpected I/O operation.

Parameters:

nodes - A collection of nodes to format.

toAppendTo - Where to format the tree.

format

public StringBuffer format(Object tree,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Writes a graphical representation of the specified tree in the given buffer. The default implementation delegates to one of the following method depending on the type of the given tree:

• format(TreeModel, Appendable)
• format(TreeNode, Appendable)
• format(Iterable, Appendable)

Specified by:

format in class Format

Parameters:

tree - The tree to format.

toAppendTo - Where to format the tree.

pos - Ignored in current implementation.

Returns:

The given buffer, returned for convenience.