ilog.views.tiling
Class IlvTileController

java.lang.Object
  ilog.views.tiling.IlvTileController

All Implemented Interfaces:

IlvPersistentObject

public class IlvTileController
extends Object
implements IlvPersistentObject

This class manages the load-on-demand mechanism. This mechanism works on tiles that represent rectangular parts of the drawing space. Each time a tile becomes visible in a view of the manager to which it is attached, the tile controller notifies a loader (called tile loader) to load the data attached to this tile. A cache releases the invisible tiles (called the cached tiles) when it is necessary to free memory.

The tile controller has two modes: indexed mode and free mode.

• In indexed mode, the space is divided into a number of identical rectangular tile areas. The individual tiles can be accessed by row and column index. The tiles are allocated automatically when needed.
• In free mode, the tiles must be provided to the controller via addTile(ilog.views.tiling.IlvFreeTile). There can be gaps between the tiles and tiles can overlap. The row and column index of the tile doesn't play a role in this mode. The controller does not allocate tiles automatically but merely manages the loading of the contents of a tile when the tile becomes visible.

A predefined class called IlvTiledLayer implements this mechanism to dynamically load graphic objects when they become visible in a view. Using an IlvTiledLayer does not always require direct use of its tile controller, unless a fine control is needed.

Since:

ILOG JViews 3.0

See Also:

IlvTiledLayer

Field Summary

static int	FREE The free mode of the tile controller: the tiles must be provided to the controller via addTile(ilog.views.tiling.IlvFreeTile).
static int	INDEXED The indexed mode of the tile controller: the space is divided into a number of identical rectangular tile areas.
static int	LEFT_COLUMN_INDEX The index that contains the rank of the column farthest to the left in the array of integers returned by getTileIndexes.
static int	LOWER_ROW_INDEX The index that contains the rank of the lower row in the array of integers returned by getTileIndexes.
static int	RIGHT_COLUMN_INDEX The index that contains the rank of the column farthest to the right in the array of integers returned by getTileIndexes.
static int	UPPER_ROW_INDEX The index that contains the rank of the upper row in the array of integers returned by getTileIndexes.

Constructor Summary

IlvTileController(IlvInputStream stream)
Reads the tile controller from an IlvInputStream.

IlvTileController(IlvManager manager)
Creates an instance of a tile controller for the manager.

IlvTileController(IlvManager manager, IlvRect tileOrigin)
Creates an instance of a tile controller for the manager.

IlvTileController(IlvManager manager, IlvRect tileOrigin, IlvTileCache cache)
Creates an instance of a tile controller for the manager and specifies the cache.

IlvTileController(IlvManager manager, IlvTileCache cache)
Creates an instance of a tile controller for the manager and specifies the cache.

Method Summary

void	addTile(IlvFreeTile tile) Adds a free tile to this tile controller.
void	addTileListener(TileListener listener) Adds a listener that will be notified of the changes in the tile status.
void	dispose() Stops the load-on-demand mechanism.
IlvTileCache	getCache() Returns the cache that manages the cached tiles of the controller.
Collection	getIntersectingTiles(IlvRect rect) Gets all tiles intersecting the specified rectangle.
IlvTiledLayer	getLayer() Returns the layer if the tile controller is the tile controller of an IlvTiledLayer.
IlvTileLockFilter	getLockFilter() Returns the lock filter of the controller.
IlvManager	getManager() Returns the manager of the tile controller.
int	getMode() Returns the mode of the controller.
IlvRect	getSize() Returns the specified size of the tile controller if it has been specified.
IlvTile	getTile(int column, int row) Returns the specified tile or null if the tile is neither loaded nor cached.
int[]	getTileIndexes(IlvRect rect) Returns the indexes of the tiles intersecting rect (rect is expressed in the manager coordinate system).
IlvTileLoader	getTileLoader() Returns the tile loader of the controller.
IlvRect	getTileOrigin() Returns the bounding box of the tile (0, 0).
Collection	getTiles() Returns a collection of all tiles managed by this controller.
void	ignoreView(IlvManagerView view, boolean ignore) Specifies to the tile loader to never load a tile if it is visible in the specified view.
boolean	isIgnoringView(IlvManagerView view) Returns true if the view is ignored by the tile controller.
boolean	isPrintingErrors() Returns whether this tile controller is printing the errors occurring while loading a tile.
boolean	isUnlockFilteredTiles() Indicates if unlocking locked filtered tiles is allowed or not.
void	lockTile(IlvTile tile, Object source) Loads the specified tile.
void	lockTile(int column, int row, Object source) Loads the specified tile.
void	removeAllFreeTiles() Removes all the free tiles.
void	removeTileListener(TileListener listener) Removes the listener from the tile controller.
void	setLockFilter(IlvTileLockFilter lockFilter) Sets a filter that allows a view to lock tiles.
void	setPrintingErrors(boolean print) Specifies whether this tile controller should print all errors occurring while loading a tile.
void	setSize(IlvRect rect) Specifies the area in which the tiles are contained.
void	setTileLoader(IlvTileLoader tileLoader) Sets the tile loader of the controller.
void	setUnlockFilteredTiles(boolean unlockFilteredTiles) Allows or avoids to unlock filtered tiles which are already locked but which are not anymore lockable.
void	tileBBox(int column, int row, IlvRect result) Computes the bounding box of the specified tile and sets it to result.
boolean	unlockTile(int row, int column, Object source) Removes the lock of the specified tile for the source object.
void	unlockTiles(Object source) Unlocks all the tiles that have been locked by the specified object.
void	updateView(IlvManagerView view) Updates a view and loads the required tiles.
void	write(IlvOutputStream stream) Writes the tile controller to an IlvOutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

INDEXED

public static final int INDEXED

The indexed mode of the tile controller: the space is divided into a number of identical rectangular tile areas. The individual tiles can be accessed by row and column index. The tiles are allocated automatically when needed.

Since:

JViews 7.5

See Also:

getMode(), Constant Field Values

FREE

public static final int FREE

The free mode of the tile controller: the tiles must be provided to the controller via addTile(ilog.views.tiling.IlvFreeTile). There can be gaps between the tiles and tiles can overlap. The row and column index of the tile doesn't play a role in this mode.

Since:

JViews 7.5

See Also:

getMode(), Constant Field Values

LEFT_COLUMN_INDEX

public static final int LEFT_COLUMN_INDEX

The index that contains the rank of the column farthest to the left in the array of integers returned by getTileIndexes.

See Also:

getTileIndexes(ilog.views.IlvRect), Constant Field Values

RIGHT_COLUMN_INDEX

public static final int RIGHT_COLUMN_INDEX

The index that contains the rank of the column farthest to the right in the array of integers returned by getTileIndexes.

See Also:

getTileIndexes(ilog.views.IlvRect), Constant Field Values

UPPER_ROW_INDEX

public static final int UPPER_ROW_INDEX

The index that contains the rank of the upper row in the array of integers returned by getTileIndexes.

See Also:

getTileIndexes(ilog.views.IlvRect), Constant Field Values

LOWER_ROW_INDEX

public static final int LOWER_ROW_INDEX

The index that contains the rank of the lower row in the array of integers returned by getTileIndexes.

See Also:

getTileIndexes(ilog.views.IlvRect), Constant Field Values

Constructor Detail

IlvTileController

public IlvTileController(IlvManager manager,
                         IlvRect tileOrigin)

Creates an instance of a tile controller for the manager. The tile controller will manage the loading and caching of tiles depending on what is visible in the views of the manager. This tile controller uses the indexed mode.

Parameters:

manager - The manager

tileOrigin - The position of the tile of row 0 and column 0

See Also:

getMode()

IlvTileController

public IlvTileController(IlvManager manager,
                         IlvRect tileOrigin,
                         IlvTileCache cache)

Creates an instance of a tile controller for the manager and specifies the cache. The tile controller will manage the loading and caching of tiles depending on what is visible in the views of the manager. This tile controller uses the indexed mode.

Parameters:

manager - The manager

tileOrigin - The position of the tile of row 0 and column 0

cache - The tile cache that will manage the tiles cached by this controller. A cache can be shared by several tile controllers or tiled layers.

See Also:

getMode()

IlvTileController

public IlvTileController(IlvManager manager)

Creates an instance of a tile controller for the manager. The tile controller will manage the loading and caching of tiles depending on what is visible in the views of the manager. This tile controller uses the free mode.

Parameters:

manager - The manager

Since:

JViews 7.5

IlvTileController

public IlvTileController(IlvManager manager,
                         IlvTileCache cache)

Creates an instance of a tile controller for the manager and specifies the cache. The tile controller will manage the loading and caching of tiles depending on what is visible in the views of the manager. This tile controller uses the free mode.

Parameters:

manager - The manager

cache - The tile cache that will manage the tiles cached by this controller. A cache can be shared by several tile controllers or tiled layers.

Since:

JViews 7.5

IlvTileController

public IlvTileController(IlvInputStream stream)
                  throws IlvReadFileException

Reads the tile controller from an IlvInputStream.

Parameters:

stream - The input stream

Throws:

IlvReadFileException - if the format is not correct.

Method Detail

getMode

public int getMode()

Returns the mode of the controller. The mode of the controller depends on which constructor was used to create the controller. The options are:

• INDEXED - the space is divided into a number of identical rectangular tile areas. The individual tiles can be accessed by row and column index. The tiles are allocated automatically when needed.
• FREE - the tiles must be provided to the controller via addTile(ilog.views.tiling.IlvFreeTile). There can be gaps between the tiles and tiles can overlap. The row and column index of the tile doesn't play a role in this mode. The controller does not allocate tiles automatically but merely manages the loading of the contents of a tile when the tile becomes visible.

Since:

JViews 7.5

setLockFilter

public void setLockFilter(IlvTileLockFilter lockFilter)

Sets a filter that allows a view to lock tiles. If null is provided, tiles can be locked by any view where they become visible.

getLockFilter

public IlvTileLockFilter getLockFilter()

Returns the lock filter of the controller. If a tile filter is set to the tile controller, it will be called to potentially veto any tile lock triggered by an event in a view (scrolling, zooming, resizing and so on).
If no lock filter has been attached to the tile controller, the method returns null.

setPrintingErrors

public void setPrintingErrors(boolean print)

Specifies whether this tile controller should print all errors occurring while loading a tile.

isPrintingErrors

public boolean isPrintingErrors()

Returns whether this tile controller is printing the errors occurring while loading a tile.

setSize

public void setSize(IlvRect rect)

Specifies the area in which the tiles are contained. If the rect parameter is set to null, there is no limit to the tiling grid. Only in indexed mode, setting the size has an effect. In free mode, the size is always calculated from the tiles added to the controller.

Parameters:

rect - The area in which the tiles are contained.

getSize

public IlvRect getSize()

Returns the specified size of the tile controller if it has been specified.

getTileIndexes

public int[] getTileIndexes(IlvRect rect)

Returns the indexes of the tiles intersecting rect (rect is expressed in the manager coordinate system).

The following example prints the list of tiles that are visible in a rectangle.

 int indexes[] = 
       tileController.getTileIndexes(new IlvRect(0, 0, 100, 100));
 int left = indexes[IlvTileController.LEFT_COLUMN_INDEX];
 int right = indexes[IlvTileController.RIGHT_COLUMN_INDEX];
 int top = indexes[IlvTileController.UPPER_ROW_INDEX];
 int bottom = indexes[IlvTileController.LOWER_ROW_INDEX];
 for (int i = left; i < right; i++)
   for (int j = top; j < bottom; j++)
     System.out.println("Tile " + i + "," + j +
                            " intersects the rectangle");
 

Parameters:

rect - The rectangle expressed in the manager coordinate system

Returns:

an array of int where result[LEFT_COLUMN_INDEX] is the index of the left column, result[RIGHT_COLUMN_INDEX] is the index of the right column, result[UPPER_ROW_INDEX] is the index of the upper row, result[LOWER_ROW_INDEX] is the index of the lower row.

See Also:

LEFT_COLUMN_INDEX, RIGHT_COLUMN_INDEX, UPPER_ROW_INDEX, LOWER_ROW_INDEX

getTileOrigin

public IlvRect getTileOrigin()

Returns the bounding box of the tile (0, 0).

tileBBox

public void tileBBox(int column,
                     int row,
                     IlvRect result)

Computes the bounding box of the specified tile and sets it to result.

Parameters:

column - The column of the tile

row - The row of the tile

result - A rectangle that will contain the result

getTile

public IlvTile getTile(int column,
                       int row)

Returns the specified tile or null if the tile is neither loaded nor cached.

lockTile

public void lockTile(int column,
                     int row,
                     Object source)

Loads the specified tile. If the tile is locked for the first time, it will be loaded. When a tile is no longer locked, it is cached. Tiles are automatically locked if they are visible in a view of the manager (unless the lock was vetoed by a lock filter, or the view is ignored). This method can be called by the application to force the loading of a specific tile, even if it is not yet visible, or to prevent it from being disposed of.

Parameters:

column - The column of the tile

row - The row of the tile

source - The object that locks the tile

getIntersectingTiles

public Collection getIntersectingTiles(IlvRect rect)

Gets all tiles intersecting the specified rectangle.

Returns:

A vector of tiles.

Since:

JViews 7.5

getTiles

public Collection getTiles()

Returns a collection of all tiles managed by this controller. In free mode, this method returns the tiles that have been added to the controller. In indexed mode, this method return null.

Since:

JViews 7.5

addTile

public void addTile(IlvFreeTile tile)

Adds a free tile to this tile controller. This can only be used in free mode. All tiles must be added to the controller in free mode before the controller can manage the tiles.

Parameters:

tile - The tile to add.

Since:

JViews 7.5

lockTile

public void lockTile(IlvTile tile,
                     Object source)

Loads the specified tile. If the tile is locked for the first time, it will be loaded. When a tile is no longer locked, it is cached. Tiles are automatically locked if they are visible in a view of the manager (unless the lock was vetoed by a lock filter, or the view is ignored). This method can be called by the application to force the loading of a specific tile, even if it is not yet visible, or to prevent it from being disposed of.

Parameters:

tile - The tile.

source - The object that locks the tile.

Since:

JViews 7.5

getCache

public IlvTileCache getCache()

Returns the cache that manages the cached tiles of the controller.

getManager

public final IlvManager getManager()

Returns the manager of the tile controller.

ignoreView

public void ignoreView(IlvManagerView view,
                       boolean ignore)

Specifies to the tile loader to never load a tile if it is visible in the specified view. This can be used, for example, to avoid loading tiles that become visible in an overview. It is recommended to call updateView(ilog.views.IlvManagerView) explicitly after you enable or disable the ignoring of a view.

Parameters:

view - The view to ignore

ignore - If set to true, the view will be ignored, otherwise, the events in the view will be processed normally

isIgnoringView

public boolean isIgnoringView(IlvManagerView view)

Returns true if the view is ignored by the tile controller.

Parameters:

view - The view

unlockTiles

public void unlockTiles(Object source)

Unlocks all the tiles that have been locked by the specified object. If a tile no longer has a lock, it is cached.

Parameters:

source - The object that locked the tiles

See Also:

lockTile(int, int, java.lang.Object)

unlockTile

public boolean unlockTile(int row,
                          int column,
                          Object source)

Removes the lock of the specified tile for the source object. If a tile no longer has a lock, it is cached. This method is automatically called if a tile becomes invisible in a view of the manager. It can be used by the application to remove the locks that it has placed using the lockTile method.

Parameters:

row - The row of the tile to unlock

column - The column of the tile to unlock

source - The object that locked the tiles

See Also:

lockTile(int, int, java.lang.Object)

updateView

public void updateView(IlvManagerView view)

Updates a view and loads the required tiles. It can be used, for example, to reactivate a view that was ignored until then by the load-on-demand mechanism.

Parameters:

view - The manager view to update

getLayer

public IlvTiledLayer getLayer()

Returns the layer if the tile controller is the tile controller of an IlvTiledLayer.

addTileListener

public void addTileListener(TileListener listener)

Adds a listener that will be notified of the changes in the tile status.

Parameters:

listener - The tile listener to add

removeTileListener

public void removeTileListener(TileListener listener)

Removes the listener from the tile controller.

Parameters:

listener - The listener to remove

getTileLoader

public final IlvTileLoader getTileLoader()

Returns the tile loader of the controller.

setTileLoader

public void setTileLoader(IlvTileLoader tileLoader)

Sets the tile loader of the controller.

write

public void write(IlvOutputStream stream)
           throws IOException

Writes the tile controller to an IlvOutputStream.

Specified by:

write in interface IlvPersistentObject

Parameters:

stream - the output stream

Throws:

IOException - if an error occurs while saving.

dispose

public void dispose()

Stops the load-on-demand mechanism.

isUnlockFilteredTiles

public boolean isUnlockFilteredTiles()

Indicates if unlocking locked filtered tiles is allowed or not.

Since:

JViews 7.5

setUnlockFilteredTiles

public void setUnlockFilteredTiles(boolean unlockFilteredTiles)

Allows or avoids to unlock filtered tiles which are already locked but which are not anymore lockable.

Since:

JViews 7.5

removeAllFreeTiles

public void removeAllFreeTiles()

Removes all the free tiles.

Since:

JViews 7.5