Using event listeners

> > > >

All layout classes support two kinds of events: layout events and parameter events. The listening mechanism therefore provides:

Graph layout event listeners

The layout event listening mechanism provides a way to inform the user of what is happening during the layout. At times, a layout algorithm can take a long time to execute, especially when dealing with large graphs. In addition, an algorithm might not converge in some cases. No matter what the situation, the user must be informed of the events that occur during the layout.

This can be done by implementing a simple progress bar or by displaying appropriate information, such as the percentage of completion after each iteration or step.

The layout event listener is defined by the GraphLayoutEventListener interface. To receive the layout events delivered during the layout, a class must implement the GraphLayoutEventListener interface and must register itself using the addGraphLayoutEventListener method of the IlvGraphLayout class.

When you implement the GraphLayoutEventListener interface, you must implement the layoutStepPerformed method. The layout algorithm will call this method on all the registered layout event listeners, passing the layout report as an argument.

See Using a graph layout report. In this way, you can read information about the current state of the layout report. (For example, you can read this information after each iteration or step of the layout algorithm).

The following example shows how to implement a layout event listener:

class LayoutIterationListener 
  implements GraphLayoutEventListener 
{ 
  public void layoutStepPerformed(GraphLayoutEvent event)
  { 
    IlvGraphLayoutReport layoutReport = event.getLayoutReport(); 
    System.out.println("percentage of completion: " + 
                       layoutReport.getPercentageComplete()); 
  } 
}

Then, register the listener on the layout instance as follows:

layout.addGraphLayoutEventListener(new LayoutIterationListener());

Parameter event listeners

The layout parameter event listeners mechanism provides a way to inform the user that any layout parameter has changed.

This is useful when the layout parameter values are displayed in a dialog box that needs to be updated to indicate parameter changes. The parameter event listener is defined by the GraphLayoutParameterEventListener interface. To receive the layout parameter events, a class must implement the GraphLayoutParameterEventListener interface and must register itself using the addGraphLayoutParameterEventListener method of the IlvGraphLayout class.

When you implement the GraphLayoutParameterEventListener interface, you must implement the parametersUpToDate method. The layout class will call this method on all the registered layout parameter event listeners. The layout parameter event contains a flag accessible by the isParametersUpToDate method:

It returns true if the event occurs at the end of a run of the layout when the layout is considered up-to-date with respect to the layout parameters.
It returns false if the event occurs when any layout parameter has changed.

The following example shows how to implement a layout parameter event listener.

class LayoutParameterListener 
  implements GraphLayoutParameterEventListener 
{ 
  public void parametersUpToDate(GraphLayoutParameterEvent event)
  { 
    if (!event.isParametersUpToDate())
      System.out.println("Any layout parameter has changed.”);
  } 
}

Then, register the listener with the layout instance as follows:

layout.addGraphLayoutParameterEventListener(new LayoutParameterListener());

Current section

Using advanced features