ilog.views.graphlayout.labellayout
Class IlvLabelLayout

java.lang.Object
  ilog.views.graphlayout.labellayout.IlvLabelLayout

All Implemented Interfaces:

LabelingModelListener, Serializable, EventListener

Direct Known Subclasses:

IlvAnnealingLabelLayout, IlvRandomLabelLayout

public abstract class IlvLabelLayout
extends Object
implements Serializable, LabelingModelListener

The base class of the Label Layout algorithms.

A Label Layout algorithm has the task to place labels at graphic objects such that the labels are well readable. Labels should not overlap each other or overlap the graphic objects of the IlvManager. ILOG JViews provides special support for this task. Using the IlvManager class, any graphic object can be defined to behave like a label and can be automatically placed as a decoration close to any graphic obstacle object.

The Label Layout algorithms are not restricted to be used only with IlvManager. They can be used with any data structure. This is achieved an IlvLabelingModel. This abstract class defines the API that is necessary to allow the label layout algorithms to work. To use your own data structures, all you need to do is to implement an adapter (a bridge) that connects your graphic data with the generic labeling model. For details, see the class IlvLabelingModel.

The class IlvLabelLayout is abstract and cannot be used directly. You must use one of its subclasses provided in this package.

You can also create your own subclasses to implement other layout algorithms. Note that, in order to be applied on any data structures, the layout algorithms must be written using the API of IlvLabelingModel instead of the API of IlvManager.

The class contains layout parameters or options that can be useful for different layout algorithms. The implementation of the layout(boolean) method is solely responsible for whether or not the current settings of the parameters are taken into account.

If the documentation does not indicate a different coordinate space, all dimensional parameters are expressed in the same coordinate space as the position and dimension of the labels and obstacles. In particular, when laying out an IlvManager, the dimensional parameters are expressed in manager coordinates, not in manager view coordinates. However, optionally, the coordinate space of the view can be used. For details, see setCoordinatesMode(int).

To learn more about the layout algorithms and the corresponding IlvLabelLayout subclasses, read the sections of the Reference Manual describing those classes and the ILOG JViews Label Layout User's Manual.

Note that the initialization of all instance variables of the subclasses needs to be done in the overridden implementation of the method init(). This is to prevent execution of methods of the subclasses before the initialization of the instance variables of the subclasses.

Note also that you must call the method detach() when you no longer need the layout instance; otherwise, some objects may not be garbage collected. This is necessary only if the layout instance is directly created by your code. Calling detach() is not necessary if the layout instance is created internally by the ILOG JViews Graph Layout library.

Since:

JViews 5.0

See Also:

IlvAnnealingLabelLayout, IlvRandomLabelLayout, IlvLabelingModel, IlvDefaultLabelingModel, IlvManager, Serialized Form

Field Summary

static int	INVERSE_VIEW_COORDINATES Inverse view coordinates mode.
static int	MANAGER_COORDINATES Manager coordinates mode.
static int	VIEW_COORDINATES View coordinates mode.

Constructor Summary

IlvLabelLayout()
Creates a new instance of the layout algorithm.

IlvLabelLayout(IlvLabelLayout source)
Creates a new label layout instance by copying an existing one.

Method Summary

void	addLabelLayoutEventListener(LabelLayoutEventListener listener) Adds a listener for the layout events delivered during the layout.
void	addLabelLayoutParameterEventListener(LabelLayoutParameterEventListener listener) Adds a listener for the layout parameter events delivered when layout parameters change.
void	attach(IlvLabelingModel labelingModel) Allows you to specify the labeling model you want to lay out.
void	attach(IlvManager manager) Allows you to specify the manager you want to lay out.
void	callLayoutStepPerformedIfNeeded() Calls layoutStepPerformed when necessary.
void	cleanLabel(IlvLabelingModel labelingModel, Object label) Cleans a label.
void	cleanLabelingModel(IlvLabelingModel labelingModel) Cleans a labeling model.
void	cleanObstacle(IlvLabelingModel labelingModel, Object obstacle) Cleans an obstacle.
void	contentsChanged(LabelingModelEvent event) Invoked when the structure or the geometry of the graph changes.
abstract IlvLabelLayout	copy() Copies the layout instance.
void	copyParameters(IlvLabelLayout source) Copies the parameters from a given layout instance.
protected IlvLabelLayoutLabelProperty	createLayoutLabelProperty(String name, IlvGraphic label, boolean withDefaults) Returns a new instance of a named property that can store the parameter settings of this layout class for labels.
protected IlvLabelLayoutManagerProperty	createLayoutManagerProperty(String name, boolean withDefaults) Returns a new instance of a named property that can store the parameter settings of this layout class.
protected IlvLabelLayoutReport	createLayoutReport() Returns a new instance of the layout report.
void	detach() Detaches the labeling model from the layout instance.
long	getAllowedTime() Returns the currently allowed time for the layout algorithm in milliseconds.
int	getCoordinatesMode() Returns the current coordinates mode.
int	getInstanceId() An utility method that returns an unique integer value for each layout instance inside the same java program.
IlvLabelingModel	getLabelingModel() Returns the attached labeling model.
IlvLabelLayoutReport	getLayoutReport() Returns the layout report, that is, the object that contains information about the behavior of the layout algorithm.
IlvManager	getManager() Returns the IlvManager which contains the labels to be laid out.
long	getMinBusyTime() Returns the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.
long	getSeedValueForRandomGenerator() Returns the user-defined seed value for the random generator.
void	increasePercentageComplete(int newPercentage) Increases the percentage of completion that is stored in the layout report to the input value.
protected void	init() Initializes instance variables.
boolean	isGeometryUpToDate() Returns false if at least one label or obstacle was moved or resized since the last time the layout was successfully performed on the same labeling model or if the layout has never been performed successfully on the same labeling model.
boolean	isInputCheckEnabled() Returns true if the checks for the labels and obstacles are enabled.
protected boolean	isLayoutNeeded() Verifies that it is necessary to perform the layout.
boolean	isLayoutRunning() Tells whether the layout algorithm is running or not.
protected boolean	isLayoutTimeElapsed() Returns true if, at the moment the method is called, the allowed layout time is exceeded; returns false otherwise.
boolean	isParametersUpToDate() Returns false if at least one parameter was modified since last time the layout was successfully performed on the same labeling model or if the layout has never been performed successfully on the same labeling model.
boolean	isStoppedImmediately() Returns true if the method stopImmediately was called.
boolean	isStoppedPrematurely() Returns true if the layout should stopped before completion.
boolean	isStructureUpToDate() Returns false if at least one modification occurred in the structure of the labeling model (a label or obstacle was added or removed) since the last time the layout was successfully performed on the same labeling model using this layout instance or if the layout has never been performed successfully on the same labeling model.
boolean	isUseDefaultParameters() Returns the current options for the parameters.
boolean	isUseSeedValueForRandomGenerator() Returns true if the user-defined seed value is used for the random generator and false otherwise.
protected abstract void	layout(boolean redraw) Executes the label layout.
void	layoutStepPerformed() This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed.
IlvLabelLayoutReport	performLayout() Starts the layout algorithm using the currently attached labeling model and the current settings for the layout parameters.
IlvLabelLayoutReport	performLayout(boolean force, boolean redraw) Starts the layout algorithm using the currently attached labeling model and the current settings for the layout parameters.
void	removeLabelLayoutEventListener(LabelLayoutEventListener listener) Removes a listener for the layout events delivered during the layout.
void	removeLabelLayoutParameterEventListener(LabelLayoutParameterEventListener listener) Removes a listener for the layout parameter events when layout parameters change.
void	setAllowedTime(long time) Allows you to specify an upper limit for the duration of the layout algorithm.
void	setCoordinatesMode(int mode) Sets the coordinates mode to be used during layout.
void	setGeometryUpToDate(boolean uptodate) If the argument is false, notifies the layout instance that the geometry of the manager was changed since the last time the layout was successfully performed.
void	setInputCheckEnabled(boolean enable) Enables or disables the checks for the labels and obstacles provided as arguments for the different methods of the layout algorithms.
protected void	setLayoutReport(IlvLabelLayoutReport report) Sets the layout report; that is, the object that contains information about the behavior of the layout algorithm.
void	setManager(IlvManager manager) Allows you to specify the manager you want to lay out.
void	setMinBusyTime(long time) Sets the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.
void	setParametersUpToDate(boolean uptodate) If the argument is false, notifies the layout instance that a parameter value was changed.
void	setSeedValueForRandomGenerator(long seed) Allows you to specify a seed value for the random generator.
void	setStructureUpToDate(boolean uptodate) If the argument is false, notifies the layout instance that the structure of the manager was changed since the last time the layout was successfully performed.
void	setUseDefaultParameters(boolean option) If the argument is true, the layout uses the default values of all the parameters; that is, the "get..." and "is..." methods return the default values.
void	setUseSeedValueForRandomGenerator(boolean option) Allows you to specify whether the user-defined seed value should be used for the random generator.
boolean	stopImmediately() Stops the running layout algorithm as soon as possible.
boolean	supportsAllowedTime() Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded.
boolean	supportsPercentageComplete() Indicates whether the layout class can estimate the percentage of completion during the run of layout.
boolean	supportsRandomGenerator() Indicates whether the layout class uses randomly-generated numbers (or randomly-chosen parameters) for which it can accept a user-defined seed value.
boolean	supportsSaveParametersToNamedProperties() Indicates whether the layout class can transfer the layout parameters to named properties.
boolean	supportsStopImmediately() Indicates whether the layout class can interrupt the current run of layout immediately in a controlled way.

Methods inherited from class java.lang.Object

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

Field Detail

INVERSE_VIEW_COORDINATES

public static final int INVERSE_VIEW_COORDINATES

Inverse view coordinates mode. When used as the argument of the method setCoordinatesMode(int), labels are placed in the coordinate system given by transforming view coordinates back into the coordinate system of the manager. For zoomable graphics, this is the same as the manager coordinates mode.

See Also:

Constant Field Values

MANAGER_COORDINATES

public static final int MANAGER_COORDINATES

Manager coordinates mode. When used as the argument of the method setCoordinatesMode(int), labels are placed in the coordinate system of the manager. This works well for zoomable graphic objects. If nonzoomable graphics are used and the view is transformed, it is recommended to use the inverse view coordinates mode instead.

See Also:

Constant Field Values

VIEW_COORDINATES

public static final int VIEW_COORDINATES

View coordinates mode. When used as the argument of the method setCoordinatesMode(int), labels are placed in the coordinate system of the view.

See Also:

Constant Field Values

Constructor Detail

IlvLabelLayout

public IlvLabelLayout()

Creates a new instance of the layout algorithm.

IlvLabelLayout

public IlvLabelLayout(IlvLabelLayout source)

Creates a new label layout instance by copying an existing one. This constructor is used by the copy() method. Any subclass should provide a copy constructor.

The parameters of the source layout are copied using the method copyParameters(ilog.views.graphlayout.labellayout.IlvLabelLayout).

Parameters:

source - The layout instance that is copied.

Method Detail

copyParameters

public void copyParameters(IlvLabelLayout source)

Copies the parameters from a given layout instance.

Note that layout parameters which are specific to a label or obstacle are not copied. Global layout parameters are copied.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

Subclasses that need to copy additional parameters must override this method. The method can be implemented as follows:

 public void copyParameters(IlvLabelLayout source)
 { 
   super.copyParameters(source);
   // MyLayout is the name of the subclass
   if (source instanceof MyLayout) {
     MyLayout msource = (MyLayout)source;
     // copy the attribute of the subclass
     setMyParameter(msource.getMyParameter());
   }
 }
 

Parameters:

source - The layout instance from which the parameters are copied.

init

protected void init()

Initializes instance variables.

You should not call this method directly. The method is called internally by the constructor without arguments and by the copy constructor.

The method must be overridden by subclasses that need to initialize additional instance variables. The initialization of all the instance variables of the subclasses must be done in this method.

copy

public abstract IlvLabelLayout copy()

Copies the layout instance.

This method copies the layout instance by calling a constructor defined like this: public <CLASSNAME>(<CLASSNAME> source).

Note that layout parameters which are specific to a label or obstacle are not copied. Global layout parameters are copied.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

Returns:

A copy of the layout instance.

See Also:

IlvLabelLayout(IlvLabelLayout)

attach

public void attach(IlvManager manager)

Allows you to specify the manager you want to lay out. This method automatically creates an IlvDefaultLabelingModel to encapsulate the manager. Then, the labeling model is attached to the layout instance by calling the method attach(IlvLabelingModel).

You must attach the manager before performing the layout, that is, before calling the method performLayout(), and before specifying layout parameters for specific labels or obstacles.

The method does nothing if the manager is already attached.

You can get the IlvDefaultLabelingModel instance created by this method using getLabelingModel(). However, notice that you are not allowed to do the following:

• Attach this model instance to any other layout instance.
• Use this model instance in any way once the method detach() has been called on the layout instance.

In case you need to be able to do any of the above operations, directly create the instance of IlvDefaultLabelingModel and attach it using attach(IlvLabelingModel).

Parameters:

manager - The manager to lay out.

See Also:

attach(IlvLabelingModel), detach(), getLabelingModel(), getManager()

attach

public void attach(IlvLabelingModel labelingModel)

Allows you to specify the labeling model you want to lay out.

You must attach the labeling model before performing the layout, that is, before calling the method performLayout(), and before specifying layout parameters for specific labels or obstacles.

This method first calls detach() if another labeling model is already attached. The method does nothing if the labeling model is already attached.

Parameters:

labelingModel - The labeling model to lay out.

See Also:

attach(ilog.views.IlvManager), detach(), getLabelingModel()

detach

public void detach()

Detaches the labeling model from the layout instance.

When a new labeling model is attached to the layout instance, it is not necessary to detach the previously attached labeling model because this is done automatically when the method attach(ilog.views.IlvManager) is called.

This method performs cleaning operations on the labeling model (for example, properties added to the labels and labeling model listeners are removed). The method cleanLabelingModel(ilog.views.graphlayout.labellayout.IlvLabelingModel) is called with the currently attached labeling model as argument. The methods cleanLabel(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object) and cleanObstacle(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object) are called for each label and obstacle.

Subclasses can override this method to remove additional information stored in the layout instance.

Note that you must call this method when you no longer need the layout instance; otherwise, some objects may not be garbage collected.

See Also:

attach(ilog.views.IlvManager), attach(IlvLabelingModel), cleanLabelingModel(ilog.views.graphlayout.labellayout.IlvLabelingModel), cleanLabel(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object), cleanObstacle(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object)

cleanLabelingModel

public void cleanLabelingModel(IlvLabelingModel labelingModel)

Cleans a labeling model. This method removes any data that has been stored by the layout algorithm on a labeling model.

Subclasses can override this method to remove additional information stored in the labeling model.

Parameters:

labelingModel - The labeling model to be cleaned.

See Also:

detach(), IlvLabelingModel.dispose()

cleanLabel

public void cleanLabel(IlvLabelingModel labelingModel,
                       Object label)

Cleans a label. This method removes any data that has been stored by the layout algorithm on a label.

The method is automatically called by contentsChanged(ilog.views.graphlayout.labellayout.LabelingModelEvent) whenever a LabelingModelEvent of type LabelingModelEvent.LABEL_REMOVED is received.

Subclasses can override this method to remove additional information stored in the labels. Notice that the method may be called multiple times for the same label. At the time this method is called, the label may already be removed; therefore, overridden versions of this method should be implemented so that they work even if the object is no longer a label.

Parameters:

labelingModel - The labeling model the label belongs to.

label - The label to be cleaned.

See Also:

detach()

cleanObstacle

public void cleanObstacle(IlvLabelingModel labelingModel,
                          Object obstacle)

Cleans an obstacle. This method removes any data that has been stored by the layout algorithm on an obstacle.

The method is automatically called by contentsChanged(ilog.views.graphlayout.labellayout.LabelingModelEvent) whenever a LabelingModelEvent of type LabelingModelEvent.OBSTACLE_REMOVED is received.

Subclasses can override this method to remove additional information stored in the obstacles. Notice that the method may be called multiple times for the same obstacle. At the time this method is called, the obstacle may already be removed; therefore, overridden versions of this method should be implemented so that they work even if the object is no longer an obstacle.

Parameters:

labelingModel - The labeling model the obstacle belongs to.

obstacle - The obstacle to be cleaned.

See Also:

detach()

getInstanceId

public final int getInstanceId()

An utility method that returns an unique integer value for each layout instance inside the same java program.

getLabelingModel

public IlvLabelingModel getLabelingModel()

Returns the attached labeling model. It returns null if no labeling model is attached.

If an IlvManager is attached directly using attach(IlvManager), the method returns the instance of IlvDefaultLabelingModel that has been created internally.

See Also:

attach(IlvLabelingModel), attach(ilog.views.IlvManager)

setManager

public void setManager(IlvManager manager)

Allows you to specify the manager you want to lay out. This method exists for JavaBean support. The method simply calls attach(ilog.views.IlvManager).

See Also:

attach(ilog.views.IlvManager), getManager()

getManager

public IlvManager getManager()

Returns the IlvManager which contains the labels to be laid out.

The method returns null if no manager is attached to the layout instance. Otherwise, it returns the object returned by the method IlvLabelingModel.getManager() called on the attached labeling model.

This means that the method returns the instance of IlvManager that has been attached directly using the method attach(IlvManager) or indirectly by passing an IlvDefaultLabelingModel as argument to the method attach(IlvLabelingModel). If the labels are not contained in an IlvManager (for instance, if you use a labeling model that is not a subclass of IlvDefaultLabelingModel), the method returns null.

See Also:

setManager(ilog.views.IlvManager), attach(ilog.views.IlvManager)

createLayoutReport

protected IlvLabelLayoutReport createLayoutReport()

Returns a new instance of the layout report. The default implementation returns a new instance of IlvLabelLayoutReport.

You can overwrite this method in order to create subclasses of IlvLabelLayoutReport.

This method is called by performLayout(). The returned object is stored internally in the layout instance and will be returned by the method performLayout().

You can use this method to obtain information about the behavior of the layout algorithm if the information is added in the layout report inside the implementation of the layout(boolean) method where it can be obtained using getLayoutReport().

While the layout(boolean) method is running, you can also obtain the layout report outside this method using the layout event listener mechanism (see addLabelLayoutEventListener(LabelLayoutEventListener)).

See Also:

getLayoutReport(), IlvLabelLayoutReport, performLayout(boolean, boolean), addLabelLayoutEventListener(LabelLayoutEventListener)

setLayoutReport

protected void setLayoutReport(IlvLabelLayoutReport report)

Sets the layout report; that is, the object that contains information about the behavior of the layout algorithm.

This method is called automatically by performLayout() with the layout report created using the method createLayoutReport(). Subclasses can override this method in order to perform additional actions.

See Also:

createLayoutReport(), getLayoutReport(), performLayout(boolean, boolean)

getLayoutReport

public final IlvLabelLayoutReport getLayoutReport()

Returns the layout report, that is, the object that contains information about the behavior of the layout algorithm.

If this method is called after the method performLayout() was called for the first time on this layout instance, it returns the instance of layout report created by createLayoutReport(). Otherwise, it returns null.

See Also:

createLayoutReport(), setLayoutReport(ilog.views.graphlayout.labellayout.IlvLabelLayoutReport)

performLayout

public IlvLabelLayoutReport performLayout()

Starts the layout algorithm using the currently attached labeling model and the current settings for the layout parameters.

This method simply calls performLayout(boolean, boolean) with the force argument set to false and the redraw argument set to true.

Returns:

The instance of the layout report created by createLayoutReport().

See Also:

performLayout(boolean, boolean)

performLayout

public IlvLabelLayoutReport performLayout(boolean force,
                                          boolean redraw)

Starts the layout algorithm using the currently attached labeling model and the current settings for the layout parameters.

The implementation of this method first calls createLayoutReport() to obtain a new instance of the layout report. This instance is stored internally and can be used to obtain information about the behavior of the layout algorithm when the method returns. The implementation of the layout(boolean) method is solely responsible for adding this information to the layout report. Note that subclasses of IlvLabelLayout can override the method createLayoutReport() in order to return a subclass of IlvLabelLayoutReport when additional information needs to be stored in the report.

If there are no labels, the appropriate code (IlvLabelLayoutReport.NO_LABELS) is stored in the layout report and the method returns.

If the argument force is false, the method calls isLayoutNeeded() to determine if it is necessary to perform the layout. If this method returns false, the appropriate code (IlvLabelLayoutReport.NOT_NEEDED) is stored in the layout report and the method returns.

Otherwise, if the argument force is true or isLayoutNeeded() returns true, the method IlvLabelingModel.beforeLayout(IlvLabelLayout, boolean) is called on the attached labeling model. The redraw argument is passed to this method. Then, the method layout(boolean), which executes the layout algorithm, is called.

Note that while the layout(boolean) method is running, you can also obtain the layout report outside this method using the layout event listener mechanism (see addLabelLayoutEventListener(LabelLayoutEventListener)).

If the layout is successfully performed (that is, if the method IlvLabelLayoutReport.getCode() called on the layout report instance returns IlvLabelLayoutReport.LAYOUT_DONE or IlvLabelLayoutReport.STOPPED_AND_VALID), the layout instance is notified that the structure, the geometry, and the parameters are now up-to-date (see the methods isStructureUpToDate(), isGeometryUpToDate(), and isParametersUpToDate()).

In any case, if the method IlvLabelingModel.beforeLayout(IlvLabelLayout, boolean) has been * called, the method IlvLabelingModel.afterLayout(IlvLabelLayout, IlvLabelLayoutReport, boolean) is finally called on the attached labeling model. The redraw argument is passed to this method.

Parameters:

force - If true, the method isLayoutNeeded() is not called. No check is made to determine if it is necessary to perform the layout.

redraw - If true, the attached labeling model will be asked to redraw all objects after layout. To move the labels, the implementation of this method passes the value of the redraw argument to the method IlvLabelingModel.moveLabel(java.lang.Object, float, float, boolean).

Returns:

The instance of the layout report created by createLayoutReport().

See Also:

performLayout(), layout(boolean), isLayoutNeeded(), isStructureUpToDate(), isGeometryUpToDate(), isParametersUpToDate(), IlvDefaultLabelingModel.addLayer(ilog.views.IlvManagerLayer)

isLayoutNeeded

protected boolean isLayoutNeeded()

Verifies that it is necessary to perform the layout. The default implementation returns the value returned by a call of the method IlvLabelingModel.isLayoutNeeded(ilog.views.graphlayout.labellayout.IlvLabelLayout) on the attached labeling model, with this layout instance as argument.

If no labeling model is attached, the method returns false.

Basically, the method returns false if no changes occurred on the labeling model (no labels or obstacles were inserted, removed, resized or moved) and no parameters changed since the last time the layout was successfully performed using this layout instance. Otherwise, the method returns true.

Returns:

true if it is necessary to perform the layout, false otherwise.

See Also:

isStructureUpToDate(), isGeometryUpToDate(), isParametersUpToDate()

layout

protected abstract void layout(boolean redraw)

Executes the label layout.

This method must be implemented by each layout algorithm (subclasses of IlvLabelLayout). This method computes the coordinates of the labels in the attached labeling model and moves the labels to the new positions using the method IlvLabelingModel.moveLabel(java.lang.Object, float, float, boolean).

When writing the implementation of this method, you can obtain an instance of the layout report using getLayoutReport() and can store particular information about the behavior of the layout algorithm in the layout report. You can also notify the layout event listeners using the method layoutStepPerformed().

When the layout algorithm is finished and if the layout is performed successfully, you must call the method IlvLabelLayoutReport.setCode(int) with the argument IlvLabelLayoutReport.LAYOUT_DONE on the layout report instance.

