Rogue Wave Views
Maps Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Static Public Member Functions | Protected Member Functions
IlvTileController Class Reference

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

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

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. More...
 
void addTileListener (IlvTileListener *listener)
 Adds a listener that will be notified of the changes in the tile status. More...
 
void enableStart (const IlvRect &tileOrigin, const IlvRect &size)
 Enables the start (delayed start due to tile loader initialization). More...
 
void fireLoadError (IlvTile *tile, IlvMapsError errorCode)
 Notifies all the listeners of a tile error while loading. More...
 
void fireTileChanged (IlvTile *tile, IlvTileStatus oldStatus, IlvTileStatus newStatus)
 Notifies all the listeners of a tile change. More...
 
IlvTileCachegetCache () const
 Returns the cache that manages the cached tiles of the controller. More...
 
IlInt getControlledTilesCount () const
 This method returns the number of tiles controlled by this controller, that is tiles that are either locked or cached. More...
 
virtual IlvMapsError getInitStatus () const
 Returns the initialization status of this tile controller. More...
 
IlvTiledLayergetLayer () const
 Returns the layer if the tile controller is the tile controller of an IlvTiledLayer. More...
 
IlvManagergetManager () const
 Returns the manager of the tile controller. More...
 
const IlvRectgetSize () const
 Returns the specified size of the tile controller. More...
 
IlvTilegetTile (IlInt column, IlInt row) const
 Returns the specified tile or a null pointer if the tile is neither loaded nor cached. More...
 
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). More...
 
IlvTileLoadergetTileLoader () const
 Returns the tile loader of the controller. More...
 
const IlvRectgetTileOrigin () const
 Returns the bounding box of the tile (0, 0). More...
 
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. More...
 
void lockTile (IlInt column, IlInt row, IlAny source)
 Loads the specified tile. More...
 
void mapToTiles (IlvTileControllerMapFunction func, IlAny arg)
 Maps a function to all tiles. More...
 
IlBoolean mapToTilesUntilMatch (IlvTileControllerMatchFunction f, IlAny arg)
 Maps a function to all tiles. More...
 
void removeTileListener (IlvTileListener *listener)
 Removes the listener from the tile controller. More...
 
void setSize (const IlvRect &size)
 Specifies the area in which the tiles are contained. More...
 
void setTileLoader (IlvTileLoader *tileLoader)
 Sets the tile loader of the controller. More...
 
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. More...
 
IlBoolean unLockTile (IlInt row, IlInt column, IlAny source)
 Removes the lock of the specified tile for the source object. More...
 
void unLockTiles (IlAny source)
 Unlocks all the tiles that have been locked by the specified object. More...
 
void updateView (IlvView *view)
 Updates a view and loads the required tiles. More...
 

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. More...
 
static IlBoolean IsIgnoringView (IlvView *view)
 Returns IlTrue if the view is ignored by the tile controllers. More...
 

Protected Member Functions

virtual void setInitStatus (IlvMapsError status)
 Sets the initialization status of this tile controller. More...
 

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
managerThe manager.
tileOriginThe position of the tile of row 0 and column 0.
cacheAn 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.
startEnabledSpecifies 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
listenerThe 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
tileOriginThe layer's tile origin.
sizeThe 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
tileThe tile involved.
errorCodeThe 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
tileThe tile whose status has changed.
oldStatusThe tile previous status.
newStatusThe 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
columnThe column of the tile.
rowThe 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
rectThe rectangle expressed in the manager coordinate system.
upperRowThis variable is set to the index of the upper row intersecting the rectangle.
lowerRowThis variable is set to the index of the lower row intersecting the rectangle.
leftColThis variable is set to the index of the most left column intersecting the rectangle.
rightColThis 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
viewThe view to be ignored.
ignoreIf 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
viewThe 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
columnThe column of the tile.
rowThe row of the tile.
sourceThe 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
funcThe map function.
argThe user argument.
IlBoolean IlvTileController::mapToTilesUntilMatch ( IlvTileControllerMatchFunction  f,
IlAny  arg 
)

Maps a function to all tiles.

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

Parameters
fThe map function.
argThe user argument.
Returns
IlTrue if a tile matched, IlFalse otherwise.
void IlvTileController::removeTileListener ( IlvTileListener listener)

Removes the listener from the tile controller.

Parameters
listenerThe listener to be removed.
virtual void IlvTileController::setInitStatus ( IlvMapsError  status)
protectedvirtual

Sets the initialization status of this tile controller.

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

Parameters
statusThe 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
sizeThe area in which the tiles are contained.
void IlvTileController::setTileLoader ( IlvTileLoader tileLoader)

Sets the tile loader of the controller.

Parameters
tileLoaderThe 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
columnThe column of the tile.
rowThe row of the tile.
resultA 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
rowThe row of the tile to unLock.
columnThe column of the tile to unLock.
sourceThe 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
sourceThe 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
viewThe manager view to be updated.

© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.