Lugares (C++)
Descripción general
La API de Lugares permite a los usuarios descubrir lugares o puntos de interés y consultar información detallada sobre ellos, como la dirección y los datos de contacto; algunos lugares pueden incluso incluir contenido enriquecido, como imágenes y reseñas. La API de Lugares también facilita la gestión de lugares y categorías, permitiendo a los usuarios guardarlos y eliminarlos.
Definición de «lugar»
Un lugar es un punto de interés; puede ser un restaurante favorito, un parque o la casa de alguien. Un objeto ` QPlace ` representa un lugar actuando como contenedor de diversa información sobre dicho lugar.
Esta información se puede dividir en dos grandes categorías
- Detalles
- Contenido enriquecido
Los detalles del lugar consisten en las características del mismo, como el nombre, la ubicación, la información de contacto, etc. Cuando se muestra un lugar como resultado de una búsqueda, se rellenan estos detalles. A veces, para ahorrar ancho de banda, hay más detalles sobre el lugar que se pueden recuperar de forma individual para cada lugar, si el usuario está interesado. Se puede consultar la función ` QPlace::detailsFetched()` para comprobar si se han obtenido todos los detalles disponibles y, en caso contrario, se puede utilizar ` QPlaceManager::getPlaceDetails()` para recuperarlos. Los detalles concretos que se rellenan durante una búsqueda y los que deben recuperarse individualmente pueden variar de un proveedor a otro. Consulta la documentación del complemento para obtener más detalles.
El contenido enriquecido de un lugar está compuesto por elementos como imágenes, reseñas y artículos editoriales. Es posible que haya muchos elementos de contenido enriquecido, por lo que se tratan por separado de los detalles del lugar. Se pueden recuperar por páginas mediante QPlaceManager::getPlaceContent(). Si es necesario, el contenido se puede asignar a un lugar para que este actúe como un contenedor práctico.
Operaciones comunes
Inicialización de un gestor
La funcionalidad de «All places» se gestiona mediante una instancia de ` QPlaceManager `. Es necesario especificar un ` QGeoServiceProvider ` para crear el QPlaceManager
//The "provider name" is used to select a particular provider
QGeoServiceProvider *provider = new QGeoServiceProvider("provider name");
QPlaceManager *manager = provider->placeManager();Descubrimiento/Búsqueda
Para realizar una operación de búsqueda, basta con crear un objeto ` QPlaceSearchRequest ` y establecer los parámetros de búsqueda deseados, como el término de búsqueda y el centro de búsqueda.
//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);La solicitud es una operación asíncrona, por lo que necesitamos un slot para gestionar la finalización de la misma. En el controlador, comprobamos que no haya errores y que el tipo de resultado de la búsqueda sea un lugar. Si es así, podemos recuperar algunos de los datos principales del lugar. Al final del slot, eliminamos la respuesta, ya que es de un solo uso.
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(); // descartar respuesta
searchReply = nullptr;
}Nota: Dependiendo del backend del complemento que se haya elegido, los resultados de la búsqueda pueden contener lugares que tengan más detalles que se pueden obtener de forma individual para cada lugar. Para obtener estos otros detalles, consulta Obtención de detalles de lugares.
Recomendaciones
Las recomendaciones se pueden recuperar proporcionando un identificador de lugar mediante QPlaceSearchRequest::setRecommendationId(). Se recuperan todos los lugares similares al lugar indicado.
Paginación
Si el complemento admite la paginación, se puede incluir el parámetro «limit» en la solicitud de búsqueda.
QPlaceSearchRequest searchRequest;
searchRequest.setLimit(15); //specify how many results are to be retrieved.Obtención de detalles de un lugar
Un lugar que haya sido devuelto por una solicitud de búsqueda puede tener más detalles que se puedan recuperar. A continuación se muestra cómo comprobar si hay más detalles y, en caso afirmativo, cómo solicitarlos.
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;
}Obtención de contenido enriquecido
El contenido enriquecido, como imágenes y reseñas, se recupera a través del gestor y, a continuación, si es necesario, se asigna a un lugar.
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);Podemos gestionar la solicitud de contenido tal y como se muestra a continuación.
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 imagen = iter.value();
qDebug() << image.url();
qDebug() << image.mimeType();
}
//O bien, si los índices no son relevantes
for (const QPlaceImage &image: contentReply->content()) {
qDebug() << image.url();
qDebug() << image.mimeType();
}
//Podemos asignar el contenido al lugar al que pertenece.
//El objeto «place» actúa como un contenedor en el que podemos recuperar
//el contenido que ya se ha obtenido
place.insertContent(contentReply->request().contentType(), contentReply->content());
place.setTotalContentCount(contentReply->request().contentType(), contentReply->totalCount());
}
contentReply->deleteLater();
contentReply = nullptr;
}Es importante señalar que los resultados en ` QPlaceContentReply` son un ` QPlaceContent::Collection `, que es esencialmente un ` QMap<int, QPlaceContent>`. La clave ` int `, en este caso, es el índice del contenido, y el valor es el propio contenido. Debido a la forma en que se implementa `Content`, es posible convertir un tipo de contenido de la siguiente manera
QPlaceImage image = content; //provided that 'content' has a type QPlace::ImageTypeEl uso de QPlaceContent::Collection y la conversión entre «content» y sus subtipos permiten compartir fácilmente el código encargado de gestionar los mecanismos de paginación de reseñas, imágenes y artículos de opinión.
Sugerencias de búsqueda
La obtención de sugerencias de términos de búsqueda es muy similar a la realización de una búsqueda de lugar. Se utiliza un « QPlaceSearchRequest » igual que en una búsqueda de lugar, con la única diferencia de que el término de búsqueda se establece como una cadena parcialmente completada.
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);Y una vez realizada la solicitud, podemos utilizar la respuesta para mostrar las sugerencias.
void handleSuggestionReply() {
if (suggestionReply->error()== QPlaceReply::NoError) {
for (const QString&suggestion: suggestionReply->suggestions())
qDebug() << suggestion;
}
suggestionReply->deleteLater(); // descartar respuesta
suggestionReply = nullptr;
}Guardar un lugar
El guardado de un nuevo lugar se realiza de la siguiente manera: creamos una instancia de ` QPlace ` y la rellenamos con información como el nombre, la dirección y las coordenadas. Una vez hecho esto, podemos llamar a ` QPlaceManager::savePlace()` para iniciar la operación de guardado.
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);Una vez guardado un lugar, la respuesta contiene el nuevo identificador de dicho lugar.
void handleSavePlaceReply() {
if (savePlaceReply->error()== QPlaceReply::NoError)
qDebug() << savePlaceReply->id();
savePlaceReply->deleteLater(); // descartar respuesta
savePlaceReply = nullptr;
}Ten en cuenta que, para guardar un lugar ya existente, la función QPlace::placeId() debe completarse con el identificador correcto. De lo contrario, se creará un nuevo lugar si está vacío o se sobrescribirá el lugar equivocado si el identificador es incorrecto.
Cuando se guarda un lugar, el ` QPlaceManager ` puede emitir las señales `QPlaceManager::placedAdded()` o ` QPlaceManager::placeUpdated()`. Sin embargo, el hecho de que un gestor lo haga o no depende del proveedor; los gestores que acceden a los lugares desde un servicio web normalmente no emiten estas señales, mientras que los que acceden a lugares almacenados localmente sí lo hacen por lo general.
Advertencias
Actualmente, la API de lugares está diseñada únicamente para guardar los datos de core. No se admite el almacenamiento de contenido enriquecido, como imágenes y reseñas, ni de datos como el proveedor y la valoración. Por lo general, un gestor ignorará estos campos al guardar y puede mostrar un mensaje de advertencia si están rellenados.
La API de Places solo admite el almacenamiento de los siguientes datos básicos:
- nombre
- ID del lugar
- ubicación
- datos de contacto
- icono
- categorías (nombres similares a etiquetas para describir un lugar)
- ámbito de visibilidad
Es posible que los proveedores solo admitan un subconjunto de estas opciones. Consulta la documentación del complemento para obtener más detalles.
La API de Places no admite explícitamente el almacenamiento de propiedades como la valoración, los atributos ampliados, las imágenes, las reseñas, los artículos editoriales y el proveedor.
Almacenamiento entre gestores
A la hora de guardar lugares entre gestores, hay algunos aspectos que hay que tener en cuenta. Algunos campos de un lugar, como el ID, las categorías y los iconos, son entidades específicas de cada gestor; por ejemplo, es posible que las categorías de un gestor no se reconozcan en otro. Por lo tanto, no es posible intentar guardar un lugar directamente de un gestor a otro.
El método habitual consiste en utilizar la función « QPlaceManager::compatiblePlace()», que crea una copia de un lugar, pero solo copia los datos que admite el gestor. Los datos específicos del gestor, como el identificador del lugar, no se copian. La nueva copia ya es apta para guardarse en el gestor. Si el gestor admite la correspondencia mediante identificadores alternativos, se asigna un atributo de identificador alternativo a la copia (véase «Correspondencia de lugares entre gestores»).
//result retrieved from a different manager)
QPlace place = manager->compatiblePlace(result.place());
saveReply = manager->savePlace(place);Eliminación de un lugar
La eliminación de un lugar se lleva a cabo de la siguiente manera:
/* 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() << "se ha realizado correctamente";
removePlaceReply->deleteLater(); // descartar respuesta
removePlaceReply = nullptr;
}Cuando se elimina un lugar, el QPlaceManager puede emitir la señal QPlaceManager::placeRemoved(). Que un gestor lo haga o no depende del proveedor. Los gestores que acceden a los lugares desde un servicio web no suelen emitir estas señales, mientras que los que acceden a lugares almacenados localmente sí lo hacen por lo general.
Uso de categorías
Las categorías son palabras clave que pueden describir un lugar. Por ejemplo, «parque», «teatro» o «restaurante». Un lugar puede describirse mediante muchas categorías; podría ser un parque, una sala de conciertos y una parada de ferry o de autobús.
Para utilizar las categorías, primero hay que inicializarlas.
/* QPlaceReply * */initCatReply = manager->initializeCategories();
connect(initCatReply, &QPlaceReply::finished, this, &RequestHandler::handleInitCatReply);
...
...
void handleInitCatReply() {
if (initCatReply->error()== QPlaceReply::NoError)
qDebug() << "Categories initialized";
sino
qDebug() << "Failed to initialize categories";
initCatReply->deleteLater();
initCatReply = nullptr;
}Una vez inicializadas las categorías, ya podemos utilizar estas funciones de categoría.
- QPlaceManager::childCategories()
- QPlaceManager::category()
- QPlaceManager::parentCategoryId()
- QPlaceManager::childCategoryIds();
Para recuperar las categorías de primer nivel, utilizamos la función QPlaceManager::childCategories(), pero no proporcionamos ningún identificador de categoría.
const QList<QPlaceCategory> topLevelCategories = manager->childCategories();
for (const QPlaceCategory&category: topLevelCategories)
qDebug() << category.name();Si proporcionáramos un identificador, podríamos recuperar los elementos secundarios de una categoría.
QList<QPlaceCategory> childCategories = manager->childCategories(pizza.categoryId());Guardar una categoría
A continuación se muestra cómo guardar una categoría
QPlaceCategory fastFood;
QPlaceCategory categoría;
categoría.setName("pizza");
/*QPlaceIdReply */ saveCategoryReply = manager->saveCategory(categoría);
connect(saveCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSaveCategoryReply);
//Podríamos haber guardado una categoría como hija proporcionando un identificador de padre.
saveCategoryReply = manager->saveCategory(category, fastFood.categoryId());
...
...
void handleSaveCategoryReply() {
if (saveCategoryReply->error()== QPlaceReply::NoError) {
qDebug() << "Saved category id =" << saveCategoryReply->id();
}
saveCategoryReply->deleteLater();
saveCategoryReply = nullptr;
}Cuando se guarda una categoría, el QPlaceManager puede emitir las señales QPlaceManager::categoryAdded() o QPlaceManager::categoryUpdated(). Sin embargo, el hecho de que un gestor emita o no estas señales depende del proveedor; los gestores que acceden a lugares desde un servicio web no suelen emitir estas señales, mientras que los que acceden a lugares almacenados localmente sí lo hacen por lo general.
Eliminación de una categoría
La eliminación de una categoría es muy similar a la eliminación de un lugar
/* 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() << "se ha realizado correctamente";
removeCategoryReply->deleteLater(); // descartar respuesta
removeCategoryReply = nullptr;
}Cuando se elimina una categoría, el QPlaceManager puede emitir la señal QPlaceManager::categoryRemoved(). El hecho de que un gestor lo haga o no depende del proveedor. Los gestores que acceden a lugares desde un servicio web no suelen emitir estas señales, mientras que los que acceden a lugares almacenados localmente sí suelen hacerlo.
Coincidencia de lugares entre gestores
En ocasiones, puede que se desee comprobar si los lugares de un gestor coinciden con los de otro. Esta situación puede darse cuando un gestor proporciona acceso de solo lectura a los lugares (gestor de origen), mientras que se utiliza un segundo gestor de lectura/escritura (gestor de destino) para guardar los favoritos seleccionados del primero. Durante una búsqueda en el gestor de origen, puede que queramos saber cuáles se han marcado como «favoritos» en el gestor de destino y, tal vez, mostrar un nombre de favorito personalizado en lugar del nombre original.
El mecanismo de coincidencia puede variar entre gestores, pero normalmente se lleva a cabo mediante un identificador alternativo. Como parte del proceso de guardado, el identificador de lugar del gestor de origen se guarda como un atributo de identificador alternativo en el gestor de destino (que puede tener su propio esquema de identificadores de lugar). En el siguiente ejemplo, el gestor de origen procede del QGeoServiceProvider «here»; por lo tanto, como parte del proceso de guardado, se establece un atributo de identificador alternativo, x_id_here, para el lugar guardado en el gestor de destino (cuando se llama a 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: ae246Para realizar la correspondencia, creamos un ` QPlaceMatchRequest ` y le asignamos los resultados de la búsqueda del gestor de origen. El ` QPlaceMatchRequest ` se utilizará en el gestor de destino para devolver los lugares correspondientes. También especificamos los parámetros de coincidencia, que son pares clave-valor. Como se ha mencionado anteriormente, esto puede variar en función del gestor, pero normalmente la clave es « QPlaceMatchRequest::AlternativeId » para indicar que estamos realizando la coincidencia por «alternative id»; el valor, en este caso, sería «x_id_here», que especifica qué atributo de identificador alternativo estamos utilizando para realizar la coincidencia.
QPlaceMatchRequest solicitud;
solicitud.setResults(resultados);
QVariantMap parámetros;
parámetros.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();
sino
qDebug() << "Place is not a favorite";
}
}
matchReply->deleteLater();
matchReply = nullptr;
}Clases en Places
Clases de datos
Representa la dirección de un QGeoLocation | |
Representa información básica sobre una ubicación | |
Representa un conjunto de datos sobre un lugar | |
Representa información genérica sobre los atributos de un lugar | |
Representa una categoría a la que se puede asociar un QPlace | |
Representa un dato de contacto, como un número de teléfono o la URL de un sitio web | |
Contiene contenido sobre lugares | |
Representa un icono | |
Representa un resultado de búsqueda que contiene una propuesta de búsqueda | |
Contiene información sobre la valoración de un lugar | |
Representa un resultado de búsqueda que contiene un lugar | |
La clase base para los resultados de búsqueda | |
Representa a un usuario individual |
Clases de solicitud
Representa los parámetros de una solicitud de contenido | |
Se utiliza para encontrar lugares de un gestor que coincidan con los de otro. Representa un conjunto de parámetros de solicitud | |
Representa el conjunto de parámetros de una solicitud de búsqueda |
Clases de respuesta
Gestiona una operación de recuperación de contenido iniciada por una instancia de QPlaceManager | |
Gestiona una operación de obtención de detalles de un lugar iniciada por una instancia de QPlaceManager | |
Gestiona operaciones que devuelven un identificador, como las operaciones de guardado y eliminación de lugares y categorías | |
Gestiona una operación de búsqueda de coincidencias de lugares iniciada por una instancia de QPlaceManager | |
Gestiona una operación iniciada por una instancia de QPlaceManager y sirve como clase base para respuestas más especializadas | |
Gestiona una operación de búsqueda de lugares iniciada por una instancia de QPlaceManager | |
Gestiona una operación de sugerencia de búsqueda iniciada por una instancia de QPlaceManager |
Clases de gestión
La interfaz que permite a los clientes acceder a los lugares almacenados en un backend concreto | |
Interfaz para los desarrolladores de complementos de QGeoServiceProvider que deseen proporcionar acceso a la funcionalidad de lugares |
© 2026 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.