Here is a sample implementation for a Random layout:

 protected void layout(boolean redraw)
   throws RuntimeException
 {
   // obtain the labeling model
   IlvLabelingModel labelingModel = getLabelingModel();
   // obtain the layout report
   IlvLabelLayoutReport layoutReport = getLayoutReport();

   // obtain the layout region
   float xMin = 0f;
   float yMin = 0f;
   float xMax = 100f;
   float yMax = 100f;

   // initialize the random generator
   Random random = (isUseSeedValueForRandomGenerator()) ?
     new Random(getSeedValueForRandomGenerator()) :
     new Random();

   // get an enumeration of the labels
   Enumeration labels = labelingModel.getLabels();

   // browse the labels
   while (labels.hasMoreElements()) {
     Object label = labels.nextElement();

     // compute coordinates
     float x = xMin + (xMax - xMin) * random.nextFloat();
     float y = yMin + (yMax - yMin) * random.nextFloat();

     // move the label to the computed position
     labelingModel.moveLabel(label, x, y, redraw);

     // notify listeners on layout events
     layoutStepPerformed();
   }

   layoutReport.setCode(IlvLabelLayoutReport.LAYOUT_DONE);
 }
 

Parameters:

redraw - If true, the attached labeling model will be asked to redraw the manager after layout. When the layout algorithm moves the labels, it is required to pass the value of the redraw argument to the method IlvLabelingModel.moveLabel(java.lang.Object, float, float, boolean).

See Also:

performLayout(boolean, boolean), getLayoutReport(), layoutStepPerformed(), IlvLabelingModel

isLayoutRunning

public final boolean isLayoutRunning()

Tells whether the layout algorithm is running or not. Returns true if the layout has been started and is not yet completed. Returns false otherwise.

The layout is considered as started once the method performLayout() is called. It is considered as completed after this method returns or throws an exception.

See Also:

performLayout()

addLabelLayoutEventListener

public void addLabelLayoutEventListener(LabelLayoutEventListener listener)

Adds a listener for the layout events delivered during the layout.

If you add a listener, you can receive information during the execution of the layout (after each iteration, for example). You can use a listener in this way, for example, to implement a progress bar.

Note that to have a listener notified, the subclass of IlvLabelLayout that you use must call layoutStepPerformed().

Parameters:

listener - The listener to add.

See Also:

removeLabelLayoutEventListener(LabelLayoutEventListener), layoutStepPerformed()

removeLabelLayoutEventListener

public void removeLabelLayoutEventListener(LabelLayoutEventListener listener)

Removes a listener for the layout events delivered during the layout.

Parameters:

listener - The listener to remove.

See Also:

addLabelLayoutEventListener(LabelLayoutEventListener)

addLabelLayoutParameterEventListener

public void addLabelLayoutParameterEventListener(LabelLayoutParameterEventListener listener)

Adds a listener for the layout parameter events delivered when layout parameters change.

If you add a listener, you can receive an event each time the method setParametersUpToDate(boolean) is called; that is, each time when a layout parameter changes and each time the layout was successfully performed. You can use a listener in this way, for example, to update a display that shows the current values of the layout parameters or to update the a flag indicating whether the set of layout parameters must be saved to a file.

See Also:

removeLabelLayoutParameterEventListener(LabelLayoutParameterEventListener), setParametersUpToDate(boolean)

removeLabelLayoutParameterEventListener

public void removeLabelLayoutParameterEventListener(LabelLayoutParameterEventListener listener)

Removes a listener for the layout parameter events when layout parameters change.

See Also:

addLabelLayoutParameterEventListener(LabelLayoutParameterEventListener)

layoutStepPerformed

public void layoutStepPerformed()

This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed. The method notifies the listeners of the layout events (if any).

This method is intended to be called from the implementation of the method layout(boolean).

See Also:

addLabelLayoutEventListener(LabelLayoutEventListener), removeLabelLayoutEventListener(LabelLayoutEventListener), LabelLayoutEvent, layout(boolean)

callLayoutStepPerformedIfNeeded

public final void callLayoutStepPerformedIfNeeded()

Calls layoutStepPerformed when necessary.

This method is provided for convenience of the implementation of layout algorithms. It calls layoutStepPerformed() when the last call finished earlier than the minimal busy time before this call. It avoids calling layoutStepPerformed() when the layout time has elapsed or when the layout is notified to stop immediately, if the algorithm supports these features.

This mechanism is used by some algorithms to avoid the overhead of layoutStepPerformed() becoming too high if it is called too often. Internal routines of layout algorithms can use callLayoutStepPerformedIfNeeded often without worrying that too many layout events are raised.

Layout algorithms call layoutStepPerformed() directly instead of using callLayoutStepPerformedIfNeeded when it is necessary to report a specific state (for example, when the layout report sets the code IlvLabelLayoutReport.LAYOUT_STARTED or IlvLabelLayoutReport.LAYOUT_FINISHED).

See Also:

LabelLayoutEvent, IlvLabelLayoutReport, layoutStepPerformed(), setMinBusyTime(long), setAllowedTime(long), stopImmediately()

isStoppedPrematurely

public final boolean isStoppedPrematurely()

Returns true if the layout should stopped before completion. This may happen if the layout algorithm supports the setting of the allowed time, and the layout time elapsed, or the algorithm was stopped by stopImmediately().

