ilog.views.graphlayout.labellayout
Class IlvLabelingModel

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

Direct Known Subclasses:

IlvDefaultLabelingModel

public abstract class IlvLabelingModel
extends Object

IlvLabelingModel defines a suitable generic API for labels that have to be automatically positioned with ILOG JViews label layout algorithms.

The label model is similar to the graph model (or Swing's TreeModel and TableModel). Instead of asking programmers to extend their data objects from a predefined base class, it allows the use of any application object as a label or an obstacle. This makes it much easier to add labeling features to existing applications.

All the labeling algorithms provided in ILOG JViews are designed to lay out a labeling model. This allows any application to benefit from the ILOG JViews label layout algorithms, whether or not it uses the ILOG JViews manager (IlvManager) or the typical ILOG JViews labels (IlvLabel). However, to make things very simple for the common case of applications that use an IlvManager, it is not mandatory to work directly with the labeling model. ILOG JViews provides a default implementation of the labeling model (IlvDefaultLabelingModel) that can be used to handle labels in an IlvManager.

The main goal of the labeling model is to tell the labeling algorithm which are the labels and how to move them, and which are the obstacles that the labels should not overlap after the movement. An object is either a label or an obstacle, or neither (that means it is ignored). To keep the model very generic, it can work with any arbitrary objects of class java.lang.Object.

This class is abstract. Since its purpose is not to provide a concrete implementation of a label data structure, a complete implementation must be provided by "adapter" classes. To create a concrete labeling model, you need to subclass the IlvLabelingModel to create the adapter class, and you need to provide an implementation for the abstract methods. A special adapter class, IlvDefaultLabelingModel, is provided in order to use an IlvManager as the underlying label container data structure.

Note that if an application uses the class IlvManager, the manager can be attached directly to the label layout instance without explicitly using a labeling model (see the method IlvLabelLayout.attach). In this case, the appropriate labeling model (IlvDefaultLabelingModel) will be created internally. If necessary, it can be retrieved using the method IlvLabelLayout.getLabelingModel(), which in this case returns an instance of IlvDefaultLabelingModel.

The methods defined in this class can be divided into the following categories:

• Methods that provide information about the labels and allow you to move labels to new positions. For instance getLabels(), moveLabel, and so on.
• Methods that provide information about the obstacles that should not be overlapped by labels. For instance: getObstacles(), isObstacle(java.lang.Object), and so on.
• Methods that provide information about the geometry of the objects. For instance: boundingBox(Object), getLabelOverlap, and so on.
• Methods that provide useful services such as the notification of changes of the manager, the capability to store "property objects" for labels and obstacles, and so on.

Some of these methods are abstract and must be implemented by the concrete labeling model class. Note that the efficiency of the label layout algorithms directly depends on the efficiency of the implementation of the concrete label model subclass. This is also the reason why the model provides some extra methods for polyline obstacles (see isPolylineObstacle(java.lang.Object)), in addition to the generic methods, because these are likely to become subjects of optimizations.

To improve performance, you can replace the default implementation of the nonabstract methods with an overridden version in the adapter class that is optimized for your particular data structure. The IlvDefaultLabelingModel provides the optimized methods for the ILOG JViews manager (IlvManager).

Note that you must call the method dispose() after detaching the label layouts when you no longer need the labeling model instance; otherwise, some objects may not be garbage collected. This is necessary only if the labeling model instance is directly created by your code. Calling dispose() is not necessary if the labeling model instance is created internally by the ILOG JViews Graph Layout library, for instance when attaching directly an IlvManager to a layout instance using IlvLabelLayout.attach(IlvManager).

Since:

JViews 5.0

See Also:

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

Constructor Summary

IlvLabelingModel()
Creates a new IlvLabelingModel.

Method Summary

void	addLabelingModelListener(LabelingModelListener listener) Adds a listener to listen for modifications of the labeling model.
void	adjustmentEnd() Notifies the labeling model that this is the end of a series of events.
void	afterLayout(IlvLabelLayout layout, IlvLabelLayoutReport layoutReport, boolean redraw) Notifies the labeling model that a layout session has finished.
void	beforeLayout(IlvLabelLayout layout, boolean redraw) Notifies the labeling model that a layout session has been started.
abstract IlvRect	boundingBox(Object labelOrObstacle) Returns the bounding rectangle of a label or obstacle.
IlvLabelingModel	createLabelingModel(Object subgraph) Creates a new labeling model for a subgraph.
void	dispose() Disposes of this IlvLabelingModel and releases any resources that it is using.
protected void	fireLabelingModelEvent(LabelingModelEvent event) This method must be called by the adapter classes when the contents have changed (labels or obstacles were added, moved, or removed).
void	fireLabelingModelEvent(Object obstacleOrLabel, int eventType, boolean adjusting) Notifies the labeling-model-event listeners that labels or obstacles have been added or removed, or that their geometry has changed (labels or obstacles were moved or resized).
void	geometryChanged(boolean adjusting, Object obstacleOrLabel) Deprecated. Beginning with JViews 5.5, use the method fireLabelingModelEvent(Object, int, boolean) instead.
int	getInstanceId() A utility method that returns a unique integer value for each labeling model instance inside the same Java program.
abstract double	getLabelOverlap(Object label1, IlvRect bbox1, Object label2, IlvRect bbox2, float minDist) Returns the overlap between two labels, if the labels would be at the given positions specified by the passed bounding boxes.
abstract Enumeration	getLabels() Returns the enumeration of all labels.
int	getLabelsCount() Returns the number of labels.
IlvManager	getManager() Returns the IlvManager that stores the labels and the obstacles.
abstract double	getObstacleOverlap(Object label, IlvRect labelBBox, Object obstacle, IlvRect obstacleBBox, float minDist) Returns the overlap between the label and the obstacle, if the label would be at the given position specified by the passed bounding box.
abstract Enumeration	getObstacles() Returns the enumeration of all obstacles.
int	getObstaclesCount() Returns the number of obstacles.
double	getPolylineObstacleOverlap(Object label, IlvRect labelBBox, Object polylineObstacle, IlvPoint[] pts, float lineWidth, float minDist) Returns the overlap between the label and the polyline obstacle, if the label would be at the given position specified by the passed bounding box.
IlvPoint[]	getPolylinePoints(Object polylineObstacle) Returns the points that define the shape of a polyline obstacle.
float	getPolylineWidth(Object polylineObstacle) Returns the line width of a polyline obstacle.
Object	getProperty(Object labelOrObstacle, String key) Returns the value of a property.
Object	getProperty(String key) Returns the value of a property of the labeling model.
boolean	isBoundingBoxDependent() Returns true if two objects overlap only if their bounding boxes overlap.
abstract boolean	isLabel(Object obj) Returns true if an object is a valid label and false otherwise.
boolean	isLayoutNeeded(IlvLabelLayout layout) Returns true if a given layout that has been already applied to this manager is still valid.
abstract boolean	isObstacle(Object obj) Returns true if an object is a valid obstacle and false otherwise.
boolean	isPolylineObstacle(Object obj) Returns true if an object is a valid polyline obstacle and false otherwise.
abstract void	moveLabel(Object label, float x, float y, boolean redraw) Changes the position of the specified label.
void	removeLabelingModelListener(LabelingModelListener listener) Removes a listener added with addLabelingModelListener.
void	setProperty(Object labelOrObstacle, String key, Object value) Sets the value of a property for a label or an obstacle.
void	setProperty(String key, Object value) Sets the value of a property for the labeling model.
void	structureChanged(boolean adjusting, Object obstacleOrLabel) Deprecated. Beginning with JViews 5.5, use the method fireLabelingModelEvent(Object, int, boolean) instead.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvLabelingModel

public IlvLabelingModel()

Creates a new IlvLabelingModel.

Method Detail

dispose

public void dispose()

Disposes of this IlvLabelingModel and releases any resources that it is using. An IlvLabelingModel object cannot be used after the dispose method has been called. If there are any layouts still attached, they get automatically detached from the labeling model.

See Also:

Object.finalize()

getInstanceId

public final int getInstanceId()

A utility method that returns a unique integer value for each labeling model instance inside the same Java program. This method can be used to obtain names for properties that are unique for each labeling model instance.

getManager

public IlvManager getManager()

Returns the IlvManager that stores the labels and the obstacles. It returns null if the labels and obstacles are not stored by the ILOG JViews manager class (IlvManager).

The default implementation always returns null. The method is overridden in the class IlvDefaultLabelingModel.

createLabelingModel

public IlvLabelingModel createLabelingModel(Object subgraph)

Creates a new labeling model for a subgraph. The method is used when performing a layout of nested graphs that contain labels. It is called on the labeling model of a top-level graph that contains the subgraph.

Subclasses must override this method in order to return a new instance of the appropriate subclass of IlvLabelingModel, encapsulating subgraph.

Parameters:

subgraph - The subgraph object.

Returns:

Always null

Since:

JViews 5.5

getLabels

public abstract Enumeration getLabels()

Returns the enumeration of all labels.

See Also:

getLabelsCount()

getLabelsCount

public int getLabelsCount()

Returns the number of labels. The default implementation simply counts the number of labels as returned by the method getLabels().

See Also:

getLabels()

isLabel

public abstract boolean isLabel(Object obj)

Returns true if an object is a valid label and false otherwise.

Parameters:

obj - The object to test.

Returns:

true if the object is a label.

moveLabel

public abstract void moveLabel(Object label,
                               float x,
                               float y,
                               boolean redraw)

Changes the position of the specified label. The x and y coordinates correspond to the top-left corner of the rectangle that defines the label (see also the method boundingBox(Object)).

Parameters:

label - The label.

x - The new x-position of the label.

y - The new y-position of the label.

redraw - If true, the label is redrawn.

getLabelOverlap

public abstract double getLabelOverlap(Object label1,
                                       IlvRect bbox1,
                                       Object label2,
                                       IlvRect bbox2,
                                       float minDist)

Returns the overlap between two labels, if the labels would be at the given positions specified by the passed bounding boxes. This is used as a test before the labels are actually moved to these positions. Therefore, the labels are still at the old positions at the time of the call. A return value of 0 indicates that there is no overlap if the labels are moved to the given positions. For instance, the size of the overlapped area can be used as the overlap value.

The overlap value should be symmetric, that is, the returned value should be the same for label pairs independent of the order in which the labels are passed as arguments.

Parameters:

label1 - The first label.

bbox1 - The bounding box of the first label, translated to the proposed position of the label.

label2 - The second label.

bbox2 - The bounding box of the second label, translated to the proposed position of the label.

minDist - The desired minimal distance between labels.

Returns:

A value that describes the amount of overlap.

getObstacles

public abstract Enumeration getObstacles()

Returns the enumeration of all obstacles.

See Also:

getObstaclesCount()

getObstaclesCount

public int getObstaclesCount()

Returns the number of obstacles. The default implementation simply counts the number of obstacles as returned by the method getObstacles().

See Also:

getObstacles()

isObstacle

public abstract boolean isObstacle(Object obj)

Returns true if an object is a valid obstacle and false otherwise.

Parameters:

obj - The object to test.

Returns:

true if the object is an obstacle.

See Also:

isPolylineObstacle(java.lang.Object)

getObstacleOverlap

public abstract double getObstacleOverlap(Object label,
                                          IlvRect labelBBox,
                                          Object obstacle,
                                          IlvRect obstacleBBox,
                                          float minDist)

Returns the overlap between the label and the obstacle, if the label would be at the given position specified by the passed bounding box. This is used as a test before the label is actually moved to this position. Therefore, the label is still at the old position at the time of the call. A return value of 0 indicates that there is no overlap if the label is moved to the given position. For instance, the size of the overlapped area can be used as the overlap value.

Parameters:

label - The label.

labelBBox - The bounding box of the label, translated to the proposed position of the label.

obstacle - The obstacle.

obstacleBBox - The bounding box of the obstacle.

minDist - The desired minimal distance between label and obstacle.

Returns:

A value that describes the amount of overlap.

isPolylineObstacle

public boolean isPolylineObstacle(Object obj)

Returns true if an object is a valid polyline obstacle and false otherwise.

Typical polyline obstacles are IlvLine, IlvPolyline, and IlvLinkImage. If an object is a polyline obstacle, the method isObstacle(java.lang.Object) should also return true. Some labeling layout algorithms allow you to handle polyline obstacles in a more efficient way than other obstacles. If an obstacle is a polyline obstacle, the method getPolylineObstacleOverlap is called instead of the method getObstacleOverlap to obtain the overlap value.

The default implementation always returns false.

Parameters:

obj - The object to test.

Returns:

true if the object is a polyline obstacle.

See Also:

isObstacle(java.lang.Object)

getPolylineObstacleOverlap

public double getPolylineObstacleOverlap(Object label,
                                         IlvRect labelBBox,
                                         Object polylineObstacle,
                                         IlvPoint[] pts,
                                         float lineWidth,
                                         float minDist)

Returns the overlap between the label and the polyline obstacle, if the label would be at the given position specified by the passed bounding box. This is used as a test before the label is actually moved to this position. Therefore, the label is still at the old position at the time of the call. A return value of 0 indicates that there is no overlap if the label is moved to the given position.

The default implementation simply calls getObstacleOverlap. Labeling models may override this method in order to handle polyline obstacles more efficiently. Label layout algorithms should call this method for polyline obstacles instead of getObstacleOverlap. to allow the concrete labeling model to optimize the treatment of polyline obstacles.

Parameters:

label - The label.

labelBBox - The bounding box of the label, translated to the proposed position of the label.

polylineObstacle - The polyline obstacle.

pts - The points that define the shape of the polyline obstacle.

lineWidth - The line width of the polyline obstacle.

minDist - The desired minimal distance between label and obstacle.

Returns:

A value that describes the amount of overlap.

See Also:

isPolylineObstacle(java.lang.Object)

getPolylineWidth

public float getPolylineWidth(Object polylineObstacle)

Returns the line width of a polyline obstacle. The default implementation returns 1.

Parameters:

polylineObstacle - The polyline obstacle.

Returns:

The line width, a positive value.

See Also:

isPolylineObstacle(java.lang.Object)

getPolylinePoints

public IlvPoint[] getPolylinePoints(Object polylineObstacle)

Returns the points that define the shape of a polyline obstacle. The default implementation returns null.

Parameters:

polylineObstacle - The polyline obstacle.

Returns:

The points of the polyline, including the start and end points.

See Also:

isPolylineObstacle(java.lang.Object)

boundingBox

public abstract IlvRect boundingBox(Object labelOrObstacle)

Returns the bounding rectangle of a label or obstacle.

Note that the IlvRect object that is returned by this method may be modified by internal methods of ILOG JViews.

If the labeling model supports rotated labels, this method must return the unrotated bounding box of the label.

Parameters:

labelOrObstacle - The label.

Returns:

The bounding rectangle of the input object.

isBoundingBoxDependent

public boolean isBoundingBoxDependent()

Returns true if two objects overlap only if their bounding boxes overlap.

If the method getLabelOverlap or getObstacleOverlap always returns 0 if the bounding boxes of the objects do not overlap, then this method may return true. If the method getLabelOverlap or getObstacleOverlap may return a nonzero value even though the bounding boxes of the objects do not overlap, then this method must return false.

If this method returns true, then the label layout algorithms may run faster due to possibilities for optimization.

The default implementation returns false.

isLayoutNeeded

public boolean isLayoutNeeded(IlvLabelLayout layout)

Returns true if a given layout that has been already applied to this manager is still valid. The method returns true if at least one of the following holds:

• The method IlvLabelLayout.isParametersUpToDate() called on layout returns false.
• The method IlvLabelLayout.isGeometryUpToDate() called on layout returns false.
• The method IlvLabelLayout.isStructureUpToDate() called on layout returns false.

If none of the conditions above holds, the method returns false

See Also:

IlvLabelLayout.isLayoutNeeded(), IlvLabelLayout.isStructureUpToDate(), IlvLabelLayout.isGeometryUpToDate(), IlvLabelLayout.isParametersUpToDate()

beforeLayout

public void beforeLayout(IlvLabelLayout layout,
                         boolean redraw)

Notifies the labeling model that a layout session has been started. This method is always called by IlvLabelLayout.performLayout() before the call to the method IlvLabelLayout.layout(boolean).

The default implementation does nothing. If necessary, you can override this method to perform preliminary operations before the layout.

Parameters:

layout - The layout instance that is the origin of the notification.

redraw - If true, the layout algorithm will ask the labeling model to redraw the objects when the method afterLayout is called (that is, it will pass true for its redraw argument).

See Also:

afterLayout(ilog.views.graphlayout.labellayout.IlvLabelLayout, ilog.views.graphlayout.labellayout.IlvLabelLayoutReport, boolean)

afterLayout

public void afterLayout(IlvLabelLayout layout,
                        IlvLabelLayoutReport layoutReport,
                        boolean redraw)

Notifies the labeling model that a layout session has finished. This method is always called by IlvLabelLayout.performLayout() after the method IlvLabelLayout.layout(boolean) has finished, even if an exception is thrown during the layout process.

Note that you can detect whether the layout was performed successfully using the test layoutReport.getCode() == IlvLabelLayoutReport.LAYOUT_DONE.

The default implementation does nothing. Any implementation of this method should redraw the objects if the argument redraw is true.

Parameters:

layout - The layout instance that is the origin of the notification.

layoutReport - The layout report.

redraw - If true, the layout algorithm asks the labeling model to redraw the graph.

See Also:

beforeLayout(ilog.views.graphlayout.labellayout.IlvLabelLayout, boolean)

setProperty

public void setProperty(Object labelOrObstacle,
                        String key,
                        Object value)

Sets the value of a property for a label or an obstacle. If value is null, the property is removed. Otherwise, the property value is set to value.

The default implementation uses an internal hash table to store the property. A concrete labeling model that allows you to store properties directly in the labels and obstacles should override this method to gain more efficiency.

Parameters:

labelOrObstacle - The label or obstacle for which the property is to be set.

key - The key string for the property.

value - The new value of the property.

See Also:

getProperty(java.lang.Object, java.lang.String)

getProperty

public Object getProperty(Object labelOrObstacle,
                          String key)

Returns the value of a property. The method returns null if the property does not exist.

The default implementation uses an internal hash table to store the property. A concrete labeling model that allows you to store properties directly in the labels and obstacles should override this method to gain more efficiency.

Parameters:

labelOrObstacle - The label or obstacle for which the property is to be retrieved.

key - The key string for the property.

Returns:

The value of the property.

See Also:

setProperty(java.lang.Object, java.lang.String, java.lang.Object)

setProperty

public void setProperty(String key,
                        Object value)

Sets the value of a property for the labeling model. If value is null, the property is removed. Otherwise, the property value is set to value.

The default implementation uses an internal hash table to store the property. This is the same hash table as used for the properties of labels and obstacles. A concrete labeling model may override this method to gain more efficiency.

Parameters:

key - The key string for the property.

value - The new value of the property.

See Also:

getProperty(java.lang.Object, java.lang.String)

getProperty

public Object getProperty(String key)

Returns the value of a property of the labeling model. The method returns null if the property does not exist.

The default implementation uses an internal hash table to store the property. This is the same hash table as used for the properties of labels and obstacles. A concrete labeling model may override this method to gain more efficiency.

Parameters:

key - The key string for the property.

Returns:

The value of the property.

See Also:

setProperty(java.lang.Object, java.lang.String, java.lang.Object)

addLabelingModelListener

public void addLabelingModelListener(LabelingModelListener listener)

Adds a listener to listen for modifications of the labeling model.

Parameters:

listener - The listener to add.

See Also:

removeLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener)

