Lugares (C++)

Visión general

La API de Lugares permite a los usuarios descubrir lugares/puntos de interés y ver detalles sobre ellos, como la dirección y la información de contacto; algunos lugares pueden tener incluso 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 ese lugar.

Esta información puede dividirse en dos grandes categorías

• Detalles
• Contenido rico

Los detalles del lugar consisten en propiedades del lugar, como el nombre, la ubicación, la información de contacto, etc. Cuando se devuelve un lugar durante una búsqueda, estos detalles se rellenan. A veces, para ahorrar ancho de banda, hay más detalles sobre el lugar que pueden recuperarse lugar por lugar, si el usuario está interesado. Se puede consultar la función QPlace::detailsFetched() para ver si se han obtenido todos los detalles disponibles y, si no es así, se puede utilizar QPlaceManager::getPlaceDetails() para recuperarlos. Los detalles que se rellenan durante una búsqueda y los que deben obtenerse individualmente pueden variar de un proveedor a otro. Para más información, consulte la documentación del complemento.

El contenido enriquecido de un lugar consiste en elementos como imágenes, reseñas y editoriales. Potencialmente puede haber muchos elementos de contenido enriquecido, por lo que se tratan por separado de los detalles del lugar. Pueden recuperarse de forma paginada a través de QPlaceManager::getPlaceContent(). Si es necesario, el contenido puede asignarse a un lugar para que actúe como un contenedor conveniente.

Operaciones comunes

Inicialización de un gestor

Toda la funcionalidad de los lugares se facilita mediante una instancia de QPlaceManager. Es necesario especificar un QGeoServiceProvider para crear la instancia 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 QPlaceSearchRequest y establecer los parámetros de búsqueda deseados, como un término de búsqueda y un 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 petición es una operación asíncrona por lo que necesitamos un slot para manejar la finalización de la petición. En el manejador comprobamos que no hay errores y que nuestro tipo de resultado de búsqueda es un lugar. Si es así, podemos recuperar algunos de los detalles básicos del lugar. Al final de la ranura, borramos la respuesta, ya que son de un solo uso.

void handleSearchReply() { if (searchReply->error() == QPlaceReply::NoError) { for(const QPlaceSearchResult &result:  searchReply->results()) { if (result.type() == QPlaceSearchResult::LugarResultado) { QPlaceResult placeResult = resultado;                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(); //descarta la respuestasearchReply = nullptr; }

Nota: Dependiendo del plugin backend elegido, los resultados de la búsqueda pueden contener lugares con más detalles que pueden ser obtenidos lugar por lugar. Para obtener estos detalles, consulte Obtener detalles de un lugar.

Recomendaciones

Las recomendaciones pueden obtenerse proporcionando un identificador de lugar a través de QPlaceSearchRequest::setRecommendationId(). Se recuperan todos los lugares similares al lugar indicado.

Paginación

Si el complemento admite la paginación, se puede proporcionar el parámetro limit a la petición de búsqueda.

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

Obtención de detalles de lugares

Un lugar que ha sido devuelto desde una petición de búsqueda puede tener más detalles que pueden ser obtenidos. A continuación se muestra cómo comprobar si existen 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 manejar la solicitud de contenido 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.valor();            qDebug() << image.url();
            qDebug() << image.mimeType();
        } //alternativa si los índices son irrelevantes for(const QPlaceImage &image:  contentReply->content()) {            qDebug() << image.url();
            qDebug() << image.mimeType();
        } //podemos asignar contenido al lugar al que pertenece. //el objeto place sirve como contenedor donde podemos recuperar //contenido que ya ha sido obtenidoplace.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 el QPlaceContentReply, es 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 el contenido es posible convertir un tipo de contenido de la siguiente manera

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

El uso de QPlaceContent::Collection y la conversión entre contenido y sus subtipos significa que el código para manejar la mecánica de paginación de reseñas, imágenes y editoriales puede compartirse fácilmente.

Sugerencias de búsqueda

La recuperación de sugerencias de términos de búsqueda es muy similar a la búsqueda de un 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 en 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 cuando se realiza la petición, 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 respuestasuggestionReply = nullptr; }

Guardar un lugar

El guardado de un nuevo lugar se realiza de la siguiente manera, creamos una instancia QPlace y la rellenamos con información como un nombre, dirección y coordenadas. Una vez hecho esto podemos invocar a QPlaceManager::savePlace() para comenzar una 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 ese lugar.

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

    savePlaceReply->deleteLater(); //descartar respuestasavePlaceReply = nullptr; }

Tenga en cuenta que para guardar un lugar ya existente, el QPlace::placeId() debe rellenarse con el identificador correcto. De lo contrario, se creará un nuevo lugar si está vacío o se sobrescribirá el lugar incorrecto si el identificador es incorrecto.

Cuando se guarda un lugar, el QPlaceManager puede emitir señales QPlaceManager::placedAdded() o QPlaceManager::placeUpdated(). Sin embargo el que un gestor lo haga o no es específico del proveedor, los gestores que acceden a lugares desde un servicio web normalmente no emitirán estas señales mientras que los gestores que acceden a lugares almacenados localmente generalmente sí lo harán.

Advertencias

La API de Lugares está diseñada actualmente sólo para guardar detalles de core. Guardar contenido enriquecido como imágenes y reseñas o detalles como proveedor y valoración no es un caso de uso soportado. Por lo general, un gestor ignorará estos campos al guardar y puede producir un mensaje de advertencia si se rellenan.

La API de Lugares sólo permite guardar los siguientes datos básicos:

• nombre
• id de lugar
• lugar
• datos de contacto
• icono
• categorías (nombres tipo etiqueta para describir un lugar)
• ámbito de visibilidad

Es posible que los proveedores sólo admitan un subconjunto de estos elementos. Consulte la documentación del complemento para obtener más información.

La API de Places no admite explícitamente el almacenamiento de propiedades como la calificación, los atributos ampliados, las imágenes, las reseñas, las editoriales y el proveedor.

Almacenamiento entre gestores

Al guardar lugares entre gestores, hay que tener en cuenta algunas cosas. Algunos campos de un lugar como el id, las categorías y los iconos son entidades específicas de un gestor, por ejemplo, las categorías de un gestor pueden no ser reconocidas en otro. Por lo tanto, no es posible guardar un lugar directamente de un gestor a otro.

El enfoque típico es utilizar la función QPlaceManager::compatiblePlace(), que crea una copia de un lugar, pero sólo 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 puede guardarse en el gestor. Si el gestor admite la correspondencia por 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);

