ilog.views

Class IlvIndexedSet

java.lang.Object

ilog.views.IlvIndexedSet

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

IlvManagerLayer

public class IlvIndexedSet
extends Object
implements Serializable

IlvIndexedSet is a class dedicated to managing a large number of graphic objects in a list or a quadtree.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
IlvIndexedSet() Creates a new indexed set.
IlvIndexedSet(int maxInNode, int maxInList) Creates a new indexed set.

Method Summary

Modifier and Type	Method and Description
void	addObject(IlvGraphic obj) Adds an object.
void	afterUpdate(IlvGraphic obj, IlvRect bbox) Updates the location of the object in the quadtree.
void	beforeUpdate(IlvGraphic obj, IlvRect bbox) Prepares the update of the IlvIndexedSet.
void	collectObjects(IlvPoint p, IlvPoint tp, IlvTransformer t, IlvGraphicVector result) Collects all visible objects at a specified location.
void	collectSelectableObjects(IlvPoint p, IlvPoint tp, IlvTransformer t, IlvGraphicVector result) Collects all visible and selectable objects at a specified location.
IlvRect	computeBBox(IlvTransformer t) Returns the bounding rectangle of the set when drawn with the specified transformer.
void	deleteAll() Removes all the objects.
int	getCardinal() Returns the number of objects.
IlvGraphicEnumeration	getElements() Returns an enumeration of all the objects.
int	getIndex(IlvGraphic obj) Returns the index of the specified object in the IlvIndexedSet.
IlvGraphicEnumeration	getManagers() Returns an enumeration of all the instances of IlvManager that have been added in this IlvIndexedSet.
int	getManagersCount() Returns the number of IlvManager objects that have been added in this IlvIndexedSet.
IlvGraphic	getObject(IlvPoint p, IlvPoint tp, IlvTransformer t) Looks for a visible object at a specified location.
IlvGraphic	getObject(int index) Returns the object at the input index.
IlvGraphic	getSelectableObject(IlvPoint p, IlvPoint tp, IlvTransformer t) Looks for a visible and selectable object at a specified location.
long	getSubsequentRemoveThreshold() Returns the threshold for optimized remove operations.
boolean	isQuadtreeEnabled() Returns true if the quadtree is enabled.
boolean	isZOrdering() Returns whether Z-ordering is enabled.
void	map(IlvApplyObject f, Object arg) Applies a function to all the objects in the set.
void	mapInside(IlvRect rect, IlvRect trect, IlvApplyObject f, Object arg, IlvTransformer t) Applies a function to all objects located in a specified rectangle.
void	mapInside(IlvRect rect, IlvRect trect, IlvApplyObject f, Object arg, IlvTransformer t, boolean traverse) Applies a function to all objects located in a specified rectangle.
void	mapIntersects(IlvRect rect, IlvRect trect, IlvApplyObject f, Object arg, IlvTransformer t) Applies a function to all objects with a bounding box that intersects a specified rectangle.
void	mapIntersects(IlvRect rect, IlvRect trect, IlvApplyObject f, Object arg, IlvTransformer t, boolean traverse) Applies a function to all objects with a bounding box that intersects a specified rectangle.
void	removeObject(IlvGraphic obj) Removes an object.
void	setIndex(IlvGraphic obj, int index) Changes the index of the specified object in the IlvIndexedSet.
static void	SetInitialNumberOfNonZoomablesCapacity(int length) Sets the initial capacity of the internal vector of the indexed set that stores the nonzoomable objects.
static void	SetInitialNumberOfObjectsCapacity(int length) Sets the initial capacity of the internal vector of the indexed set that stores all (zoomable and nonzoomable) objects.
void	setQuadtreeEnabled(boolean enable) Enables or disables the quadtree.
void	setSubsequentRemoveThreshold(long threshold) Sets the threshold when to use optimized remove operations.
void	setZOrdering(boolean enable) Sets whether Z-ordering is enabled.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvIndexedSet

public IlvIndexedSet()

Creates a new indexed set.

IlvIndexedSet

public IlvIndexedSet(int maxInNode,
                     int maxInList)

Creates a new indexed set.

Parameters:

maxInNode - The maximum number of objects for a node of the quadtree.

maxInList - The maximum number of objects before using the quadtree.

Method Detail

setQuadtreeEnabled

public void setQuadtreeEnabled(boolean enable)

Enables or disables the quadtree. By default, the quadtree is enabled. If disabled, the graphic objects of this indexed set are stored in a list.

Compared to a list, the quadtree is a spatial data structure that speeds up the search of graphic objects at a given location (for instance getObject, mapInside, mapIntersects) but requires a (usually negligible) slowdown of operations that modify the location of any objects (see afterUpdate).

Parameters:

enable - If true, the quadtree gets enabled; otherwise it gets disabled.

Since:

JViews 3.5

See Also:

isQuadtreeEnabled(), getObject(ilog.views.IlvPoint, ilog.views.IlvPoint, ilog.views.IlvTransformer), mapInside(ilog.views.IlvRect, ilog.views.IlvRect, ilog.views.IlvApplyObject, java.lang.Object, ilog.views.IlvTransformer), mapIntersects(ilog.views.IlvRect, ilog.views.IlvRect, ilog.views.IlvApplyObject, java.lang.Object, ilog.views.IlvTransformer), afterUpdate(ilog.views.IlvGraphic, ilog.views.IlvRect), IlvQuadtree

isQuadtreeEnabled

public boolean isQuadtreeEnabled()

Returns true if the quadtree is enabled.

Since:

JViews 3.5

See Also:

setQuadtreeEnabled(boolean), IlvQuadtree

setZOrdering

public void setZOrdering(boolean enable)

Sets whether Z-ordering is enabled. This affects the drawing order of objects within the indexed set.

If Z-ordering is disabled, the quadtree is free to choose any drawing order. This is in general the fastest option, since the quadtree is able to optimize the drawing performance by fine-tuned drawing orders. However, in this case, you cannot influence the drawing order through the method setIndex(ilog.views.IlvGraphic, int).

If Z-ordering is enabled, the drawing order is given by the indices of the objects (see getIndex(ilog.views.IlvGraphic)) and can be influenced through the method setIndex(ilog.views.IlvGraphic, int). This works when the quadtree is enabled as well as when the quadtree is disabled. The drawing order with disabled quadtree is anyway not chosen by the quadtree.

In terms of performance, using the quadtree without Z-ordering is the fastest option, using the quadtree with Z-ordering is slightly slower, and using no quadtree at all is the slowest option. The speed depends on various factors:

• if the objects are evenly distributed in the space, as it is normally in nearly all applications, it is better to use the quadtree. In this case, the performance of operations such as the hit-test getObject(IlvPoint, IlvPoint, IlvTransformer) are several magnitudes faster, even if Z-ordering is enabled.
• If nearly all objects are placed at exactly the same position and hence overlap each other, the quadtree does not bring much performance gain. In this case, the speed of the hit-test is nearly the same whether the quadtree is enabled or not. Such situations of heavy overlaps are however rather seldom in normal applications.

Since:

JViews 8.5

See Also:

isZOrdering(), setQuadtreeEnabled(boolean), setIndex(ilog.views.IlvGraphic, int)

isZOrdering

public boolean isZOrdering()

Returns whether Z-ordering is enabled.

Since:

JViews 8.5

See Also:

setZOrdering(boolean)

SetInitialNumberOfObjectsCapacity

public static void SetInitialNumberOfObjectsCapacity(int length)

Sets the initial capacity of the internal vector of the indexed set that stores all (zoomable and nonzoomable) objects. This is an expert option. The default value is 15. If more objects are added, the capacity of the internal vector is adjusted automatically. Usually you never need to change this value. However, if you know in advance how many objects will be contained in an indexed set in average, then you can adjust the initial capacity to avoid that memory is wasted or that too many automatic adjustments of the vector are necessary which may slow down the addObject(ilog.views.IlvGraphic) operation. You can change this value before allocating any indexed set. Once an indexed set is allocated and already filled, changing this value has no effect on that indexed set.

Since:

JViews 8.5

SetInitialNumberOfNonZoomablesCapacity

public static void SetInitialNumberOfNonZoomablesCapacity(int length)

Sets the initial capacity of the internal vector of the indexed set that stores the nonzoomable objects. This is an expert option. The default value is 15. If more objects are added, the capacity of the internal vector is adjusted automatically. Usually you never need to change this value. However, if you know in advance how many nonzoomable objects will be contained in an indexed set in average, then you can adjust the initial capacity to avoid that memory is wasted or that too many automatic adjustments of the vector are necessary which may slow down the addObject(ilog.views.IlvGraphic) operation. You can change this value before allocating any indexed set. Once an indexed set is allocated and already filled with nonzoomable objects, changing this value has no effect on that indexed set.

Since:

JViews 8.5

setSubsequentRemoveThreshold

public void setSubsequentRemoveThreshold(long threshold)

Sets the threshold when to use optimized remove operations. A sequence of remove operations might be very slow. If the number of subsequent remove operations exceeds the threshold, the indexed set starts using an optimized mechanism to remove elements, which is much faster. However, the disadvantage is that errors such as removing a nonexisting element are recognized delayed, so that error stack traces caused by such coding mistakes don't point to the original cause of the error.

You can set the threshold to Long.MAX_VALUE to disable the optimized mechanism, so that errors of the remove operation are detected immediately. This is in general better if you want to debug operations related to IlvIndexedSet.

The default value is 3.

Since:

JViews 8.1

See Also:

removeObject(ilog.views.IlvGraphic), getSubsequentRemoveThreshold()

getSubsequentRemoveThreshold

public long getSubsequentRemoveThreshold()

Returns the threshold for optimized remove operations.

Since:

JViews 8.1

See Also:

setSubsequentRemoveThreshold(long)

addObject

public void addObject(IlvGraphic obj)

Adds an object.

Parameters:

obj - The graphic object to be added.

removeObject

public void removeObject(IlvGraphic obj)

Removes an object.

Parameters:

obj - The graphic object to be removed.

getCardinal

public int getCardinal()

Returns the number of objects.

deleteAll

public void deleteAll()

Removes all the objects.

getObject

public IlvGraphic getObject(IlvPoint p,
                            IlvPoint tp,
                            IlvTransformer t)

Looks for a visible object at a specified location.

Parameters:

p - The point at which the search will be started.

tp - The point p transformed.

t - The transformer through which the set is drawn.

Returns:

The object located at location p if there is one. Otherwise it returns null.

See Also:

setQuadtreeEnabled(boolean)

getSelectableObject

public IlvGraphic getSelectableObject(IlvPoint p,
                                      IlvPoint tp,
                                      IlvTransformer t)

Looks for a visible and selectable object at a specified location.

Parameters:

p - The point at which the search will be started.

tp - The point p transformed.

t - The transformer through which the set is drawn.

Returns:

The object located at location p if there is one. Otherwise it returns null.

Since:

JViews 8.8

See Also:

setQuadtreeEnabled(boolean)

collectObjects

public void collectObjects(IlvPoint p,
                           IlvPoint tp,
                           IlvTransformer t,
                           IlvGraphicVector result)

Collects all visible objects at a specified location. Note that it returns the object in inverse drawing order, that is, the objects that appear topmost in the view are returned first.

Parameters:

p - The point at which the search will be started.

tp - The point p transformed.

t - The transformer through which the set is drawn.

result - The resulting objects.

Since:

JViews 8.1

See Also:

setQuadtreeEnabled(boolean)

collectSelectableObjects

public void collectSelectableObjects(IlvPoint p,
                                     IlvPoint tp,
                                     IlvTransformer t,
                                     IlvGraphicVector result)

Collects all visible and selectable objects at a specified location. Note that it returns the object in inverse drawing order, that is, the objects that appear topmost in the view are returned first.

Parameters:

p - The point at which the search will be started.

tp - The point p transformed.

t - The transformer through which the set is drawn.

result - The resulting objects.

Since:

JViews 8.8

See Also:

setQuadtreeEnabled(boolean)

beforeUpdate

public void beforeUpdate(IlvGraphic obj,
                         IlvRect bbox)

Prepares the update of the IlvIndexedSet. This method is called before a change of the bounding box of a graphic object.

You should not call this method directly.

Parameters:

obj - The graphic object.

bbox - The old bounding box of the graphic object in manager coordinates. It can be null, in which case it will be computed.

Since:

JViews 3.5

See Also:

afterUpdate(ilog.views.IlvGraphic, ilog.views.IlvRect)

afterUpdate

public void afterUpdate(IlvGraphic obj,
                        IlvRect bbox)

Updates the location of the object in the quadtree. Note that this method is used when you change the bounding box of the object. In this case, the object may need to first be removed from the quadtree, and then added again.

You should not call this method directly.

Parameters:

obj - The graphic object.

bbox - The new bounding box of the graphic object in manager coordinates. It can be null, in which case it will be computed.

Since:

JViews 3.5

See Also:

beforeUpdate(ilog.views.IlvGraphic, ilog.views.IlvRect), setQuadtreeEnabled(boolean)

getElements

public IlvGraphicEnumeration getElements()

Returns an enumeration of all the objects.

Note that it is not allowed to remove or add graphic objects while browsing the enumeration returned by this method. Wrap the returned enumeration into IlvBufferedGraphicEnumeration if it is necessary to add or remove objects while using the enumeration.

setIndex

public void setIndex(IlvGraphic obj,
                     int index)

Changes the index of the specified object in the IlvIndexedSet. If the specified graphic object is not in this IlvIndexedSet, the method does nothing and does not issue any exception. Elements between the current index of the object and the desired index are shifted by one position, that is, their index changes. Note that changing the index of an object in the IlvIndexedSet will only change the drawing order of the object if the Z-ordering option is enabled or if the quadtree is turned off. If the quadtree is enabled and the Z-ordering option is turned off, the quadtree is free to choose any faster drawing order regardless the indices of the objects of this indexed set.

Since:

JViews 5.0

See Also:

setQuadtreeEnabled(boolean), setZOrdering(boolean), getIndex(ilog.views.IlvGraphic)

