com.tensegrity.graph.layout
Interface LayoutService

All Known Implementing Classes:

GraphLayoutService

public interface LayoutService

This interface defines a component that pools objects of type Layout and use them to perform layout on the given graph elements. It encapsulates the layout classes (objects of type NodeLayout) and allows accessing these through layout context. A layout context is a unique identifier that associates with an object of type Layout and its particular setting.

To handle layouter together with a specified setting of them as a unit simplifies the modeling clustered graphs. The LayoutService provides a set of essential methods to:

• Create, remove, duplicate of layout context and configuration of them.
• Performing layout on the nodes and edges of a graph.
• Saving and loading.
• Viewing a progress bar.
• Error handling.

Version:

$Id: LayoutService.java,v 1.62 2005/10/20 13:55:28 SharokhKhani Exp $

Author:

Sharokh Khani

Method Summary

boolean	addLayoutContext(java.lang.String basicEngine, java.lang.String layoutContext) Creates a new layout-context and add it into the pool of the layout-contexts.
void	addProgressListener(ProgressListener progresslistener) Adds a progress-listener.
AttributeSet	duplicateLayoutContext(java.lang.String templateLayoutContext, java.lang.String newLayoutContext) Creates a copy from the layout-context specified by templateLayoutContext and adds it into the pool of .
boolean	error() Returns true if an error has occurred; otherwise false.
AttributeSet	getAttribute() This method gets the attribute-set of LayoutService.
java.lang.Object	getAttribute(java.lang.String key) This method may be used to obtain a specified attribute of the LayoutService.
java.lang.String	getBaseLayoutEngine(java.lang.String layoutContext) This method returns the base layouter of an specified layout-contexts.
AttributeSet	getConfiguration(java.lang.String[] listOfLayoutContexts) This method returns an attribute-set which contains attributes of all layout contexts specified by listOfLayoutContexts.
AttributeSet	getEdgeDefaultLayoutAttributes(java.lang.String layoutContext) This method returns the default edge attributes of specified layout-context.
java.lang.String[]	getEdgeLayoutContextList() This method returns the list of all defined edge layout-contexts.
java.lang.String[]	getEdgeLayoutEngineList() This method returns the list of registered edge layouter.
java.lang.String	getErrorMessage() Returns the error-message if an error has occurred.
java.lang.Object	getLayoutAttribute(java.lang.String layoutContext, java.lang.String key) Obtains the value of the attribute specified by key and the layout-context.
AttributeSet	getLayoutAttributeSet(java.lang.String layoutContext) Returns the attribute-set of the specified layout-context.
java.lang.String[]	getLayoutContextList() This method returns the list of all defined node and edge layout-contexts.
java.lang.String[]	getLayoutContextList(java.lang.String basicLayoutEngine) This method returns array of layout-contexts that are associated with the specified basicLayoutEngine.
AttributeSet	getLayoutReport(java.lang.String layoutContext) This method submits a report about the last layout process.
AttributeSet	getNodeDefaultLayoutAttributes(java.lang.String layoutContext) This method returns the default node attributes of specified layout-context.
java.lang.String[]	getNodeLayoutContextList() This method returns the list of all defined node layout-contexts.
java.lang.String[]	getNodeLayoutEngineList() Returns an array of registered layouter.
void	init() Initializes the internal state of the layout Service.
boolean	isValidLayoutContext(java.lang.String layoutContext) Verifies whether the specified layout-context is valid.
void	keepCurrentEdgesRoute(LayoutableEdge edge) Call this method to keep the current edge's route.
boolean	layout(java.util.List objectList, java.lang.String nodeLayoutContext, java.lang.String edgeLayoutContext) Applies layout on the nodes and edges of viusalGraph.
boolean	layout(VisualGraphObjectContainer visualgraph, java.lang.String nodeLayoutContext, java.lang.String edgeLayoutContext) Applies layout on the graph specified by viusalGraph.
boolean	layoutEdges(java.util.List objectList, java.lang.String edgeLayoutContext, java.lang.String nodeLayoutContext) Applies layout on the edges of the graph specified by objectList
boolean	layoutEdges(VisualGraphObjectContainer visualgraph, java.lang.String edgeLayoutContext, java.lang.String nodeLayoutContext) Applies layout on the edges of the graph specified by viusalGraph.
void	onBeginLayout() Informs the layout service that the layout of a nested graph is beginning.
void	onEndLayout() Informs the layout service that the layout of a nested graph is finished.
boolean	registerLayoutEngine(EdgeLayout edgeLayoutEngine) This method may be used to add a new edge layouter into the layout pool.
boolean	registerLayoutEngine(NodeLayout newBasicLayoutEngine) This method may be used to add a new layouter into the layout pool.
boolean	removeLayoutContext(java.lang.String layoutContext) Removes the specified layout-context
void	removeProgressListener(ProgressListener progresslistener) Removes the specified Progress-listener.
void	setAttribute(AttributeSet attributeSet) This method may be used to set the attribute-set for this object.
void	setAttribute(java.lang.String key, java.lang.Object value) This method may be used to modify a specified attribute of the LayoutService.
void	setConfiguration(AttributeSet attributeSet) This method uses the given AttributeSet to configure the layout contexts and the LayouService itself.
boolean	setDefaultLayoutContext(java.lang.String defaultLayoutContext) Deprecated. This method is become redundant since the method layoutEdges is expanded to a new parameter for the according edge layout context.
boolean	setLayoutAttribute(java.lang.String layoutContext, java.lang.String key, java.lang.Object value) This method may be used to change the value of an attribute specified by layout-context and key.
boolean	setLayoutAttributeSet(java.lang.String layoutContext, AttributeSet attributeSet) Returns the attribute-set of the layout context specified by layout-context.
void	updateLayoutAttributeSet(java.lang.String layoutContext, AttributeSet layoutAttribute) This method updates a specified attributes-set with the view of consistency.

Method Detail

registerLayoutEngine

public boolean registerLayoutEngine(NodeLayout newBasicLayoutEngine)

This method may be used to add a new layouter into the layout pool. A layouter must implement the interface Layout.

Parameters:

newBasicLayoutEngine - A new layouter.

Returns:

Returns true if the registering was successful.

registerLayoutEngine

public boolean registerLayoutEngine(EdgeLayout edgeLayoutEngine)

This method may be used to add a new edge layouter into the layout pool. An edge layouter must implement the interface EdgeLayout.

Parameters:

edgeLayoutEngine - A new edge layouter.

Returns:

Returns true if the registering was successful.

See Also:

registerLayoutEngine(EdgeLayout)

addLayoutContext

public boolean addLayoutContext(java.lang.String basicEngine,
                                java.lang.String layoutContext)

Creates a new layout-context and add it into the pool of the layout-contexts. Note: The new layout-context must be unique. You can use isValidLayoutContext(String) to check whether the new name already exists.

Parameters:

basicEngine - The name of basic NodeLayout or EdgeLayout.

layoutContext - The name for the new layout context

Returns:

Returns true if the function was successful or false if the name of the new layout context already exists or the specified basicEngine was not valid.

See Also:

registerLayoutEngine(NodeLayout)

duplicateLayoutContext

public AttributeSet duplicateLayoutContext(java.lang.String templateLayoutContext,
                                           java.lang.String newLayoutContext)

Creates a copy from the layout-context specified by templateLayoutContext and adds it into the pool of .

Parameters:

templateLayoutContext - The source layout-context

newLayoutContext - The name for the new copy of templateLayoutContext

Returns:

Returns the attribute set of the new layout-context

removeLayoutContext

public boolean removeLayoutContext(java.lang.String layoutContext)

Removes the specified layout-context

Parameters:

layoutContext - The layout-contextto be removed

Returns:

Returns true if the function was successful.

isValidLayoutContext

public boolean isValidLayoutContext(java.lang.String layoutContext)

Verifies whether the specified layout-context is valid.

Parameters:

layoutContext - layout-context that is to be checked

Returns:

true if the specified layout-context is valid, otherwise false.

getLayoutContextList

public java.lang.String[] getLayoutContextList()

This method returns the list of all defined node and edge layout-contexts.

Returns:

a string array which contains a list of layout-contexts.

getNodeLayoutContextList

public java.lang.String[] getNodeLayoutContextList()

This method returns the list of all defined node layout-contexts.

Returns:

Returns a string array which contains a list of layout-contexts.

getEdgeLayoutContextList

public java.lang.String[] getEdgeLayoutContextList()

This method returns the list of all defined edge layout-contexts.

Returns:

a String array which contains a list of layout-contexts.

getLayoutContextList

public java.lang.String[] getLayoutContextList(java.lang.String basicLayoutEngine)

This method returns array of layout-contexts that are associated with the specified basicLayoutEngine.

Parameters:

basicLayoutEngine - The basic Layout of which the derived layout contexts is requested.

Returns:

an array containing the derived layout contexts.

getNodeLayoutEngineList

public java.lang.String[] getNodeLayoutEngineList()

Returns an array of registered layouter.

Returns:

a String array of registered layouter.

getEdgeLayoutEngineList

public java.lang.String[] getEdgeLayoutEngineList()

This method returns the list of registered edge layouter.

Returns:

Returns string array of registered edge layouter.

getNodeDefaultLayoutAttributes

public AttributeSet getNodeDefaultLayoutAttributes(java.lang.String layoutContext)

This method returns the default node attributes of specified layout-context. Note: The default node attributes are not to be confused with layout attributes which can set by setLayoutAttribute(String, String, Object) and setLayoutAttributeSet(String, AttributeSet). The layout-attributes configure the layout as a whole. But some layouter also accept configuration of nodes to allow different treatment.

Parameters:

layoutContext - specifies the target layout context.

Returns:

Returns the default AttributeSet. It may be null since some layouter does not offer special attributes for nodes.

getEdgeDefaultLayoutAttributes

public AttributeSet getEdgeDefaultLayoutAttributes(java.lang.String layoutContext)

This method returns the default edge attributes of specified layout-context. Note: The default edge attributes are not to be confused with layout attributes which can set by setLayoutAttribute(String, String, Object) and setLayoutAttributeSet(String, AttributeSet). The layout-attributes configure the layout as a whole. But some layouter also accept configuration of edges to allow different treatment.

Parameters:

layoutContext - specifies the target layout context

Returns:

the default AttributeSet. It may be null since some layouter does not offer special attributes for nodes.

setDefaultLayoutContext

public boolean setDefaultLayoutContext(java.lang.String defaultLayoutContext)

Deprecated. This method is become redundant since the method layoutEdges is expanded to a new parameter for the according edge layout context.

Sets the default layout context of the edges. The default layout context will be used to arrange edges without a specified layout context. Note: The layout context of edges can be set using Layoutable.getLayoutContext().

Parameters:

defaultLayoutContext - The layout context which is to be used.

Returns:

Returns true if the layout context was valid.

layout

public boolean layout(VisualGraphObjectContainer visualgraph,
                      java.lang.String nodeLayoutContext,
                      java.lang.String edgeLayoutContext)

Applies layout on the graph specified by viusalGraph. Note: This method calls layoutEdges(VisualGraphObjectContainer, String, String) internally.

Parameters:

visualgraph - The VisualGraph that should be arranged.

nodeLayoutContext - The layout-context that should be used to layout nodes.

edgeLayoutContext - The layout-context that should be used to layout edges.

Returns:

Returns true if the function was successful; otherwise false, in which case the method getErrorMessage() could be used to obtain details about the error.

layout

public boolean layout(java.util.List objectList,
                      java.lang.String nodeLayoutContext,
                      java.lang.String edgeLayoutContext)

Applies layout on the nodes and edges of viusalGraph. Note:: This method calls layoutEdges(List, String, String) internally.

Parameters:

objectList - The list of VisualNode and VisualEdge that should be arranged.

nodeLayoutContext - The node layout-context that should be used.

edgeLayoutContext - The edge layout-context that should be used.

Returns:

Returns true if the function was successful; otherwise false, in which case the method getErrorMessage() could be used to obtain details about the error.

layoutEdges

public boolean layoutEdges(VisualGraphObjectContainer visualgraph,
                           java.lang.String edgeLayoutContext,
                           java.lang.String nodeLayoutContext)

Applies layout on the edges of the graph specified by viusalGraph.

Parameters:

visualgraph - The VisualGraph of which the edges should be arranged.

edgeLayoutContext - The layout-context that should be used to arrange edge of the graph.

nodeLayoutContext - The layout-context that should be used to arrange nodes of the graph. The layout-context must associate with a Edge layouter.

Returns:

Returns true if the function was successful; otherwise false, in which case the method getErrorMessage() could be used to obtain details about the error.

layoutEdges

public boolean layoutEdges(java.util.List objectList,
                           java.lang.String edgeLayoutContext,
                           java.lang.String nodeLayoutContext)

Applies layout on the edges of the graph specified by objectList

Parameters:

objectList - The list of nodes and edges of the graph

edgeLayoutContext - The layout-context that should be used to arrange edge of the graph.

nodeLayoutContext - The layout-context that should be used to arrange nodes of the graph.

Returns:

Returns true if the function was successful; otherwise false, in which case the method getErrorMessage() could be used to obtain details about the error.

getLayoutAttributeSet

public AttributeSet getLayoutAttributeSet(java.lang.String layoutContext)

Returns the attribute-set of the specified layout-context.

Parameters:

layoutContext - layout-context of which the attribute set is required.

Returns:

Returns the attribute-set of specified layout-context.

See Also:

setLayoutAttribute(String, String, Object), AttributeSet

setLayoutAttributeSet

public boolean setLayoutAttributeSet(java.lang.String layoutContext,
                                     AttributeSet attributeSet)

Returns the attribute-set of the layout context specified by layout-context. Note: the LayoutService ensures that the modified AttributeSet will updated by corresponding layouter. A layouter may change the attribute set if necessarily. A tree layouter for example may change the attribute layer distance to radius if the user changes the arrangement type from plan to radial.

Parameters:

layoutContext - layout-context of which the attribute set is to be set.

attributeSet - The new AttributeSet

Returns:

Returns true if the setting of attributes was successful.

See Also:

setLayoutAttribute(String, String, Object), AttributeSet

setLayoutAttribute

public boolean setLayoutAttribute(java.lang.String layoutContext,
                                  java.lang.String key,
                                  java.lang.Object value)

This method may be used to change the value of an attribute specified by layout-context and key.

Parameters:

layoutContext - The layout context which attribute is to be changed.

key - The name of attribute which is to be set.

value - The new value of the attribute specified by key

Returns:

Returns true if the setting of attributes was successful.

See Also:

setLayoutAttributeSet(String, AttributeSet)

getLayoutAttribute

public java.lang.Object getLayoutAttribute(java.lang.String layoutContext,
                                           java.lang.String key)

Obtains the value of the attribute specified by key and the layout-context.

Parameters:

layoutContext - The layout context of target layout

key - The name of the target attribute.

Returns:

Returns the value of the specified attribute.

See Also:

getLayoutAttributeSet(String)

updateLayoutAttributeSet

public void updateLayoutAttributeSet(java.lang.String layoutContext,
                                     AttributeSet layoutAttribute)

This method updates a specified attributes-set with the view of consistency.

A tree layouter for example may change the attribute layer distance to radius if the user changes the arrangement type from plan to radial.

Parameters:

layoutContext - The according layout context

layoutAttribute - The attribute-Set which should be updated

getAttribute

public java.lang.Object getAttribute(java.lang.String key)

This method may be used to obtain a specified attribute of the LayoutService. Note: This Attributes are global and have an effect of all layout-context. To obtain the attributes of a layout instance, use getLayoutAttribute(String, String);

Parameters:

key - The name of the target attribute.

Returns:

Returns the value of attribute specified by key.

See Also:

getAttribute(), AttributeSet

setAttribute

public void setAttribute(java.lang.String key,
                         java.lang.Object value)

This method may be used to modify a specified attribute of the LayoutService. Note: This Attributes are global and have an effect of all layout-context. To set change the attributes of a layouter use setLayoutAttribute(String, String, Object);