Eliminar un lugar

La eliminación de un lugar se realiza del siguiente modo:

/* 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()<< "tuvo éxito";  removePlaceReply->deleteLater(); //descartar respuestaremovePlaceReply = nullptr; }

Cuando se elimina un lugar, el QPlaceManager puede emitir la señal QPlaceManager::placeRemoved(). El que un gestor lo haga es específico del proveedor. Los gestores que acceden a lugares desde un servicio web normalmente no emitirán estas señales, mientras que los gestores que acceden a lugares almacenados localmente generalmente sí lo harán.

Uso de categorías

Las categorías son palabras clave que pueden describir un lugar. Por ejemplo, 'parque', 'teatro', 'restaurante'. Un lugar puede ser descrito por muchas categorías, puede ser un parque y un local de música y un ferry o una parada 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";
   si no        qDebug() << "Failed to initialize categories";

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

Una vez inicializadas las categorías podemos utilizar estas funciones de categoría.

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

Para recuperar las categorías de nivel superior utilizamos la función QPlaceManager::childCategories() pero no proporcionamos un 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 hijos 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 category; category.setName("pizza");/*QPlaceIdReply */ saveCategoryReply =  manager->saveCategory(category); connect(saveCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSaveCategoryReply);//podríamos haber guardado una categoría como hijo proporcionando un identificador 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 gestor QPlaceManager puede emitir señales QPlaceManager::categoryAdded() o QPlaceManager::categoryUpdated(). Sin embargo el que un gestor lo haga o no es específico del proveedor, los gestores que acceden a lugares desde un servicio web normalmente no emitirán estas señales mientras que los gestores que acceden a lugares almacenados localmente generalmente sí lo harán.

Eliminar 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()<< "tuvo éxito";  removeCategoryReply->deleteLater(); //descartar respuestaremoveCategoryReply = nullptr; }

Cuando se elimina una categoría, el QPlaceManager puede emitir la señal QPlaceManager::categoryRemoved(). El que un gestor lo haga es específico del proveedor. Los gestores que acceden a lugares desde un servicio web normalmente no emitirán estas señales, mientras que los gestores que acceden a lugares almacenados localmente generalmente sí lo harán.

Correspondencia de lugares entre gestores

A veces es posible que desees comprobar si los lugares de un gestor coinciden con los de otro. Una situación de este tipo puede darse cuando un gestor proporciona acceso de sólo lectura a lugares (gestor de origen) mientras que otro segundo gestor r/w (gestor de destino) se utiliza para guardar favoritos seleccionados del primero. Durante una búsqueda en el gestor de origen podemos querer saber cuáles han sido 'favoritos' en el gestor de destino y quizás mostrar un nombre de favorito personalizado en lugar del nombre original.

El mecanismo de emparejamiento puede variar entre gestores, pero normalmente se realiza a través de 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 identificador de lugar). En el siguiente ejemplo, el gestor de origen es de la 'aquí' QGeoServiceProider, por lo tanto, como parte del proceso de ahorro de un atributo identificador alternativo, x_id_aquí, se establece para el lugar guardado en el gestor de destino (cuando QPlaceManager::compatiblePlace() se llama)

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

Para realizar el cotejo, 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 correspondencia, que son pares clave-valor. Como se mencionó anteriormente, esto puede variar dependiendo del gestor, pero por lo general la clave es QPlaceMatchRequest::AlternativeId para indicar que estamos coincidiendo por id alternativo, el valor en este caso sería x_id_here que especifica qué atributo de identificador alternativo estamos utilizando para hacer la coincidencia.

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();
           si no                qDebug() << "Place is not a favorite";
        } }  matchReply->deleteLater(); matchReply = nullptr; }

Clases en Lugares

Clases de Datos

Clases de solicitud

Clases de respuesta

Clases de Gestores