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
Stellt eine Adresse eines QGeoLocation dar | |
Stellt grundlegende Informationen über einen Ort dar | |
Stellt einen Satz von Daten über einen Ort dar | |
Stellt generische Attributinformationen über einen Ort dar | |
Stellt eine Kategorie dar, der ein QPlace zugeordnet werden kann | |
Stellt ein Kontaktdetail wie eine Telefonnummer oder eine Website-URL dar | |
Enthält Inhalte über Orte | |
Stellt ein Symbol dar | |
Stellt ein Suchergebnis dar, das eine vorgeschlagene Suche enthält | |
Enthält Bewertungsinformationen über einen Ort | |
Stellt ein Suchergebnis dar, das einen Ort enthält | |
Die Basisklasse für Suchergebnisse | |
Stellt einen Anbieter eines Ortes oder eines mit einem Ort verbundenen Inhalts dar | |
Repräsentiert einen einzelnen Benutzer |
Anfrage-Klassen
Stellt die Parameter einer Inhaltsanforderung dar | |
Wird verwendet, um Orte von einem Manager zu finden, die mit denen eines anderen übereinstimmen. Stellt einen Satz von Anfrageparametern dar | |
Stellt den Satz von Parametern für eine Suchanfrage dar |
Antwort-Klassen
Verwaltet einen Vorgang zum Abrufen von Inhalten, der von einer Instanz von QPlaceManager gestartet wurde | |
Verwaltet einen Vorgang zum Abrufen von Ortsdetails, der von einer Instanz von QPlaceManager gestartet wird | |
Verwaltet Operationen, die einen Bezeichner zurückgeben, wie das Speichern und Entfernen von Orten und Kategorien | |
Verwaltet eine Operation zum Abgleich von Orten, die von einer Instanz von QPlaceManager gestartet wird | |
Verwaltet einen Vorgang, der von einer Instanz von QPlaceManager gestartet wird und dient als Basisklasse für speziellere Antworten | |
Verwaltet eine Operation zur Ortssuche, die von einer Instanz von QPlaceManager gestartet wird | |
Verwaltet einen Suchvorschlag, der von einer Instanz von QPlaceManager gestartet wurde |
Manager-Klassen
Die Schnittstelle, über die Clients auf Orte zugreifen können, die in einem bestimmten Backend gespeichert sind | |
Schnittstelle für Implementierer von QGeoServiceProvider-Plugins, die Zugriff auf Ortsfunktionen bieten wollen |
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.