Orte (C++)

Übersicht

Mit der Places-API können Nutzer Orte und Sehenswürdigkeiten entdecken und Details dazu einsehen, wie beispielsweise Adressen und Kontaktinformationen; einige Orte verfügen sogar über umfangreiche Inhalte wie Bilder und Bewertungen. Die Places-API erleichtert zudem die Verwaltung von Orten und Kategorien und ermöglicht es Nutzern, diese zu speichern und zu löschen.

Definition eines Ortes

Ein Ort ist ein Sehenswürdigkeit – das kann ein Lieblingsrestaurant, ein Park oder das Zuhause einer Person sein. Ein „ QPlace “-Objekt repräsentiert einen Ort, indem es als Container für verschiedene Informationen zu diesem Ort dient.

Diese Informationen lassen sich in zwei große Kategorien unterteilen

• Details
• Umfangreiche Inhalte

Die Ortsdetails umfassen Eigenschaften des Ortes, wie beispielsweise den Namen, den Standort, Kontaktinformationen und so weiter. Wenn ein Ort bei einer Suche angezeigt wird, werden diese Details ausgefüllt. Manchmal gibt es, um Bandbreite zu sparen, weitere Details zum Ort, die bei Interesse des Nutzers für jeden einzelnen Ort abgerufen werden können. Mit der Funktion „ QPlace::detailsFetched()“ lässt sich abfragen, ob alle verfügbaren Details bereits abgerufen wurden; ist dies nicht der Fall, können diese mit „ QPlaceManager::getPlaceDetails()“ nachgeladen werden. Welche Details genau bei einer Suche ausgefüllt werden und welche einzeln abgerufen werden müssen, kann je nach Anbieter variieren. Weitere Informationen finden Sie in der Plugin-Dokumentation.

Die Rich-Content-Elemente eines Ortes bestehen aus Elementen wie Bildern, Bewertungen und redaktionellen Beiträgen. Da es potenziell viele Rich-Content-Elemente geben kann, werden diese getrennt von den Ortsdetails behandelt. Sie können paginiert über ` QPlaceManager::getPlaceContent()` abgerufen werden. Bei Bedarf können die Inhalte einem Ort zugeordnet werden, der dann als praktischer Container dient.

Häufige Operationen

Initialisierung eines Managers

Die gesamte „Places“-Funktionalität wird durch eine Instanz von ` QPlaceManager ` bereitgestellt. Man muss eine ` QGeoServiceProvider ` angeben, um den QPlaceManager

//The "provider name" is used to select a particular provider
QGeoServiceProvider *provider = new QGeoServiceProvider("provider name");
QPlaceManager *manager = provider->placeManager();

Erkennung/Suche

Um eine Suche durchzuführen, erstellen wir einfach ein ` QPlaceSearchRequest ` und legen die gewünschten Suchparameter fest, wie beispielsweise einen Suchbegriff und ein Suchzentrum.

//instantiate request and set parameters
QPlaceSearchRequest searchRequest;
searchRequest.setSearchTerm("ice cream");
searchRequest.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));

//send off a search request
/*QPlaceSearchReply * */ searchReply = manager->search(searchRequest);

//connect a slot to handle the reply
connect(searchReply, &QPlaceSearchReply::finished, this, &RequestHandler::handleSearchReply);

Da es sich bei der Anfrage um einen asynchronen Vorgang handelt, benötigen wir einen Slot, um den Abschluss der Anfrage zu verarbeiten. Im Handler prüfen wir, ob keine Fehler aufgetreten sind und ob unser Suchergebnistyp ein Ort ist. Ist dies der Fall, können wir einige der wichtigsten Details des Ortes abrufen. Am Ende des Slots löschen wir die Antwort, da diese nur für den einmaligen Gebrauch bestimmt ist.

void handleSearchReply() {
    if (searchReply->error()== QPlaceReply::NoError) {
        for (const QPlaceSearchResult&result: searchReply->results()) {
            if (result.type()== QPlaceSearchResult::PlaceResult) {
                QPlaceResult placeResult = result;
                qDebug() << "Name: " << placeResult.place().name();
                qDebug() << "Coordinate " << placeResult.place().location().coordinate().toString();
                qDebug() << "Street: " << placeResult.place().location().address().street();
                qDebug() << "Distance: " << placeResult.distance();
            }
        }
    }
    searchReply->deleteLater();  //Antwort verwerfen
    searchReply = nullptr;
}

Hinweis: Je nach gewähltem Plugin-Backend können die Suchergebnisse Orte enthalten, zu denen weitere Details vorliegen, die für jeden Ort einzeln abgerufen werden können. Informationen zum Abrufen dieser weiteren Details finden Sie unter „Ortsdetails abrufen“.

Empfehlungen

Empfehlungen können durch Angabe einer Orts-ID über ` QPlaceSearchRequest::setRecommendationId()` abgerufen werden. Dabei werden alle Orte abgerufen, die dem angegebenen Ort ähnlich sind.

Paginierung

Wenn das Plugin die Paginierung unterstützt, kann der Parameter „limit“ in der Suchanfrage angegeben werden.

QPlaceSearchRequest searchRequest;
searchRequest.setLimit(15); //specify how many results are to be retrieved.

Abrufen von Ortsdetails

Zu einem Ort, der im Rahmen einer Suchanfrage zurückgegeben wurde, können weitere Details abgerufen werden. Im Folgenden wird gezeigt, wie überprüft werden kann, ob weitere Details vorhanden sind, und wie diese gegebenenfalls angefordert werden können.

if (!place.detailsFetched()) {
    /*QPlaceDetailsReply * */ detailsReply = manager->getPlaceDetails(place.placeId());
    connect(detailsReply, &QPlaceDetailsReply::finished, this, &RequestHandler::handleDetailsReply);
}
    ...
    ...
void handleDetailsReply() {
    QPlace place;
    if (detailsReply->error() == QPlaceReply::NoError)
        place = detailsReply->place();

    detailsReply->deleteLater(); //discard reply
    detailsReply = nullptr;
}

Abrufen von Rich Content

Rich Content wie Bilder und Bewertungen wird über den Manager abgerufen und bei Bedarf einem Ort zugeordnet.

QPlaceContentRequest request;
request.setContentType(QPlaceContent::ImageType);
request.setPlaceId(place.placeId());
request.setLimit(5);
/*QPlaceContentReply * */ contentReply = manager->getPlaceContent(request);
connect(contentReply, &QPlaceContentReply::finished, this, &RequestHandler::handleImagesReply);

Die Abfrage der Inhalte können wir wie unten gezeigt bearbeiten.

void handleImagesReply() {
    if (contentReply->error()== QPlaceReply::NoError) {
        const auto content = contentReply->content();
        for (auto iter = content.cbegin(), end = content.cend(); iter != end;++iter) {
            qDebug() << "Index: " << iter.key();
           QPlaceImage image = iter.value();
            qDebug() << image.url();
            qDebug() << image.mimeType();
        }

        // alternativ, wenn Indizes keine Rolle spielen
        for (const QPlaceImage &image: contentReply->content()) {
            qDebug() << image.url();
            qDebug() << image.mimeType();
        }

        //Wir können Inhalte dem Ort zuweisen, zu dem sie gehören.
        //Das „place“-Objekt dient als Container, aus dem wir
        //bereits abgerufene Inhalte  abrufen können
        place.insertContent(contentReply->request().contentType(), contentReply->content());
        place.setTotalContentCount(contentReply->request().contentType(), contentReply->totalCount());
    }

    contentReply->deleteLater();
    contentReply = nullptr;
}

Es ist wichtig zu beachten, dass die Ergebnisse in ` QPlaceContentReply` ein ` QPlaceContent::Collection ` sind, bei dem es sich im Wesentlichen um ein ` QMap<int, QPlaceContent>` handelt. Der Schlüssel ` int ` ist in diesem Fall der Index des Inhalts, und der Wert ist der Inhalt selbst. Aufgrund der Art und Weise, wie `Content` implementiert ist, ist es möglich, einen Inhaltstyp wie folgt zu konvertieren

QPlaceImage image = content; //provided that 'content' has a type QPlace::ImageType

Durch die Verwendung des „ QPlaceContent::Collection “ und die Konvertierung zwischen „Content“ und seinen Untertypen lässt sich der Code für die paginierte Darstellung von Rezensionen, Bildern und Leitartikeln problemlos gemeinsam nutzen.

Suchvorschläge

Das Abrufen von Suchbegriffsvorschlägen erfolgt sehr ähnlich wie bei einer Ortssuche. Es wird ein „ QPlaceSearchRequest “ verwendet, genau wie bei einer Ortssuche, mit dem einzigen Unterschied, dass der Suchbegriff auf eine teilweise vervollständigte Zeichenfolge gesetzt ist.

