Map QML Type

Le type « Carte » affiche une carte. En savoir plus...

• Liste de tous les membres, y compris les membres hérités
• Map fait partie du plugin QML Maps.

Propriétés

• activeMapType : mapType
• bearing : real (since QtLocation 5.9)
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : enumeration
• errorString : string
• fieldOfView : real (since QtLocation 5.9)
• mapItems : list<MapItem>
• mapReady : bool
• maximumFieldOfView : real (since QtLocation 5.9)
• maximumTilt : real (since QtLocation 5.9)
• maximumZoomLevel : real
• minimumFieldOfView : real (since QtLocation 5.9)
• minimumTilt : real (since QtLocation 5.9)
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : list<mapType>
• tilt : real (since QtLocation 5.9)
• visibleArea : rect
• visibleRegion : geoShape
• zoomLevel : real

Signaux

• copyrightLinkActivated(string link)

Méthodes

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void alignCoordinateToPoint(coordinate coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems(list<MapItems> items)
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate coordinate, bool clipToViewPort)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem item)
• void removeMapItemGroup(MapItemGroup itemGroup)
• void removeMapItemView(MapItemView itemView)
• void setBearing(real bearing, coordinate coordinate)
• coordinate toCoordinate(QPointF position, bool clipToViewPort)

Description détaillée

Le type « Carte » sert à afficher une carte ou une image de la Terre, avec la possibilité d’afficher également des objets interactifs liés à la surface de la carte.

Il existe différentes façons de visualiser la surface de la Terre en deux dimensions, mais toutes impliquent une forme de projection : une relation mathématique entre les coordonnées 3D (latitude, longitude et altitude) et les coordonnées 2D (X et Y en pixels) à l'écran.

Différentes sources de données cartographiques peuvent utiliser différentes projections, et du point de vue du type « Carte », nous les traitons comme une seule unité remplaçable : le plugin « Carte ». Un plugin « Carte » se compose d’une source de données, ainsi que de tous les autres éléments nécessaires à l’affichage de ses données à l’écran.

Le plugin « Map » actuellement utilisé est défini par la propriété « plugin » de l’élément « Map ». Pour afficher une image dans un élément « Map », vous devez définir cette propriété. Consultez le type « Plugin » pour savoir comment récupérer un plugin adapté à vos besoins.

La région géographique affichée dans l’élément « Map » est appelée « fenêtre d’affichage » ; elle est définie par les propriétés center et zoomLevel. La propriété center contient un geoCoordinate spécifiant le centre de la fenêtre d’affichage, tandis que zoomLevel contrôle l’échelle de la carte. Reportez-vous à chacune de ces propriétés pour plus de détails sur leurs valeurs.

Lorsque la carte est affichée, chaque coordonnée géographique visible correspond à des coordonnées X et Y en pixels à l’écran. Pour effectuer des conversions entre ces deux systèmes, Map fournit les fonctions ` toCoordinate ` et ` fromCoordinate `, qui sont d’une utilité générale.

Objets de la carte

Les objets liés à la carte peuvent être déclarés dans le corps d’un objet Map via ` Qt Quick ` et apparaîtront automatiquement sur la carte. Pour ajouter un objet par programmation, assurez-vous d’abord qu’il est créé avec la carte comme parent (par exemple dans un argument de ` Component::createObject`). Appelez ensuite la méthode ` addMapItem ` sur la carte, si le type de cet objet est l’un des suivants : ` MapCircle`, ` MapRectangle`, ` MapPolyline`, ` MapPolygon`, ` MapRoute ` ou ` MapQuickItem`. Une méthode correspondante, ` removeMapItem `, existe également pour effectuer l’opération inverse et supprimer de la carte l’un des types d’objets de carte mentionnés ci-dessus.

Déplacer des objets `Map`, les redimensionner ou modifier leur forme n’implique généralement aucune interaction particulière avec `Map` elle-même : la modification de ces propriétés dans un objet `Map` met automatiquement à jour l’affichage.

Performances

Les cartes sont rendues à l’aide d’OpenGL (ES) et de la pile Qt Scene Graph ; elles offrent donc de très bonnes performances lorsque du matériel accélérant OpenGL est disponible.