Parameters:

key - The name of the attribute which is to be set.

value - The new value of the specified attribute.

See Also:

setAttribute(AttributeSet)

getAttribute

public AttributeSet getAttribute()

This method gets the attribute-set of LayoutService. Note: This Attributes are global and have an effect of all layout-context. To obtain the attributes of a layouter use getLayoutAttributeSet(String);

Returns:

Returns the AttributeSet of LayoutService

See Also:

getAttribute(String)

setAttribute

public void setAttribute(AttributeSet attributeSet)

This method may be used to set the attribute-set for this object. Note: This Attributes are global and have an effect of all layout-context. To obtain the attributes of a layouter use setLayoutAttributeSet(String, AttributeSet);

Parameters:

attributeSet - The AttributeSet that is to be used.

See Also:

setAttribute(String, Object)

getConfiguration

public AttributeSet getConfiguration(java.lang.String[] listOfLayoutContexts)

This method returns an attribute-set which contains attributes of all layout contexts specified by listOfLayoutContexts. It may be used to obtain attributes of a set of layout contexts with the view of saving of the current state of the layout contexts and the LayoutService. The Atribute tree has following structure:

 
 LayoutConfiguration (Attr) 
 
                    +--- Global attributes (Attr)
 
                      |
 
                      +---- Layout Contexts  (Attr)
 
                        | 
 
                        +---- Context   
 
                        |    |--- Base Layouter (string)
 
                        |    |--- Attributes (Attr)
 
                        +----- Context   
 
                        |    |--- Base Layouter (string)
 
                        |    |--- Attributes (Attr)
 
                        +----- ........
 

Parameters:

listOfLayoutContexts - the list of the requested layout contexts, or null if the configuration of all registered layout contexts is required.

Returns:

the AttributeSet.

See Also:

setConfiguration(AttributeSet)

setConfiguration

public void setConfiguration(AttributeSet attributeSet)

This method uses the given AttributeSet to configure the layout contexts and the LayouService itself. Note: The LayoutService creates a new layout-context automatically if a layout-context was saved but not existing at the loading time.

Parameters:

attributeSet - The attribute set that contains the global options and the attributes of each layout context.

See Also:

getConfiguration(String[])

error

public boolean error()

Returns true if an error has occurred; otherwise false. Use method getErrorMessage() to obtain a description text about the last occurred error.

Returns:

true if an error has occurred; otherwise false.

getErrorMessage

public java.lang.String getErrorMessage()

Returns the error-message if an error has occurred. You can use error() to find out whether an error has occurred.

Returns:

the error description

init

public void init()

Initializes the internal state of the layout Service.

getLayoutReport

public AttributeSet getLayoutReport(java.lang.String layoutContext)

This method submits a report about the last layout process. It provides detail information accordingly. A report contains typically the calculation durations of different processing steps.

Parameters:

layoutContext - The layout-context of which the report is required.

Returns:

Returns an attribute-set which contains the report. or null, if no report is available

See Also:

AttributeSet

addProgressListener

public void addProgressListener(ProgressListener progresslistener)

Adds a progress-listener. The progress bar will update during the layout process.

Parameters:

progresslistener - a ProgressListener

removeProgressListener

public void removeProgressListener(ProgressListener progresslistener)

Removes the specified Progress-listener.

Parameters:

progresslistener - the ProgressListener that is to be removed.

onBeginLayout

public void onBeginLayout()

Informs the layout service that the layout of a nested graph is beginning.

onEndLayout

public void onEndLayout()

Informs the layout service that the layout of a nested graph is finished.

getBaseLayoutEngine

public java.lang.String getBaseLayoutEngine(java.lang.String layoutContext)

This method returns the base layouter of an specified layout-contexts.

Parameters:

layoutContext - the layout context of which the base layouter is requested.

Returns:

the base layouter with which the specified layoutContext associates. The return value is null if the specified layoutContext is not valid.

keepCurrentEdgesRoute

public void keepCurrentEdgesRoute(LayoutableEdge edge)

Call this method to keep the current edge's route.

Parameters:

edge - the edge of which the current route is to be considered.