QPlaceSearchRequest request;
request.setSearchTerm("piz");
request.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));
/* QPlaceSearchSuggestion * */suggestionReply = manager->searchSuggestions(request);
connect(suggestionReply, &QPlaceSearchSuggestion::finished, this, &RequestHandler::handleSuggestionReply);

Und sobald die Anfrage abgeschlossen ist, können wir die Antwort nutzen, um die Vorschläge anzuzeigen.

void handleSuggestionReply() {
    if (suggestionReply->error()== QPlaceReply::NoError) {
        for (const QString&suggestion: suggestionReply->suggestions())
            qDebug() << suggestion;
    }

    suggestionReply->deleteLater(); //Antwort verwerfen
    suggestionReply = nullptr;
}

Einen Ort speichern

Das Speichern eines neuen Ortes erfolgt wie folgt: Wir erstellen eine Instanz von ` QPlace ` und füllen sie mit Informationen wie Name, Adresse und Koordinaten. Anschließend können wir ` QPlaceManager::savePlace()` aufrufen, um den Speichervorgang zu starten.

QPlace  place;
place.setName( "Fred's Ice Cream Parlor" );

QGeoLocation location;
location.setCoordinate(QGeoCoordinate(12.34, 56.78));

QGeoAddress address;
address.setStreet("111 Nother Street");
    ...
location.setAddress(address);
place.setLocation(location);

/* QPlaceIdReply * */savePlaceReply = manager->savePlace(place);
connect(savePlaceReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSavePlaceReply);

Sobald ein Ort gespeichert wurde, enthält die Antwort die neue Kennung für diesen Ort.

void handleSavePlaceReply() {
    if (savePlaceReply->error()== QPlaceReply::NoError)
        qDebug() << savePlaceReply->id();

    savePlaceReply->deleteLater(); //Antwort verwerfen
    savePlaceReply = nullptr;
}

Beachten Sie, dass zum Speichern eines bereits vorhandenen Ortes die Funktion ` QPlace::placeId()` mit der korrekten Kennung übergeben werden muss. Andernfalls wird ein neuer Ort angelegt, wenn das Feld leer ist, oder der falsche Ort überschrieben, wenn die Kennung falsch ist.

Wenn ein Ort gespeichert wird, kann der ` QPlaceManager ` die Signale `QPlaceManager::placedAdded()` oder ` QPlaceManager::placeUpdated()` auslösen. Ob ein Manager dies tut oder nicht, ist jedoch anbieterspezifisch: Manager, die über einen Webdienst auf Orte zugreifen, lösen diese Signale in der Regel nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Hinweise

Die Places-API ist derzeit ausschließlich für das Speichern von „ core “-Details ausgelegt. Das Speichern von umfangreichen Inhalten wie Bildern und Bewertungen oder von Details wie Anbieter und Bewertung wird nicht unterstützt. In der Regel ignoriert ein Manager diese Felder beim Speichern und gibt möglicherweise eine Warnmeldung aus, wenn sie ausgefüllt sind.

Die Places-API unterstützt ausschließlich das Speichern der folgenden Kernangaben:

• Name
• Orts-ID
• Standort
• Kontaktdaten
• Symbol
• Kategorien (tagähnliche Bezeichnungen zur Beschreibung eines Ortes)
• Sichtbarkeitsbereich

Es ist möglich, dass Anbieter nur einen Teil davon unterstützen. Weitere Informationen finden Sie in der Plugin-Dokumentation.

Das Speichern von Eigenschaften wie Bewertung, erweiterte Attribute, Bilder, Bewertungen, redaktionelle Beiträge und Anbieter wird von der Places-API ausdrücklich nicht unterstützt.

Speichern zwischen Managern

Beim Speichern von Orten zwischen Managern gibt es einige Dinge zu beachten. Einige Felder eines Ortes, wie z. B. die ID, Kategorien und Symbole, sind managerspezifische Entitäten – so werden beispielsweise die Kategorien in einem Manager in einem anderen möglicherweise nicht erkannt. Daher ist es nicht möglich, einen Ort direkt von einem Manager in einen anderen zu speichern.

Der übliche Ansatz ist die Verwendung der Funktion „ QPlaceManager::compatiblePlace()“. Diese erstellt eine Kopie eines Ortes, kopiert jedoch nur Daten, die der Manager unterstützt. Managereigene Daten wie die Orts-ID werden nicht übernommen. Die neue Kopie kann nun im Manager gespeichert werden. Wenn der Manager den Abgleich anhand alternativer Identifikatoren unterstützt, wird der Kopie ein Attribut für einen alternativen Identifikator zugewiesen (siehe „Orte zwischen Managern abgleichen“).

//result retrieved from a different manager)
QPlace place = manager->compatiblePlace(result.place());
saveReply = manager->savePlace(place);

Einen Ort entfernen

Das Löschen eines Ortes erfolgt wie folgt:

/* QPlaceIdReply * */removePlaceReply = manager->removePlace(place.placeId());
connect(removePlaceReply, &QPlaceIdReply::finished, this, &RequestHandler::handleRemovePlaceReply);
    ...
    ...
void handleRemovePlaceReply() {
    if (removePlaceReply->error()== QPlaceReply::NoError)
        qDebug() << "Removal of place identified by"
                << removePlaceReply->id() << "war erfolgreich";

    removePlaceReply->deleteLater(); //Antwort verwerfen
    removePlaceReply = nullptr;
}

Wenn ein Ort entfernt wird, kann der „ QPlaceManager “ das Signal „ QPlaceManager::placeRemoved()“ auslösen. Ob ein Manager dies tut, ist anbieterspezifisch. Manager, die über einen Webdienst auf Orte zugreifen, lösen diese Signale in der Regel nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Verwendung von Kategorien

Kategorien sind Schlüsselwörter, die einen Ort beschreiben können. Zum Beispiel „Park“, „Theater“, „Restaurant“. Ein Ort kann durch viele Kategorien beschrieben werden; er könnte beispielsweise ein Park, ein Konzertsaal sowie eine Fähr- oder Bushaltestelle sein.

Um Kategorien zu verwenden, müssen sie zunächst initialisiert werden.

/* QPlaceReply * */initCatReply = manager->initializeCategories();
connect(initCatReply, &QPlaceReply::finished, this, &RequestHandler::handleInitCatReply);
    ...
    ...
void handleInitCatReply() {
    if (initCatReply->error()== QPlaceReply::NoError)
        qDebug() << "Categories initialized";
   sonst
        qDebug() << "Failed to initialize categories";

    initCatReply->deleteLater();
    initCatReply = nullptr;
}

Nachdem die Kategorien initialisiert wurden, können wir diese Kategorie-Funktionen nutzen.

• QPlaceManager::childCategories()
• QPlaceManager::category()
• QPlaceManager::parentCategoryId()
• QPlaceManager::childCategoryIds();

Um die Kategorien der obersten Ebene abzurufen, verwenden wir die Funktion „ QPlaceManager::childCategories()“, geben jedoch keine Kategorie-ID an.

const QList<QPlaceCategory> topLevelCategories = manager->childCategories();
for (const QPlaceCategory&category: topLevelCategories)
    qDebug() << category.name();

Wenn wir eine Kennung angeben würden, könnten wir die untergeordneten Elemente einer Kategorie abrufen.

QList<QPlaceCategory> childCategories = manager->childCategories(pizza.categoryId());

Eine Kategorie speichern

Im Folgenden wird gezeigt, wie man eine Kategorie speichert

QPlaceCategory fastFood;

QPlaceCategory category;
category.setName("pizza");
/*QPlaceIdReply */ saveCategoryReply = manager->saveCategory(category);
connect(saveCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSaveCategoryReply);

// Wir hätten eine Kategorie als untergeordnete Kategorie speichern können, indem wir eine übergeordnete ID angegeben hätten.
saveCategoryReply = manager->saveCategory(category, fastFood.categoryId());
    ...
    ...
void handleSaveCategoryReply() {
    if (saveCategoryReply->error()== QPlaceReply::NoError) {
        qDebug() << "Saved category id =" << saveCategoryReply->id();
    }

    saveCategoryReply->deleteLater();
    saveCategoryReply = nullptr;
}

Wenn eine Kategorie gespeichert wird, kann der „ QPlaceManager “ die Signale „ QPlaceManager::categoryAdded()“ oder „ QPlaceManager::categoryUpdated()“ auslösen. Ob ein Manager dies tut oder nicht, ist jedoch anbieterspezifisch: Manager, die über einen Webdienst auf Orte zugreifen, lösen diese Signale in der Regel nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Eine Kategorie entfernen

