MapData

#include <bb/cascades/maps/MapData>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadesmaps

A collection of data providers to be represented on a map.

Object Ownership

This class is under the ownership of the client application. The client is responsible for creating and destroying this object. However, if the client wants to link the lifetime of this object with a MapView instance, then the client needs to explicitly set this object as the child of the MapView.

When a DataProvider instance is given to this object, it becomes a child of this object. When this object is destroyed, so are all of the DataProviders inside of it. Additionally, a single DataProvider instance cannot be shared across multiple MapData instances.

Geographic elements that are added to this class have their parent set to that of the default provider (see below). Since this class is the parent of that DataProvider, this class becomes the indirect parent of the added Geographic.

Reference Type

MapData is expected to be used as a reference type. As such, care needs to be made when referencing this object in multi-threaded environments. For example, deletion in one thread can cause a dangling pointer in another thread.

Also note that the contents of this container (bb::platform::geo::DataProvider) are also reference types.

Default Provider

Every MapData instance has a default DataProvider. This object is available to the client to store client created data (such as GeoLocations), without requiring them to create a provider, or write their own provider.

The default provider cannot be removed.

Since:

BlackBerry 10.0.0

Public Functions Index

	MapData (QObject *parent=0)
virtual	~MapData ()
bool	addProvider (bb::cascades::maps::DataProvider *provider)
bool	removeProvider (const QString &providerId)
int	providerCount () const
QList< QString >	providerIds () const
bb::cascades::maps::DataProvider *	defaultProvider () const
bb::cascades::maps::DataProvider *	provider (const QString &providerId) const
bb::platform::geo::GeoList	find (const bb::platform::geo::BoundingBox &box) const
QString	focusedId () const
bool	setFocusedId (const QString &newId)
void	resetFocusedId ()
bb::platform::geo::Geographic *	focusedGeographic ()
bool	add (bb::platform::geo::Geographic *geo)
int	add (const bb::platform::geo::GeoList &elements)
bool	remove (const QString &id)
int	remove (const QStringList &elements)
bb::platform::geo::Geographic *	geographic (const QString &id)
void	clear ()
int	count (bool visibleOnly=true) const
bb::platform::geo::BoundingBox	boundingBox (bool visibleOnly=true) const

Signals Index

void	focusedIdChanged (const QString &focusedId)
void	geoAdded (const QString &providerId, const QString &elementId)
void	geoAddedBulk (const QString &providerId, const QStringList &elementIds)
void	geoRemoved (const QString &providerId, const QString &elementId)
void	geoRemovedBulk (const QString &providerId, const QStringList &elementIds)
void	visibilityChanged (const QString &providerId, bool visible)
void	providerAdded (const QString &providerId)
void	providerRemoved (const QString &providerId)
void	topographyChanged (const QString &providerId, const QString &elementId)

Public Functions

MapData (
QObject *parent)

Constructor.

Since:

BlackBerry 10.0.0

virtual~MapData ()

Destructor.

Since:

BlackBerry 10.0.0

bool addProvider (
bb::cascades::maps::DataProvider *provider)

Adds a new DataProvider to the collection.

This object takes ownership of the added provider. (See class level documentation.)

Parameters
provider	The new provider to add.

Return:

true if the provider was added successfully, false if the provider couldn't be added (due to provider ID collision).

Since:

BlackBerry 10.0.0

bool removeProvider (
const QString &providerId)

Removes a DataProvider from the collection.

Note: The default data provider cannot be removed.

The memory for the provider is also freed, since it is owned by this object. (See class level documentation.)

Parameters
providerId	The ID of the provider to remove.

Return:

true if the removal was successful, false if the provider could not be deleted or does not exist.

Since:

BlackBerry 10.0.0

int providerCount ()

Gets the number of DataProviders in this collection.

Return:

The number of providers in this collection.

Since:

BlackBerry 10.0.0

QList< QString > providerIds ()

Retrieves a list of all the provider IDs within this container.

Return:

A list of provider IDs.

Since:

BlackBerry 10.0.0

bb::cascades::maps::DataProvider * defaultProvider ()

Gets the default provider.

Return:

The default provider.

Since:

BlackBerry 10.0.0

bb::cascades::maps::DataProvider * provider (
const QString &providerId)

Gets the provider with the given ID.

Parameters
providerId	The ID of the desired DataProvider instance.

Return:

