Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
QGeoCoordinate Class Reference

\inmodule QtPositioning More...

#include <qgeocoordinate.h>

+ Collaboration diagram for QGeoCoordinate:

Public Types

enum  CoordinateType { InvalidCoordinate , Coordinate2D , Coordinate3D }
 Defines the types of a coordinate. More...
 
enum  CoordinateFormat {
  Degrees , DegreesWithHemisphere , DegreesMinutes , DegreesMinutesWithHemisphere ,
  DegreesMinutesSeconds , DegreesMinutesSecondsWithHemisphere
}
 Defines the possible formatting options for toString(). More...
 

Public Member Functions

 QGeoCoordinate ()
 Constructs a coordinate.
 
 QGeoCoordinate (double latitude, double longitude)
 Constructs a coordinate with the given latitude and longitude.
 
 QGeoCoordinate (double latitude, double longitude, double altitude)
 Constructs a coordinate with the given latitude, longitude and altitude.
 
 QGeoCoordinate (const QGeoCoordinate &other)
 Constructs a coordinate from the contents of other.
 
 QGeoCoordinate (QGeoCoordinate &&other) noexcept=default
 
 ~QGeoCoordinate ()
 Destroys the coordinate object.
 
QGeoCoordinateoperator= (const QGeoCoordinate &other)
 Assigns other to this coordinate and returns a reference to this coordinate.
 
void swap (QGeoCoordinate &other) noexcept
 
bool isValid () const
 Returns true if the \l longitude and \l latitude are valid.
 
CoordinateType type () const
 Returns the type of this coordinate.
 
void setLatitude (double latitude)
 Sets the latitude (in decimal degrees) to latitude.
 
double latitude () const
 Returns the latitude, in decimal degrees.
 
void setLongitude (double longitude)
 Sets the longitude (in decimal degrees) to longitude.
 
double longitude () const
 Returns the longitude, in decimal degrees.
 
void setAltitude (double altitude)
 Sets the altitude (meters above sea level) to altitude.
 
double altitude () const
 Returns the altitude (meters above sea level).
 
Q_INVOKABLE qreal distanceTo (const QGeoCoordinate &other) const
 Returns the distance (in meters) from this coordinate to the coordinate specified by other.
 
Q_INVOKABLE qreal azimuthTo (const QGeoCoordinate &other) const
 Returns the azimuth (or bearing) in degrees from this coordinate to the coordinate specified by other.
 
Q_INVOKABLE QGeoCoordinate atDistanceAndAzimuth (qreal distance, qreal azimuth, qreal distanceUp=0.0) const
 Returns the coordinate that is reached by traveling distance meters from the current coordinate at azimuth (or bearing) along a great-circle.
 
Q_INVOKABLE QString toString (CoordinateFormat format=DegreesMinutesSecondsWithHemisphere) const
 Returns this coordinate as a string in the specified format.
 

Properties

double latitude
 This property holds the latitude in decimal degrees.
 
double longitude
 This property holds the longitude in decimal degrees.
 
double altitude
 This property holds the altitude in meters above sea level.
 
bool isValid
 This property holds the validity of this geo coordinate.
 

Friends

class QGeoCoordinatePrivate
 
class QQuickGeoCoordinateAnimation
 
bool operator== (const QGeoCoordinate &lhs, const QGeoCoordinate &rhs)
 Returns true if the latitude, longitude and altitude of the lhs coordinate are the same as those of the rhs coordinate.
 
bool operator!= (const QGeoCoordinate &lhs, const QGeoCoordinate &rhs)
 Returns true if latitude, longitude, or altitude of the lhs coordinate are not identical to those of the rhs coordinate.
 
QDebug operator<< (QDebug dbg, const QGeoCoordinate &coord)
 
QDataStreamoperator<< (QDataStream &stream, const QGeoCoordinate &coordinate)
 Writes the given coordinate to the specified stream.
 
QDataStreamoperator>> (QDataStream &stream, QGeoCoordinate &coordinate)
 Reads a coordinate from the specified stream into the given coordinate.
 

Detailed Description

\inmodule QtPositioning

Since
5.2

The QGeoCoordinate class defines a geographical position on the surface of the Earth.

A QGeoCoordinate is defined by latitude, longitude, and optionally, altitude.

Use type() to determine whether a coordinate is a 2D coordinate (has latitude and longitude only) or 3D coordinate (has latitude, longitude and altitude). Use distanceTo() and azimuthTo() to calculate the distance and bearing between coordinates.

The coordinate values should be specified using the WGS84 datum. For more information on geographical terms see this article on \l {http://en.wikipedia.org/wiki/Geographic_coordinate_system}{coordinates} and another on \l {http://en.wikipedia.org/wiki/Geodetic_system}{geodetic systems} including WGS84.

Azimuth in this context is equivalent to a compass bearing based on true north.

This class is a \l Q_GADGET since Qt 5.5. It can be \l{Cpp_value_integration_positioning}{directly used from C++ and QML}.

Definition at line 21 of file qgeocoordinate.h.

Member Enumeration Documentation

◆ CoordinateFormat

Defines the possible formatting options for toString().

\value Degrees Returns a string representation of the coordinates in decimal degrees format. \value DegreesWithHemisphere Returns a string representation of the coordinates in decimal degrees format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates. \value DegreesMinutes Returns a string representation of the coordinates in degrees-minutes format. \value DegreesMinutesWithHemisphere Returns a string representation of the coordinates in degrees-minutes format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates. \value DegreesMinutesSeconds Returns a string representation of the coordinates in degrees-minutes-seconds format. \value DegreesMinutesSecondsWithHemisphere Returns a string representation of the coordinates in degrees-minutes-seconds format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates.

See also
toString()
Enumerator
Degrees 
DegreesWithHemisphere 
DegreesMinutes 
DegreesMinutesWithHemisphere 
DegreesMinutesSeconds 
DegreesMinutesSecondsWithHemisphere 

Definition at line 39 of file qgeocoordinate.h.

◆ CoordinateType

Defines the types of a coordinate.

\value InvalidCoordinate An invalid coordinate. A coordinate is invalid if its latitude or longitude values are invalid. \value Coordinate2D A coordinate with valid latitude and longitude values. \value Coordinate3D A coordinate with valid latitude and longitude values, and also an altitude value.

Enumerator
InvalidCoordinate 
Coordinate2D 
Coordinate3D 

Definition at line 33 of file qgeocoordinate.h.

Constructor & Destructor Documentation

◆ QGeoCoordinate() [1/5]

QGeoCoordinate::QGeoCoordinate ( )

Constructs a coordinate.

The coordinate will be invalid until setLatitude() and setLongitude() have been called.

Definition at line 168 of file qgeocoordinate.cpp.

Referenced by atDistanceAndAzimuth().

+ Here is the caller graph for this function:

◆ QGeoCoordinate() [2/5]

QGeoCoordinate::QGeoCoordinate ( double latitude,
double longitude )

Constructs a coordinate with the given latitude and longitude.

If the latitude is not between -90 to 90 inclusive, or the longitude is not between -180 to 180 inclusive, none of the values are set and the type() will be QGeoCoordinate::InvalidCoordinate.

See also
isValid()

Definition at line 182 of file qgeocoordinate.cpp.

References QLocationUtils::isValidLat(), QLocationUtils::isValidLong(), QGeoCoordinatePrivate::lat, latitude, QGeoCoordinatePrivate::lng, and longitude.

+ Here is the call graph for this function:

◆ QGeoCoordinate() [3/5]

QGeoCoordinate::QGeoCoordinate ( double latitude,
double longitude,
double altitude )

Constructs a coordinate with the given latitude, longitude and altitude.

If the latitude is not between -90 to 90 inclusive, or the longitude is not between -180 to 180 inclusive, none of the values are set and the type() will be QGeoCoordinate::InvalidCoordinate.

Note that altitude specifies the meters above sea level.

See also
isValid()

Definition at line 203 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::alt, altitude, QLocationUtils::isValidLat(), QLocationUtils::isValidLong(), QGeoCoordinatePrivate::lat, latitude, QGeoCoordinatePrivate::lng, and longitude.

+ Here is the call graph for this function:

◆ QGeoCoordinate() [4/5]

QGeoCoordinate::QGeoCoordinate ( const QGeoCoordinate & other)

Constructs a coordinate from the contents of other.

Definition at line 216 of file qgeocoordinate.cpp.

◆ QGeoCoordinate() [5/5]

QGeoCoordinate::QGeoCoordinate ( QGeoCoordinate && other)
defaultnoexcept
Since
6.2

Constructs a coordinate by moving from other.

Note
The moved-from QGeoCoordinate object can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

◆ ~QGeoCoordinate()

QGeoCoordinate::~QGeoCoordinate ( )

Destroys the coordinate object.

Definition at line 258 of file qgeocoordinate.cpp.

Member Function Documentation

◆ altitude()

double QGeoCoordinate::altitude ( ) const

Returns the altitude (meters above sea level).

The return value is undefined if the altitude has not been set.

See also
setAltitude(), type()

Definition at line 367 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::alt.

◆ atDistanceAndAzimuth()

QGeoCoordinate QGeoCoordinate::atDistanceAndAzimuth ( qreal distance,
qreal azimuth,
qreal distanceUp = 0.0 ) const

Returns the coordinate that is reached by traveling distance meters from the current coordinate at azimuth (or bearing) along a great-circle.

There is an assumption that the Earth is spherical for the purpose of this calculation.

The altitude will have distanceUp added to it.

Returns an invalid coordinate if this coordinate is invalid.

Definition at line 480 of file qgeocoordinate.cpp.

References QGeoCoordinate(), QGeoCoordinatePrivate::alt, QGeoCoordinatePrivate::atDistanceAndAzimuth(), isValid, and QLocationUtils::wrapLong().

Referenced by QGeoCirclePrivate::updateBoundingBox().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ azimuthTo()

qreal QGeoCoordinate::azimuthTo ( const QGeoCoordinate & other) const

Returns the azimuth (or bearing) in degrees from this coordinate to the coordinate specified by other.

Altitude is not used in the calculation.

The bearing returned is the bearing from the origin to other along the great-circle between the two coordinates. There is an assumption that the Earth is spherical for the purpose of this calculation.

Returns 0 if the type of this coordinate or the type of other is QGeoCoordinate::InvalidCoordinate.

Definition at line 426 of file qgeocoordinate.cpp.

References InvalidCoordinate, QGeoCoordinatePrivate::lat, QGeoCoordinatePrivate::lng, other(), qDegreesToRadians(), qRadiansToDegrees(), and type().

+ Here is the call graph for this function:

◆ distanceTo()

qreal QGeoCoordinate::distanceTo ( const QGeoCoordinate & other) const

Returns the distance (in meters) from this coordinate to the coordinate specified by other.

Altitude is not used in the calculation.

This calculation returns the great-circle distance between the two coordinates, with an assumption that the Earth is spherical for the purpose of this calculation.

Returns 0 if the type of this coordinate or the type of other is QGeoCoordinate::InvalidCoordinate.

Definition at line 393 of file qgeocoordinate.cpp.

References InvalidCoordinate, QGeoCoordinatePrivate::lat, QGeoCoordinatePrivate::lng, other(), qDegreesToRadians(), qgeocoordinate_EARTH_MEAN_RADIUS, and type().

Referenced by QGeoCirclePrivate::contains(), QGeoCirclePrivate::crossNorthPole(), QGeoCirclePrivate::crossSouthPole(), QGeoCirclePrivate::extendCircle(), QGeoPathPrivate::length(), and QGeoPathPrivate::lineContains().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ isValid()

bool QGeoCoordinate::isValid ( ) const

Returns true if the \l longitude and \l latitude are valid.

Definition at line 285 of file qgeocoordinate.cpp.

◆ latitude()

double QGeoCoordinate::latitude ( ) const

Returns the latitude, in decimal degrees.

The return value is undefined if the latitude has not been set.

A positive latitude indicates the Northern Hemisphere, and a negative latitude indicates the Southern Hemisphere.

See also
setLatitude(), type()

Definition at line 315 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::lat.

◆ longitude()

double QGeoCoordinate::longitude ( ) const

Returns the longitude, in decimal degrees.

The return value is undefined if the longitude has not been set.

A positive longitude indicates the Eastern Hemisphere, and a negative longitude indicates the Western Hemisphere.

See also
setLongitude(), type()

Definition at line 342 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::lng.

◆ operator=()

QGeoCoordinate & QGeoCoordinate::operator= ( const QGeoCoordinate & other)

Assigns other to this coordinate and returns a reference to this coordinate.

Since
6.2

Move-assigns other to this coordinate and returns a reference to this coordinate.

Note
The moved-from QGeoCoordinate object can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

Definition at line 234 of file qgeocoordinate.cpp.

References other().

+ Here is the call graph for this function:

◆ setAltitude()

void QGeoCoordinate::setAltitude ( double altitude)

Sets the altitude (meters above sea level) to altitude.

See also
altitude()

Definition at line 377 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::alt, and altitude.

◆ setLatitude()

void QGeoCoordinate::setLatitude ( double latitude)

Sets the latitude (in decimal degrees) to latitude.

The value should be in the WGS84 datum.

To be valid, the latitude must be between -90 to 90 inclusive.

See also
latitude()

Definition at line 328 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::lat, and latitude.

Referenced by QDeclarativeGeoMap::geometryChange(), QDeclarativeGeoMap::initialize(), QGeoRectangle::operator|=(), propagateCoordinate(), QDeclarativeGeoMap::setZoomLevel(), and QGeoCirclePrivate::updateBoundingBox().

+ Here is the caller graph for this function:

◆ setLongitude()

void QGeoCoordinate::setLongitude ( double longitude)

Sets the longitude (in decimal degrees) to longitude.

The value should be in the WGS84 datum.

To be valid, the longitude must be between -180 to 180 inclusive.

See also
longitude()

Definition at line 355 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::lng, and longitude.

Referenced by QGeoCirclePrivate::updateBoundingBox().

+ Here is the caller graph for this function:

◆ swap()

void QGeoCoordinate::swap ( QGeoCoordinate & other)
inlinenoexcept

Definition at line 58 of file qgeocoordinate.h.

References d, and other().

+ Here is the call graph for this function:

◆ toString()

QString QGeoCoordinate::toString ( CoordinateFormat format = DegreesMinutesSecondsWithHemisphere) const

Returns this coordinate as a string in the specified format.

For example, if this coordinate has a latitude of -27.46758, a longitude of 153.027892 and an altitude of 28.1, these are the strings returned depending on format:

\table \header

  • format value
  • Returned string \row
  • \l Degrees
  • -27.46758\unicode{0xB0}, 153.02789\unicode{0xB0}, 28.1m \row
  • \l DegreesWithHemisphere
  • 27.46758\unicode{0xB0} S, 153.02789\unicode{0xB0} E, 28.1m \row
  • \l DegreesMinutes
  • -27\unicode{0xB0} 28.054', 153\unicode{0xB0} 1.673', 28.1m \row
  • \l DegreesMinutesWithHemisphere
  • 27\unicode{0xB0} 28.054 S', 153\unicode{0xB0} 1.673' E, 28.1m \row
  • \l DegreesMinutesSeconds
  • -27\unicode{0xB0} 28' 3.2", 153\unicode{0xB0} 1' 40.4", 28.1m \row
  • \l DegreesMinutesSecondsWithHemisphere
  • 27\unicode{0xB0} 28' 3.2" S, 153\unicode{0xB0} 1' 40.4" E, 28.1m \endtable

The altitude field is omitted if no altitude is set.

If the coordinate is invalid, an empty string is returned.

Definition at line 527 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::alt, Degrees, DegreesMinutes, DegreesMinutesSeconds, DegreesMinutesSecondsWithHemisphere, DegreesMinutesWithHemisphere, DegreesWithHemisphere, QString::fromLatin1(), InvalidCoordinate, QGeoCoordinatePrivate::lat, QGeoCoordinatePrivate::lng, QString::number(), qAbs(), qIsNaN(), qRound(), QStringLiteral, and type().

+ Here is the call graph for this function:

◆ type()

QGeoCoordinate::CoordinateType QGeoCoordinate::type ( ) const

Returns the type of this coordinate.

Definition at line 294 of file qgeocoordinate.cpp.

References QGeoCoordinatePrivate::alt, Coordinate2D, Coordinate3D, InvalidCoordinate, QLocationUtils::isValidLat(), QLocationUtils::isValidLong(), QGeoCoordinatePrivate::lat, QGeoCoordinatePrivate::lng, and qIsNaN().

Referenced by azimuthTo(), distanceTo(), and toString().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ operator!=

bool QGeoCoordinate::operator!= ( const QGeoCoordinate & lhs,
const QGeoCoordinate & rhs )
friend

Returns true if latitude, longitude, or altitude of the lhs coordinate are not identical to those of the rhs coordinate.

Otherwise returns false.

Definition at line 64 of file qgeocoordinate.h.

◆ operator<< [1/2]

QDataStream & QGeoCoordinate::operator<< ( QDataStream & stream,
const QGeoCoordinate & coordinate )
friend

Writes the given coordinate to the specified stream.

See also
{Serializing Qt Data Types}

Definition at line 102 of file qgeocoordinate.h.

◆ operator<< [2/2]

QDebug operator<< ( QDebug dbg,
const QGeoCoordinate & coord )
friend

Definition at line 95 of file qgeocoordinate.h.

◆ operator==

bool QGeoCoordinate::operator== ( const QGeoCoordinate & lhs,
const QGeoCoordinate & rhs )
friend

Returns true if the latitude, longitude and altitude of the lhs coordinate are the same as those of the rhs coordinate.

Otherwise returns false.

The longitude will be ignored if the latitude is +/- 90 degrees.

Definition at line 60 of file qgeocoordinate.h.

◆ operator>>

QDataStream & QGeoCoordinate::operator>> ( QDataStream & stream,
QGeoCoordinate & coordinate )
friend

Reads a coordinate from the specified stream into the given coordinate.

See also
{Serializing Qt Data Types}

Definition at line 106 of file qgeocoordinate.h.

◆ QGeoCoordinatePrivate

friend class QGeoCoordinatePrivate
friend

Definition at line 92 of file qgeocoordinate.h.

◆ QQuickGeoCoordinateAnimation

friend class QQuickGeoCoordinateAnimation
friend

Definition at line 93 of file qgeocoordinate.h.

Property Documentation

◆ altitude

QGeoCoordinate::altitude
readwrite

This property holds the altitude in meters above sea level.

The property is undefined (\l {qQNaN()}) if the altitude has not been set.

While this property is introduced in Qt 5.5, the related accessor functions exist since the first version of this class.

Since
5.5

Definition at line 28 of file qgeocoordinate.h.

Referenced by QGeoCoordinate(), QWebMercator::coordinateInterpolation(), q_coordinateEastInterpolator(), q_coordinateShortestInterpolator(), q_coordinateWestInterpolator(), QHash< Key, T >::qHash(), setAltitude(), and QDeclarativePosition::setPosition().

◆ isValid

◆ latitude

QGeoCoordinate::latitude
readwrite

This property holds the latitude in decimal degrees.

The property is undefined (\l {qQNaN()}) if the latitude has not been set. A positive latitude indicates the Northern Hemisphere, and a negative latitude indicates the Southern Hemisphere. When setting the latitude the new value should be in the \l {http://en.wikipedia.org/wiki/World_Geodetic_System}{WGS84} datum format.

To be valid, the latitude must be between -90 to 90 inclusive.

While this property is introduced in Qt 5.5, the related accessor functions exist since the first version of this class.

Since
5.5

Definition at line 26 of file qgeocoordinate.h.

Referenced by QGeoCoordinate(), QGeoCoordinate(), QGeoRectanglePrivate::center(), QGeoRectanglePrivate::contains(), QGeoRectanglePrivate::extendRectangle(), QDeclarativeGeoMap::initialize(), QGeoRectangle::intersects(), QGeoRectanglePrivate::isEmpty(), QGeoRectanglePrivate::isValid(), QLocationUtils::metersPerPixel(), QGeoRectangle::operator|=(), QHash< Key, T >::qHash(), GeoCodingManagerEngineEsri::reverseGeocode(), QGeoCodingManagerEngineMapbox::reverseGeocode(), QGeoCodingManagerEngineNokia::reverseGeocode(), QGeoCodingManagerEngineOsm::reverseGeocode(), PlaceManagerEngineEsri::search(), QPlaceManagerEngineOsm::search(), QGeoRectangle::setBottomLeft(), QDeclarativeGeoMap::setCenter(), QGeoRectangle::setCenter(), setLatitude(), QDeclarativePosition::setPosition(), QGeoRectangle::setTopRight(), QDeclarativeGeoMap::setVisibleRegion(), QGeoCirclePrivate::updateBoundingBox(), and QGeoMapMapboxGLPrivate::updateSceneGraph().

◆ longitude

QGeoCoordinate::longitude
readwrite

This property holds the longitude in decimal degrees.

The property is undefined (\l {qQNaN()}) if the longitude has not been set. A positive longitude indicates the Eastern Hemisphere, and a negative longitude indicates the Western Hemisphere. When setting the longitude the new value should be in the \l {http://en.wikipedia.org/wiki/World_Geodetic_System}{WGS84} datum format.

To be valid, the longitude must be between -180 to 180 inclusive.

While this property is introduced in Qt 5.5, the related accessor functions exist since the first version of this class.

Since
5.5

Definition at line 27 of file qgeocoordinate.h.

Referenced by QGeoCoordinate(), QGeoCoordinate(), QGeoRectanglePrivate::center(), QGeoRectanglePrivate::contains(), QGeoCirclePrivate::crossNorthPole(), QGeoCirclePrivate::crossSouthPole(), QGeoRectanglePrivate::extendRectangle(), QGeoRectangle::intersects(), QGeoRectanglePrivate::isEmpty(), QGeoRectangle::operator|=(), QHash< Key, T >::qHash(), GeoCodingManagerEngineEsri::reverseGeocode(), QGeoCodingManagerEngineMapbox::reverseGeocode(), QGeoCodingManagerEngineNokia::reverseGeocode(), QGeoCodingManagerEngineOsm::reverseGeocode(), PlaceManagerEngineEsri::search(), QPlaceManagerEngineOsm::search(), QGeoRectangle::setBottomLeft(), QGeoRectangle::setCenter(), setLongitude(), QDeclarativePosition::setPosition(), QGeoRectangle::setTopRight(), updateBBox(), QGeoCirclePrivate::updateBoundingBox(), and QGeoMapMapboxGLPrivate::updateSceneGraph().


The documentation for this class was generated from the following files: