API QML Places

Vue d'ensemble

L'API Lieux permet aux utilisateurs de découvrir des lieux d'intérêt et d'en afficher les détails, tels que l'adresse et les coordonnées. Certains lieux peuvent être associés à un contenu supplémentaire, tel que des images et des commentaires. L'API Lieux vous permet également de gérer les lieux et les catégories, en les enregistrant et en les supprimant. Les lieux peuvent également inclure des chemins, des routes ou des moyens de transport, ce qui permet d'optimiser la navigation et de fournir une assistance. Pour plus d'informations sur la navigation, voir routes.

Concepts d'introduction

Plugin

Un Plugin est une abstraction pour un backend. Un Plugin peut accéder à des lieux à partir d'un serveur REST, tandis qu'un autre peut accéder à des lieux à partir d'une base de données locale. Ce qui suit instancie un objet Plugin en lui donnant le nom "osm". Le nom Plugin identifie le backend à choisir. Les plugins peuvent également être dotés d'un ensemble de parameters, qui prend essentiellement la forme d'un ensemble de paires clé-valeur. Les parameters qui peuvent être spécifiés varient selon les différents backends Plugin. Pour obtenir de la documentation sur les parameters possibles et les nuances de chaque Plugin, voir les références des plugins.

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

Modèles, vues et délégués

L'API QML Places s'articule autour de la notion de modèles, de vues et de délégués.

La section Cas d'utilisation courante ci-dessous présente des exemples concrets de la manière dont ces concepts s'articulent.

Cas d'utilisation courants

Recherche de lieux

La recherche s'effectue par l'intermédiaire de la propriété PlaceSearchModel. La propriété plugin spécifie le backend avec lequel les opérations de recherche doivent être effectuées. Les paramètres de recherche peuvent être fournis par des propriétés telles que searchTerm et searchArea. Une opération de recherche peut alors être lancée en invoquant la méthode update(). Par souci de simplicité, l'extrait ci-dessous invoque la méthode update() une fois la construction du modèle achevée ; en règle générale, la méthode update() serait invoquée en réponse à une action de l'utilisateur telle qu'un clic sur un bouton. Pendant l'opération de recherche, la propriété PlaceSearchModel::status passe à l'état Loading et, une fois la recherche terminée, à l'état Ready.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "food"
    searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

    Component.onCompleted: update()

}

Affichage des résultats de la recherche à l'aide d'une liste déroulante

Une page ListView peut être utilisée pour afficher les résultats de la recherche trouvés par le modèle. Il définit la région visuelle dans laquelle les résultats sont affichés et, dans le cas ci-dessous, il remplit la totalité de son parent. Le site ListView a un comportement intégré qui permet à la région de répondre aux événements de défilement et de défiler de manière appropriée.

Dans l'extrait ci-dessous, le modèle de recherche a été affecté à la propriété model de ListView. Lorsque le modèle est mis à jour avec de nouveaux résultats, le site ListView est automatiquement mis à jour pour refléter les nouveaux éléments de données du modèle.

Un simple délégué a été lié à la propriété ListView's delegate. Le site PlaceSearchModel expose un ensemble de roles dont les rôles title et place ont été utilisés ci-dessous, ceux-ci étant respectivement de type string et Place. Essentiellement, pour chaque élément de données qui doit être visible dans la vue, la vue invoque le délégué pour créer une représentation visuelle de l'élément.

ListView { anchors.fill: parent model: searchModel delegate: Component { Row { spacing: 5 Marker { height: parent.height } Column { Text { text: title; font.bold: true } Text { text: place.location.address.text } } } } }

Voir l'exemple de la liste des lieux pour le code source complet.

Affichage des résultats de recherche à l'aide d'un MapItemView

Au lieu d'un ListView, le PlaceSearchModel peut être utilisé en conjonction avec un MapItemView pour afficher des marqueurs sur une carte. Tout d'abord, un Map est utilisé pour définir la région visuelle occupée par la carte, dans ce cas, elle remplit l'intégralité de son parent. D'autres propriétés sont spécifiées, telles que le site plugin qui fournit les cartes et les sites center et zoomLevel de la carte.

À l'intérieur du site Map, un site MapItemView est déclaré, dont la propriété model a été définie comme étant le modèle de recherche, et un site delegate composé d'un site MapQuickItem est utilisé pour afficher l'image d'un marqueur. Un marqueur est affiché pour chaque lieu trouvé par le modèle de recherche. Le délégué utilise le rôle place pour positionner le marqueur.

MapView { id: view anchors.fill: parent map.plugin: myPlugin; map.center: positionSource.lastSearchPosition map.zoomLevel: 13 MapItemView { model: searchModel parent: view.map delegate: MapQuickItem { coordinate: place.location.coordinate anchorPoint.x: image.width * 0.5 anchorPoint.y: image.height sourceItem: Column { Image { id: image; source: "marker.png" } Text { text: title; font.bold: true } } } } }

Voir l'exemple de la carte des lieux pour le code source complet.

Récupération des détails d'un lieu

Afin d'économiser de la bande passante, il arrive qu'un backend ne renvoie que les lieux dont les détails sont partiellement renseignés. Ceci peut être vérifié avec la propriété Place::detailsFetched qui indique si tous les détails disponibles ont été récupérés ou non. Si ce n'est pas le cas, la méthode Place::getDetails() peut être invoquée pour récupérer les détails restants.

if (!place.detailsFetched)
    place.getDetails();

Sauvegarde et suppression de lieux

Certains backends peuvent prendre en charge l'enregistrement et la suppression de lieux. Pour ce faire, il suffit d'appeler les méthodes Place::save() et Place::remove() respectivement. Notez que pour sauvegarder un Place, un Plugin doit être attribué pour spécifier le backend dans lequel nous sauvegardons. La propriété status passera à l'état Saving pendant que l'opération de sauvegarde se déroule et, une fois l'opération terminée, passera à l'état Ready. L'extrait suivant montre comment sauvegarder et supprimer un lieu à l'aide de javascript.

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

En savoir plus

Les extraits ci-dessus ne présentent qu'un petit sous-ensemble des fonctionnalités de Places. Reportez-vous aux types de lieux présentés ci-dessous pour un contenu plus riche tel que images, reviews etc, ainsi que pour des descriptions et des explications plus approfondies.

Voir également l'exemple Places (QML) pour une démonstration plus complète de l'utilisation de l'API.

Types de lieux

Types de données

Modèles