Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgscoordinateformatter.h
3 : : ------------------------
4 : : begin : Decemeber 2015
5 : : copyright : (C) 2015 by Nyall Dawson
6 : : email : nyall dot dawson at gmail dot com
7 : : ***************************************************************************/
8 : :
9 : : /***************************************************************************
10 : : * *
11 : : * This program is free software; you can redistribute it and/or modify *
12 : : * it under the terms of the GNU General Public License as published by *
13 : : * the Free Software Foundation; either version 2 of the License, or *
14 : : * (at your option) any later version. *
15 : : * *
16 : : ***************************************************************************/
17 : :
18 : : #ifndef QGSCOORDINATEFORMATTER_H
19 : : #define QGSCOORDINATEFORMATTER_H
20 : :
21 : : #include <QString>
22 : : #include "qgis_sip.h"
23 : : #include "qgspointxy.h"
24 : :
25 : : /**
26 : : * \ingroup core
27 : : * \class QgsCoordinateFormatter
28 : : * \brief Contains methods for converting coordinates for display in various formats.
29 : : *
30 : : * QgsCoordinateFormatter contains static methods for converting numeric coordinates into different
31 : : * formats, for instance as degrees, minutes, seconds values. Note that QgsCoordinateFormatter has
32 : : * no consideration for the validity of converting coordinates to the various display formats, and it
33 : : * is up to the caller to ensure that sensible formats are used for particular coordinates. For instance,
34 : : * ensuring that only geographic coordinates and not projected coordinates are formatted to degree
35 : : * based formats.
36 : : *
37 : : * \since QGIS 3.0
38 : : */
39 : :
40 : : class CORE_EXPORT QgsCoordinateFormatter
41 : : {
42 : : public:
43 : :
44 : : /**
45 : : * Available formats for displaying coordinates.
46 : : */
47 : : enum Format
48 : : {
49 : : FormatPair, //!< Formats coordinates as an "x,y" pair
50 : : FormatDegreesMinutesSeconds, //!< Degrees, minutes and seconds, eg 30 degrees 45'30"
51 : : FormatDegreesMinutes, //!< Degrees and decimal minutes, eg 30degrees 45.55'
52 : : FormatDecimalDegrees, //!< Decimal degrees, eg 30.7555 degrees
53 : : };
54 : :
55 : : /**
56 : : * Flags for controlling formatting of coordinates.
57 : : */
58 : : enum FormatFlag
59 : : {
60 : : FlagDegreesUseStringSuffix = 1 << 1, //!< Include a direction suffix (eg 'N', 'E', 'S' or 'W'), otherwise a "-" prefix is used for west and south coordinates
61 : : FlagDegreesPadMinutesSeconds = 1 << 2, //!< Pad minute and second values with leading zeros, eg '05' instead of '5'
62 : : };
63 : : Q_DECLARE_FLAGS( FormatFlags, FormatFlag )
64 : :
65 : : /**
66 : : * Formats an \a x coordinate value according to the specified parameters.
67 : : *
68 : : * The \a format argument indicates the desired display format for the coordinate.
69 : : *
70 : : * The \a precision argument gives the number of decimal places to include for coordinates.
71 : : *
72 : : * Optional \a flags can be specified to control the output format.
73 : : *
74 : : * \see formatY()
75 : : */
76 : : static QString formatX( double x, Format format, int precision = 12, FormatFlags flags = FlagDegreesUseStringSuffix );
77 : :
78 : : /**
79 : : * Formats a \a y coordinate value according to the specified parameters.
80 : : *
81 : : * The \a format argument indicates the desired display format for the coordinate.
82 : : *
83 : : * The \a precision argument gives the number of decimal places to include for coordinates.
84 : : *
85 : : * Optional \a flags can be specified to control the output format.
86 : : *
87 : : * \see formatX()
88 : : */
89 : : static QString formatY( double y, Format format, int precision = 12, FormatFlags flags = FlagDegreesUseStringSuffix );
90 : :
91 : : /**
92 : : * Formats a \a point according to the specified parameters.
93 : : *
94 : : * The \a format argument indicates the desired display format for the coordinate.
95 : : *
96 : : * The \a precision argument gives the number of decimal places to include for coordinates.
97 : : *
98 : : * Optional \a flags can be specified to control the output format.
99 : : */
100 : : static QString format( const QgsPointXY &point, Format format, int precision = 12, FormatFlags flags = FlagDegreesUseStringSuffix );
101 : :
102 : : /**
103 : : * Formats coordinates as an "\a x,\a y" pair, with optional decimal \a precision (number
104 : : * of decimal places to include).
105 : : */
106 : : static QString asPair( double x, double y, int precision = 12 );
107 : :
108 : : private:
109 : :
110 : : static QString formatAsPair( double val, int precision );
111 : :
112 : : static QString formatXAsDegreesMinutesSeconds( double val, int precision, FormatFlags flags );
113 : : static QString formatYAsDegreesMinutesSeconds( double val, int precision, FormatFlags flags );
114 : :
115 : : static QString formatXAsDegreesMinutes( double val, int precision, FormatFlags flags );
116 : : static QString formatYAsDegreesMinutes( double val, int precision, FormatFlags flags );
117 : :
118 : : static QString formatXAsDegrees( double val, int precision, FormatFlags flags );
119 : : static QString formatYAsDegrees( double val, int precision, FormatFlags flags );
120 : : };
121 : :
122 : 0 : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsCoordinateFormatter::FormatFlags )
123 : :
124 : : #endif // QGSCOORDINATEFORMATTER_H
|
