API QML « Places »

Présentation

L'API « Lieux » permet aux utilisateurs de découvrir des lieux d'intérêt et d'afficher des informations détaillées à leur sujet, telles que l'adresse et les coordonnées. Certains lieux peuvent être associés à du contenu supplémentaire, comme des images et des avis. L’API « Lieux » vous permet également de gérer les lieux et les catégories, en vous offrant la possibilité de les enregistrer et de les supprimer. Les lieux peuvent également inclure des itinéraires, 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, consultez routes.

Concepts d’introduction

Plugin

Un « Plugin » est une abstraction d’un backend. Un « Plugin » peut accéder aux lieux à partir d’un serveur REST tandis qu’un autre peut y accéder à partir d’une base de données locale. L’exemple suivant instancie un objet « Plugin » en lui attribuant le nom « osm ». Le nom « Plugin » identifie le backend à sélectionner. Les plugins peuvent également être fournis avec un ensemble de paramètres de configuration ( parameters), qui se présente essentiellement sous la forme d'un ensemble de paires clé-valeur. Les paramètres de configuration ( parameters ) pouvant être spécifiés varient selon les différents backends Plugin. Pour obtenir de la documentation sur les paramètres de configuration ( parameters ) possibles et les nuances de chaque Plugin, consultez 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 des notions de modèles, de vues et de délégués.

La section « Cas d’utilisation courants » ci-dessous présente des exemples concrets illustrant comment ces concepts s’articulent entre eux.

Cas d’utilisation courants

Recherche de lieux

La recherche s’effectue via l’interface PlaceSearchModel. La propriété plugin spécifie le backend sur lequel effectuer les opérations de recherche. Les paramètres de recherche peuvent être fournis via des propriétés telles que searchTerm et searchArea. Une opération de recherche peut alors être lancée en appelant la méthode update(). Par souci de simplicité, l’extrait de code ci-dessous appelle ` update()` une fois la construction du modèle terminée ; en règle générale, ` update()` serait appelé en réponse à une action de l’utilisateur, telle qu’un clic sur un bouton. Pendant que l’opération de recherche est en cours, la propriété ` PlaceSearchModel::status ` passe à l’état ` Loading ` et, une fois l’opération terminée avec succès, passe à l’état ` Ready `.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

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

    Component.onCompleted: update()

}

Afficher les résultats de la recherche à l’aide d’un ListView

Un ListView peut être utilisé pour afficher les résultats de recherche trouvés par le modèle. Il définit la zone visuelle dans laquelle les résultats s’affichent et, dans l’exemple ci-dessous, occupe la totalité de son élément parent. Le ListView dispose d’un comportement intégré qui permet à cette zone de réagir aux événements de balayage et de défiler de manière appropriée.

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

Un délégué simple a été lié à la propriété ` delegate ` de l’ ListView. L’ PlaceSearchModel expose un ensemble d’ roles, dont les rôles « title » et « place » ont été utilisés ci-dessous ; ceux-ci sont respectivement de type chaîne de caractères et Place. Concrètement, pour chaque élément de données devant être visible dans la vue, celle-ci invoque le délégué afin de 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 } } } } }

Consultez l’exemple « Liste des lieux » pour obtenir le code source complet.

Affichage des résultats de recherche à l’aide d’une MapItemView

Au lieu d’un ` ListView`, le ` PlaceSearchModel ` peut être utilisé conjointement avec un ` MapItemView ` pour afficher des marqueurs sur une carte. Tout d’abord, un ` Map ` est utilisé pour définir la zone visuelle occupée par la carte ; dans ce cas, il occupe l’intégralité de son élément parent. D’autres propriétés sont spécifiées, telles que l’ plugin fournissant les cartes, ainsi que les propriétés ` center ` et ` zoomLevel` de la carte.

À l’intérieur de l’ Map, un MapItemView est déclaré, dont la propriété model a été définie sur le modèle de recherche, et un delegate composé d’un MapQuickItem est utilisé pour afficher une image de 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 } } } } }

Consultez l’exemple « Places Map » pour obtenir le code source complet.

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

Afin d’économiser de la bande passante, il arrive parfois qu’un backend ne renvoie que des lieux dont les détails ne sont que partiellement renseignés. Cela peut être vérifié à l’aide de 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 appelée pour récupérer les détails restants.

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

Enregistrement et suppression de lieux

Certains backends peuvent prendre en charge l’enregistrement et la suppression de lieux. Cela peut être effectué en appelant respectivement les méthodes ` Place::save()` et ` Place::remove()`. Notez que pour enregistrer un « Place », il faut lui attribuer un « Plugin » afin de spécifier le backend dans lequel l’enregistrement doit s’effectuer. La propriété « status » passera à l’état « Saving » pendant l’opération d’enregistrement, puis à l’état « Ready » une fois celle-ci terminée avec succès. L’extrait de code suivant montre comment enregistrer 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 de code ci-dessus ne présentent qu’une petite partie des fonctionnalités de Places. Reportez-vous aux types de lieux présentés ci-dessous pour découvrir des contenus plus riches tels que images, reviews, etc., ainsi que des descriptions et des explications plus détaillées.

Consultez é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