Orte (C++)

Übersicht

Die Places-API ermöglicht es Nutzern, Orte/Punkte von Interesse zu entdecken und Details zu ihnen anzuzeigen, wie z. B. Adresse und Kontaktinformationen; einige Orte können sogar umfangreiche Inhalte wie Bilder und Bewertungen enthalten. Die Places-API erleichtert auch die Verwaltung von Orten und Kategorien, so dass Benutzer sie speichern und entfernen können.

Definition von Orten

Ein Ort ist ein Punkt von Interesse, z. B. ein Lieblingsrestaurant, ein Park oder das Haus einer Person. Ein QPlace Objekt repräsentiert einen Ort, indem es als Container für verschiedene Informationen über diesen Ort dient.

Diese Informationen können in 2 große Kategorien unterteilt werden

• Einzelheiten
• Reichhaltiger Inhalt

Die Ortsdetails bestehen aus den Eigenschaften des Ortes, wie Name, Standort, Kontaktinformationen usw. Wenn ein Ort bei einer Suche zurückgegeben wird, werden diese Details ausgefüllt. Um Bandbreite zu sparen, gibt es manchmal weitere Details über den Ort, die für jeden Ort einzeln abgerufen werden können, wenn der Nutzer daran interessiert ist. Die Funktion QPlace::detailsFetched() kann abgefragt werden, um zu sehen, ob alle verfügbaren Details abgerufen wurden, und wenn nicht, kann QPlaceManager::getPlaceDetails() verwendet werden, um sie abzurufen. Welche Details genau bei einer Suche ausgefüllt werden und welche einzeln abgerufen werden müssen, kann von Anbieter zu Anbieter variieren. Weitere Einzelheiten finden Sie in der Plugin-Dokumentation.

Der Rich Content eines Ortes besteht aus Elementen wie Bildern, Bewertungen und redaktionellen Beiträgen. Da es möglicherweise viele Rich-Content-Elemente geben kann, werden sie getrennt von den Ortsangaben behandelt. Sie können über QPlaceManager::getPlaceContent() seitenweise abgerufen werden. Falls erforderlich, kann der Inhalt einem Ort zugewiesen werden, damit er als praktischer Container fungieren kann.

Allgemeine Operationen

Initialisierung eines Managers

Alle Funktionen von Places werden durch eine Instanz von QPlaceManager unterstützt. Man muss eine QGeoServiceProvider angeben, um die QPlaceManager

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

Entdeckung/Suche

Um einen Suchvorgang durchzuführen, erstellen wir einfach eine QPlaceSearchRequest und legen die gewünschten Suchparameter fest, wie z. B. 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);

Die Anfrage ist eine asynchrone Operation, so dass wir einen Slot benötigen, um den Abschluss der Anfrage zu behandeln. 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 Kerndaten des Ortes abrufen. Am Ende des Slots löschen wir die Antwort, da sie 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 verwerfensearchReply = nullptr; }

Hinweis: Je nach gewähltem Plugin-Backend können die Suchergebnisse Orte enthalten, die weitere Details enthalten, die für jeden Ort einzeln abgerufen werden können. Um diese weiteren Details abzurufen, siehe Abrufen von Ortsdetails.

Empfehlungen

Empfehlungen können durch Angabe einer Ortskennung über QPlaceSearchRequest::setRecommendationId() abgerufen werden. Es werden alle Orte abgerufen, die dem angegebenen Ort ähnlich sind.

Paging

Wenn das Plugin Paging unterstützt, kann der Suchanfrage der Parameter limit mitgegeben werden.

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

Abruf von Ortsdetails

Ein Ort, der von einer Suchanfrage zurückgegeben wurde, kann weitere Details enthalten, die abgerufen werden können. Im Folgenden wird gezeigt, wie man prüft, ob weitere Details vorhanden sind, und wie man sie gegebenenfalls anfordert.

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 umfangreicher Inhalte

Umfangreiche Inhalte wie Bilder und Bewertungen werden über den Manager abgerufen und dann 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);

Wir können die Inhaltsanforderung wie unten gezeigt behandeln.

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 irrelevant sind for(const QPlaceImage &image:  contentReply->content()) {            qDebug() << image.url();
            qDebug() << image.mimeType();
        } //Wir können Inhalte dem Ort zuordnen, zu dem sie gehören. //Das Place-Objekt dient als Container, in dem wir  bereits abgeholte //Inhalte  abrufen könnenplace.insertContent(contentReply->request().contentType(),  contentReply->content()); place.setTotalContentCount(contentReply->request().contentType(),  contentReply->totalCount()); }  contentReply->deleteLater(); contentReply = nullptr; }

Es ist wichtig zu beachten, dass das Ergebnis in QPlaceContentReply ein QPlaceContent::Collection ist, das im Wesentlichen ein QMap<int, QPlaceContent> ist. 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

Die Verwendung von QPlaceContent::Collection und die Konvertierung zwischen Content und seinen Subtypen bedeutet, dass der Code für die Handhabung der Mechanik des Blätterns von Rezensionen, Bildern und Leitartikeln leicht gemeinsam genutzt werden kann.

Vorschläge für die Suche

Das Abrufen von Vorschlägen für Suchbegriffe ist der Suche nach einem Ort sehr ähnlich. Eine QPlaceSearchRequest wird genau wie eine Ortssuche verwendet, mit dem einzigen Unterschied, dass der Suchbegriff auf eine teilweise vervollständigte Zeichenkette gesetzt wird.

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 wenn die Anfrage abgeschlossen ist, können wir die Antwort verwenden, um die Vorschläge anzuzeigen.

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

Speichern eines Ortes

Das Speichern eines neuen Ortes wird wie folgt durchgeführt: Wir erstellen eine Instanz von QPlace und füllen sie mit Informationen wie einem Namen, einer Adresse und einer Koordinate. Danach können wir QPlaceManager::savePlace() aufrufen, um einen 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 ist, enthält die Antwort den neuen Bezeichner für diesen Ort.

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

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

Um einen bereits existierenden Ort zu speichern, muss QPlace::placeId() mit dem richtigen Bezeichner ausgefüllt werden. Andernfalls wird ein neuer Ort erstellt, wenn er leer ist, oder der falsche Ort überschrieben, wenn der Bezeichner falsch ist.

Wenn ein Ort gespeichert wird, kann QPlaceManager die Signale QPlaceManager::placedAdded() oder QPlaceManager::placeUpdated() ausgeben. Ob ein Manager dies tut oder nicht, ist jedoch anbieterspezifisch. Manager, die auf Orte von einem Webdienst zugreifen, geben diese Signale normalerweise nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Vorbehalte

Die Places API ist derzeit nur für das Speichern von core Details ausgelegt. Das Speichern von umfangreichen Inhalten wie Bildern und Bewertungen oder Details wie Anbieter und Bewertung ist kein unterstützter Anwendungsfall. Normalerweise ignoriert ein Manager diese Felder beim Speichern und kann eine Warnmeldung ausgeben, wenn sie ausgefüllt sind.

Die Places API unterstützt nur das Speichern der folgenden Kerndetails:

• Name
• Ortskennung
• Ort
• Kontaktdetails
• Symbol
• Kategorien (tagähnliche Namen zur Beschreibung eines Ortes)
• Sichtbarkeitsbereich

Es ist möglich, dass Anbieter nur eine Teilmenge davon unterstützen. Weitere Einzelheiten finden Sie in der Plugin-Dokumentation.

Das Speichern von Eigenschaften wie Bewertung, erweiterte Attribute, Bilder, Rezensionen, 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 ein paar Dinge zu beachten. Einige Felder eines Ortes, wie z.B. die ID, Kategorien und Icons, sind managerabhängig. Daher ist es nicht möglich, einen Ort direkt von einem Manager in einem anderen zu speichern.

Der typische Ansatz ist die Verwendung der Funktion QPlaceManager::compatiblePlace(), die eine Kopie eines Ortes erstellt, aber nur Daten kopiert, die der Manager unterstützt. Managerspezifische Daten wie der Ortsbezeichner werden nicht mitkopiert. Die neue Kopie eignet sich nun zum Speichern im Manager. Wenn der Manager den Abgleich durch alternative Bezeichner unterstützt, wird der Kopie ein Attribut für alternative Bezeichner zugewiesen (siehe Abgleich von Orten zwischen Managern)

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

Entfernen eines Ortes

Das Entfernen eines Ortes wird wie folgt durchgeführt:

/* 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 verwerfenremovePlaceReply = nullptr; }

Wenn ein Ort entfernt wird, kann QPlaceManager das Signal QPlaceManager::placeRemoved() ausgeben. Ob ein Manager dies tut, ist anbieterspezifisch. Manager, die auf Orte von einem Webdienst zugreifen, senden diese Signale normalerweise nicht, 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 kann ein Park und ein Musiklokal und eine Fähre oder eine 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 worden sind, können wir diese Kategoriefunktionen verwenden.

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

Um die Kategorien der obersten Ebene abzurufen, verwenden wir die Funktion QPlaceManager::childCategories(), geben aber keinen Kategoriebezeichner an.

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

Wenn wir einen Bezeichner angeben würden, könnten wir die Kinder 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 Kind speichern können, indem wir eine übergeordnete Kennung 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 QPlaceManager die Signale QPlaceManager::categoryAdded() oder QPlaceManager::categoryUpdated() ausgeben. Ob ein Manager dies tut oder nicht, ist jedoch anbieterspezifisch. Manager, die auf Orte von einem Webdienst zugreifen, geben diese Signale in der Regel nicht aus, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Entfernen einer Kategorie

Das Entfernen einer Kategorie ist dem Entfernen eines Ortes sehr ähnlich

/* 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 verwerfenremoveCategoryReply = nullptr; }

Wenn eine Kategorie entfernt wird, kann QPlaceManager das Signal QPlaceManager::categoryRemoved() ausgeben. Ob ein Manager dies tut, ist anbieterspezifisch. Manager, die auf Orte von einem Webdienst zugreifen, senden diese Signale normalerweise nicht, während Manager, die auf lokal gespeicherte Orte zugreifen, dies im Allgemeinen tun.

Abgleich von Orten zwischen Managern

Manchmal möchten Sie vielleicht abgleichen, ob Orte von einem Manager mit denen eines anderen Managers übereinstimmen. Eine solche Situation kann eintreten, wenn ein Manager einen Nur-Lese-Zugriff auf Orte bietet (Ursprungsmanager), während ein anderer, zweiter R/W-Manager (Zielmanager) verwendet wird, um ausgewählte Favoriten des ersten zu speichern. Während einer Suche im Ursprungsmanager möchten wir vielleicht wissen, welche Orte im Zielmanager "favorisiert" wurden, und vielleicht einen angepassten Favoritennamen anstelle des Originalnamens anzeigen.

Der Abgleichsmechanismus kann von Manager zu Manager variieren, wird aber in der Regel durch einen alternativen Bezeichner erreicht. Als Teil des Speichervorgangs wird der Ortsbezeichner des Ursprungsmanagers als alternatives Bezeichnerattribut im Zielmanager gespeichert (der sein eigenes Ortsbezeichnerschema haben kann). Im folgenden Beispiel stammt der Ursprungsmanager aus dem QGeoServiceProider "here", daher wird als Teil des Speichervorgangs ein alternatives Bezeichnerattribut, x_id_here, für den im Zielmanager gespeicherten Ort gesetzt (wenn QPlaceManager::compatiblePlace() aufgerufen wird)

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 ein QPlaceMatchRequest und weisen ihm die Suchergebnisse aus dem Herkunftsmanager zu. Die QPlaceMatchRequest wird im Zielmanager verwendet, um die entsprechenden Orte zurückzugeben. Wir geben auch Parameter für den Abgleich an, die Schlüssel-Wert-Paare sind. Wie bereits erwähnt, kann dies je nach Manager variieren, aber in der Regel ist der Schlüssel QPlaceMatchRequest::AlternativeId, um anzugeben, dass der Abgleich anhand der alternativen Kennung erfolgt; der Wert wäre in diesem Fall x_id_here, der angibt, welches Attribut der alternativen Kennung 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 in Plätzen

Daten-Klassen

Anfrage-Klassen

Antwort-Klassen

Manager-Klassen