y.layout.genealogy
Class FamilyTreeLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.genealogy.FamilyTreeLayouter

All Implemented Interfaces:

Layouter

public class FamilyTreeLayouter
extends CanonicMultiStageLayouter

This layout algorithm arranges genealogical graphs (family trees).

Layout Style

The family trees consist of nodes that represent individuals and nodes that represent families. Individuals are connected via these family nodes. The graph is arranged in layers that describe generations.

Basic Family Tree

Concept

In order to determine whether a node represents an individual or a partnership, a DataProvider has to be registered with key DP_KEY_FAMILY_TYPE. If this DataProvider is missing, an IllegalArgumentException will be thrown.

This DataProvider provides:

• TYPE_MALE for a node representing a male individual.
• TYPE_FEMALE for a node representing a female individual.
• TYPE_FAMILY for a node representing a family.

All other values will be interpreted as if the node represents an individual.

A TYPE_FAMILY node links all members of a family. It can only have two incoming edges from the parents. Two nodes of the same type (families or individuals) cannot be directly connected. If the input graph violates these specifications, a WrongGraphStructure exception will be thrown.

The layout is calculated basically in two steps:

• The families are laid out by the inner layouter in a compact way.
• The relations between these "family groups" and their children and other families are laid out by the top layout algorithm.

Features

The distances between nodes in the same generation as well as between individuals and family nodes can be adjusted.

Nodes in the same generation can be aligned at three different coordinates: top, center, bottom.

The location of TYPE_FAMILY nodes can be specified in relation to the partners. This placement can be set independently for parents.

Field Summary

static int	ALIGN_BOTTOM Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their bottom coordinate.
static int	ALIGN_CENTER Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their center coordinate.
static int	ALIGN_TOP Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their top coordinate.
static int	DO_NOT_SORT_BY_SEX Order specifier that disables sorting of individuals according to their sex.
static java.lang.String	DP_KEY_FAMILY_TYPE A DataProvider key for assigning a node type for each node The layout algorithm will handle the nodes according to this type.
static int	FEMALE_ALWAYS_FIRST Order specifier that places female individuals before their male siblings and partners.
static int	FEMALE_FIRST Order specifier that places female individuals before their male siblings and partners, if possible.
static int	MALE_ALWAYS_FIRST Order specifier that places male individuals before their female siblings and partners.
static int	MALE_FIRST Order specifier that places male individuals before their female siblings and partners, if possible.
static java.lang.String	TYPE_FAMILY Type specifier for nodes that connect partners with each other and their children.
static java.lang.String	TYPE_FEMALE Type specifier for nodes that represent women.
static java.lang.String	TYPE_MALE Type specifier for nodes that represent men.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

FamilyTreeLayouter()
Creates a new instance of FamilyTreeLayouter with default settings.

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts graphs that have a family tree structure.
protected void	doLayoutCore(LayoutGraph graph) Applies a family tree layout to the given graph.
int	getAlignment() Returns the vertical alignment of the individual nodes in the same generation.
double	getOffsetForFamilyNodes() Returns the offset by which a TYPE_FAMILY node is shifted down if its parents are not direct neighbors.
int	getSortFamilyMembers() Returns the order of individuals in the same generation (siblings, partners) based on their sex.
double	getSpacingBetweenFamilyMembers() Returns the spacing between two nodes representing members of the same family in one generation.
Layouter	getTopLayouter() Returns the layout algorithm that is responsible for the layout between family groups.
boolean	isFamilyNodesAlwaysBelow() Returns whether or not TYPE_FAMILY nodes are placed between or below the partners.
boolean	isPartnerlessBelow() Returns whether or not TYPE_FAMILY nodes of individuals that have only children but no partners are placed below this individual or next to it.
void	setAlignment(int alignment) Specifies the vertical alignment of the individual nodes in the same generation.
void	setFamilyNodesAlwaysBelow(boolean familyNodesAlwaysBelow) Specifies whether or not TYPE_FAMILY nodes are placed between or below the partners.
void	setOffsetForFamilyNodes(double vSpace) Specifies the offset by which a TYPE_FAMILY node is shifted down if its parents are not direct neighbors.
void	setParallelEdgeLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for routing parallel edges is activated.
void	setPartnerlessBelow(boolean partnerlessBelow) Specifies whether or not TYPE_FAMILY nodes of individuals that have only children but no partners are placed below this individual or next to it.
void	setSelfLoopLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for routing self-loops is activated.
void	setSortFamilyMembers(int sortFamilyMembers) Specifies the order of individuals in the same generation (siblings, partners) based on their sex.
void	setSpacingBetweenFamilyMembers(double hSpace) Specifies the spacing between two nodes representing members of the same family in one generation.
void	setTopLayouter(Layouter topLayouter) Specifies the layout algorithm that is responsible for the layout between family groups.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setComponentLayouterEnabled, setGroupNodeHider, setGroupNodeHidingEnabled, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setOrientationLayouterEnabled, setParallelEdgeLayouter, setSelfLoopLayouter, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Field Detail

