KPublicTransport

path.h
1/*
2 SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KPUBLICTRANSPORT_PATH_H
8#define KPUBLICTRANSPORT_PATH_H
9
10#include "kpublictransport_export.h"
11#include "datatypes.h"
12
13#include <QPolygonF>
14
15namespace KPublicTransport {
16
17class PathSectionPrivate;
18
19/** A section of a Path.
20 * A path section consists of a poly-line of geo-coordinates to follow,
21 * an initial maneuver instructions as well as additional properties for
22 * this part of the path, such as the floor level.
23 */
24class KPUBLICTRANSPORT_EXPORT PathSection
25{
26 KPUBLICTRANSPORT_GADGET(PathSection)
27 /** The geo coordinate poly-line followed by this path section. */
28 KPUBLICTRANSPORT_PROPERTY(QPolygonF, path, setPath)
29 /** Human-readable description of this path segment. */
30 KPUBLICTRANSPORT_PROPERTY(QString, description, setDescription)
31
32 // TODO add more properties: maneuver instructions, floor level
33
34 /** The length of this path section in meters. */
35 Q_PROPERTY(int distance READ distance STORED false)
36 /** The overall direction of this section in degree. */
37 Q_PROPERTY(int direction READ direction STORED false)
38
39 /** Floor level change during this path section.
40 * Negative values indicate going down, positive values indicate going up
41 */
42 KPUBLICTRANSPORT_PROPERTY(int, floorLevelChange, setFloorLevelChange)
43
44public:
45 /** Maneuver associated with a path section. */
46 enum Maneuver {
47 Move, ///< Move/drive with the default mode of transport for this path
48 Stairs, ///< Walk up or down stairs
49 Elevator, ///< Take an elevator
50 Escalator, ///< Take an escalator
51 };
52 Q_ENUM(Maneuver)
53 /** Movement maneuver for this path section. */
54 KPUBLICTRANSPORT_PROPERTY(Maneuver, maneuver, setManeuver)
55
56 /** An icon representing the maneuver.
57 * Can be a qrc: URL or XDG icon name.
58 */
59 Q_PROPERTY(QString iconName READ iconName STORED false)
60
61public:
62 /** Length of this path section in meters. */
63 [[nodiscard]] int distance() const;
64 /** The overall direction of this section in degree.
65 * @returns 0-359 for valid results, -1 for sections with no direction (e.g. points).
66 */
67 [[nodiscard]] int direction() const;
68
69 /** First point on the path of this section. */
70 [[nodiscard]] QPointF startPoint() const;
71 /** Last point on the path of this section. */
72 [[nodiscard]] QPointF endPoint() const;
73
74 [[nodiscard]] QString iconName() const;
75
76 /** An icon representing @p maneuver.
77 * Can be a qrc: URL or XDG icon name.
78 */
79 Q_INVOKABLE [[nodiscard]] static QString maneuverIconName(KPublicTransport::PathSection::Maneuver maneuver);
80
81 /** Serializes one path section section to JSON. */
82 [[nodiscard]] static QJsonObject toJson(const PathSection &section);
83 /** Serializes a vector of path sections to JSON. */
84 [[nodiscard]] static QJsonArray toJson(const std::vector<PathSection> &sections);
85 /** Deserialize an object from JSON. */
86 [[nodiscard]] static PathSection fromJson(const QJsonObject &obj);
87 /** Deserialize a vector of path sections from JSON. */
88 [[nodiscard]] static std::vector<PathSection> fromJson(const QJsonArray &array);
89};
90
91class PathPrivate;
92
93/** A path followed by any kind of location change.
94 * This can be the way a train or bus takes, routing instructions
95 * for taking a rental vehicle, or instructions for transferring at
96 * a train station.
97 *
98 * A path consists of one or more PathSection.
99 */
100class KPUBLICTRANSPORT_EXPORT Path
101{
102 KPUBLICTRANSPORT_GADGET(Path)
103
104 /** Access to path sections for QML. */
105 Q_PROPERTY(std::vector<KPublicTransport::PathSection> sections READ sections)
106 /** Number of path sections for QML. */
107 Q_PROPERTY(int sectionCount READ sectionCount STORED false)
108
109 /** The length of this path in meters. */
110 Q_PROPERTY(int distance READ distance STORED false)
111
112public:
113 /** Returns @c true if this is an empty/not-set path. */
114 [[nodiscard]] bool isEmpty() const;
115
116 /** The path sections. */
117 [[nodiscard]] const std::vector<PathSection>& sections() const;
118 /** Moves the path sections out of this object. */
119 [[nodiscard]] std::vector<PathSection>&& takeSections();
120 /** Sets the path sections. */
121 void setSections(std::vector<PathSection> &&sections);
122
123 /** Length of this path in meters. */
124 [[nodiscard]] int distance() const;
125
126 /** First point on this path. */
127 [[nodiscard]] QPointF startPoint() const;
128 /** Last point on this path. */
129 [[nodiscard]] QPointF endPoint() const;
130
131 /** Serializes one path object to JSON. */
132 [[nodiscard]] static QJsonObject toJson(const Path &path);
133 /** Deserialize an object from JSON. */
134 [[nodiscard]] static Path fromJson(const QJsonObject &obj);
135
136private:
137 [[nodiscard]] int sectionCount() const;
138};
139
140}
141
142Q_DECLARE_METATYPE(KPublicTransport::PathSection)
143Q_DECLARE_METATYPE(std::vector<KPublicTransport::PathSection>)
144Q_DECLARE_METATYPE(KPublicTransport::Path)
145
146#endif // KPUBLICTRANSPORT_PATH_H
A section of a Path.
Definition path.h:25
Maneuver
Maneuver associated with a path section.
Definition path.h:46
@ Elevator
Take an elevator.
Definition path.h:49
@ Escalator
Take an escalator.
Definition path.h:50
@ Move
Move/drive with the default mode of transport for this path.
Definition path.h:47
@ Stairs
Walk up or down stairs.
Definition path.h:48
A path followed by any kind of location change.
Definition path.h:101
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 Jun 7 2024 12:05:22 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.