QPlaceManager Class
La clase QPlaceManager proporciona la interfaz que permite a los clientes acceder a los lugares almacenados en un backend concreto. Más información...
| Header: | #include <QPlaceManager> |
| qmake: | QT += location |
| Inherits: | QObject |
Funciones públicas
| virtual | ~QPlaceManager() |
| QPlaceCategory | category(const QString &categoryId) const |
| QList<QPlaceCategory> | childCategories(const QString &parentId = QString()) const |
| QStringList | childCategoryIds(const QString &parentId = QString()) const |
| QPlace | compatiblePlace(const QPlace &original) const |
| QPlaceContentReply * | getPlaceContent(const QPlaceContentRequest &request) const |
| QPlaceDetailsReply * | getPlaceDetails(const QString &placeId) const |
| QPlaceReply * | initializeCategories() |
| QList<QLocale> | locales() const |
| QString | managerName() const |
| int | managerVersion() const |
| QPlaceMatchReply * | matchingPlaces(const QPlaceMatchRequest &request) const |
| QString | parentCategoryId(const QString &categoryId) const |
| QPlaceIdReply * | removeCategory(const QString &categoryId) |
| QPlaceIdReply * | removePlace(const QString &placeId) |
| QPlaceIdReply * | saveCategory(const QPlaceCategory &category, const QString &parentId = QString()) |
| QPlaceIdReply * | savePlace(const QPlace &place) |
| QPlaceSearchReply * | search(const QPlaceSearchRequest &request) const |
| QPlaceSearchSuggestionReply * | searchSuggestions(const QPlaceSearchRequest &request) const |
| void | setLocale(const QLocale &locale) |
| void | setLocales(const QList<QLocale> &locales) |
Señales
| void | categoryAdded(const QPlaceCategory &category, const QString &parentId) |
| void | categoryRemoved(const QString &categoryId, const QString &parentId) |
| void | categoryUpdated(const QPlaceCategory &category, const QString &parentId) |
| void | dataChanged() |
| void | errorOccurred(QPlaceReply *reply, QPlaceReply::Error error, const QString &errorString = QString()) |
| void | finished(QPlaceReply *reply) |
| void | placeAdded(const QString &placeId) |
| void | placeRemoved(const QString &placeId) |
| void | placeUpdated(const QString &placeId) |
Descripción detallada
La siguiente tabla ofrece una visión general de las funcionalidades que ofrece QPlaceManager
| Funcionalidades | Descripción |
|---|---|
| Búsqueda de lugares | Mediante un conjunto de parámetros, como un término de búsqueda y un área de búsqueda, se pueden mostrar al usuario los lugares relevantes. |
| Categorías | Los lugares se pueden clasificar en diferentes categorías. El gestor permite acceder a estas categorías. |
| Sugerencias de términos de búsqueda | A partir de un término de búsqueda parcialmente completado, se puede ofrecer una lista de posibles términos de búsqueda. |
| Recomendaciones | A partir de un lugar existente, se puede sugerir al usuario un conjunto de lugares similares recomendados. |
| Contenido enriquecido | Se puede recuperar contenido enriquecido, como imágenes, reseñas, etc., en formato paginado. |
| Gestión de lugares o categorías | Los lugares y las categorías se pueden guardar y eliminar. Es posible recibir notificaciones cuando esto ocurra. |
| Localización | Se pueden especificar diferentes configuraciones regionales para mostrar los datos de los lugares en distintos idiomas. |
Obtención de una instancia de QPlaceManager
La creación de un `QPlaceManager` se simplifica mediante el método ` QGeoServiceProvider`. Consulte «Inicialización de un gestor» para ver un ejemplo de cómo crear un gestor.
Interfaz asíncrona
La clase `QPlaceManager` proporciona una abstracción del almacén de datos que contiene información sobre los lugares. Las funciones que ofrece el `QPlaceManager` son principalmente asíncronas y siguen un modelo de solicitud-respuesta. Normalmente, se envía una solicitud al gestor, compuesta por un conjunto de parámetros, y se crea un objeto de respuesta. El objeto de respuesta dispone de una señal para notificar cuándo se ha completado la solicitud y, una vez completada, la respuesta contiene los resultados de la solicitud, junto con los errores que se hayan producido, si los hubiera.
Una solicitud asíncrona se gestiona generalmente de la siguiente manera:
//1) Realizar la solicitud correspondiente
QPlaceSearchRequest searchRequest;
searchRequest.setSearchTerm("helado");
searchRequest.setSearchArea(QGeoCircle(QGeoCoordinate(12,34 ; 56,78)));
//2) Utilizar el gestor para iniciar una solicitud y recuperar un objeto de respuesta
QPlaceSearchReply* searchReply = manager->search(searchRequest);
//3) Conecta el objeto de respuesta a una ranura que se invoca al finalizar la operación
connect(searchReply, &QPlaceSearchReply::finished,
this, &RequestHandler::processSearchReply);
...
...
//4) Hacer que la ranura procese adecuadamente los resultados de la operación
void processSearchReply() {
if (searchReply->error()== QPlaceReply::NoError) {
for (const QPlaceSearchResult&result: searchReply->results()) {
if (result.type()== QPlaceSearchResult::PlaceResult)
qDebug() << "Title:" << result.title();
}
}
//5) Deshacerse del objeto «rely» cuando haya terminado.
searchReply->deleteLater();
searchReply = nullptr;
}Consulta «Operaciones comunes » para ver una lista de ejemplos que muestran cómo se utiliza QPlaceManager.
Inicialización de la categoría
En algún momento durante el inicio de una aplicación, se debe llamar a la función initializeCategories() para configurar las categorías. La inicialización de las categorías permite el uso de las siguientes funciones:
- QPlaceManager::childCategories()
- QPlaceManager::category()
- QPlaceManager::parentCategoryId()
- QPlaceManager::childCategoryIds();
Si es necesario actualizar o volver a cargar las categorías, se puede volver a llamar a la función initializeCategories().
Documentación de las funciones miembro
[virtual noexcept] QPlaceManager::~QPlaceManager()
Destruye el gestor. Este destructor lo utiliza internamente QGeoServiceProvider y nunca debería ser necesario llamarlo en el código de la aplicación.
QPlaceCategory QPlaceManager::category(const QString &categoryId) const
Devuelve la categoría correspondiente al categoryId indicado.
[signal] void QPlaceManager::categoryAdded(const QPlaceCategory &category, const QString &parentId)
Esta señal se emite si se ha añadido un ` category ` al almacén de datos del gestor. El elemento padre del ` category ` se especifica mediante ` parentId`.
Esta señal solo la emiten los gestores que admiten la característica QPlaceManager::NotificationsFeature.
Véase también dataChanged().
[signal] void QPlaceManager::categoryRemoved(const QString &categoryId, const QString &parentId)
Esta señal se emite cuando la categoría correspondiente a categoryId se ha eliminado del almacén de datos del gestor. La categoría principal de la categoría eliminada se especifica mediante parentId.
Esta señal solo la emiten los gestores que admiten la característica QPlaceManager::NotificationsFeature.
Véase también dataChanged().
[signal] void QPlaceManager::categoryUpdated(const QPlaceCategory &category, const QString &parentId)
Esta señal se emite si se ha modificado una categoría ( category ) en el almacén de datos del gestor. La categoría principal de la categoría modificada se especifica mediante ` parentId`.
Esta señal solo la emiten los gestores que admiten la función QPlaceManager::NotificationsFeature.
Véase también dataChanged().
QList<QPlaceCategory> QPlaceManager::childCategories(const QString &parentId = QString()) const
Devuelve una lista de las categorías que son subordinadas de la categoría correspondiente a parentId. Si parentId está vacío, se devuelven todas las categorías de primer nivel.
QStringList QPlaceManager::childCategoryIds(const QString &parentId = QString()) const
Devuelve los identificadores de las categorías secundarias de la categoría correspondiente a parentId. Si parentId está vacío, se devuelven todos los identificadores de las categorías de primer nivel.
QPlace QPlaceManager::compatiblePlace(const QPlace &original) const
Devuelve una versión recortada o modificada del lugar original que es apta para guardarse en este gestor.
En la versión modificada solo figuran los detalles del lugar que son compatibles con este gestor. Los datos específicos del gestor, como el identificador del lugar, no se copian desde original.
[signal] void QPlaceManager::dataChanged()
El gestor emite esta señal cuando se producen cambios a gran escala en su almacén de datos subyacente y considera que dichos cambios son lo suficientemente radicales como para que los clientes tengan que volver a cargar todos los datos.
Si se emite esta señal, no se emitirán otras señales para los cambios asociados.
Esta señal solo la emiten los gestores que admiten la función QPlaceManager::NotificationsFeature.
[signal] void QPlaceManager::errorOccurred(QPlaceReply *reply, QPlaceReply::Error error, const QString &errorString = QString())
Esta señal se emite cuando se ha detectado un error en el procesamiento de reply. Probablemente se emitirá a continuación la señal QPlaceManager::finished().
El error se describirá mediante el código de error error. Si errorString no está vacío, contendrá una descripción textual del error destinada a los desarrolladores y no a los usuarios finales.
Esta señal y QPlaceReply::errorOccurred() se emitirán al mismo tiempo.
Nota: No elimines el objeto ` reply ` en la ranura conectada a esta señal. Utiliza ` deleteLater()` en su lugar.
[signal] void QPlaceManager::finished(QPlaceReply *reply)
Esta señal se emite cuando « reply » ha finalizado el procesamiento.
Si reply->error() es igual a QPlaceReply::NoError, el procesamiento ha finalizado correctamente.
Esta señal y QPlaceReply::finished() se emitirán al mismo tiempo.
Nota: No elimines el objeto ` reply ` en la ranura conectada a esta señal. Utiliza en su lugar ` deleteLater()`.
QPlaceContentReply *QPlaceManager::getPlaceContent(const QPlaceContentRequest &request) const
Recupera contenido sobre un lugar según los parámetros especificados en request.
Consulta «Obtención de contenido enriquecido » para ver un ejemplo de uso.
QPlaceDetailsReply *QPlaceManager::getPlaceDetails(const QString &placeId) const
Recupera los detalles de un lugar correspondiente a la dirección placeId indicada.
Consulta «Obtención de detalles de un lugar » para ver un ejemplo de uso.
QPlaceReply *QPlaceManager::initializeCategories()
Inicializa las categorías del gestor.
Consulta «Uso de categorías » para ver un ejemplo de uso.
QList<QLocale> QPlaceManager::locales() const
Devuelve una lista de configuraciones regionales preferidas. Estas configuraciones regionales sirven de indicación al gestor sobre el idioma en el que deben mostrarse los detalles de lugar y categoría.
Si no es posible adaptarse a la primera configuración regional especificada, el gestor recurre a la siguiente y así sucesivamente. Es posible que algunos backends del gestor no admitan un conjunto de configuraciones regionales definidas de forma rígida. Un ejemplo arbitrario es que algunos lugares de Francia podrían tener localizaciones en francés e inglés, mientras que en ciertas zonas de Estados Unidos solo podría estar disponible la localización en inglés. En este ejemplo, el conjunto de configuraciones regionales admitidas depende del contexto de la ubicación de la búsqueda.
Si el gestor no puede adaptarse a ninguna de las configuraciones regionales preferidas, recurre a un idioma compatible específico del backend.
La compatibilidad con las configuraciones regionales puede variar de un proveedor a otro. En el caso de los que sí las admiten, por defecto, la configuración regional global predeterminada se establece como la única configuración regional del gestor.
En el caso de los gestores que no admiten configuraciones regionales, la lista de configuraciones regionales siempre está vacía.
Véase también setLocales().
QString QPlaceManager::managerName() const
Devuelve el nombre del gestor
int QPlaceManager::managerVersion() const
Devuelve la versión del gestor.
QPlaceMatchReply *QPlaceManager::matchingPlaces(const QPlaceMatchRequest &request) const
Devuelve una respuesta que contiene una lista de lugares que se corresponden o coinciden con los especificados en request. Los lugares especificados en la solicitud proceden de otro gestor.
QString QPlaceManager::parentCategoryId(const QString &categoryId) const
Devuelve el identificador de la categoría principal de la categoría correspondiente a categoryId.
[signal] void QPlaceManager::placeAdded(const QString &placeId)
Esta señal se emite cuando se ha añadido un lugar al almacén de datos del motor de gestión. El lugar concreto que se ha añadido se especifica mediante ` placeId`.
Esta señal solo la emiten los gestores que admiten la característica QPlaceManager::NotificationsFeature.
Véase también ` dataChanged()`.
[signal] void QPlaceManager::placeRemoved(const QString &placeId)
Esta señal se emite si se ha eliminado un lugar del almacén de datos del gestor. El lugar concreto que se ha eliminado se especifica mediante ` placeId`.
Esta señal solo la emiten los gestores que admiten la función QPlaceManager::NotificationsFeature.
Véase también dataChanged().
[signal] void QPlaceManager::placeUpdated(const QString &placeId)
Esta señal se emite si se ha modificado un lugar en el almacén de datos del gestor. El lugar concreto que se ha modificado se especifica mediante ` placeId`.
Esta señal solo la emiten los gestores que admiten la función QPlaceManager::NotificationsFeature.
Véase también dataChanged().
QPlaceIdReply *QPlaceManager::removeCategory(const QString &categoryId)
Elimina del gestor la categoría correspondiente a « categoryId ».
Consulta «Eliminar una categoría » para ver un ejemplo de uso.
QPlaceIdReply *QPlaceManager::removePlace(const QString &placeId)
Elimina del gestor el lugar correspondiente a placeId.
Consulta «Eliminar un lugar cpp» para ver un ejemplo de uso.
QPlaceIdReply *QPlaceManager::saveCategory(const QPlaceCategory &category, const QString &parentId = QString())
Guarda una categoría « category » que es una subcategoría de la categoría especificada en « parentId ». Si « parentId » está vacío, significa que « category » se guarda como categoría de primer nivel.
Consulta «Guardar una categoría » para ver un ejemplo de uso.
QPlaceIdReply *QPlaceManager::savePlace(const QPlace &place)
Guarda un ` place` especificado.
Consulta «Guardar un lugar cpp» para ver un ejemplo de uso.
QPlaceSearchReply *QPlaceManager::search(const QPlaceSearchRequest &request) const
Busca lugares según los parámetros especificados en request.
Consulta la sección «Descubrimiento/Búsqueda» para ver un ejemplo de uso.
QPlaceSearchSuggestionReply *QPlaceManager::searchSuggestions(const QPlaceSearchRequest &request) const
Solicita un conjunto de sugerencias de términos de búsqueda según los parámetros especificados en request. El objeto ` request ` puede contener el término de búsqueda incompleto, junto con otros datos, como un área de búsqueda, para acotar los resultados relevantes.
Consulta «Sugerencias de búsqueda » para ver un ejemplo de uso.
void QPlaceManager::setLocale(const QLocale &locale)
Función práctica que establece la lista de configuraciones regionales preferidas del administrador en una única: locale.
void QPlaceManager::setLocales(const QList<QLocale> &locales)
Configura la lista de sitios preferidos en locales.
Véase también locales().
© 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.