getIndex

public int getIndex(IlvGraphic obj)

Returns the index of the specified object in the IlvIndexedSet. If the specified graphic object is not in this IlvIndexedSet, the method returns -1. Note that the index of an object in the IlvIndexedSet defines the drawing order of the object only if the Z-ordering option is enabled or if the quadtree is turned off. If the quadtree is enabled and the Z-ordering option is turned off, there is no way to influence the drawing order within the indexed set. If the quadtree is enabled and the Z-ordering option is turned off, the quadtree is free to choose any faster drawing order regardless the indices of the objects of this indexed set.

Since:

JViews 5.0

See Also:

setQuadtreeEnabled(boolean), setZOrdering(boolean), setIndex(ilog.views.IlvGraphic, int)

getObject

public IlvGraphic getObject(int index)

Returns the object at the input index. The input index must be a valid index between 0 and the cardinal of the IlvIndexedSet. Note that the index of an object in the IlvIndexedSet defines the drawing order of the object only if the Z-ordering option is enabled or if the quadtree is turned off. If the quadtree is enabled and the Z-ordering option is turned off, the quadtree is free to choose any faster drawing order regardless the indices of the objects of this indexed set.

Since:

JViews 8.1

See Also:

setQuadtreeEnabled(boolean), setZOrdering(boolean), getCardinal(), setIndex(ilog.views.IlvGraphic, int)

getManagers

public IlvGraphicEnumeration getManagers()

Returns an enumeration of all the instances of IlvManager that have been added in this IlvIndexedSet. Note that it is not allowed to remove or add managers while browsing the enumeration returned by this method. Wrap the returned enumeration into IlvBufferedGraphicEnumeration if it is necessary to add or remove managers while using the enumeration.

Since:

JViews 5.0

getManagersCount

public int getManagersCount()

Returns the number of IlvManager objects that have been added in this IlvIndexedSet.

Since:

JViews 5.0

map

public void map(IlvApplyObject f,
                Object arg)

Applies a function to all the objects in the set.

Parameters:

f - The function to be applied.

arg - The argument of the function.

mapInside

public void mapInside(IlvRect rect,
                      IlvRect trect,
                      IlvApplyObject f,
                      Object arg,
                      IlvTransformer t)

Applies a function to all objects located in a specified rectangle. This method applies the method f to all graphic objects inside the rectangle rect.

Parameters:

rect - The rectangle.

trect - The transformed rectangle.

f - The method to be applied.

arg - The argument passed to the method.

t - The transformer used to display the set.

See Also:

setQuadtreeEnabled(boolean)

mapInside

public void mapInside(IlvRect rect,
                      IlvRect trect,
                      IlvApplyObject f,
                      Object arg,
                      IlvTransformer t,
                      boolean traverse)

Applies a function to all objects located in a specified rectangle. This method applies the method f to all graphic objects inside the rectangle rect. This method will traverse recursively the IlvManager objects added in this set to apply the function to all objects that are inside the specified rectangle if the parameter traverse is set to true.

Parameters:

rect - The rectangle.

trect - The transformed rectangle.

f - The method to be applied.

arg - The argument passed to the method.

t - The transformer used to display the set.

traverse - When true, the method will traverse recursively the IlvManager objects added in this set to apply the function to all objects that are inside the specified rectangle.

Since:

JViews 5.0

See Also:

setQuadtreeEnabled(boolean)

mapIntersects

public void mapIntersects(IlvRect rect,
                          IlvRect trect,
                          IlvApplyObject f,
                          Object arg,
                          IlvTransformer t)

Applies a function to all objects with a bounding box that intersects a specified rectangle.

Parameters:

rect - The rectangle.

trect - The transformed rectangle.

f - The method to be applied.

arg - The argument passed to the method.

t - The transformer used to display the set.

See Also:

setQuadtreeEnabled(boolean)

mapIntersects

public void mapIntersects(IlvRect rect,
                          IlvRect trect,
                          IlvApplyObject f,
                          Object arg,
                          IlvTransformer t,
                          boolean traverse)

Applies a function to all objects with a bounding box that intersects a specified rectangle. This method will traverse recursively the IlvManager objects added in this set to apply the function to all objects that intersect the rectangle if the parameter traverse is set to true.

Parameters:

rect - The rectangle.

trect - The transformed rectangle.

f - The method to be applied.

arg - The argument passed to the method.

t - The transformer used to display the set.

traverse - If true, then the method will traverse recursively the IlvManager objects added in this set to apply the function to all objects that intersect the rectangle.

Since:

JViews 5.0

See Also:

setQuadtreeEnabled(boolean)

computeBBox

public IlvRect computeBBox(IlvTransformer t)

Returns the bounding rectangle of the set when drawn with the specified transformer.

Parameters:

t - The transformer.