The setup for using interactive organic layout in a single-threaded execution environment needs an implementation of interface InteractiveOrganicLayouter_SingleThreadContext. This so-called context object is used to control the layout calculation. When starting the algorithm, class InteractiveOrganicLayouter returns an appropriate implementation:

startLayoutSingleThreaded(graph:LayoutGraph):InteractiveOrganicLayouter_SingleThreadContext

Interface SingleThreadContext in particular defines the following method that can be used in an application to yield time to the layout algorithm:

doLayout(duration:uint):void

If the graph that is to be processed by InteractiveOrganicLayouter is intended to allow structural modifications by a user, then it is strongly recommended to use an instance of CopiedLayoutGraph instead of a simple LayoutGraph. Doing so helps avoiding synchronization problems that occur when nodes and/or edges can be added to or removed from the graph while the layout algorithm performs its calculations.

Starting the layout algorithm using a copy of the original graph is shown in the following code snippet:

// create a copy of the graph for the layout algorithm
var adapter:LayoutGraphAdapter = new LayoutGraphAdapter(graph);
_copiedLayoutGraph = CopiedLayoutGraph.newCopiedLayoutGraph2(adapter, adapter);

// create the layouter
var organicLayouter:InteractiveOrganicLayouter = new InteractiveOrganicLayouter();
organicLayouter.maxTime = 2000;
// start the layouter for a single thread (see note 1) and retrieve the context
// to handle the layouter.
// (note 1): Flash is single threaded, so we don't have a choice here.
_layoutContext = organicLayouter.startLayoutSingleThreaded(_copiedLayoutGraph);

Interactive organic layout algorithm can be in either of three states: running, sleeping, or stopped. When running, the algorithm lives on the allowed maximal runtime and continuously calculates "intermediate" layouts for the given graph. When sleeping, the algorithm does nothing, but is still "alive." In contrast, when stopped, the algorithm is terminated. Figure 5.60, “State diagram for InteractiveOrganicLayouter” depicts the states and the possible state transitions of InteractiveOrganicLayouter.

Figure 5.60. State diagram for InteractiveOrganicLayouter

The following properties and methods can be used to query the current state of an InteractiveOrganicLayouter instance, change its state, and set the maximal runtime. Note that when an instance is changed from "sleeping" to "running" state, the maximal runtime is again fully available.

running:Boolean
sleeping:Boolean
stopped:Boolean

wakeUp():void
stop():void
stopAndWait():void

maxTime:uint

The cooperative setup as used with InteractiveOrganicLayouter means that the layout process does not return a single result by itself, but instead, in each calculation time slice and as long as it is in "running" state, continuously generates "intermediate" results. These results are in the layout algorithm's data structures only, but can be polled by the application and be used as continuous updates to the layout of a graph.

The following methods allow to easily poll either the current coordinates of single nodes or commit all current positions of nodes to the original graph at once:

getCenterX(node:Node):Number
getCenterY(node:Node):Number
getCenter(node:Node):YPoint

commitPositions():void
commitPositionsSmoothly(maxMovement:Number, percentage:Number):Number

In tutorial demo application InteractiveOrganicLayouterDemo.mxml the "intermediate" results are repeatedly calculated and assigned to the original graph in a contiuous fashion by means of a callback function in an animation:

// Create a Tween animation to continuously update the layout
var tween:Tween = new Tween(new Object(), 0, 1, Number.MAX_VALUE, -1, 
                            function(value:Object):void {
  // on each tween update: re-calculate the layout
  _layoutContext.doLayout(100);
  // update the visible graph with the changes
  if (_layouter.commitPositionsSmoothly(50, 0.1) > 0) {
    // if anything changed: invalidate the display
    graphCanvas.updateContentRect();
    graphCanvas.invalidateDisplayList();
  }
});

The interactive organic layout algorithm allows a user to seemingly simultaneously modify node positions and also node-related parameters while layout calculation takes place. The following methods can be used to update InteractiveOrganicLayouter's data structures with new node positions, and also to specify further node-related parameters that determine, e.g., the size of a node or its inertia:

setCenterX(node:Node, x:Number):void
setCenterY(node:Node, y:Number):void
setCenter(node:Node, x:Number, y:Number):void

setInertia(node:Node, inertia:Number):void
setRadius(node:Node, radius:Number):void

In addition, InteractiveOrganicLayouter optionally also supports modifications to the original graph's structure, i.e., nodes and/or edges can be added to or removed from the graph and the layout calculation subsequently properly accounts for these changes. The following property has to be used to enable support for structural modifications.

automaticStructureUpdateEnabled:Boolean

To support structural modifications to the original graph, interactive organic layout relies on proper notification by means of graph events. Graph listeners registered with the original graph inform InteractiveOrganicLayouter of any structural changes that occur. See also the description of graph listeners in the section called “Events and Listeners”.

As an alternative to using automatic structure updates, the structure of the original graph can also be synchronized explicitly using code similar to that shown in Example 5.27, “Performing explicit structure updates”.

Tutorial demo application InteractiveOrganicLayouterDemo.mxml uses a graph listener and explicit synchronization to support structural modifications to the original graph:

/**
 * Initializes the default style, creates a sample graph and starts the 
 * interactive layouter.
 */  
private function initializeGraph():void {
  var graph:IGraph = graphCanvas.graph;
  ...
  
  // register a listener so that structure updates are handled automatically
  graph.addEventListener(GraphEvent.GRAPH_CHANGED, onStructureChanged);
}

/**
 * Commit graph structure changes to the copied layout graph.
 */ 
private function onStructureChanged(event:GraphEvent):void {
  if (event.kind == GraphEventKind.NODE_CREATED) {
    // a new node was created:
    var node:INode = INode(event.item);
    var layout:IRectangle = node.layout;
    // update the layout graph
    _layouter.syncStructure();
    _layoutContext.doLayout(10);
    // we nail down all newly created nodes
    var copiedNode:Node = _copiedLayoutGraph.getCopiedNode(node);
    _layouter.setCenter(copiedNode, layout.x + layout.width/2, 
                                    layout.y + layout.height/2);
    _layouter.setInertia(copiedNode, 1);
    _layouter.setStress(copiedNode, 0);
  }
  else {
    // anything else has changed: update the layout graph
    if (_layouter != null) {
      _layouter.syncStructure();
      _layoutContext.doLayout(10);
    }
  }                
}

Class InteractiveOrganicLayouter allows to impose so-called "output restrictions" on the result of the layout calculcation. More precisely, the layout result can be determined to fit into a specified region, e.g., a rectangle or a circle. Also, the layout result can be restricted to a specified aspect ratio, too.

outputRestriction:OutputRestriction
Description	Class OutputRestriction serves as a factory to create predefined output restrictions that can be used in conjunction with this property.