KPublicTransport

journey.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_JOURNEY_H
8#define KPUBLICTRANSPORT_JOURNEY_H
9
10#include "datatypes.h"
11#include "disruption.h"
12#include "individualtransport.h"
13#include "line.h"
14#include "load.h"
15#include "location.h"
16#include "path.h"
17#include "platform.h"
18#include "vehicle.h"
19
20#include <QDateTime>
21
22#include <vector>
23
24namespace KPublicTransport {
25
26class JourneySectionPrivate;
27class RentalVehicle;
28class Stopover;
29
30/** A segment of a journey plan. */
31class KPUBLICTRANSPORT_EXPORT JourneySection
32{
33 KPUBLICTRANSPORT_GADGET(JourneySection)
34
35public:
36 /** Mode of transport.
37 * These categories are fairly coarse, for a more detailed break-down of PublicTransport see Line::Mode.
38 */
39 enum Mode {
40 Invalid = 0,
41 PublicTransport = 1,
42 Transfer = 2,
43 Walking = 4,
44 Waiting = 8,
45 RentedVehicle = 16, ///< free floating or dock-based rental bike service, electric scooters, car sharing services, ie. any vehicle you drive yourself but that isn't your own
46 IndividualTransport = 32, ///< using your own vehicle (bike, car, etc).
47 };
48 Q_ENUM(Mode)
49 Q_DECLARE_FLAGS(Modes, Mode)
50 Q_FLAG(Modes)
51
52 /** Mode of transport for this section. */
53 KPUBLICTRANSPORT_PROPERTY(Mode, mode, setMode)
54
55 /** Planned departure time. */
56 KPUBLICTRANSPORT_PROPERTY(QDateTime, scheduledDepartureTime, setScheduledDepartureTime)
57 /** Actual departure time, if available.
58 * Set to invalid to indicate real-time data is not available.
59 */
60 KPUBLICTRANSPORT_PROPERTY(QDateTime, expectedDepartureTime, setExpectedDepartureTime)
61 /** @c true if this has real-time data. */
62 Q_PROPERTY(bool hasExpectedDepartureTime READ hasExpectedDepartureTime STORED false)
63 /** Difference to schedule in minutes. */
64 Q_PROPERTY(int departureDelay READ departureDelay STORED false)
65
66 /** Planned arrival time. */
67 KPUBLICTRANSPORT_PROPERTY(QDateTime, scheduledArrivalTime, setScheduledArrivalTime)
68 /** Actual arrival time, if available.
69 * Set to invalid to indicate real-time data is not available.
70 */
71 KPUBLICTRANSPORT_PROPERTY(QDateTime, expectedArrivalTime, setExpectedArrivalTime)
72 /** @c true if this has real-time data. */
73 Q_PROPERTY(bool hasExpectedArrivalTime READ hasExpectedArrivalTime STORED false)
74 /** Difference to schedule in minutes. */
75 Q_PROPERTY(int arrivalDelay READ arrivalDelay STORED false)
76
77 /** Duration of the section in seconds. */
78 Q_PROPERTY(int duration READ duration STORED false)
79 /** Distance of the section in meter. */
80 KPUBLICTRANSPORT_PROPERTY(int, distance, setDistance)
81
82 /** Departure location of this segment. */
83 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, from, setFrom)
84 /** Arrival location of this segment. */
85 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, to, setTo)
86 /** Route to take on this segment. */
87 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Route, route, setRoute)
88
89 /** Planned departure platform. */
90 KPUBLICTRANSPORT_PROPERTY(QString, scheduledDeparturePlatform, setScheduledDeparturePlatform)
91 /** Actual departure platform, in case real-time information are available. */
92 KPUBLICTRANSPORT_PROPERTY(QString, expectedDeparturePlatform, setExpectedDeparturePlatform)
93 /** @c true if real-time platform information are available. */
94 Q_PROPERTY(bool hasExpectedDeparturePlatform READ hasExpectedDeparturePlatform STORED false)
95 /** @c true if we have real-time platform information and the platform changed. */
96 Q_PROPERTY(bool departurePlatformChanged READ departurePlatformChanged STORED false)
97
98 /** Planned arrival platform. */
99 KPUBLICTRANSPORT_PROPERTY(QString, scheduledArrivalPlatform, setScheduledArrivalPlatform)
100 /** Actual arrival platform, in case real-time information are available. */
101 KPUBLICTRANSPORT_PROPERTY(QString, expectedArrivalPlatform, setExpectedArrivalPlatform)
102 /** @c true if real-time platform information are available. */
103 Q_PROPERTY(bool hasExpectedArrivalPlatform READ hasExpectedArrivalPlatform STORED false)
104 /** @c true if we have real-time platform information and the platform changed. */
105 Q_PROPERTY(bool arrivalPlatformChanged READ arrivalPlatformChanged STORED false)
106
107 /** Disruption effect on this section, if any. */
108 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Disruption::Effect, disruptionEffect, setDisruptionEffect)
109 /** General human-readable notes on this service, e.g. details about a disruption. */
110 KPUBLICTRANSPORT_PROPERTY(QStringList, notes, setNotes)
111
112 /** Intermediate stops for consumption by QML. */
113 Q_PROPERTY(QVariantList intermediateStops READ intermediateStopsVariant)
114
115 /** All departure information represented as Stopover object. */
116 Q_PROPERTY(KPublicTransport::Stopover departure READ departure STORED false)
117 /** All arrival information represented as Stopover object. */
118 Q_PROPERTY(KPublicTransport::Stopover arrival READ arrival STORED false)
119
120 /** CO₂ emission during this journey section, in gram.
121 * In case the backend doesn't provide this value, it is estimated based on the
122 * distance travelled during this section and the mode of transport, based on
123 * average emission values from https://en.wikipedia.org/wiki/Environmental_impact_of_transport
124 * This value can be 0 (e.g. in case of walk or wait sections), or -1 if no
125 * information is available.
126 */
127 KPUBLICTRANSPORT_PROPERTY(int, co2Emission, setCo2Emission)
128
129 /** Vehicle load information for this journey section.
130 * Contains LoadInfo objects for consumption by QML.
131 */
132 Q_PROPERTY(QVariantList loadInformation READ loadInformationVariant STORED false)
133
134 /** Information about a rental vehicle, for sections using one. */
135 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::RentalVehicle, rentalVehicle, setRentalVehicle)
136
137 /** Movement path for this journey section.
138 * This can be navigation instructions for individual transport modes and transfers,
139 * or the path a public transport vehicle takes.
140 */
141 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Path, path, setPath)
142
143 /** Vehicle coach layout information at departure. */
144 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Vehicle, departureVehicleLayout, setDepartureVehicleLayout)
145 /** Platform layout information at departure. */
146 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Platform, departurePlatformLayout, setDeparturePlatformLayout)
147 /** Vehicle coach layout information at arrival.
148 * Note that this does not necessarily need to be the same as departureVehicleLayout, as e.g. trains
149 * can be split up or merged along the way.
150 */
151 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Vehicle, arrivalVehicleLayout, setArrivalVehicleLayout)
152 /** Platform layout information at arrival. */
153 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Platform, arrivalPlatformLayout, setArrivalPlatformLayout)
154
155 /** Individual transport details for sections using your own vehicle. */
156 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::IndividualTransport, individualTransport, setIndividualTransport)
157
158 /** Features of the vehicle used on this section.
159 * This is identical to departureVehicleLayout.features and provided for convenience
160 * for cases where no more detailed vehicle information are available.
161 */
162 Q_PROPERTY(std::vector<KPublicTransport::Feature> features READ features)
163
164 /** The best available icon to represent this journey section.
165 * Can be a qrc: or file: URL or an XDG icon name.
166 */
167 Q_PROPERTY(QString iconName READ iconName STORED false)
168
169public:
170 [[nodiscard]] bool hasExpectedDepartureTime() const;
171 [[nodiscard]] int departureDelay() const;
172 [[nodiscard]] bool hasExpectedArrivalTime() const;
173 [[nodiscard]] int arrivalDelay() const;
174
175 [[nodiscard]] int duration() const;
176
177 [[nodiscard]] bool hasExpectedDeparturePlatform() const;
178 [[nodiscard]] bool departurePlatformChanged() const;
179 [[nodiscard]] bool hasExpectedArrivalPlatform() const;
180 [[nodiscard]] bool arrivalPlatformChanged() const;
181
182 /** Adds a note. This will check for duplicates and normalize the notes. */
183 void addNote(const QString &note);
184 void addNotes(const QStringList &notes);
185
186 /** Intermediate stop-overs along this journey section.
187 * This does not include the departure and arrival stops, and might be empty on backends not providing this information.
188 */
189 [[nodiscard]] const std::vector<Stopover>& intermediateStops() const;
190 /** Moves the intermediate stops out of this object. */
191 std::vector<Stopover>&& takeIntermediateStops();
192 /** Set the intermediate stops. */
193 void setIntermediateStops(std::vector<Stopover> &&stops);
194
195 /** Returns the departure stopover of this journey section.
196 * This is the same information as accessible by individual properties,
197 * so this is mainly useful if you have to interface with code expecting a Stopover object.
198 */
199 [[nodiscard]] Stopover departure() const;
200 /**
201 * Sets all departure properties from a given Stopover.
202 * This effects location and time, but doesn't modify intermediate stops or paths.
203 */
204 void setDeparture(const Stopover &departure);
205
206 /** Returns the arrival stopover of this journey section.
207 * This is the same information as accessible by individual properties,
208 * so this is mainly useful if you have to interface with code expecting a Stopover object.
209 */
210 [[nodiscard]] Stopover arrival() const;
211 /**
212 * Sets all arrival properties from a given Stopover.
213 * This effects location and time, but doesn't modify intermediate stops or paths.
214 */
215 void setArrival(const Stopover &arrival);
216
217 /** Vehicle load information for this journey section, if available. */
218 [[nodiscard]] const std::vector<LoadInfo>& loadInformation() const;
219 /** Moves the load information out of this object for modification. */
220 std::vector<LoadInfo>&& takeLoadInformation();
221 /** Set the vehicle load information for this journey section. */
222 void setLoadInformation(std::vector<LoadInfo>&& loadInfo);
223
224 /** Augment line meta data.
225 * @param download if set to @p true, trigger the download of locally missing assets.
226 */
227 void applyMetaData(bool download);
228
229 /** Checks if two instances refer to the same journey section (which does not necessarily mean they are exactly equal). */
230 [[nodiscard]] static bool isSame(const JourneySection &lhs, const JourneySection &rhs);
231
232 /** Merge two instances.
233 * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
234 */
235 [[nodiscard]] static JourneySection merge(const JourneySection &lhs, const JourneySection &rhs);
236
237 /** Serializes one journey section to JSON. */
238 [[nodiscard]] static QJsonObject toJson(const JourneySection &section);
239 /** Serializes a vector of journey sections to JSON. */
240 [[nodiscard]] static QJsonArray toJson(const std::vector<JourneySection> &sections);
241 /** Deserialize an object from JSON. */
242 [[nodiscard]] static JourneySection fromJson(const QJsonObject &obj);
243 /** Deserialize a vector of journey sections from JSON. */
244 [[nodiscard]] static std::vector<JourneySection> fromJson(const QJsonArray &array);
245
246 /** Vehicle features.
247 * This is identical to departureVehicleLayout.features and provided for convenience
248 * for cases where no more detailed vehicle information are available.
249 */
250 [[nodiscard]] const std::vector<KPublicTransport::Feature>& features() const;
251 [[nodiscard]] std::vector<KPublicTransport::Feature>&& takeFeatures();
252 void setFeatures(std::vector<KPublicTransport::Feature> &&features);
253
254 [[nodiscard]] QString iconName() const;
255
256private:
257 [[nodiscard]] QVariantList intermediateStopsVariant() const;
258 [[nodiscard]] QVariantList loadInformationVariant() const;
259};
260
261Q_DECLARE_OPERATORS_FOR_FLAGS(JourneySection::Modes)
262
263class JourneyPrivate;
264
265/** A journey plan. */
266class KPUBLICTRANSPORT_EXPORT Journey
267{
268 KPUBLICTRANSPORT_GADGET(Journey)
269 /** Journey sections for consumption by QML. */
270 Q_PROPERTY(QVariantList sections READ sectionsVariant)
271 /** Departure time of the journey, according to schedule. */
272 Q_PROPERTY(QDateTime scheduledDepartureTime READ scheduledDepartureTime STORED false)
273 /** @c true if this has real-time data. */
274 Q_PROPERTY(bool hasExpectedDepartureTime READ hasExpectedDepartureTime STORED false)
275 /** Actual departure time, if available.
276 * Set to invalid to indicate real-time data is not available.
277 */
278 Q_PROPERTY(QDateTime expectedDepartureTime READ expectedDepartureTime STORED false)
279 /** Difference to schedule in minutes. */
280 Q_PROPERTY(int departureDelay READ departureDelay STORED false)
281
282 /** Arrival time of the journey, according to schedule. */
283 Q_PROPERTY(QDateTime scheduledArrivalTime READ scheduledArrivalTime STORED false)
284 /** @c true if this has real-time data. */
285 Q_PROPERTY(bool hasExpectedArrivalTime READ hasExpectedArrivalTime STORED false)
286 /** Actual arrival time, if available.
287 * Set to invalid to indicate real-time data is not available.
288 */
289 Q_PROPERTY(QDateTime expectedArrivalTime READ expectedArrivalTime STORED false)
290 /** Difference to schedule in minutes. */
291 Q_PROPERTY(int arrivalDelay READ arrivalDelay STORED false)
292
293 /** Duration of the entire journey in seconds. */
294 Q_PROPERTY(int duration READ duration STORED false)
295 /** Number of changes on this journey. */
296 Q_PROPERTY(int numberOfChanges READ numberOfChanges STORED false)
297 /** Worst disruption effect of any of the journey sections. */
298 Q_PROPERTY(KPublicTransport::Disruption::Effect disruptionEffect READ disruptionEffect STORED false)
299
300public:
301 /** The journey sections. */
302 [[nodiscard]] const std::vector<JourneySection>& sections() const;
303 /** Moves the journey sections out of this object. */
304 [[nodiscard]] std::vector<JourneySection>&& takeSections();
305 /** Sets the journey sections. */
306 void setSections(std::vector<JourneySection> &&sections);
307
308 [[nodiscard]] QDateTime scheduledDepartureTime() const;
309 [[nodiscard]] bool hasExpectedDepartureTime() const;
310 [[nodiscard]] QDateTime expectedDepartureTime() const;
311 [[nodiscard]] int departureDelay() const;
312
313 [[nodiscard]] QDateTime scheduledArrivalTime() const;
314 [[nodiscard]] bool hasExpectedArrivalTime() const;
315 [[nodiscard]] QDateTime expectedArrivalTime() const;
316 [[nodiscard]] int arrivalDelay() const;
317
318 [[nodiscard]] int duration() const;
319 [[nodiscard]] int numberOfChanges() const;
320 [[nodiscard]] Disruption::Effect disruptionEffect() const;
321
322 /** Augment line meta data.
323 * @param download if set to @p true, trigger the download of locally missing assets.
324 */
325 void applyMetaData(bool download);
326
327 /** Checks if two instances refer to the same journey (which does not necessarily mean they are exactly equal). */
328 [[nodiscard]] static bool isSame(const Journey &lhs, const Journey &rhs);
329
330 /** Merge two instances.
331 * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
332 */
333 [[nodiscard]] static Journey merge(const Journey &lhs, const Journey &rhs);
334
335 /** Serializes one journey object to JSON. */
336 [[nodiscard]] static QJsonObject toJson(const Journey &journey);
337 /** Serializes a vector of journey objects to JSON. */
338 [[nodiscard]] static QJsonArray toJson(const std::vector<Journey> &journeys);
339 /** Deserialize an object from JSON. */
340 [[nodiscard]] static Journey fromJson(const QJsonObject &obj);
341 /** Deserialize a list of journey from JSON. */
342 [[nodiscard]] static std::vector<Journey> fromJson(const QJsonArray &array);
343
344private:
345 [[nodiscard]] QVariantList sectionsVariant() const;
346};
347
348}
349
350Q_DECLARE_METATYPE(KPublicTransport::JourneySection)
351Q_DECLARE_METATYPE(KPublicTransport::Journey)
352
353#endif // KPUBLICTRANSPORT_JOURNEY_H
An amenity, facility or other relevant property of a vehicle (train, bus, etc), vehicle part (e....
Definition feature.h:20
Individual transport mode details for a journey section, and for specifying journey requests.
A segment of a journey plan.
Definition journey.h:32
A journey plan.
Definition journey.h:267
Vehicle load information.
Definition load.h:38
A path followed by any kind of location change.
Definition path.h:101
Information about the layout of a station platform.
Definition platform.h:45
An individual rental vehicle used on a JourneySection, ie.
A route of a public transport line.
Definition line.h:146
Information about an arrival and/or departure of a vehicle at a stop area.
Definition stopover.h:26
Information about the vehicle used on a journey.
Definition vehicle.h:186
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 May 17 2024 11:47:54 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.