gumbo.visualize.data.layout
Class WholeLayoutEngine

java.lang.Object
  |
  +--gumbo.visualize.data.layout.WholeLayoutEngine

Direct Known Subclasses:

GraphLayoutEngine

public abstract class WholeLayoutEngine

extends java.lang.Object

Abstract base class for layout engines that manage a whole layout and its view. The whole layout engine is responsible for laying out the parts in a whole using a particular style of layout. Initialization and display of the layout whole and its parts is the responsibility of the layout whole and parts. Includes support for controlling and animating the layout process in an application GUI.

View layout is distinct from that of the graphics technology (e.g. Swing layout manager) to avoid graphics dependencies, and to promote efficiency and specialization. Efficiency is gained by laying out the part views (typically a highly iterative process) without updating or realizing the display state of the corresponding graphic shapes until the layout is complete.

Version:

$Revision: 1.11 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary

static class

WholeLayoutEngine.LayoutAction A Swing action that calls a layout engine's doLayout().

Constructor Summary

WholeLayoutEngine(LayoutWholeView whole)

Method Summary

void	doLayout() Called by the client or system to update the whole view layout and show the result.
protected void	doLayoutWork() Performs the whole view layout and display work for doLayout().
double	getAnimationSpeed() Gets the animation speed factor.
int	getDimensionality() Gets the dimensionality of the layout.
int[]	getDimensionMap() Maps layout order of precedence (layout space dimension) to graphic space dimension.
int[]	getDirectionMap() Maps layout order of precedence (layout space dimension) to layout direction (+1, 0, -1).
LayoutWholeView	getLayoutWholeView() Gets the whole layout view being managed by this engine.
protected abstract void	realizeDisplay() Implemented by subclasses to show the results of the layout generated by realizeLayout(), by transfering the layout state to the part view graphics, and making any changes visible in the whole view graphic.
protected abstract void	realizeLayout() Implemented by subclasses to perform the layout of the whole view's part views.
void	setAnimationSpeed(double speed) Sets the animation speed factor, which scales the delay time between animation frames.
void	setDirections(int firstDir, int secondDir, int thirdDir) Sets the layout direction in order of precedence (layout space).
protected void	showLayoutFrame(long frameTime) If animation is enabled (see setAnimationSpeed()), shows the current layout using realizeDisplay() and then sleeps for the frame time multiplied by the animation speed factor.

Methods inherited from class java.lang.Object

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

Constructor Detail

WholeLayoutEngine

public WholeLayoutEngine(LayoutWholeView whole)

Parameters:

whole - The layout whole view managed by this layout engine. Represents the input data model to be laid out and the whole view used for display of the layout. The layout engine will never modify the data model, but it may modify its view by adding part views. Never null.

Method Detail

getLayoutWholeView

public LayoutWholeView getLayoutWholeView()

Gets the whole layout view being managed by this engine.

Returns:

Reference to the whole. Null if not yet set.

setDirections

public void setDirections(int firstDir,
                          int secondDir,
                          int thirdDir)

Sets the layout direction in order of precedence (layout space). Use DIRECTION_???_NONE to hold a dimension constant (e.g. less than three dimensions). Defaults to canonical directions (+X first, +Y second, +Z third). A dimension must only be used once, and all dimensions must be accounted for.

Parameters:

firstDir - Highest order layout direction (Layout.DIRECTION_???).

secondDir - Middle order layout direction (Layout.DIRECTION_???).

thirdDir - Lowest order layout direction (Layout.DIRECTION_???).

Throws:

java.lang.IllegalStateException - A precedence or dimension has not been specified, a non-none direction occurs after a none one, or the dimensionality is less than 1.

getDimensionality

public int getDimensionality()

Gets the dimensionality of the layout.

Returns:

Number of dimensions (i.e. non-none directions). [0, 3].

getDimensionMap

public int[] getDimensionMap()

Maps layout order of precedence (layout space dimension) to graphic space dimension.

Returns:

Dimension map. Never null.

getDirectionMap

public int[] getDirectionMap()

Maps layout order of precedence (layout space dimension) to layout direction (+1, 0, -1). Note that "0" indicates an unused dimension; "+1" indicates normal direction; and, "-1" indicates reverse direction.

Returns:

Direction map. Never null.

setAnimationSpeed

public void setAnimationSpeed(double speed)

Sets the animation speed factor, which scales the delay time between animation frames. If less than or equal to zero, animation is disabled, in which case calls to showLayoutFrame() are ignored and layout will run at full speed (i.e. no frame delays). Normal speed is 1.0.

Parameters:

speed - Speed factor. Defaults to 0.0, with animation disabled.

getAnimationSpeed

public double getAnimationSpeed()

Gets the animation speed factor. If less than or equal to zero, animation is disabled.

doLayout

public void doLayout()

Called by the client or system to update the whole view layout and show the result. Calls doLayoutWork() to perform the actual work. If called by the Swing GUI thread a separate thread is used to perform the work to avoid contention with the GUI thread during any layout animation, in which case any previous layout thread still running is first stopped.

Throws:

java.lang.IllegalStateException - The whole is null. Use setLayoutSpaceTransform() to set it.

doLayoutWork

protected void doLayoutWork()

Performs the whole view layout and display work for doLayout(). Updates the layout with realizeLayout() and shows the result with realizeDisplay().

showLayoutFrame

protected void showLayoutFrame(long frameTime)

If animation is enabled (see setAnimationSpeed()), shows the current layout using realizeDisplay() and then sleeps for the frame time multiplied by the animation speed factor. Called by layout engines at strategic points in the layout process to update the display following geometric or appearance changes to the layout contents.

Parameters:

frameTime - The frame time (milliseconds). Zero if <0.

realizeLayout

protected abstract void realizeLayout()

Implemented by subclasses to perform the layout of the whole view's part views. Does not affect the display state of any view graphics (see realizeDisplay()).

realizeDisplay

protected abstract void realizeDisplay()

Implemented by subclasses to show the results of the layout generated by realizeLayout(), by transfering the layout state to the part view graphics, and making any changes visible in the whole view graphic.