Qt Mobility Reference Documentation

QGeoSearchManager Class Reference

The QGeoSearchManager class provides support for searching operations related to geographic information. More...

 #include <QGeoSearchManager>

Public Types

enum SearchType { SearchNone, SearchGeocode, SearchLandmarks, SearchAll }
flags SearchTypes

Public Functions

~QGeoSearchManager ()
void addAdditionalLandmarkManager ( QLandmarkManager * landmarkManager )
QList<QLandmarkManager *> additionalLandmarkManagers () const
QLandmarkManager * defaultLandmarkManager () const
QGeoSearchReply * geocode ( const QGeoAddress & address, const QGeoBoundingBox & bounds = QGeoBoundingBox() )
QGeoSearchReply * geocode ( const QGeoCoordinate & coordinate, const QGeoBoundingBox & bounds = QGeoBoundingBox() )
QString managerName () const
QMap<QString, QString> managerParameters () const
int managerVersion () const
QGeoSearchReply * placeSearch ( const QString & searchString, SearchTypes searchTypes = SearchTypes( SearchAll ), const QGeoBoundingBox & bounds = QGeoBoundingBox() )
void setAdditionalLandmarkManagers ( const QList<QLandmarkManager *> & landmarkManagers )
SearchTypes supportedSearchTypes () const
bool supportsGeocoding () const

Signals

void error ( QGeoSearchReply * reply, QGeoSearchReply::Error error, QString errorString = QString() )
void finished ( QGeoSearchReply * reply )

Detailed Description

The QGeoSearchManager class provides support for searching operations related to geographic information.

The geocode(QGeoAddress), geocode(QGeoCoordinate) and placeSearch() functions return QGeoSearchReply objects, which manage these operations and report on the result of the operations and any errors which may have occurred.

The geocode(QGeoAddress) and geocode(QGeoCoordinate) functions can be used to convert QGeoAddress instances to QGeoCoordinate instances and vice-versa.

The placeSearch() function allows a user to perform a free text search for place information. If the string provided can be interpreted as an address it can be geocoded to coordinate information, and the string can also be used to search a landmarks database, depending on the level of support supplied by the service provider.

The defaultLandmarkManager() function will return a QLandmarkManager instance if access to the service providers landmark database is available outside of the placeSearch() method.

A user can supply other QLandmarkManager instances to be searched during the execution of placeSearch() with setAdditionalLandmarkManagers(). This means that a personal database store can be combined with a public source of database information with very little effort.

Instances of QGeoSearchManager can be accessed with QGeoServiceProvider::searchManager().

A small example of the usage of QGeoSearchManager and the handling of QLandmark results follows:

 class MySearchHandler : public QObject
 {
     Q_OBJECT
 public:
     MySearchHandler(QGeoSearchManager *searchManager, QString searchString)
     {
         QGeoSearchReply *reply = searchManager->placeSearch(searchString);

         if (reply->isFinished()) {
             if (reply->error() != QGeoSearchReply::NoError) {
                 searchResults(reply);
             } else {
                 searchError(reply, reply->error(), reply->errorString());
             }
         } else {
             connect(searchManager,
                     SIGNAL(finished(QGeoSearchReply*)),
                     this,
                     SLOT(searchResults(QGeoSearchReply*)));

             connect(searchManager,
                     SIGNAL(error(QGeoSearchReply*,QGeoSearchReply::Error,QString)),
                     this
                     SLOT(searchError(QGeoSearchReply*,QGeoSearchReply::Error,QString)));
         }
     }

 private slots:
     void searchResults(QGeoSearchReply *reply)
     {
         // We now have the results as QGeoPlace objects
         QList<QGeoPlace> places = reply->places();

         // The QLandmark results can be created from the simpler
         // QGeoPlace results if that is required.
         QList<QLandmark> landmarks;
         for (int i = 0; i < places().size(); ++i) {
             QGeoPlace place = places.at(i);
             if (place.type() == QGeoPlace::LandmarkType) {
                 landmarks.append(QLandmark(place));
             }
         }

         // ... now we have to make use of the places and landmarks ...
         reply->deleteLater();
     }

     void searchError(QGeoSearchReply *reply, QGeoSearchReply::Error error, const QString &errorString)
     {
         // ... inform the user that an error has occurred ...
     }
 };

Member Type Documentation

enum QGeoSearchManager::SearchType
flags QGeoSearchManager::SearchTypes

Describes the type of search that should be performed by placeSearch().

ConstantValueDescription
QGeoSearchManager::SearchNone0x0000Do not use the search string.
QGeoSearchManager::SearchGeocode0x0001Use the search string as a textual address in a geocoding operation.
QGeoSearchManager::SearchLandmarks0x0002Use the search string for free-text search against the available landmark information sources.
QGeoSearchManager::SearchAll0xFFFFAll available information sources should be used as part of the search.

The SearchTypes type is a typedef for QFlags<SearchType>. It stores an OR combination of SearchType values.


Member Function Documentation

QGeoSearchManager::~QGeoSearchManager ()

Destroys this manager.

void QGeoSearchManager::addAdditionalLandmarkManager ( QLandmarkManager * landmarkManager )

Adds landmarkManager to the list of landmark managers that will be used with placeSearch().

These landmark managers will be used along with the landmark manager returned by defaultLandmarkManager().

QList<QLandmarkManager *> QGeoSearchManager::additionalLandmarkManagers () const

Returns the landmark managers that will be used with placeSearch().

These landmark managers will be used along with the landmark manager returned by defaultLandmarkManager().

See also setAdditionalLandmarkManagers().

QLandmarkManager * QGeoSearchManager::defaultLandmarkManager () const

Returns the landmark manager provided by the service provider for use with placeSearch().

Will return 0 if the no landmark manager is associated with the service provider. This does not indicate that placeSearch() does not support landmark searching, only that any landmark searching which occurs within in placeSearch() is done without the use of a QLandmarkManager.

void QGeoSearchManager::error ( QGeoSearchReply * reply, QGeoSearchReply::Error error, QString errorString = QString() ) [signal]

This signal is emitted when an error has been detected in the processing of reply. The QGeoSearchManager::finished() signal will probably follow.

The error will be described by the error code error. If errorString is not empty it will contain a textual description of the error.

This signal and QGeoSearchReply::error() will be emitted at the same time.

Note: Do no delete the reply object in the slot connected to this signal. Use deleteLater() instead.

void QGeoSearchManager::finished ( QGeoSearchReply * reply ) [signal]

This signal is emitted when reply has finished processing.

If reply::error() equals QGeoSearchReply::NoError then the processing finished successfully.

This signal and QGeoSearchReply::finished() will be emitted at the same time.

Note: Do no delete the reply object in the slot connected to this signal. Use deleteLater() instead.

QGeoSearchReply * QGeoSearchManager::geocode ( const QGeoAddress & address, const QGeoBoundingBox & bounds = QGeoBoundingBox() )

Begins the geocoding of address. Geocoding is the process of finding a coordinate that corresponds to a given address.

A QGeoSearchReply object will be returned, which can be used to manage the geocoding operation and to return the results of the operation.

This manager and the returned QGeoSearchReply object will emit signals indicating if the operation completes or if errors occur.

If supportsGeocoding() returns false an QGeoSearchReply::UnsupportedOptionError will occur.

Once the operation has completed, QGeoSearchReply::places() can be used to retrieve the results, which will consist of a list of QGeoPlace objects. These object represent a combination of coordinate and address data.

The address data returned in the results may be different from address. This will usually occur if the geocoding service backend uses a different canonical form of addresses or if address was only partially filled out.

If bounds is a valid QGeoBoundingBox it will be used to limit the results to thos that are contained within bounds. This is particularly useful if address is only partially filled out, as the service will attempt to geocode all matches for the specified data.

The user is responsible for deleting the returned reply object, although this can be done in the slot connected to QGeoSearchManager::finished(), QGeoSearchManager::error(), QGeoSearchReply::finished() or QGeoSearchReply::error() with deleteLater().

QGeoSearchReply * QGeoSearchManager::geocode ( const QGeoCoordinate & coordinate, const QGeoBoundingBox & bounds = QGeoBoundingBox() )

Begins the reverse geocoding of coordinate. Reverse geocoding is the process of finding an address that corresponds to a given coordinate.

A QGeoSearchReply object will be returned, which can be used to manage the reverse geocoding operation and to return the results of the operation.

This manager and the returned QGeoSearchReply object will emit signals indicating if the operation completes or if errors occur.

If supportsGeocoding() returns false an QGeoSearchReply::UnsupportedOptionError will occur.

At that point QGeoSearchReply::places() can be used to retrieve the results, which will consist of a list of QGeoPlace objects. These object represent a combination of coordinate and address data.

The coordinate data returned in the results may be different from coordinate. This will usually occur if the reverse geocoding service backend shifts the coordinates to be closer to the matching addresses, or if the backend returns results at multiple levels of detail.

If multiple results are returned by the reverse geocoding service backend they will be provided in order of specificity. This normally occurs if the backend is configured to reverse geocode across multiple levels of detail. As an example, some services will return address and coordinate pairs for the street address, the city, the state and the country.

If bounds is a valid QGeoBoundingBox it will be used to limit the results to thos that are contained within bounds.

The user is responsible for deleting the returned reply object, although this can be done in the slot connected to QGeoSearchManager::finished(), QGeoSearchManager::error(), QGeoSearchReply::finished() or QGeoSearchReply::error() with deleteLater().

QString QGeoSearchManager::managerName () const

Returns the name of the engine which implements the behaviour of this search manager.

The combination of managerName() and managerVersion() should be unique amongst the plugin implementations.

QMap<QString, QString> QGeoSearchManager::managerParameters () const

Returns the parameters used in the creation of this search manager.

int QGeoSearchManager::managerVersion () const

Returns the version of the engine which implements the behaviour of this search manager.

The combination of managerName() and managerVersion() should be unique amongst the plugin implementations.

QGeoSearchReply * QGeoSearchManager::placeSearch ( const QString & searchString, SearchTypes searchTypes = SearchTypes( SearchAll ), const QGeoBoundingBox & bounds = QGeoBoundingBox() )

Begins searching for a place matching searchString. The value of searchTypes will determine whether the search is for addresses only, for landmarks only or for both.

A QGeoSearchReply object will be returned, which can be used to manage the geocoding operation and to return the results of the operation.

This manager and the returned QGeoSearchReply object will emit signals indicating if the operation completes or if errors occur.

If supportsGeocoding() returns false and searchTypes is QGeoSearchManager::SearchGeocode an QGeoSearchReply::UnsupportedOptionError will occur.

Once the operation has completed, QGeoSearchReply::places() can be used to retrieve the results, which will consist of a list of QGeoPlace objects. These object represent a combination of coordinate and address data.

If any of the QGeoPlace instances in the results have landmark associated data, QGeoPlace::type() will return QGeoPlace::LandmarkType and QLandmark::QLandmark(const QGeoPlace &place) can be used to convert the QGeoPlace instance into a QLandmark instance.

If searchTypes is QGeoSearchManager::SearchLandmarks or QGeoSearchManager::SearchAll, a free text landmark search will be performed. The results will be a combination of the backend specific landmark search and the same free text search applied to each of the QLandmarkManager instances in additionalLandmarkManagers().

If bounds is a valid QGeoBoundingBox it will be used to limit the results to thos that are contained within bounds.

The user is responsible for deleting the returned reply object, although this can be done in the slot connected to QGeoSearchManager::finished(), QGeoSearchManager::error(), QGeoSearchReply::finished() or QGeoSearchReply::error() with deleteLater().

void QGeoSearchManager::setAdditionalLandmarkManagers ( const QList<QLandmarkManager *> & landmarkManagers )

Sets the landmark managers to be used with placeSearch() to landmarkManagers.

These landmark managers will be used along with the landmark manager returned by defaultLandmarkManager().

See also additionalLandmarkManagers().

SearchTypes QGeoSearchManager::supportedSearchTypes () const

Returns the search types supported by the placeSearch() with this manager.

bool QGeoSearchManager::supportsGeocoding () const

Returns whether this manager supports geocoding operations.


Copyright © 2009-2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.1.0