Das Entfernen einer Kategorie erfolgt sehr ähnlich wie das Entfernen eines Ortes

/* QPlaceIdReply * */removeCategoryReply = manager->removeCategory(place.placeId());
connect(removeCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleRemoveCategoryReply);
    ...
    ...
void handleRemoveCategoryReply() {
    if (removeCategoryReply->error()== QPlaceReply::NoError)
        qDebug() << "Removal of category identified by"
                << removeCategoryReply->id() <<  „war erfolgreich“;

    removeCategoryReply->deleteLater(); //Antwort verwerfen
    removeCategoryReply = nullptr;
}

Wenn eine Kategorie entfernt wird, kann der „ QPlaceManager “ das Signal „ QPlaceManager::categoryRemoved()“ auslösen. Ob ein Manager dies tut, ist anbieterspezifisch. Manager, die über einen Webdienst auf Orte zugreifen, lösen diese Signale in der Regel nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Abgleich von Orten zwischen Managern

Manchmal möchte man möglicherweise überprüfen, ob Orte aus einem Manager mit denen aus einem anderen Manager übereinstimmen. Eine solche Situation kann auftreten, wenn ein Manager Lesezugriff auf Orte gewährt (Ursprungsmanager), während ein zweiter Manager mit Lese-/Schreibzugriff (Zielmanager) verwendet wird, um ausgewählte Favoriten aus dem ersten zu speichern. Bei einer Suche im Ursprungsmanager möchten wir möglicherweise wissen, welche Orte im Zielmanager als „Favoriten“ gespeichert wurden, und vielleicht einen benutzerdefinierten Favoritennamen anstelle des ursprünglichen Namens anzeigen.

Der Abgleichmechanismus kann je nach Manager variieren, wird jedoch in der Regel über einen alternativen Bezeichner realisiert. Im Rahmen des Speichervorgangs wird der Ortsbezeichner des Ursprungsmanagers als Attribut für den alternativen Bezeichner im Zielmanager gespeichert (der über ein eigenes Schema für Ortsbezeichner verfügen kann). Im folgenden Beispiel stammt der Ursprungsmanager vom QGeoServiceProvider „here“; daher wird im Rahmen des Speichervorgangs ein Attribut für die alternative Kennung, x_id_here, für den im Zielmanager gespeicherten Ort gesetzt (beim Aufruf von ` QPlaceManager::compatiblePlace()`).

origin R/O manager(here)       destination R/W manager (places_jsondb)
                        Save
Place id: ae246         --->    Place id: 0001
Attribute type: x_provider      Attribute type: x_id_here
Attribute value: here           Attribute text value: ae246

Um den Abgleich durchzuführen, erstellen wir einen ` QPlaceMatchRequest ` und weisen ihm die Suchergebnisse aus dem Ursprungsmanager zu. Der ` QPlaceMatchRequest ` wird im Zielmanager verwendet, um entsprechende Orte zurückzugeben. Außerdem geben wir Abgleichparameter an, bei denen es sich um Schlüssel-Wert-Paare handelt. Wie bereits erwähnt, kann dies je nach Manager variieren, doch typischerweise lautet der Schlüssel „ QPlaceMatchRequest::AlternativeId “, um anzugeben, dass wir anhand der „Alternative ID“ abgleichen; der Wert wäre in diesem Fall „x_id_here“, der angibt, welches „Alternative Identifier“-Attribut wir für den Abgleich verwenden.

QPlaceMatchRequest request;
request.setResults(results);
QVariantMap parameters;
parameters.insert(QPlaceMatchRequest::AlternativeId, "x_id_here");
request.setParameters(parameters);
matchReply = manager->matchingPlaces(request);
    ...
    ...
void matchHandler() {
    if (matchReply->error()== QPlaceReply::NoError) {
        const auto places = matchReply->places();
        for (const QPlace&place: places) {
            if (place != QPlace())
                qDebug() << "Place is a favorite with name" << place.name();
           sonst
                qDebug() << "Place is not a favorite";
        }
    }

    matchReply->deleteLater();
    matchReply = nullptr;
}

Klassen an verschiedenen Stellen

Datenklassen

Anfrageklassen

Antwortklassen

Manager-Klassen