IlvTileController Class Reference

This class manages the load-on-demand process. More...

#include <ilviews/maps/tiling/tilectrl.h>

List of all members.

Public Member Functions
	IlvTileController (IlvManager *manager, const IlvRect &tileOrigin, IlvTileCache *cache=0, IlBoolean startEnabled=IlTrue)
	Creates an instance of a tile controller for the manager.
void	addTileListener (IlvTileListener *listener)
	Adds a listener that will be notified of the changes in the tile status.
void	enableStart (const IlvRect &tileOrigin, const IlvRect &size)
	Enables the start (delayed start due to tile loader initialization).
void	fireLoadError (IlvTile *tile, IlvMapsError errorCode)
	Notifies all the listeners of a tile error while loading.
void	fireTileChanged (IlvTile *tile, IlvTileStatus oldStatus, IlvTileStatus newStatus)
	Notifies all the listeners of a tile change.
IlvTileCache *	getCache () const
	Returns the cache that manages the cached tiles of the controller.
IlInt	getControlledTilesCount () const
	This method returns the number of tiles controlled by this controller, that is tiles that are either locked or cached.
virtual IlvMapsError	getInitStatus () const
	Returns the initialization status of this tile controller.
IlvTiledLayer *	getLayer () const
	Returns the layer if the tile controller is the tile controller of an IlvTiledLayer.
IlvManager *	getManager () const
	Returns the manager of the tile controller.
const IlvRect &	getSize () const
	Returns the specified size of the tile controller.
IlvTile *	getTile (IlInt column, IlInt row) const
	Returns the specified tile or a null pointer if the tile is neither loaded nor cached.
void	getTileIndexes (const IlvRect &rect, IlInt &upperRow, IlInt &lowerRow, IlInt &leftCol, IlInt &rightCol) const
	Returns the indexes of the tiles intersecting rect (rect is expressed in the manager coordinate system).
IlvTileLoader *	getTileLoader () const
	Returns the tile loader of the controller.
const IlvRect &	getTileOrigin () const
	Returns the bounding box of the tile (0, 0).
IlBoolean	hasBounds () const
	Returns IlTrue if a size has been specified for the layer.
IlBoolean	isStarted () const
	Checks if the load-on-demand process has started.
void	lockTile (IlInt column, IlInt row, IlAny source)
	Loads the specified tile.
void	mapToTiles (IlvTileControllerMapFunction func, IlAny arg)
	Maps a function to all tiles.
IlBoolean	mapToTilesUntilMatch (IlvTileControllerMatchFunction func, IlAny arg)
	Maps a function to all tiles.
void	removeTileListener (IlvTileListener *listener)
	Removes the listener from the tile controller.
void	setSize (const IlvRect &size)
	Specifies the area in which the tiles are contained.
void	setTileLoader (IlvTileLoader *tileLoader)
	Sets the tile loader of the controller.
void	start ()
	Starts the load-on-demand process.
void	tileBBox (IlInt column, IlInt row, IlvRect &result) const
	Computes the bounding box of the specified tile and sets it to result.
IlBoolean	unLockTile (IlInt row, IlInt column, IlAny source)
	Removes the lock of the specified tile for the source object.
void	unLockTiles (IlAny source)
	Unlocks all the tiles that have been locked by the specified object.
void	updateView (IlvView *view)
	Updates a view and loads the required tiles.
Static Public Member Functions
static void	IgnoreView (IlvView *view, IlBoolean ignore=IlTrue)
	Specifies to all the tile loaders to ignore the locks generated when the tile becomes visible in the specified view.
static IlBoolean	IsIgnoringView (IlvView *view)
	Returns IlTrue if the view is ignored by the tile controllers.
Protected Member Functions
virtual void	setInitStatus (IlvMapsError status)
	Sets the initialization status of this tile controller.

---

Detailed Description

This class manages the load-on-demand process.

Library: ilvmaps

It divides the space into a number of identical rectangular areas called tiles. 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.

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.

---

Constructor & Destructor Documentation

IlvTileController::IlvTileController	(	IlvManager *	manager,
		const IlvRect &	tileOrigin,
		IlvTileCache *	cache = 0,
		IlBoolean	startEnabled = IlTrue
	)

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.

Parameters:

	manager	The manager.
	tileOrigin	The position of the tile of row 0 and column 0.
	cache	An optional parameter specifying a cache instance. If this parameter is not provided or set to a null value, the default tile cache will be used by the controller.
	startEnabled	Specifies if the load-on-demand process is ready to start.

See also:

IlvDefaultTileCache::GetDefaultCache

enableStart

---

Member Function Documentation

void IlvTileController::addTileListener

(

IlvTileListener *

listener

)

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

The listener is not owned by the controller. It will not be deleted by the controller, and must be deleted by the application.

Parameters:

listener

The tile listener to be added.

See also:

IlvTileListener::controllerDeleted

void IlvTileController::enableStart	(	const IlvRect &	tileOrigin,
		const IlvRect &	size
	)

Enables the start (delayed start due to tile loader initialization).

Parameters:

	tileOrigin	The layer's tile origin.
	size	The size of the layer.

void IlvTileController::fireLoadError	(	IlvTile *	tile,
		IlvMapsError	errorCode
	)

Notifies all the listeners of a tile error while loading.

Calls loadError() method of all listeners registered with this IlvTileController.

Parameters:

	tile	The tile involved.
	errorCode	The error code.

See also:

IlvTileListener::loadError.

void IlvTileController::fireTileChanged	(	IlvTile *	tile,
		IlvTileStatus	oldStatus,
		IlvTileStatus	newStatus
	)

Notifies all the listeners of a tile change.

Calls tileChanged() method of all listeners registered with this IlvTileController.

Parameters:

	tile	The tile whose status has changed.
	oldStatus	The tile previous status.
	newStatus	The tile current status.

See also:

IlvTile::IlvTileStatus

IlvTileListener::tileChanged

IlvTileCache* IlvTileController::getCache

(

)

const

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

Returns:

The IlvTileCache object managing the tiles.

IlInt IlvTileController::getControlledTilesCount

(

)

const

This method returns the number of tiles controlled by this controller, that is tiles that are either locked or cached.

Returns:

The number of tiles.

virtual IlvMapsError IlvTileController::getInitStatus

(

)

const [virtual]

Returns the initialization status of this tile controller.

Returns:

IlvMaps::NoError() if this tile controller has been initialized successfully, an error otherwise.

IlvTiledLayer* IlvTileController::getLayer

(

)

const

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

Returns:

The IlvTiledLayer object.

IlvManager* IlvTileController::getManager

(

)

const

Returns the manager of the tile controller.

Returns:

The IlvManager object of the controller.

const IlvRect& IlvTileController::getSize

(

)

const

Returns the specified size of the tile controller.

If no size has been specified, the width and height of the returned rect are set to 0.

Returns:

An IlvRect object that should not be modified.

IlvTile* IlvTileController::getTile	(	IlInt	column,
		IlInt	row
	)			const

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

Parameters:

	column	The column of the tile.
	row	The row of the tile.

Returns:

An IlvTile object that should not be deleted.

void IlvTileController::getTileIndexes	(	const IlvRect &	rect,
		IlInt &	upperRow,
		IlInt &	lowerRow,
		IlInt &	leftCol,
		IlInt &	rightCol
	)			const

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

Parameters:

	rect	The rectangle expressed in the manager coordinate system.
	upperRow	This variable is set to the index of the upper row intersecting the rectangle.
	lowerRow	This variable is set to the index of the lower row intersecting the rectangle.
	leftCol	This variable is set to the index of the most left column intersecting the rectangle.
	rightCol	This variable is set to the index of the most right column intersecting the rectangle.

IlvTileLoader* IlvTileController::getTileLoader

(

)

const

Returns the tile loader of the controller.

Returns:

The IlvTileLoader object of the controller.

const IlvRect& IlvTileController::getTileOrigin

(

)

const

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

Returns:

An IlvRect object containing the bounding box.

static void IlvTileController::IgnoreView	(	IlvView *	view,
		IlBoolean	ignore = IlTrue
	)			[static]

Specifies to all the tile loaders to ignore the locks generated when the tile becomes visible in the specified view.

This can be used, for example, to avoid loading tiles that become visible in an overview.

Parameters:

	view	The view to be ignored.
	ignore	If set to IlTrue, the view will be ignored, otherwise the events in the view will be processed normally. When an ignored view is deleted, IgnoreView(views, false) must be called.

static IlBoolean IlvTileController::IsIgnoringView

(

IlvView *

view

)

[static]

Returns IlTrue if the view is ignored by the tile controllers.

Parameters:

view

The view to check.

IlBoolean IlvTileController::isStarted

(

)

const

Checks if the load-on-demand process has started.

Returns:

IlTrue if the load-on-demand process has started.

void IlvTileController::lockTile	(	IlInt	column,
		IlInt	row,
		IlAny	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 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.

Warning:

If an object locks a tile, unLockTile must be called before this object is deleted.

See also:

unLockTile.

void IlvTileController::mapToTiles	(	IlvTileControllerMapFunction	func,
		IlAny	arg
	)

Maps a function to all tiles.

This method maps the specified function func to all locked or cached tiles managed by this tile controller.

Parameters:

	func	The map function.
	arg	The user argument.

IlBoolean IlvTileController::mapToTilesUntilMatch	(	IlvTileControllerMatchFunction	func,
		IlAny	arg
	)

Maps a function to all tiles.

This method maps the specified function func to all locked or cached tiles managed by this tile controller, until the match function func returns IlTrue for a tile.

Parameters:

	func	The map function.
	arg	The user argument.

Returns:

IlTrue if a tile matched, IlFalse otherwise.

void IlvTileController::removeTileListener

(

IlvTileListener *

listener

)

Removes the listener from the tile controller.

Parameters:

listener

The listener to be removed.

virtual void IlvTileController::setInitStatus

(

IlvMapsError

status

)

[protected, virtual]

Sets the initialization status of this tile controller.

Subclasses of IlvTileController should call this method when their initialization is not successful.

Parameters:

status

The initialization status.

void IlvTileController::setSize

(

const IlvRect &

size

)

Specifies the area in which the tiles are contained.

If the rect parameter has a width and height of 0 there is no limit to the tiling grid.

Parameters:

rect

The area in which the tiles are contained.

void IlvTileController::setTileLoader

(

IlvTileLoader *

tileLoader

)

Sets the tile loader of the controller.

Parameters:

tileLoader

The tile loader used by the controller. The tile loader is not owned by the tile controller.

void IlvTileController::tileBBox	(	IlInt	column,
		IlInt	row,
		IlvRect &	result
	)			const

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.

IlBoolean IlvTileController::unLockTile	(	IlInt	row,
		IlInt	column,
		IlAny	source
	)

Removes the lock of the specified tile for the source object.

If a tile has no longer 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.

Returns:

IlTrue if the operation changes the status of the tile to IlvTileCached.

See also:

IlvTileController::lockTile.

void IlvTileController::unLockTiles

(

IlAny

source

)

Unlocks all the tiles that have been locked by the specified object.

If a tile has no longer a lock, it is cached.

Parameters:

source

The object that locked the tiles.

See also:

IlvTileController::lockTile.

void IlvTileController::updateView

(

IlvView *

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 process.

Parameters:

view

The manager view to be updated.