Place QML Type

El tipo Lugar representa una ubicación que es una posición de interés. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

Métodos

• void copyFrom(Place original)
• string errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Descripción detallada

El tipo Lugar representa una ubicación física con metadatos adicionales que describen dicha ubicación. Contrasta con Location, Address, y el tipo de coordenadas, que se utilizan para describir dónde se encuentra una ubicación. Las propiedades básicas de un lugar son name y location.

Los objetos Lugar suelen obtenerse a partir de un modelo de búsqueda y, por lo general, sólo tendrán definidas sus propiedades básicas. La propiedad detailsFetched se puede utilizar para comprobar si es necesario obtener más valores de propiedades de Plugin. Esto se puede hacer invocando el método getDetails(). El progreso de la operación de obtención se puede monitorizar con la propiedad status, que se establecerá como Place.Fetching cuando se estén obteniendo los detalles.

El tipo Place tiene muchas propiedades que contienen información sobre la ubicación. Los detalles sobre cómo contactar con el lugar están disponibles en la propiedad contactDetails. También se dispone de propiedades de conveniencia para obtener los datos primarios phone, fax, email y website.

A cada lugar se le asigna cero o más categories. Las categorías se utilizan normalmente cuando se busca un tipo concreto de lugar, como un restaurante o un hotel. Algunos lugares tienen un objeto ratings, que da una indicación de la calidad del lugar.

Los metadatos de los lugares los proporciona un supplier, que puede requerir que se muestre un mensaje attribution al usuario cuando se consultan los detalles del lugar.

Los lugares tienen un icon asociado que puede utilizarse para representar un lugar en un mapa o para decorar un delegado en una vista.

Los lugares pueden tener asociados contenidos enriquecidos adicionales. Los contenidos enriquecidos actualmente soportados incluyen descripciones editoriales, reseñas e imágenes. Estos se exponen como un conjunto de modelos para recuperar el contenido. Las descripciones editoriales del lugar están disponibles en la propiedad editorialModel. Las reseñas del lugar están disponibles en la propiedad reviewModel. Se puede acceder a una galería de fotos del lugar utilizando la propiedad imageModel.

Los lugares pueden tener atributos adicionales que no están cubiertos por la API formal. La propiedad extendedAttributes permite acceder a ellos. El tipo de atributos extendidos disponibles es específico de cada Plugin.

Un lugar casi siempre está vinculado a plugin. La propiedad plugin debe estar establecida antes de que sea posible llamar a save(), remove() o getDetails(). Las propiedades reviewModel, imageModel y editorialModel sólo son válidas si está activada la propiedad plugin.

Guardar un lugar

Si Plugin lo admite, el tipo Place puede utilizarse para guardar un lugar. En primer lugar, cree un nuevo lugar y defina sus propiedades:

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

Luego invoque el método save():

    myPlace.save();

La propiedad status cambiará a Place.Saving y luego a Place.Ready si el guardado fue exitoso o a Place.Error si ocurre un error.

Si la propiedad placeId está establecida, el backend actualizará un lugar existente, de lo contrario creará un nuevo lugar. En caso de éxito, la propiedad placeId se actualizará con el identificador del nuevo lugar guardado.

Advertencias

La API de Lugares está diseñada actualmente para guardar sólo los 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. Normalmente, un gestor ignorará estos campos al guardarlos y puede mostrar un mensaje de advertencia si se rellenan.

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

• nombre
• Id. del lugar
• ubicación
• 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 estas opciones. Consulte la documentación del complemento para obtener más información.

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

Guardar entre plugins

Al guardar lugares entre plugins, 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 plugin. Por ejemplo, las categorías en un gestor pueden no ser reconocidas en otro. Por lo tanto, intentar guardar un lugar directamente de un plugin a otro no es posible.

Por lo general, se recomienda que guardar entre plugins se gestione como guardar favorites tal y como se explica en la sección Favoritos. Sin embargo, existe otro método que consiste en crear un nuevo lugar, establecer su plugin (de destino) y, a continuación, utilizar el método copyFrom() para copiar los detalles del lugar original. Utilizando copyFrom() sólo se copian los datos soportados por el plugin de destino, los datos específicos del plugin como el identificador del lugar no se copian. Una vez realizada la copia, el lugar se encuentra en un estado adecuado para ser guardado.

El siguiente fragmento proporciona un ejemplo de cómo guardar un lugar en un plugin diferente utilizando el método copyFrom:

var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Eliminar un lugar

Para eliminar un lugar, asegúrate de que existe un objeto Place con una propiedad placeId válida y llama a su método remove(). La propiedad status cambiará a Place.Removing y luego a Place.Ready si el guardado fue exitoso o a Place.Error si ocurre un error.

Favoritos

La API de Lugares soporta el concepto de favoritos. Los favoritos se implementan generalmente utilizando dos plugins, el primer plugin es típicamente una fuente de lugares de sólo lectura (plugin de origen) y un segundo plugin de lectura/escritura (plugin de destino) se utiliza para almacenar lugares desde el origen como favoritos.

Cada lugar tiene una propiedad favorita que contiene el lugar correspondiente del plugin de destino (el lugar en sí proviene del plugin de origen). Dado que tanto el lugar original como las instancias favoritas están disponibles, el desarrollador puede elegir qué propiedades mostrar al usuario. Por ejemplo, el favorito puede tener un nombre modificado que debería mostrarse en lugar del nombre original.

Text { text: place.favorite ? place.favorite.name : place.name }

A continuación se muestra cómo guardar un nuevo favorito. Se realiza una llamada para crear/inicializar la instancia de favorito y, a continuación, se guarda la instancia.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

A continuación se muestra cómo eliminar un favorito:

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

PlaceSearchModel tiene una propiedad favoritesPlugin. Si la propiedad está activada, cualquier lugar encontrado durante una búsqueda se comprueba con el favoritesPlugin para ver si hay un lugar favorito correspondiente. Si es así, se establece la propiedad favorite del Lugar, de lo contrario la propiedad favorite se mantiene nula.

Véase también PlaceSearchModel.

Documentación de propiedades

attribution : string

Esta propiedad contiene una cadena de atribución de texto enriquecido para el lugar. Algunos proveedores pueden requerir que la atribución se muestre al usuario siempre que se muestre un lugar. El contenido de esta propiedad debe mostrarse al usuario si no está vacía.

categories : list<Category> [read-only]

Esta propiedad contiene la lista de categorías a las que pertenece este lugar. Las categorías que pueden asignarse a un lugar son específicas de cada plugin.

contactDetails : ContactDetails [read-only]

Esta propiedad contiene la información de contacto de este lugar, por ejemplo un número de teléfono o la URL de un sitio web. Esta propiedad es un mapa de objetos contactDetail.

detailsFetched : bool [read-only]

Esta propiedad indica si se han obtenido los detalles del lugar. Si esta propiedad es falsa, los detalles del lugar aún no se han obtenido. La obtención puede realizarse invocando al método getDetails().

Véase también getDetails().

editorialModel : EditorialModel [read-only]

Esta propiedad contiene un modelo que puede utilizarse para recuperar descripciones editoriales del lugar.

extendedAttributes : ExtendedAttributes [read-only]

Esta propiedad contiene los atributos extendidos de un lugar. Los atributos extendidos son información adicional sobre un lugar no cubierta por las propiedades del lugar.

favorite : Place

Esta propiedad contiene la instancia favorita de un lugar.

icon : Icon

Esta propiedad contiene un icono gráfico que puede utilizarse para representar el lugar.

imageModel : ImageModel [read-only]

Esta propiedad contiene un modelo que puede utilizarse para recuperar imágenes del lugar.

location : QtPositioning::Location

Esta propiedad contiene la ubicación del lugar que se puede utilizar para recuperar la coordenada, la dirección y el cuadro delimitador.

name : string

Esta propiedad contiene el nombre del lugar que puede utilizarse para representarlo.

placeId : string

Esta propiedad contiene el identificador único del lugar. El identificador de lugar sólo es significativo para el Plugin que lo generó y no es transferible entre Plugins. No se garantiza que el identificador de lugar sea universalmente único, sino único dentro del Plugin que lo generó.

Si sólo se conoce el identificador de lugar, todos los demás datos de lugar pueden obtenerse de Plugin.

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

plugin : Plugin

Esta propiedad contiene el Plugin que proporcionó este lugar que se puede utilizar para recuperar más información sobre el servicio.

primaryEmail : string [read-only]

Esta propiedad contiene la dirección de correo electrónico principal del lugar. Si no se ha definido ningún contacto "email" para este lugar, esta propiedad será una cadena vacía. Equivale a

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

primaryFax : string [read-only]

Esta propiedad contiene el número de fax principal del lugar. Si no se ha definido ningún contacto "fax" para este lugar, esta propiedad será una cadena vacía. Equivale a

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

primaryPhone : string [read-only]

Esta propiedad contiene el número de teléfono principal del lugar. Si no se ha definido ningún detalle de contacto "teléfono" para este lugar, esta propiedad será una cadena vacía. Es equivalente a:

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

primaryWebsite : string [read-only]

Esta propiedad contiene la URL del sitio web principal del lugar. Si no se ha definido ningún contacto "web" para este lugar, esta propiedad será una cadena vacía. Equivale a

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

ratings : Ratings

Esta propiedad contiene valoraciones del lugar. Las valoraciones proporcionan una indicación de la calidad de un lugar.

reviewModel : ReviewModel [read-only]

Esta propiedad contiene un modelo que se puede utilizar para recuperar reseñas sobre el lugar.

status : enumeration [read-only]

Esta propiedad mantiene el estatus del lugar. Puede ser uno de los siguientes

El estado de un lugar se puede comprobar conectando la propiedad de estado a una función manejadora, y luego hacer que la función manejadora procese el cambio de estado.

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

supplier : Supplier

Esta propiedad contiene el proveedor de los datos del lugar. El proveedor suele ser una empresa u organización que recopiló los datos sobre el lugar.

visibility : enumeration

Esta propiedad tiene la visibilidad del lugar. Puede ser una de las siguientes:

Ten en cuenta que la visibilidad no afecta a cómo se muestra el lugar en la interfaz de usuario de una aplicación en el dispositivo. En su lugar, define la semántica de uso compartido del lugar.

Documentación del método

void copyFrom(Place original)

Copia los datos de un lugar original en este lugar. Sólo se copian los datos compatibles con el plugin de este lugar y no se copian los datos específicos del plugin, como el identificador del lugar.

string errorString()

Devuelve una cadena descriptiva del error de la última operación. Si la última operación se completó correctamente, la cadena estará vacía.

void getDetails()

Este método inicia la obtención de los detalles del lugar.

La propiedad status cambiará a Place.Fetching mientras se realiza la obtención. En caso de éxito, las propiedades del objeto se actualizarán, status se establecerá como Place.Ready y detailsFetched se establecerá como true. En caso de error, status tendrá el valor Place.Error. El método errorString() puede utilizarse para obtener los detalles del error.

void initializeFavorite(Plugin destinationPlugin)

Crea una instancia de favorito para el lugar que se va a guardar en el plugin de destino destinationPlugin. Este método no hace nada si la propiedad favorito no es null.

void remove()

Este método realiza una operación de eliminación en el lugar.

La propiedad status cambiará a Place.Removing mientras la operación de guardado esté en curso. Si la operación se realiza correctamente, status tendrá el valor Place.Ready. En caso de error status se establecerá como Place.Error. El método errorString() se puede utilizar para obtener los detalles del error.

void save()

Este método realiza una operación de guardado en el lugar.

La propiedad status cambiará a Place.Saving mientras la operación de guardado esté en curso. En caso de éxito, la propiedad status cambiará a Place.Ready. En caso de error status se establecerá como Place.Error. El método errorString() puede utilizarse para obtener los detalles del error.

Si la propiedad placeId estaba vacía anteriormente, se le asignará un valor válido automáticamente durante una operación de guardado correcta.

Tenga en cuenta que un PlaceSearchModel llamará a Place::getDetails en cualquier lugar en el que detecte una actualización. Una consecuencia de esto es que cada vez que un lugar de PlaceSearchModel se guarda con éxito, será seguido por una obtención de los detalles del lugar, dando lugar a una secuencia de cambios de estado de Saving, Ready, Fetching, Ready.