KPublicTransport

location.h
1/*
2 SPDX-FileCopyrightText: 2018 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KPUBLICTRANSPORT_LOCATION_H
8#define KPUBLICTRANSPORT_LOCATION_H
9
10#include "datatypes.h"
11#include <QVariant>
12
13class QJsonArray;
14class QJsonObject;
15class QTimeZone;
16template <typename K, typename T> class QHash;
17
18namespace KPublicTransport {
19
20class LocationPrivate;
21class Equipment;
22class RentalVehicle;
23class RentalVehicleStation;
24
25/** A location.
26 * This can be a train station, a bus stop, a rental vehicle dock, a free-floating vehicle position,
27 * an elevator or escalator, etc.
28 */
29class KPUBLICTRANSPORT_EXPORT Location
30{
31 KPUBLICTRANSPORT_GADGET(Location)
32
33public:
34 /** Type of location. */
35 enum Type {
36 Place = 0, ///< a location that isn't of any specific type
37 Stop = 1, ///< a public transport stop (train station, bus stop, etc)
38 RentedVehicleStation = 2, ///< a pick-up/drop-off point for dock-based rental bike/scooter systems
39 RentedVehicle = 4, ///< a free-floating rental bike/scooter
40 Equipment = 8, ///< elevator/escalator
41 CarpoolPickupDropoff = 16, ///< a pickup or dropoff location for a carpool trip
42 Address = 32 ///< postal addresses
43 };
44 Q_ENUM(Type)
45 Q_DECLARE_FLAGS(Types, Type)
46 Q_FLAG(Types)
47
48 /** Location type. */
49 KPUBLICTRANSPORT_PROPERTY(Type, type, setType)
50
51 /** Human-readable name of the location. */
52 KPUBLICTRANSPORT_PROPERTY(QString, name, setName)
53 /** Latitude of the location, in degree, NaN if unknown. */
54 KPUBLICTRANSPORT_PROPERTY(double, latitude, setLatitude)
55 /** Longitude of the location, in degree, NaN if unknown. */
56 KPUBLICTRANSPORT_PROPERTY(double, longitude, setLongitude)
57
58 /** Street address of the location, if known. */
59 KPUBLICTRANSPORT_PROPERTY(QString, streetAddress, setStreetAddress)
60 /** Postal code of the location, if known. */
61 KPUBLICTRANSPORT_PROPERTY(QString, postalCode, setPostalCode)
62 /** Locality/city of the location, if known. */
63 KPUBLICTRANSPORT_PROPERTY(QString, locality, setLocality)
64 /** Region (as in ISO 3166-2) of the location, if known. */
65 KPUBLICTRANSPORT_PROPERTY(QString, region, setRegion)
66 /** Country of the location as ISO 3166-1 alpha 2 code, if known. */
67 KPUBLICTRANSPORT_PROPERTY(QString, country, setCountry)
68
69 Q_PROPERTY(bool hasCoordinate READ hasCoordinate STORED false)
70
71 /** OSM floor level of this location.
72 * Not set by default.
73 */
74 KPUBLICTRANSPORT_PROPERTY(int, floorLevel, setFloorLevel)
75 /** Indicates whether the floor level is set. */
76 Q_PROPERTY(bool hasFloorLevel READ hasFloorLevel STORED false)
77
78 /** Location type specific data.
79 * Depending on the location type this can be e.g. a RentalVehicleStation or an Equipment instance.
80 */
81 KPUBLICTRANSPORT_PROPERTY(QVariant, data, setData)
82
83 /** Rental vehicle dock information, if applicable for this location. */
84 Q_PROPERTY(KPublicTransport::RentalVehicleStation rentalVehicleStation READ rentalVehicleStation STORED false)
85 /** Rental vehicle information, if applicable for this location. */
86 Q_PROPERTY(KPublicTransport::RentalVehicle rentalVehicle READ rentalVehicle STORED false)
87 /** Equipment information, if applicable for this location. */
88 Q_PROPERTY(KPublicTransport::Equipment equipment READ equipment STORED false)
89
90 /** Icon representing the location type.
91 * Can be a qrc: URL or an XDG icon name.
92 */
93 Q_PROPERTY(QString iconName READ iconName STORED false)
94
95public:
96 void setCoordinate(double latitude, double longitude);
97 [[nodiscard]] bool hasCoordinate() const;
98 [[nodiscard]] bool hasFloorLevel() const;
99
100 /** Returns @c true if this is an default-constructed location object not specifying any location. */
101 [[nodiscard]] bool isEmpty() const;
102
103 /** The timezone this location is in, if known. */
104 [[nodiscard]] QTimeZone timeZone() const;
105 void setTimeZone(const QTimeZone &tz);
106
107 /** Location identifiers. */
108 Q_INVOKABLE [[nodiscard]] QString identifier(const QString &identifierType) const;
109 void setIdentifier(const QString &identifierType, const QString &id);
110 [[nodiscard]] bool hasIdentifier(const QString &identifierType) const;
111 [[nodiscard]] QHash<QString, QString> identifiers() const;
112
113 /** Checks if to instances refer to the same location (which does not necessarily mean they are exactly equal). */
114 [[nodiscard]] static bool isSame(const Location &lhs, const Location &rhs);
115 /** Checks if two location names refer to the same location. */
116 [[nodiscard]] static bool isSameName(const QString &lhs, const QString &rhs);
117
118 /** Merge two departure instances.
119 * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
120 */
121 [[nodiscard]] static Location merge(const Location &lhs, const Location &rhs);
122
123 /** Compute the distance between two geo coordinates, in meters. */
124 [[nodiscard]] static double distance(double lat1, double lon1, double lat2, double lon2);
125 /** Computes the distance in meters between two locations.
126 * Returns NAN if one of the arguments has no coordinates set.
127 */
128 [[nodiscard]] static double distance(const Location &lhs, const Location &rhs);
129
130 [[nodiscard]] RentalVehicleStation rentalVehicleStation() const;
131 [[nodiscard]] RentalVehicle rentalVehicle() const;
132 [[nodiscard]] KPublicTransport::Equipment equipment() const;
133
134 [[nodiscard]] QString iconName() const;
135
136 /** Serializes one Location object to JSON. */
137 [[nodiscard]] static QJsonObject toJson(const Location &loc);
138 /** Serializes an array of Location objects to JSON. */
139 [[nodiscard]] static QJsonArray toJson(const std::vector<Location> &locs);
140 /** Deserialize a Location object from JSON. */
141 [[nodiscard]] static Location fromJson(const QJsonObject &obj);
142 /** Dezerializes an array Location objects from JSON. */
143 [[nodiscard]] static std::vector<Location> fromJson(const QJsonArray &a);
144
145};
146
147Q_DECLARE_OPERATORS_FOR_FLAGS(Location::Types)
148
149}
150
151Q_DECLARE_METATYPE(KPublicTransport::Location)
152
153#endif // KPUBLICTRANSPORT_LOCATION_H
Status information about equipment such as elevators or escalators.
Definition equipment.h:25
Type
Type of location.
Definition location.h:35
Additional information for a vehicle renting station, attached to Location objects.
An individual rental vehicle used on a JourneySection, ie.
Query operations and data types for accessing realtime public transport information from online servi...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 8 2024 12:04:43 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.