DP_KEY_FAMILY_TYPE

public static final java.lang.String DP_KEY_FAMILY_TYPE

A DataProvider key for assigning a node type for each node

The layout algorithm will handle the nodes according to this type.

See Also:

Constant Field Values

TYPE_FAMILY

public static final java.lang.String TYPE_FAMILY

Type specifier for nodes that connect partners with each other and their children.

See Also:

DP_KEY_FAMILY_TYPE, Constant Field Values

TYPE_MALE

public static final java.lang.String TYPE_MALE

Type specifier for nodes that represent men.

See Also:

DP_KEY_FAMILY_TYPE, Constant Field Values

TYPE_FEMALE

public static final java.lang.String TYPE_FEMALE

Type specifier for nodes that represent women.

See Also:

DP_KEY_FAMILY_TYPE, Constant Field Values

ALIGN_TOP

public static final int ALIGN_TOP

Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their top coordinate.

The descriptions of the directions are based on LayoutOrientation.TOP_TO_BOTTOM.

See Also:

setAlignment(int), Constant Field Values

Sample Graph:

Alignment top

ALIGN_CENTER

public static final int ALIGN_CENTER

Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their center coordinate.

The descriptions of the directions are based on LayoutOrientation.TOP_TO_BOTTOM.

See Also:

setAlignment(int), Constant Field Values

Sample Graph:

Alignment center

ALIGN_BOTTOM

public static final int ALIGN_BOTTOM

Alignment specifier that defines that all nodes in the same layer (generation) are aligned based on their bottom coordinate.

The descriptions of the directions are based on LayoutOrientation.TOP_TO_BOTTOM.

See Also:

setAlignment(int), Constant Field Values

Sample Graph:

Alignment bottom

DO_NOT_SORT_BY_SEX

public static final int DO_NOT_SORT_BY_SEX

Order specifier that disables sorting of individuals according to their sex.

See Also:

setSortFamilyMembers(int), Constant Field Values

FEMALE_FIRST

public static final int FEMALE_FIRST

Order specifier that places female individuals before their male siblings and partners, if possible.

See Also:

setSortFamilyMembers(int), Constant Field Values

Sample Graph:

Females are preferable first

FEMALE_ALWAYS_FIRST

public static final int FEMALE_ALWAYS_FIRST

Order specifier that places female individuals before their male siblings and partners.

See Also:

setSortFamilyMembers(int), Constant Field Values

Sample Graph:

Females are always first

MALE_FIRST

public static final int MALE_FIRST

Order specifier that places male individuals before their female siblings and partners, if possible.

See Also:

setSortFamilyMembers(int), Constant Field Values

Sample Graph:

Males are preferable first

MALE_ALWAYS_FIRST

public static final int MALE_ALWAYS_FIRST

Order specifier that places male individuals before their female siblings and partners.

See Also:

setSortFamilyMembers(int), Constant Field Values

Sample Graph:

Males are always first

Constructor Detail

FamilyTreeLayouter

public FamilyTreeLayouter()

Creates a new instance of FamilyTreeLayouter with default settings.

Method Detail

getTopLayouter

public Layouter getTopLayouter()

Returns the layout algorithm that is responsible for the layout between family groups.

If the specified layout algorithm is null, fallback algorithm IncrementalHierarchicLayouter is used.

Returns:

the layout algorithm

See Also:

setTopLayouter(Layouter)

setTopLayouter

public void setTopLayouter(Layouter topLayouter)

Specifies the layout algorithm that is responsible for the layout between family groups.

If the specified layout algorithm is null, fallback algorithm IncrementalHierarchicLayouter is used.

Default Value:

The default value is IncrementalHierarchicLayouter

Parameters:

topLayouter - the layout algorithm

setSpacingBetweenFamilyMembers

public void setSpacingBetweenFamilyMembers(double hSpace)

Specifies the spacing between two nodes representing members of the same family in one generation.

Values should be non-negative.

Default Value:

The default value is 30.

Parameters:

hSpace - the spacing between family members

Throws:

java.lang.IllegalArgumentException - if the given spacing is negative

Sample Graphs:

30

100

getSpacingBetweenFamilyMembers

public double getSpacingBetweenFamilyMembers()

Returns the spacing between two nodes representing members of the same family in one generation.

Values should be non-negative.

Returns:

the spacing between family members

See Also:

setSpacingBetweenFamilyMembers(double)

setOffsetForFamilyNodes

public void setOffsetForFamilyNodes(double vSpace)

Specifies the offset by which a TYPE_FAMILY node is shifted down if its parents are not direct neighbors.

Values should be non-negative.

Default Value:

The default value is 10.

Parameters:

vSpace - the offset for TYPE_FAMILY nodes to their parents

Throws:

java.lang.IllegalArgumentException - if the given offset is negative

Sample Graphs:

20

60

getOffsetForFamilyNodes

public double getOffsetForFamilyNodes()

Returns the offset by which a TYPE_FAMILY node is shifted down if its parents are not direct neighbors.

Values should be non-negative.

Returns:

the offset for TYPE_FAMILY nodes to their parents

See Also:

setOffsetForFamilyNodes(double)

setPartnerlessBelow

public void setPartnerlessBelow(boolean partnerlessBelow)

Specifies whether or not TYPE_FAMILY nodes of individuals that have only children but no partners are placed below this individual or next to it.

When enabled, direct inheritance lines are straightened.

Default Value:

The default value is true. TYPE_FAMILY nodes are placed below single parents.

Parameters:

partnerlessBelow - true if TYPE_FAMILY nodes with only one parent will be placed below this individual, false otherwise

Sample Graphs:

true

false

isPartnerlessBelow

public boolean isPartnerlessBelow()

Returns whether or not TYPE_FAMILY nodes of individuals that have only children but no partners are placed below this individual or next to it.

When enabled, direct inheritance lines are straightened.

Default Value:

The default value is true. TYPE_FAMILY nodes are placed below single parents.

Returns:

true if TYPE_FAMILY nodes with only one parent will be placed below this individual, false otherwise

See Also:

setPartnerlessBelow(boolean)

setFamilyNodesAlwaysBelow

public void setFamilyNodesAlwaysBelow(boolean familyNodesAlwaysBelow)

Specifies whether or not TYPE_FAMILY nodes are placed between or below the partners.

Default Value:

The default value is false. TYPE_FAMILY nodes are placed between the partners.

Parameters:

familyNodesAlwaysBelow - true if TYPE_FAMILY nodes are placed below the partners, false otherwise

See Also:

TYPE_FAMILY

Sample Graphs:

false

true

isFamilyNodesAlwaysBelow

public boolean isFamilyNodesAlwaysBelow()

Returns whether or not TYPE_FAMILY nodes are placed between or below the partners.

Returns:

true if TYPE_FAMILY nodes are placed below the partners, false otherwise

See Also:

setFamilyNodesAlwaysBelow(boolean), TYPE_FAMILY

getAlignment

public int getAlignment()

Returns the vertical alignment of the individual nodes in the same generation.

Returns:

one of the valid alignment specifiers

See Also:

setAlignment(int)

setAlignment

public void setAlignment(int alignment)

Specifies the vertical alignment of the individual nodes in the same generation.

Default Value:

The default value is ALIGN_CENTER

Parameters:

alignment - one of the valid alignment specifiers

Throws:

java.lang.IllegalArgumentException - if the specified alignment is unknown

setParallelEdgeLayouterEnabled

public void setParallelEdgeLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for routing parallel edges is activated.

Overrides:

setParallelEdgeLayouterEnabled in class CanonicMultiStageLayouter

FamilyTreeLayouter cannot handle parallel edges. Disabling ParallelEdgeLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that routes parallel edges is activated.

Parameters:

enabled - true if the stage responsible for routing parallel edges is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isParallelEdgeLayouterEnabled(), CanonicMultiStageLayouter.setParallelEdgeLayouter(LayoutStage), ParallelEdgeLayouter

setSelfLoopLayouterEnabled

public void setSelfLoopLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for routing self-loops is activated.

Overrides:

setSelfLoopLayouterEnabled in class CanonicMultiStageLayouter

FamilyTreeLayouter cannot handle self-loops. Disabling SelfLoopLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that routes self-loops is activated.

Parameters:

enabled - true if the stage responsible for routing self-loops is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isSelfLoopLayouterEnabled(), CanonicMultiStageLayouter.setSelfLoopLayouter(LayoutStage), SelfLoopLayouter

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Accepts graphs that have a family tree structure.

A family tree graph must have a DataProvider registered with DP_KEY_FAMILY_TYPE key which provides the types of the nodes.

Each node of TYPE_FAMILY must have at most two predecessors and cannot be followed by other TYPE_FAMILY nodes. All other node types represent individuals which can only be connected to TYPE_FAMILY nodes.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true if the graph has a family tree structure, false otherwise

See Also:

DP_KEY_FAMILY_TYPE, TYPE_FAMILY, TYPE_FEMALE, TYPE_MALE

getSortFamilyMembers

public int getSortFamilyMembers()

Returns the order of individuals in the same generation (siblings, partners) based on their sex.

Returns:

one of the valid order specifiers

See Also:

setSortFamilyMembers(int)

setSortFamilyMembers

public void setSortFamilyMembers(int sortFamilyMembers)

Specifies the order of individuals in the same generation (siblings, partners) based on their sex.

Default Value:

The default value is DO_NOT_SORT_BY_SEX

Parameters:

sortFamilyMembers - one of the valid order specifiers

Throws:

java.lang.IllegalArgumentException - if the specified order is unknown

doLayoutCore

protected void doLayoutCore(LayoutGraph graph)

Applies a family tree layout to the given graph.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Throws:

java.lang.IllegalStateException - if no DataProvider is registered using DP_KEY_FAMILY_TYPE

WrongGraphStructure - if a TYPE_FAMILY node has more than two parents or two nodes of the same type are linked together

See Also:

canLayoutCore(LayoutGraph)