The desired provider, or NULL if it doesn't exist in this collection.

Since:

BlackBerry 10.0.0

bb::platform::geo::GeoList find (
const bb::platform::geo::BoundingBox &box)

Retrieves all the visible data that's in the given latitude/longitude box.

This operation is executed on all visible providers (non-visible providers are not included).

Parameters
box	The bounding box to search within.

Return:

A list of visible entities.

Since:

BlackBerry 10.0.0

QString focusedId ()

Retrieves the ID of the element that currently has focus.

If no element has focus, then the return value is an empty string (QString::isEmpty()).

Return:

ID of the focused element.

Since:

BlackBerry 10.0.0

bool setFocusedId (
const QString &newId)

Sets the ID of the element to have focus.

Note: At this time, it is undefined what will happen if the provided ID does not exist within the data set.

Parameters
newId	the ID of the element that has focus.

Return:

true if a change occured.

Since:

BlackBerry 10.0.0

void resetFocusedId ()

Removes the focus from the element that has focus.

Since:

BlackBerry 10.0.0

bb::platform::geo::Geographic * focusedGeographic ()

Retrieves the element that currently has focus.

If no element has focus, NULL is returned.

Return:

The element which has focus.

Since:

BlackBerry 10.0.0

bool add (
bb::platform::geo::Geographic *geo)

Convenience operation that adds the parameter to the default container.

This is equivalent to:

defaultProvider()->add( geo )

Parameters
geo	The Geographic to be added.

Return:

true if added, false otherwise. The Geographic is not added if an element with that ID already exists.

Since:

BlackBerry 10.0.0

int add (
const bb::platform::geo::GeoList &elements)

Convenience operation that adds all the Geographic elements in the parameter to the default provider.

This is equivalent to:

defaultProvider()->add( elements );

Parameters
elements	The Geographic elements to be added.

Return:

The number of successfully added elements.

Since:

BlackBerry 10.0.0

bool remove (
const QString &id)

Convenience operation that removes the Geographic with the given ID from the default container.

This is equivalent to:

defaultProvider()->remove( id )

Parameters
id	The ID of the Geographic to be removed.

Return:

true if the element was removed.

Since:

BlackBerry 10.0.0

int remove (
const QStringList &elements)

Convenience operation that removes all the Geographic elements named in the parameter from the default container.

This is equivalent to:

defaultProvider()->remove( elements )

Parameters
elements	The Geographic elements to be removed.

Return:

The number of successfully removed elements.

Since:

BlackBerry 10.0.0

bb::platform::geo::Geographic * geographic (
const QString &id)

Convenience operation that retrieves the Geographic with the given ID.

This operation searches all DataProviders within this object.

Parameters
id	The ID of the desired Geographic.

Return:

The desired Geographic, NULL otherwise.

Since:

BlackBerry 10.0.0

void clear ()

Removes all data in all providers.

Since:

BlackBerry 10.0.0

int count (
boolvisibleOnly)

Returns the number of Geographic elements in all the visible providers.

Parameters
visibleOnly	If true, then only the elements from visible providers will be included in the count. If false, all visible and invisible elements are counted.

Since:

BlackBerry 10.1.0

bb::platform::geo::BoundingBox boundingBox (
boolvisibleOnly)

Returns the bounding box of the elements within this model.

If the number of elements is zero, then an invalid box is returned.

Parameters
visibleOnly	If true, then the bounding box will contain the elements from visible providers. If false, all visible and invisible elements are included.

Return:

The BoundingBox of all elements within this provider, or an invalid box if there are no elements.

Since:

BlackBerry 10.1.0

Signals

void focusedIdChanged (
const QString &focusedId)

Emitted when the focus has changed from one element to another.

Parameters
focusedId	The ID of the current element in focus.

Since:

BlackBerry 10.0.0

void geoAdded (
const QString &providerId,
const QString &elementId )

Emitted when a Geographic element has been added to a DataProvider.

Parameters
providerId	The ID of the provider that the Geographic was added to.
elementId	The ID of the element that was added.

Since:

BlackBerry 10.0.0

void geoAddedBulk (
const QString &providerId,
const QStringList &elementIds )

Emitted when multiple Geographic elements have been added to a DataProvider.

Parameters
providerId	The ID of the provider that the Geographic was added to.
elementIds	The IDs of the elements that were added.

Since:

BlackBerry 10.0.0

void geoRemoved (
const QString &providerId,
const QString &elementId )