removeLabelingModelListener

public void removeLabelingModelListener(LabelingModelListener listener)

Removes a listener added with addLabelingModelListener.

Parameters:

listener - The listener to remove.

See Also:

addLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener)

fireLabelingModelEvent

public final void fireLabelingModelEvent(Object obstacleOrLabel,
                                         int eventType,
                                         boolean adjusting)

Notifies the labeling-model-event listeners that labels or obstacles have been added or removed, or that their geometry has changed (labels or obstacles were moved or resized).

It is the responsibility of the labeling model subclasses to call this method any time the contents of the model have changed (for example, when changes are due to user interaction). The method constructs the event and then calls fireLabelingModelEvent(LabelingModelEvent) to pass the event to the listeners.

This notification is needed to allow the label layout algorithms to detect changes and avoid performing the label layout when it is not needed. If a labeling model subclass does not call this method but a change has occurred in the graph, you need to force a re-layout by passing a force flag of true and calling the method IlvLabelLayout.performLayout().

Furthermore, the notification is used by the default labeling model (class IlvDefaultLabelingModel to ensure that IlvLabelLayout.cleanLabel(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object) and IlvLabelLayout.cleanObstacle(ilog.views.graphlayout.labellayout.IlvLabelingModel, java.lang.Object) are called automatically at the right time. The default labeling model calls this method with event type LabelingModelEvent.LABEL_REMOVED or LabelingModelEvent.OBSTACLE_REMOVED whenever a label or obstacle is removed. If you do not use the default labeling model or if your model does not fire these events, the cleanup is not done automatically, so you need to call these cleaning methods yourself.

Parameters:

obstacleOrLabel - The object that was added or removed, or null if the event concerns unknown obstacles or labels.

eventType - The type of the event (a combination of the bit masks, see LabelingModelEvent.getType()).

adjusting - Indicates whether this event is in a series of similar events.

Since:

JViews 5.5

See Also:

addLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener), adjustmentEnd(), fireLabelingModelEvent(LabelingModelEvent)

fireLabelingModelEvent

protected void fireLabelingModelEvent(LabelingModelEvent event)

This method must be called by the adapter classes when the contents have changed (labels or obstacles were added, moved, or removed). This method notifies the listeners of the labeling model contents.

Parameters:

event - The labeling model event.

See Also:

removeLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener), addLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener), fireLabelingModelEvent(Object, int, boolean), adjustmentEnd(), LabelingModelEvent

adjustmentEnd

public final void adjustmentEnd()

Notifies the labeling model that this is the end of a series of events.

It is the responsibility of the labeling model subclasses to call this method after a series of adjusting events.

This notification is needed to allow the label layout algorithms to detect changes and avoid performing the label layout when it is not needed. If a labeling model subclass does not call this method but a change has occurred in the graph, you need to force a re-layout by passing a force flag of true and calling the method IlvLabelLayout.performLayout().

See Also:

addLabelingModelListener(ilog.views.graphlayout.labellayout.LabelingModelListener), fireLabelingModelEvent(java.lang.Object, int, boolean)

structureChanged

public final void structureChanged(boolean adjusting,
                                   Object obstacleOrLabel)

Deprecated. Beginning with JViews 5.5, use the method fireLabelingModelEvent(Object, int, boolean) instead.

Notifies the labeling-model-event listeners that labels or obstacles have been added or removed.

geometryChanged

public final void geometryChanged(boolean adjusting,
                                  Object obstacleOrLabel)

Deprecated. Beginning with JViews 5.5, use the method fireLabelingModelEvent(Object, int, boolean) instead.

Notifies the labeling model that the geometry of the labels or obstacles has changed (labels or obstacles were moved or resized).