This flag is set and tested inside callLayoutStepPerformedIfNeeded(). This method is provided for convenience of the implementation of layout algorithms. It can be called directly after a call of callLayoutStepPerformedIfNeeded() and returns true if isLayoutTimeElapsed() or isStoppedImmediately() returns true.

See Also:

supportsAllowedTime(), supportsStopImmediately()

setMinBusyTime

public void setMinBusyTime(long time)

Sets the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.

The objective is to avoid the overhead of layoutStepPerformed() becoming too high if the method is called too often. Internal routines of layout algorithms usually call callLayoutStepPerformedIfNeeded(), which calls layoutStepPerformed() if the time since the last call was at least the minimal busy time.

The default value is 50 (milliseconds).

See Also:

layoutStepPerformed(), callLayoutStepPerformedIfNeeded(), getMinBusyTime()

getMinBusyTime

public long getMinBusyTime()

Returns the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.

See Also:

layoutStepPerformed(), callLayoutStepPerformedIfNeeded(), setMinBusyTime(long)

setStructureUpToDate

public void setStructureUpToDate(boolean uptodate)

If the argument is false, notifies the layout instance that the structure of the manager was changed since the last time the layout was successfully performed.

Usually, you do not need to call this method. The method is automatically called with a true argument each time the layout is successfully performed.

See Also:

isStructureUpToDate(), isLayoutNeeded()

isStructureUpToDate

public boolean isStructureUpToDate()

Returns false if at least one modification occurred in the structure of the labeling model (a label or obstacle was added or removed) since the last time the layout was successfully performed on the same labeling model using this layout instance or if the layout has never been performed successfully on the same labeling model. The following are considered to be modifications of the structure: adding or removing a label or obstacle, or modifying one of the layers to be taken into account during the layout (see IlvDefaultLabelingModel.addLayer(ilog.views.IlvManagerLayer)).

Returns true if no changes occurred.

This method is automatically called by isLayoutNeeded().

Note that when the layout is performed successfully (that is, IlvLabelLayoutReport.getCode() called on the layout report returns IlvLabelLayoutReport.LAYOUT_DONE), the layout instance is automatically notified that the structure is now up-to-date. It is also automatically notified of the topological modifications of the labeling model using a manager-contents-changed listener.

See Also:

performLayout(boolean, boolean), isLayoutNeeded(), setStructureUpToDate(boolean)

setGeometryUpToDate

public void setGeometryUpToDate(boolean uptodate)

If the argument is false, notifies the layout instance that the geometry of the manager was changed since the last time the layout was successfully performed.

Usually, you do not need to call this method. The method is automatically called with a true argument each time the layout is successfully performed.

See Also:

isGeometryUpToDate(), isLayoutNeeded()

isGeometryUpToDate

public boolean isGeometryUpToDate()

Returns false if at least one label or obstacle was moved or resized since the last time the layout was successfully performed on the same labeling model or if the layout has never been performed successfully on the same labeling model.

Returns true if no changes occurred.

This method is automatically called by isLayoutNeeded().

Note that when the layout is performed successfully (that is, IlvLabelLayoutReport.getCode() called on the layout report returns IlvLabelLayoutReport.LAYOUT_DONE), the layout instance is automatically notified that the geometry of the manager is now up-to-date. It is also automatically notified of the modifications of the geometry of the labeling model using a manager-contents-changed listener.

See Also:

performLayout(boolean, boolean), setGeometryUpToDate(boolean), isLayoutNeeded()

setParametersUpToDate

public void setParametersUpToDate(boolean uptodate)

If the argument is false, notifies the layout instance that a parameter value was changed.

This method is automatically called with a false argument each time the value of a parameter is changed using the methods provided in this class or in its subclasses provided in ILOG JViews. If you add new parameters in your own subclass of IlvLabelLayout, you should call this method with a false argument each time they are modified.

The method is automatically called with a true argument each time the layout is successfully performed.

See Also:

isParametersUpToDate(), isLayoutNeeded(), addLabelLayoutParameterEventListener(LabelLayoutParameterEventListener), removeLabelLayoutParameterEventListener(LabelLayoutParameterEventListener)

isParametersUpToDate

public boolean isParametersUpToDate()

Returns false if at least one parameter was modified since last time the layout was successfully performed on the same labeling model or if the layout has never been performed successfully on the same labeling model.

Returns true if no parameters changed since the last time the layout was successfully performed on the same labeling model.

This method is automatically called by isLayoutNeeded().

Note that when the layout is performed successfully (that is, IlvLabelLayoutReport.getCode() called on the layout report returns IlvLabelLayoutReport.LAYOUT_DONE), the layout instance is automatically notified that the parameters are now up-to-date.

See Also:

performLayout(boolean, boolean), setParametersUpToDate(boolean), isLayoutNeeded()

setUseDefaultParameters

public void setUseDefaultParameters(boolean option)