Pour les cartes « en ligne », la bande passante réseau et la latence peuvent avoir une influence majeure sur la perception des performances par l’utilisateur. Une mise en cache intensive est effectuée pour atténuer cet effet, mais cette atténuation n’est pas toujours parfaite.

En général, les éléments de carte volumineux et complexes, tels que les polygones et les polylignes comportant un grand nombre de sommets, peuvent avoir un effet négatif sur les performances de l’interface utilisateur.

Exemple d’utilisation

L'extrait de code suivant présente une carte simple et le type de plugin nécessaire pour l'utiliser. La carte est centrée sur Oslo, en Norvège, avec un niveau de zoom de 14.

import QtQuick
import QtLocation
import QtPositioning

Window {
    ...
    Plugin {
        id: mapPlugin
        name: "osm"
    }

    Map {
        id: map
        anchors.fill: parent
        plugin: mapPlugin
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 14
        property geoCoordinate startCentroid

        PinchHandler {
            id: pinch
            target: null
            onActiveChanged: if (active) {
                map.startCentroid = map.toCoordinate(pinch.centroid.position, false)
            }
            onScaleChanged: (delta) => {
                map.zoomLevel += Math.log2(delta)
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            onRotationChanged: (delta) => {
                map.bearing -= delta
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            grabPermissions: PointerHandler.TakeOverForbidden
        }
        WheelHandler {
            id: wheel
            // workaround for QTBUG-87646 / QTBUG-112394 / QTBUG-112432:
            // Magic Mouse pretends to be a trackpad but doesn't work with PinchHandler
            // and we don't yet distinguish mice and trackpads on Wayland either
            acceptedDevices: Qt.platform.pluginName === "cocoa" || Qt.platform.pluginName === "wayland"
                             ? PointerDevice.Mouse | PointerDevice.TouchPad
                             : PointerDevice.Mouse
            rotationScale: 1/120
            property: "zoomLevel"
        }
        DragHandler {
            id: drag
            target: null
            onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
        }
        Shortcut {
            enabled: map.zoomLevel < map.maximumZoomLevel
            sequence: StandardKey.ZoomIn
            onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
        }
        Shortcut {
            enabled: map.zoomLevel > map.minimumZoomLevel
            sequence: StandardKey.ZoomOut
            onActivated: map.zoomLevel = Math.round(map.zoomLevel - 1)
        }
    }
}

Documentation des propriétés

activeMapType : mapType

Accès à l'map type actuellement active.

Cette propriété peut être définie pour modifier l'map type e active. Reportez-vous à la propriété supportedMapTypes pour connaître les valeurs possibles.

Voir également mapType.

bearing : real [since QtLocation 5.9]

Cette propriété contient le relèvement de la carte. La valeur par défaut est 0. Si le plugin utilisé pour la carte prend en charge le relèvement, cette valeur doit être comprise entre 0 et 360. Si le plugin utilisé pour la carte ne prend pas en charge le relèvement, la modification de cette propriété n'aura aucun effet.

Cette propriété a été introduite dans QtLocation 5.9.

center : coordinate

Cette propriété contient les coordonnées du centre de la fenêtre d'affichage de la carte. Les coordonnées de centre non valides sont ignorées.

La valeur par défaut est une coordonnée valide choisie arbitrairement.

color : color

Cette propriété définit la couleur d'arrière-plan de l'élément de carte.

copyrightsVisible : bool

Cette propriété détermine la visibilité de la mention de droits d'auteur. Cette mention s'affiche généralement dans le coin inférieur gauche. Par défaut, cette propriété est définie sur « true ».

error : enumeration [read-only]

Cette propriété en lecture seule contient la dernière erreur survenue au niveau du fournisseur de services de cartographie.

• Map.NoError: aucune erreur ne s'est produite.
• Map.NotSupportedError - La propriété du plugin de cartes n'a pas été définie ou aucun gestionnaire de mappage n'est associé au plugin.
• Map.UnknownParameterError - Le plugin n'a pas reconnu l'un des paramètres qui lui a été fourni.
• Map.MissingRequiredParameterError - Le plugin n'a pas trouvé l'un des paramètres attendus.
• Map.ConnectionError - Le plugin n'a pas pu se connecter à son service backend ou à sa base de données.

Voir également QGeoServiceProvider::Error.

errorString : string [read-only]

Cette propriété en lecture seule contient la description textuelle de la dernière erreur du fournisseur de mappage. Si aucune erreur ne s'est produite, une chaîne vide est renvoyée.

Une chaîne vide peut également être renvoyée si une erreur s'est produite sans représentation textuelle associée.

Voir également la fonction QGeoServiceProvider::errorString().

fieldOfView : real [since QtLocation 5.9]

Cette propriété définit le champ de vision de la caméra utilisée pour visualiser la carte, en degrés. Si la propriété « plugin » de la carte n'est pas définie, ou si le plugin ne prend pas en charge la cartographie, la valeur par défaut est de 45 degrés.

Notez que la modification de cette valeur modifie implicitement la distance entre la caméra et la carte, de sorte qu’à un angle d’inclinaison de 0 degré, l’image obtenue est identique quelle que soit la valeur utilisée pour cette propriété.

Pour plus d’informations sur ce paramètre, consultez les articles Wikipédia consacrés au champ de vision et à l’angle de vision.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également minimumFieldOfView et maximumFieldOfView.

mapItems : list<MapItem> [read-only]

Renvoie la liste de tous les éléments de la carte, sans ordre particulier. Ces éléments comprennent à la fois ceux qui ont été déclarés de manière statique dans le cadre de la déclaration de type, et ceux déclarés de manière dynamique (addMapItem, MapItemView).

Voir également addMapItem, removeMapItem et clearMapItems.

mapReady : bool [read-only]

Cette propriété indique si la carte a été initialisée avec succès et si elle est prête à être utilisée. Certaines méthodes, telles que ` fromCoordinate ` et ` toCoordinate`, ne fonctionneront pas tant que la carte ne sera pas prête. En raison de l'architecture de l'Map, il est conseillé d'utiliser le signal émis pour cette propriété plutôt que ` Component.onCompleted`, afin de s'assurer que tout se comporte comme prévu.

maximumFieldOfView : real [since QtLocation 5.9]

Cette propriété indique le champ de vision maximal valide pour la carte, en degrés.

Le champ de vision minimal en inclinaison défini par l'plugin e utilisé constitue une limite supérieure pour cette propriété. Si la propriété « plugin » n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété vaut « 179 ».

Cette propriété a été introduite dans QtLocation 5.9.

Voir également fieldOfView et minimumFieldOfView.

maximumTilt : real [since QtLocation 5.9]

Cette propriété indique l'inclinaison maximale valide pour la carte, en degrés.

L'inclinaison maximale définie par l'plugin utilisé constitue une limite supérieure pour cette propriété. Si la propriété « plugin » n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est définie sur « 89.5 ».

Depuis la version 5.12 d’ QtLocation, les plugins peuvent en outre limiter cette valeur en fonction du niveau de zoom actuel.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également tilt et minimumTilt.

maximumZoomLevel : real

Cette propriété définit le niveau de zoom maximal autorisé pour la carte.

Le niveau de zoom maximal est défini par l'plugin e utilisé. Si la propriété « plugin » n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est définie sur « 30 ».

minimumFieldOfView : real [since QtLocation 5.9]

Cette propriété indique le champ de vision minimal valide pour la carte, exprimé en degrés.

Le champ de vision minimal en inclinaison défini par l’ plugin e utilisé constitue une limite inférieure pour cette propriété. Si la propriété « plugin » n’est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est définie sur « 1 ».

Cette propriété a été introduite dans QtLocation 5.9.

Voir également fieldOfView et maximumFieldOfView.

minimumTilt : real [since QtLocation 5.9]

Cette propriété indique l'inclinaison minimale valide pour la carte, exprimée en degrés.

L'inclinaison minimale définie par l'plugin utilisé constitue une borne inférieure pour cette propriété. Si la propriété « plugin » n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété vaut « 0 ».

Depuis la version 5.12 d'QtLocation, les plugins peuvent en outre restreindre cette valeur en fonction du niveau de zoom actuel.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également tilt et maximumTilt.

minimumZoomLevel : real

Cette propriété indique le niveau de zoom minimal valide pour la carte.

Le niveau de zoom minimal défini par l’ plugin utilisé constitue une limite inférieure pour cette propriété. Cependant, la valeur renvoyée dépend également de la taille du canevas et peut être supérieure à la valeur spécifiée par l’utilisateur ou au niveau de zoom minimal défini par le plugin utilisé, afin d’éviter que la carte ne soit plus petite que la fenêtre d’affichage dans l’une ou l’autre de ses dimensions.

Si la propriété « plugin » n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété prend la valeur « 0 ».

plugin : Plugin

Cette propriété contient le plugin qui assure la fonctionnalité de mappage.

Il s'agit d'une propriété à écriture unique. Une fois qu'un plugin est associé à la carte, toute tentative de modification de ce plugin sera ignorée.

supportedMapTypes : list<mapType> [read-only]

Cette propriété en lecture seule contient l'ensemble des « map types » prises en charge par cette carte.

Voir également activeMapType.

tilt : real [since QtLocation 5.9]

Cette propriété définit l'inclinaison de la carte, en degrés. La valeur par défaut est 0. La plage de valeurs valides est comprise entre [ minimumTilt et maximumTilt ]. Si le plugin utilisé pour la carte ne prend pas en charge l'inclinaison, la modification de cette propriété n'aura aucun effet.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également minimumTilt et maximumTilt.

visibleArea : rect

Cette propriété contient la zone visible à l'intérieur de l'élément QML `Map`. Il s'agit d'un rectangle dont les coordonnées sont relatives à l'élément `Map`. Sa taille sera limitée à celle de l'élément `Map`. Une valeur `visibleArea` nulle signifie que l'intégralité de la carte est visible.

visibleRegion : geoShape

Cette propriété contient la région qui occupe la fenêtre d'affichage de la carte. La caméra est positionnée au centre de cette zone, au niveau de zoom entier le plus élevé possible permettant de visualiser l'intégralité de celle-ci à l'écran. Cela implique que si l'on relit cette propriété peu après l'avoir définie, la zone renvoyée est égale ou supérieure à la zone définie.

La définition de cette propriété modifie implicitement les propriétés ` center ` et ` zoomLevel ` de la carte. Toute valeur précédemment définie pour ces propriétés sera remplacée.

zoomLevel : real

Cette propriété définit le niveau de zoom de la carte.

Plus la valeur du niveau de zoom est élevée, plus le niveau de détail est important. Les niveaux de zoom sont toujours non négatifs. La valeur par défaut est 8,0. Selon le plugin utilisé, les valeurs situées en dehors de la plage [minimumZoomLevel, maximumZoomLevel], qui correspond à la plage pour laquelle des tuiles sont disponibles, peuvent être acceptées ou limitées.

Documentation Signal

copyrightLinkActivated(string link)

Ce signal est émis lorsque l'utilisateur clique sur un lien link figurant dans la mention de droits d'auteur. L'application doit ouvrir le lien dans un navigateur ou afficher son contenu à l'utilisateur.

Documentation de la méthode

void addMapItem(MapItem item)

Ajoute l'item on indiquée à la carte (par exemple MapQuickItem, MapCircle). Si l'objet figure déjà sur la carte, il ne sera pas ajouté une nouvelle fois.

Prenons par exemple le cas où vous disposez d'une MapCircle représentant votre position actuelle :

import QtQuick
import QtPositioning
import QtLocation

PositionSource {
    id: positionSource
}

Map {
    id: map
    property MapCircle circle

    Component.onCompleted: {
        circle = Qt.createQmlObject('import QtLocation; MapCircle {}', page)
        circle.center = positionSource.position.coordinate
        circle.radius = 5000.0
        circle.color = 'green'
        circle.border.width = 3
        map.addMapItem(circle)
    }
}

Voir également mapItems, removeMapItem et clearMapItems.

void addMapItemGroup(MapItemGroup itemGroup)

Ajoute à la carte les éléments contenus dans l'itemGroup on fournie (par exemple : MapQuickItem, MapCircle).

Voir également MapItemGroup et removeMapItemGroup.

void addMapItemView(MapItemView itemView)

Ajoute itemView à la carte.

Voir également MapItemView et removeMapItemView.

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

Aligne coordinate sur point. Cette méthode étend de manière efficace les fonctionnalités offertes par la propriété QML center, permettant d'aligner une coordonnée sur un point de l'élément Map autre que son centre. Cela s'avère utile dans les applications où le centre de la scène (par exemple, un curseur) ne doit pas être placé exactement au centre de la carte.

Si la carte est inclinée et que coordinate se trouve derrière la caméra, ou si la carte n’est pas prête (voir mapReady), l’appel de cette méthode n’aura aucun effet.

La publication de cette API avec Qt 5.10 est une préversion technologique.

Voir également center.

void clearData()

Efface les données cartographiques collectées par le plugin actuellement sélectionné.

Voir aussi plugin.

void clearMapItems()

Supprime tous les éléments et groupes d'éléments de la carte.

Voir également mapItems, addMapItem, removeMapItem, addMapItemGroup et removeMapItemGroup.

void fitViewportToGeoShape(geoShape, margins)

Adapte la fenêtre d'affichage à une forme géométrique spécifique geoShape. Les coordonnées margins sont exprimées en pixels d'écran.

Voir également visibleRegion.

void fitViewportToMapItems(list<MapItems> items = {})

Si aucun argument n'est fourni, cette méthode adapte la fenêtre d'affichage actuelle aux limites de tous les éléments de la carte. La caméra est positionnée au centre des éléments de la carte, au niveau de zoom entier le plus élevé possible permettant de visualiser tous les éléments de la carte à l'écran. Si l'argument ` items ` est fourni, cette méthode adapte la fenêtre d'affichage actuelle uniquement aux limites des éléments de la carte spécifiés.

Voir également fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

Adapte la fenêtre d'affichage actuelle aux limites de tous les éléments cartographiques visibles. La caméra est positionnée au centre des éléments cartographiques, au niveau de zoom entier le plus élevé possible permettant de visualiser tous les éléments cartographiques à l'écran.

Voir également fitViewportToMapItems.

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

Renvoie la position relative à l'élément de la carte qui correspond à l'coordinate.

Si clipToViewPort est égal à true ou n'est pas fourni, renvoie une erreur « QPointF » si coordinate ne se trouve pas dans la fenêtre d'affichage actuelle.

void pan(int dx, int dy)

Commence à faire défiler la carte de dx pixels le long de l'axe x et de dy pixels le long de l'axe y.

Les valeurs positives de dx déplacent la carte vers la droite, les valeurs négatives vers la gauche. Les valeurs positives de dy déplacent la carte vers le bas, les valeurs négatives vers le haut.

Pendant le panoramique, les valeurs de center et zoomLevel peuvent varier.

void prefetchData()

Indication facultative permettant à la carte d'effectuer une prélecture pendant cette période d'inactivité

void removeMapItem(MapItem item)

Supprime l'item donné de la carte (par exemple MapQuickItem, MapCircle). Si l' n'existe pas ou n'a pas été ajouté auparavant à la carte, la méthode ne fait rien.

Voir également mapItems, addMapItem et clearMapItems.

void removeMapItemGroup(MapItemGroup itemGroup)

Supprime « itemGroup » et les éléments qu’il contient de la carte.

Voir également MapItemGroup et addMapItemGroup.

void removeMapItemView(MapItemView itemView)

Supprime de la carte l'objet ` itemView ` ainsi que les éléments qu'il a instanciés.

Voir également MapItemView et addMapItemView.

void setBearing(real bearing, coordinate coordinate)

Définit l'orientation de la carte sur bearing, en la faisant pivoter autour de coordinate. Si le plugin utilisé pour la carte prend en charge l'orientation, la plage valide pour bearing est comprise entre 0 et 360. Si le plugin utilisé pour la carte ne prend pas en charge l’orientation, ou si la carte est inclinée et que coordinate se trouve derrière la caméra, ou encore si la carte n’est pas prête (voir mapReady), l’appel de cette méthode n’aura aucun effet.

La publication de cette API avec Qt 5.10 est une préversion technologique.

coordinate toCoordinate(QPointF position, bool clipToViewPort)

Renvoie la coordonnée correspondant à l'position, par rapport à l'élément de la carte.

Si l'clipToViewPort est « true » ou n'est pas fournie, renvoie une coordonnée non valide si « position » ne se trouve pas dans la fenêtre d'affichage actuelle.