Where to Find Up-to-date yFiles Information

This page is from the outdated yFiles for Java 2.13 documentation. You can find the most up-to-date documentation for all yFiles products on the yFiles documentation overview page.

Please see the following links for more information about the yFiles product family of diagramming programming libraries and corresponding yFiles products for modern web apps, for cross-platform Java(FX) applications, and for applications for the Microsoft .NET environment.

More about the yFiles product family Close X

Automatic Layout

Class Graph2DLayoutExecutor

Class Graph2DLayoutExecutor is a convenience class to facilitate layout calculation of a Graph2D. It can be used to reduce the code necessary for automatic layout setup in many common situations to a minimum. Especially in conjunction with grouped graphs, Graph2DLayoutExecutor is well-suited to save setup code.

Basically, Graph2DLayoutExecutor takes a Graph2D and a Layouter implementation and runs the layout algorithm using the graph as the input. Prior to starting the layout algorithm, Graph2DLayoutExecutor performs several common setup and configuration steps. By default, it:

Additionally, by default the layout is also nicely morphed in an animated fashion using a LayoutMorpher.

As an option in conjunction with swimlane layout of diagrams using TableGroupNodeRealizer, Graph2DLayoutExecutor can also convert relevant parts of the table structure model of any TableGroupNodeRealizer in the graph for the layouter (uses a TableLayoutConfigurator internally).

Example 6.55. Using Graph2DLayoutExecutor

// 'graph' is of type y.view.Graph2D.

new Graph2DLayoutExecutor(Graph2DLayoutExecutor.BUFFERED).doLayout(graph,
     new IncrementalHierarchicLayouter());

Whether a graph layout result is morphed or not, or the layout calculation is done asynchronously or not, can be specified using the Graph2DLayoutExecutor's mode property. The mode is given either at creation or using the setMode method. Whether the GroupLayoutConfigurator or TableLayoutConfigurator are actually used can be controlled, too.

void setConfiguringGrouping(boolean configuringGrouping)
void setConfiguringTableNodeRealizers(boolean configuringTableNodeRealizers)
void setConfiguringNodePorts(boolean configuringNodePorts)
Description Controls whether grouping information and table structure information is prepared, and whether strong ports constraints are created from node ports. By default, configuration of table structure information is disabled, the other options are enabled.

The following methods can be used to invoke the layout calculation using the given Layouter implementation on the given Graph2D, respectively the Graph2D in the given Graph2DView.

Important

Animation of the layout can only occur if there is a view where the animation can take place. As a consequence, the methods that take a Graph2D only cannot be used to morph the layout result, even if the mode property is set otherwise.

Asynchronous Layout

Asynchronous layout calculation allows the application to be responsive while the layout is calculated. It also offers the possibility to display a progress bar or stop the layout calculation by stopping the layout thread.

Setting the mode property to THREADED or ANIMATED_THREADED lets the executor perform the layout calculations in a separate thread. In that case, the doLayout() method returns immediately.

It is recommended to use the doLayout() methods that take a Runnable and a Graph2DLayoutExecutor.ExceptionListener for asynchronous layout calculation. These methods add the possibility to get notified about the layout progress: based on whether an exception has occurred or not, when the layout calculation has ended, the ExceptionListener is invoked. The Runnable is invoked in either case.

While performing an asynchronous layout it is advisable to lock the view such that no concurrent modification can be done by the user. Locking the view has to be enabled by void setLockingView(true). If locking is enabled, the view will be locked automatically when the layout is started and unlocked after the layout is completed.

The Graph2DLayoutExecutor.LayoutThreadHandle which is returned by doLayout can be used to stop/cancel the layout. Its method cancel() tries to cancel the running layout. If it is not possible to stop the layout safely, the layout won't be canceled. The method isRunning() can be used to determine whether the layout is still running.

The LayoutThreadHandle also provides access to the Thread instance itself through the getThread() method. The Thread instance can be used to change the thread's priority, for example, or to suspend it. It is also possible to stop the layout by directly stopping the thread as shown in Example 6.56, “Stopping a layout thread via the LayoutThreadHandle”, if canceling the layout fails.

Note

Stopping the thread directly should be used with care. It may cause problems in some environments, most notably when using a debugger.

Example 6.56. Stopping a layout thread via the LayoutThreadHandle

// 'handle' is of type y.view.Graph2DLayoutExecutor.LayoutThreadHandle.

handle.getThread().stop();

Graph2DView Support for Automatic Layout

Class Graph2DView provides convenience functionality to directly invoke an automatic layout calculation on the Graph2D it is holding. The following methods use the services of class Graph2DLayoutExecutor.

void applyLayout(Layouter layouter)
void applyLayoutAnimated(Layouter layouter)
Description Invokes automatic layout calculation on the view's Graph2D.

Tutorial Demo Code

The tutorial demo application Graph2DLayoutExecutorDemo.java gives a detailed demonstration on how to use and set up the Graph2DLayoutExecutor. It shows in particular the aspects of an asynchronous layout like locking the view, displaying a progress bar and cancelling a running layout upon user interaction.