If the argument is true, the layout uses the default values of all the parameters; that is, the "get..." and "is..." methods return the default values.

The default value of this parameter is false.

See Also:

isUseDefaultParameters()

isUseDefaultParameters

public boolean isUseDefaultParameters()

Returns the current options for the parameters.

See Also:

setUseDefaultParameters(boolean)

setCoordinatesMode

public void setCoordinatesMode(int mode)

Sets the coordinates mode to be used during layout.

Valid value are:

• MANAGER_COORDINATES - Labels are placed in the coordinate system of the manager, without applying any transformation.

  This mode should be used if you visualize objects at zoom level 1, or you don't visualize it at all, or the manager contains only fully-zoomable objects. Indeed, in all these cases there's no need to take the transformer into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager's coordinates.

• VIEW_COORDINATES - Labels are placed in the coordinate system of the manager view. In the default labeling model, all the coordinates are transformed using the current reference transformer.

  This mode should be used if you want the dimensional parameters of the layout algorithms to be considered as being specified in manager view's coordinates.

• INVERSE_VIEW_COORDINATES - Labels are placed in the coordinate system given by transforming view coordinates back into the coordinate system of the manager. This mode is equivalent to the "manager coordinates" mode if the geometry of the graphic objects strictly obeys to the transformer. (A small difference may exist because of the limited precision of the computations.)

  On the contrary, if some graphic objects are either non-zoomable (see IlvGraphic.zoomable()) or semi-zoomable (e.g. links with a maximum line width), this mode gives different results than the manager's coordinates mode. These results are optimal if the manager is visualized using the same transformer as the one taken into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager's coordinates.

This option can be used only if the attached labeling model is an IlvDefaultLabelingModel (or a subclass). Otherwise, it has no effect. Note: the coordinates mode of the layout is only used while layout is running. If layout is not running, operations on the default labeling model use the coordinates mode that was set on the labeling model directly (see IlvDefaultLabelingModel.setCoordinatesMode(int)).

See Also:

getCoordinatesMode(), IlvDefaultLabelingModel.setCoordinatesMode(int), IlvDefaultLabelingModel.setReferenceTransformer(ilog.views.IlvTransformer), IlvDefaultLabelingModel.setReferenceView(ilog.views.IlvManagerView)

getCoordinatesMode

public int getCoordinatesMode()

Returns the current coordinates mode.

See Also:

setCoordinatesMode(int)

setInputCheckEnabled

public void setInputCheckEnabled(boolean enable)

Enables or disables the checks for the labels and obstacles provided as arguments for the different methods of the layout algorithms.

If enabled, methods that require a label or an obstacle as argument check whether the object they receive is really a label or an obstacle in the attached labeling model (using the methods IlvLabelingModel.isLabel(java.lang.Object) and IlvLabelingModel.isObstacle(java.lang.Object)).

The default value is true. The checks can be disabled in order to avoid their overhead cost.

See Also:

isInputCheckEnabled()

isInputCheckEnabled

public final boolean isInputCheckEnabled()

Returns true if the checks for the labels and obstacles are enabled. Returns false otherwise.

See Also:

setInputCheckEnabled(boolean)

supportsPercentageComplete

public boolean supportsPercentageComplete()

Indicates whether the layout class can estimate the percentage of completion during the run of layout. If supported, the percentage is stored in the layout report and can be retrieved by any layout event listener. For instance, this feature can be used by a progress bar that shows how much of the layout has already been performed.

The default implementation always returns false. Subclasses can override this method in order to return true; that is, to indicate that this option is supported.

Returns:

always false.

See Also:

increasePercentageComplete(int), IlvLabelLayoutReport.getPercentageComplete()

increasePercentageComplete

public void increasePercentageComplete(int newPercentage)

Increases the percentage of completion that is stored in the layout report to the input value. Layout algorithms that support the percentage complete feature should call this method during the run of the layout. This method does not set the percentage to a lower value than the previous value. It also does not set the value to more than 100%. It silently ignores wrong input values.

See Also:

supportsPercentageComplete(), IlvLabelLayoutReport.getPercentageComplete()

supportsStopImmediately

public boolean supportsStopImmediately()

Indicates whether the layout class can interrupt the current run of layout immediately in a controlled way.

The default implementation always returns false. Subclasses can override this method in order to return true; that is, to indicate that this option is supported.

Returns:

always false.

See Also:

stopImmediately(), isStoppedImmediately(), stopImmediately()

stopImmediately

public boolean stopImmediately()

Stops the running layout algorithm as soon as possible.

This method only sets the flag isStoppedImmediately() to true. It is the sole responsibility of the implementation of the method layout(boolean) to react in an appropriate way. Layout algorithms that support the immediate stop feature should check this flag from time to time and react when the flag isStoppedImmediately() changes to true.

This method can be used when multiple threads are used for layout and GUI control. The GUI control thread calls this method to notify the layout thread that the layout run must be stopped. This method returns true if the