Emitted when a Geographic element has been removed from a DataProvider.

Parameters
providerId	The ID of the provider that the Geographic was removed from.
elementId	The ID of the element that was removed.

Since:

BlackBerry 10.0.0

void geoRemovedBulk (
const QString &providerId,
const QStringList &elementIds )

Emitted when multiple Geographic elements have been removed from this DataProvider.

Parameters
providerId	The ID of the provider that the Geographic was removed from.
elementIds	The IDs of the elements that were removed.

Since:

BlackBerry 10.0.0

void visibilityChanged (
const QString &providerId,
boolvisible )

Emitted when the visibility of a DataProvider has changed.

Parameters
providerId	The ID of the provider whose visibility has changed.
visible	The new visible state.

Since:

BlackBerry 10.0.0

void providerAdded (
const QString &providerId)

Emitted when a DataProvider has been added to this container.

Parameters
providerId	The ID of the provider that has been added.

Since:

BlackBerry 10.1.0

void providerRemoved (
const QString &providerId)

Emitted when a DataProvider has been removed from this container.

Parameters
providerId	The ID of the provider that has been added.

Since:

BlackBerry 10.1.0

void topographyChanged (
const QString &providerId,
const QString &elementId )

Emitted when a Geographic's topography has been changed.

Parameters
providerId	The ID of the provider that contains the Geographic that was changed.
elementId	The ID of the element that was changed.

Since:

BlackBerry 10.1.0

MapData

Object Ownership

Reference Type

Default Provider

Public Functions Index

Signals Index

Public Functions

MapData (QObject *parent)

virtual~MapData ()

bool addProvider (bb::cascades::maps::DataProvider *provider)

bool removeProvider (const QString &providerId)

int providerCount ()

QList< QString > providerIds ()

bb::cascades::maps::DataProvider * defaultProvider ()

bb::cascades::maps::DataProvider * provider (const QString &providerId)

bb::platform::geo::GeoList find (const bb::platform::geo::BoundingBox &box)

QString focusedId ()

bool setFocusedId (const QString &newId)

void resetFocusedId ()

bb::platform::geo::Geographic * focusedGeographic ()

bool add (bb::platform::geo::Geographic *geo)

int add (const bb::platform::geo::GeoList &elements)

bool remove (const QString &id)

int remove (const QStringList &elements)

bb::platform::geo::Geographic * geographic (const QString &id)

void clear ()

int count (boolvisibleOnly)

bb::platform::geo::BoundingBox boundingBox (boolvisibleOnly)

Signals

void focusedIdChanged (const QString &focusedId)

void geoAdded (const QString &providerId, const QString &elementId )

void geoAddedBulk (const QString &providerId, const QStringList &elementIds )

void geoRemoved (const QString &providerId, const QString &elementId )

void geoRemovedBulk (const QString &providerId, const QStringList &elementIds )

void visibilityChanged (const QString &providerId, boolvisible )

void providerAdded (const QString &providerId)

void providerRemoved (const QString &providerId)

void topographyChanged (const QString &providerId, const QString &elementId )

MapData (
QObject *parent)

bool addProvider (
bb::cascades::maps::DataProvider *provider)

bool removeProvider (
const QString &providerId)

bb::cascades::maps::DataProvider * provider (
const QString &providerId)

bb::platform::geo::GeoList find (
const bb::platform::geo::BoundingBox &box)

bool setFocusedId (
const QString &newId)

bool add (
bb::platform::geo::Geographic *geo)

int add (
const bb::platform::geo::GeoList &elements)

bool remove (
const QString &id)

int remove (
const QStringList &elements)

bb::platform::geo::Geographic * geographic (
const QString &id)

int count (
boolvisibleOnly)

bb::platform::geo::BoundingBox boundingBox (
boolvisibleOnly)

void focusedIdChanged (
const QString &focusedId)

void geoAdded (
const QString &providerId,
const QString &elementId )

void geoAddedBulk (
const QString &providerId,
const QStringList &elementIds )

void geoRemoved (
const QString &providerId,
const QString &elementId )

void geoRemovedBulk (
const QString &providerId,
const QStringList &elementIds )

void visibilityChanged (
const QString &providerId,
boolvisible )

void providerAdded (
const QString &providerId)

void providerRemoved (
const QString &providerId)

void topographyChanged (
const QString &providerId,
const QString &elementId )