MapData

Since: BlackBerry 10.0.0

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


Overview

QML properties

bb: QDeclarativeListProperty [read-only]
styles: bb::platform::geo::StyleSheet

Properties Index

QDeclarativeListPropertybb [read-only]
bb::platform::geo::StyleSheetstyles

Public Functions Index

MapData (QObject *parent=0)
virtual ~MapData ()
booladd (bb::platform::geo::Geographic *geo)
intadd (const bb::platform::geo::GeoList &elements)
booladdProvider (bb::cascades::maps::DataProvider *provider)
bb::platform::geo::BoundingBoxboundingBox (bool visibleOnly=true) const
voidclear ()
intcount (bool visibleOnly=true) const
bb::cascades::maps::DataProvider *defaultProvider () const
bb::platform::geo::GeoListfind (const bb::platform::geo::BoundingBox &box) const
bb::platform::geo::Geographic *focusedGeographic ()
QStringfocusedId () const
bb::platform::geo::Geographic *geographic (const QString &id)
bb::cascades::maps::DataProvider *provider (const QString &providerId) const
intproviderCount () const
bb::cascades::maps::DataProvider *providerFor (const bb::platform::geo::Geographic *element) const
bb::cascades::maps::DataProvider *providerFor (const QString &geoId) const
QList< QString >providerIds () const
boolremove (const QString &id)
intremove (const QStringList &elements)
boolremoveProvider (const QString &providerId)
voidresetFocusedId ()
Q_SLOT voidresetStyles ()
bb::platform::geo::StyleresolveStyle (const bb::platform::geo::Geographic *element) const
boolsetFocusedId (const QString &newId)
Q_SLOT voidsetStyles (const bb::platform::geo::StyleSheet &styles)
bb::platform::geo::StyleSheetstyles () const

Signals Index

voidfocusedIdChanged (const QString &focusedId)
voidgeoAdded (const QString &providerId, const QString &elementId)
voidgeoAddedBulk (const QString &providerId, const QStringList &elementIds)
voidgeoRemoved (const QString &providerId, const QString &elementId)
voidgeoRemovedBulk (const QString &providerId, const QStringList &elementIds)
voidproviderAdded (const QString &providerId)
voidproviderRemoved (const QString &providerId)
voidstylesChanged (const bb::platform::geo::StyleSheet &newStyles)
voidtopographyChanged (const QString &providerId, const QString &elementId)
voidvisibilityChanged (const QString &providerId, bool visible)

Properties

QDeclarativeListProperty bb[read-only]

The list of DataProvider objects associated with the data provider.

Since:

BlackBerry 10.2.0

bb::platform::geo::StyleSheet styles

The styles associated with the data provider.

Since:

BlackBerry 10.2.0

Public Functions

MapData (

Constructor.

Parameters
parent

The parent object to this object.

Since:

BlackBerry 10.0.0

virtual~MapData ()

Destructor.

Since:

BlackBerry 10.0.0

bool add (

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 (

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 addProvider (

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

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

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::cascades::maps::DataProvider * defaultProvider ()

Gets the default provider.

Return:

The default provider.

Since:

BlackBerry 10.0.0

bb::platform::geo::GeoList find (

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

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

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()).

If the DataProvider containing the element that currently has focus is set invisible the focused ID will be reset.

Return:

ID of the focused element.

Since:

BlackBerry 10.0.0

bb::platform::geo::Geographic * geographic (

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

bb::cascades::maps::DataProvider * provider (

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

int providerCount ()

Gets the number of DataProviders in this collection.

Return:

The number of providers in this collection.

Since:

BlackBerry 10.0.0

bb::cascades::maps::DataProvider * providerFor (

Gets the provider that houses the given Geographic element.

The ownership of the returned object is not transferred to the caller. This MapData instance is still the parent / owner of the returned DataProvider instance.

Parameters
element

The Geographic element to base the search upon.

Return:

The desired DataProvider, or NULL if it doesn't exist.

Since:

BlackBerry 10.2.0

bb::cascades::maps::DataProvider * providerFor (

Gets the provider that houses the given Geographic element, based on its ID.

The ownership of the returned object is not transferred to the caller. This MapData instance is still the parent / owner of the returned DataProvider instance.

Parameters
geoId

The ID of the Geographic element to base the search upon.

Return:

The desired DataProvider, or NULL if it doesn't exist.

Since:

BlackBerry 10.2.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

bool remove (

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 (

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

bool removeProvider (

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

void resetFocusedId ()

Removes the focus from the element that has focus.

Since:

BlackBerry 10.0.0

Q_SLOT void resetStyles ()

Resets the collection of styles to an empty collection.

Since:

BlackBerry 10.2.0

bb::platform::geo::Style resolveStyle (

Generates a Style applicable for the given element where all unresolved style attributes (inherited attributes) have been resolved.

The Style resolution rules for a MapData container are different than the resolution rules for a StyleSheet. A StyleSheet only knows about itself while a MapData instance can contain multiple StyleSheet: one for each DataProvider plus one for the MapData element holding all the DataProviders. Thus, style resolution for a MapData instance uses the style definition for the MapData instance, plus the DataProvider that houses the Geographic element in question.

In brief, the MapData's styles override the DataProvider's. In more explicit terms, the rules use the following sequence:
  • from the MapData's StyleSheet, any styles registered to the element's ID

  • from the DataProvider's StyleSheet from which the element resides, any styles registered to the element's ID

  • from the MapData's StyleSheet, any styles registered to the element's style family

  • from the DataProvider's StyleSheet from which the element resides, any styles registered to the element's style family

  • from the MapData's StyleSheet, any styles registered to the element's class name

  • from the DataProvider's StyleSheet from which the element resides, any styles registered to the element's class name

  • from the MapData's StyleSheet, the default style

  • from the DataProvider's StyleSheet from which the element resides, the default style

  • the system-wide default style

Parameters
element

The Geographic element to find a complete style for.

Return:

A fully populated Style instance for the given element.

Since:

BlackBerry 10.2.0

bool setFocusedId (

Sets the ID of the element to have focus.

If there is no such element with ID newId or the DataProvider containing the element with ID newId is not visible the focused ID will not change.

If the DataProvider containing the element that currently has focus is set invisible the focused ID will be reset.

Parameters
newId

the ID of the element that has focus.

Return:

true if the focused ID changed, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void setStyles (

Sets the collection of styles to be used when drawing the Geographic elements within this container.

Parameters
styles

The new styles for this provider.

Since:

BlackBerry 10.2.0

bb::platform::geo::StyleSheet styles ()

Retrieves the collection of styles to be used when drawing the Geographic elements within this container.

Return:

The styles for this provider.

Since:

BlackBerry 10.2.0

Signals

void focusedIdChanged (

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 (

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 (

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 (

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 (

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 providerAdded (

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 (

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 stylesChanged (

Emitted when the styles property for this MapData has changed.

Parameters
newStyles

The new StyleSheet for this container.

Since:

BlackBerry 10.2.0

void topographyChanged (

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

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

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus