summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Rauter <matthias.rauter@qt.io>2023-02-27 13:11:18 +0100
committerVolker Hilsheimer <volker.hilsheimer@qt.io>2023-03-09 06:21:54 +0100
commitb5b4c76830b6d718a789b44f3c5ffffae874acb3 (patch)
tree90ba0b2e08bb5d15bf52a74406a9d33c74f0802e
parentc3284feb150ec660d94711d6bcd1fcc1ec328991 (diff)
downloadqtlocation-b5b4c76830b6d718a789b44f3c5ffffae874acb3.tar.gz
Update the documentation
Change-Id: Icff1282a22c3cefbbbbfb1dc03910066eb7c85f3 Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io> (cherry picked from commit 838426f5159c795fdeb94a6e657a478d4ac63511)
-rw-r--r--src/location/doc/src/maps.qdoc4
-rw-r--r--src/location/doc/src/qt6-changes.qdoc5
-rw-r--r--src/location/maps/qgeojson.cpp99
-rw-r--r--src/location/quickmapitems/qdeclarativecirclemapitem.cpp17
-rw-r--r--src/location/quickmapitems/qdeclarativegeomap.cpp10
-rw-r--r--src/location/quickmapitems/qdeclarativepolygonmapitem.cpp15
-rw-r--r--src/location/quickmapitems/qdeclarativepolylinemapitem.cpp10
-rw-r--r--src/location/quickmapitems/qdeclarativerectanglemapitem.cpp10
-rw-r--r--src/location/quickmapitems/qdeclarativeroutemapitem.cpp5
9 files changed, 69 insertions, 106 deletions
diff --git a/src/location/doc/src/maps.qdoc b/src/location/doc/src/maps.qdoc
index ea147f2d..ad363d5c 100644
--- a/src/location/doc/src/maps.qdoc
+++ b/src/location/doc/src/maps.qdoc
@@ -24,7 +24,7 @@ A more hands-on introduction of the Maps and Navigation types can be found in th
\section2 Displaying Maps
Displaying a map is done using the \l{QtLocation::Map}{Map} QML types. The Map type supports
-user interaction through the \l{QtLocation::MapGestureArea}{MapGestureArea} QML type. The Map
+user interaction through the \l{QtLocation::MapView}{MapView} QML type. The Map
object draws the map on-screen using OpenGL (ES), allowing for hardware-accelerated rendering
where available.
@@ -37,7 +37,7 @@ where available.
\li \l{QtLocation::Map}{Map}
\li QtQuick item to display a map on-screen.
\row
- \li \l{QtLocation::MapGestureArea}{MapGestureArea}
+ \li \l{QtLocation::MapView}{MapView}
\li Interaction helper for panning, flicking and pinch-to-zoom gesture on a Map.
\endtable
diff --git a/src/location/doc/src/qt6-changes.qdoc b/src/location/doc/src/qt6-changes.qdoc
index 26941a01..9b3d57b9 100644
--- a/src/location/doc/src/qt6-changes.qdoc
+++ b/src/location/doc/src/qt6-changes.qdoc
@@ -36,12 +36,15 @@
\li The \c QGeoRouteLeg class and the QML equivalent, \c RouteLeg, have
been merged into \l QGeoRoute (and the \l route type). A route can
be an aggregate of several routes.
+ \li The \l {Map} type provides now minimal functionality without handling
+ of user intput. The \c {MapGestureArea} was removed. The \l {MapView}
+ type handles basic user input such as tap and drag events.
\endlist
\section2 Places
\list
- \li The \c {QPlaceImage}, {QPlaceEditorial}, and {QPlaceReview} classes
+ \li The \c {QPlaceImage}, \c {QPlaceEditorial}, and \c {QPlaceReview} classes
have been folded into \l QPlaceContent.
\li The \l QPlaceContent API has been changed to give access to a list of
QVariant values.
diff --git a/src/location/maps/qgeojson.cpp b/src/location/maps/qgeojson.cpp
index 765fc5ec..f699a6c5 100644
--- a/src/location/maps/qgeojson.cpp
+++ b/src/location/maps/qgeojson.cpp
@@ -18,6 +18,11 @@ QT_BEGIN_NAMESPACE
/*! \namespace QGeoJson
\inmodule QtLocation
+ \keyword QGeoJson Namespace
+
+ \brief The QGeoJson namespace contains functions to import and export
+ geolocated information from and to GeoJson files.
+
\since 5.13
The methods in the QGeoJson namespace can be used to convert between a
@@ -44,7 +49,8 @@ QT_BEGIN_NAMESPACE
MultiPolygon, \c GeometryCollection, \c FeatureCollection. The second pair
has \c data as key, and the corresponding value can be either a QGeoShape
or a list, depending on the GeoJSON type. The next section provides details
- about this node. The \c Feature type is converted into the type of the
+ about the conversation form GeoJson objects to objects known in Qt Location.
+ The \c Feature type is converted into the type of the
geometry contained within, with an additional (key, value) pair, where the
key is \c properties and the value is a \l QVariantMap. Thus, a feature Map
is distinguishable from the corresponding geometry, by looking for a \c
@@ -73,12 +79,12 @@ QT_BEGIN_NAMESPACE
\code
{
- type : Point
+ type : "Point"
data : QGeoCircle({60.000, 11.000}, -1)
}
\endcode
- \li When the type is \c LineString the data ia a QGeoPath.
+ \li When the type is \c LineString the data is a QGeoPath.
For example, the following GeoJSON document contains a \c LineString
geometry:
@@ -94,7 +100,7 @@ QT_BEGIN_NAMESPACE
\code
{
- type : LineString,
+ type : "LineString",
data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
}
\endcode
@@ -123,7 +129,7 @@ QT_BEGIN_NAMESPACE
\code
{
- type : Polygon
+ type : "Polygon"
data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
}
\endcode
@@ -157,18 +163,18 @@ QT_BEGIN_NAMESPACE
\code
{
- type : MultiPoint
+ type : "MultiPoint"
data : [
{
- type : Point
+ type : "Point"
data : QGeoCircle({60.000, 11.000}, -1)
},
{
- type : Point
+ type : "Point"
data : QGeoCircle({60.300, 5.500}, -1)
},
{
- type : Point
+ type : "Point"
data : QGeoCircle({58.900, 5.700}, -1)
}
]
@@ -194,14 +200,14 @@ QT_BEGIN_NAMESPACE
\code
{
- type : MultiLineString
+ type : "MultiLineString"
data : [
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
},
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
}
]
@@ -215,11 +221,24 @@ QT_BEGIN_NAMESPACE
\code
{
- "type" : "MultiPoint",
+ "type" : "MultiPolygon",
"coordinates" : [
- [11,60],
- [5.5,60.3],
- [5.7,58.90]
+ [
+ [
+ [17.13, 51.11],
+ [30.54, 50.42],
+ [26.74, 58.36],
+ [17.13, 51.11]
+ ]
+ ],
+ [
+ [
+ [19.84, 41.33],
+ [30.45, 49.26],
+ [17.07, 50.10],
+ [19.84, 41.33]
+ ]
+ ]
]
}
\endcode
@@ -228,19 +247,15 @@ QT_BEGIN_NAMESPACE
\code
{
- type : MultiPoint
+ type : "MultiPolygon"
data : [
{
- type : Point
- data : QGeoCircle({60.000, 11.000}, -1)
- },
- {
- type : Point
- data : QGeoCircle({60.300, 5.500}, -1)
+ type : "Polygon"
+ data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
},
{
- type : Point
- data : QGeoCircle({58.900, 5.700}, -1)
+ type : "Polygon"
+ data : QGeoPolygon([{41.330, 19.840}, {49.260,30.450}, {50.100, 17.070}, {41.330, 19.840}])
}
]
}
@@ -297,36 +312,36 @@ QT_BEGIN_NAMESPACE
\code
{
- type : GeometryCollection
+ type : "GeometryCollection"
data : [
{
- type : MultiPolygon
+ type : "MultiPolygon"
data : [
{
- type : Polygon
+ type : "Polygon"
data : QGeoPolygon([{41.330, 19.840}, {49.260, 30.450}, {50.100, 17.070}, {41.330, 19.840}])
}
{
- type : Polygon
+ type : "Polygon"
data : QGeoPolygon([{51.110, 17.130}, {50.420, 30.540}, {58.360, 26.740}, {51.110, 17.130}])
}
]
}
{
- type : MultiLineString
+ type : "MultiLineString"
data : [
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
}
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
}
]
}
{
- type : MultiPoint
+ type : "MultiPoint"
data : [
{
type : Point
@@ -383,9 +398,9 @@ QT_BEGIN_NAMESPACE
\code
{
- type : Polygon
+ type : "Polygon"
data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
- properties : {text : This is a Feature with a Polygon}
+ properties : {text : "This is a Feature with a Polygon"}
}
\endcode
@@ -442,26 +457,26 @@ QT_BEGIN_NAMESPACE
\code
{
- type : FeatureCollection
+ type : "FeatureCollection"
data : [
{
- type : MultiLineString
+ type : "MultiLineString"
data : [
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
}
{
- type : LineString
+ type : "LineString"
data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
}
]
- properties : {text : This is a Feature with a MultiLineString}
+ properties : {text : "This is a Feature with a MultiLineString"}
},
{
- type : Polygon
+ type : "Polygon"
data : QGeoPolygon({51.110, 17.130}, {50.420, 30.540}, {58.360, 26.700}, {51.110, 17.130})
- properties : {text : This is a Feature with a Polygon}
+ properties : {text : "This is a Feature with a Polygon"}
}
]
}
diff --git a/src/location/quickmapitems/qdeclarativecirclemapitem.cpp b/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
index 34aa4fb5..e01b724e 100644
--- a/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
@@ -37,8 +37,8 @@ QT_BEGIN_NAMESPACE
MapQuickItem containing a relevant Qt Quick type instead.
By default, the circle is displayed as a 1 pixel black border with
- no fill. To change its appearance, use the color, border.color
- and border.width properties.
+ no fill. To change its appearance, use the \l {color}, \l {border.color}
+ and \l {border.width} properties.
Internally, a MapCircle is implemented as a many-sided polygon. To
calculate the radius points it uses a spherical model of the Earth,
@@ -47,23 +47,12 @@ QT_BEGIN_NAMESPACE
accuracy of the circle's shape, depending on position and map
projection.
- \note Dragging a MapCircle (through the use of \l MouseArea)
+ \note Dragging a MapCircle (through the use of \l {MouseArea} or \l {PointHandler})
causes new points to be generated at the same distance (in meters)
from the center. This is in contrast to other map items which store
their dimensions in terms of latitude and longitude differences between
vertices.
- \section2 Performance
-
- MapCircle performance is almost equivalent to that of a MapPolygon with
- the same number of vertices. There is a small amount of additional
- overhead with respect to calculating the vertices first.
-
- Like the other map objects, MapCircle is normally drawn without a smooth
- appearance. Setting the opacity property will force the object to be
- blended, which decreases performance considerably depending on the graphics
- hardware in use.
-
\section2 Example Usage
The following snippet shows a map containing a MapCircle, centered at
diff --git a/src/location/quickmapitems/qdeclarativegeomap.cpp b/src/location/quickmapitems/qdeclarativegeomap.cpp
index 7033307f..c7f9415a 100644
--- a/src/location/quickmapitems/qdeclarativegeomap.cpp
+++ b/src/location/quickmapitems/qdeclarativegeomap.cpp
@@ -94,18 +94,12 @@ static qreal sanitizeBearing(qreal bearing)
Maps are rendered using OpenGL (ES) and the Qt Scene Graph stack, and as
a result perform quite well where GL accelerated hardware is available.
- For "online" Map plugins, network bandwidth and latency can be major
+ For "online" Maps, network bandwidth and latency can be major
contributors to the user's perception of performance. Extensive caching is
- performed to mitigate this, but such mitigation is not always perfect. For
- "offline" plugins, the time spent retrieving the stored geographic data
- and rendering the basic map features can often play a dominant role. Some
- offline plugins may use hardware acceleration themselves to (partially)
- avert this.
+ performed to mitigate this, but such mitigation is not always perfect.
In general, large and complex Map items such as polygons and polylines with
large numbers of vertices can have an adverse effect on UI performance.
- Further, more detailed notes on this are in the documentation for each
- map item type.
\section2 Example Usage
diff --git a/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp b/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
index 1eee3eb0..1acd3e60 100644
--- a/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
@@ -57,25 +57,12 @@ QT_BEGIN_NAMESPACE
\l border.width properties.
\note Since MapPolygons are geographic items, dragging a MapPolygon
- (through the use of \l MouseArea) causes its vertices to be
+ (through the use of \l MouseArea or \l PointHander) causes its vertices to be
recalculated in the geographic coordinate space. The edges retain the
same geographic lengths (latitude and longitude differences between the
vertices), but they remain straight. Apparent stretching of the item occurs
when dragged to a different latitude.
- \section2 Performance
-
- MapPolygons have a rendering cost that is O(n) with respect to the number
- of vertices. This means that the per frame cost of having a Polygon on the
- Map grows in direct proportion to the number of points on the Polygon. There
- is an additional triangulation cost (approximately O(n log n)) which is
- currently paid with each frame, but in future may be paid only upon adding
- or removing points.
-
- Like the other map objects, MapPolygon is normally drawn without a smooth
- appearance. Setting the \l {Item::opacity}{opacity} property will force the object to
- be blended, which decreases performance considerably depending on the hardware in use.
-
\section2 Example Usage
The following snippet shows a MapPolygon being used to display a triangle,
diff --git a/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp b/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
index e80afbee..81c135a5 100644
--- a/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
@@ -205,16 +205,6 @@ static QList<QList<QDoubleVector2D> > clipLine(
By default, the polyline is displayed as a 1-pixel thick black line. This
can be changed using the \l line.width and \l line.color properties.
- \section2 Performance
-
- MapPolylines have a rendering cost that is O(n) with respect to the number
- of vertices. This means that the per frame cost of having a polyline on
- the Map grows in direct proportion to the number of points in the polyline.
-
- Like the other map objects, MapPolyline is normally drawn without a smooth
- appearance. Setting the \l {Item::opacity}{opacity} property will force the object to
- be blended, which decreases performance considerably depending on the hardware in use.
-
\section2 Example Usage
The following snippet shows a MapPolyline with 4 points, making a shape
diff --git a/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp b/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
index 0e4e9e02..b1c03fd6 100644
--- a/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
@@ -48,16 +48,6 @@ QT_BEGIN_NAMESPACE
occurs when dragged to the a different latitude, however, its edges
remain straight.
- \section2 Performance
-
- MapRectangles have a rendering cost identical to a MapPolygon with 4
- vertices.
-
- Like the other map objects, MapRectangle is normally drawn without a smooth
- appearance. Setting the \l opacity property will force the object to be
- blended, which decreases performance considerably depending on the hardware
- in use.
-
\section2 Example Usage
The following snippet shows a map containing a MapRectangle, spanning
diff --git a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
index cf59fdd5..373d0b51 100644
--- a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
@@ -28,11 +28,6 @@ QT_BEGIN_NAMESPACE
By default, the route is displayed as a 1-pixel thick black line. This can
be changed using the \l line.width and \l line.color properties.
- \section2 Performance
-
- For notes about the performance on MapRoute, refer to the documentation for
- \l MapPolyline.
-
\section2 Example Usage
Here is how to draw a \l{route}{route} on a \l{Map}{map}: