KPublicTransport

line.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_LINE_H
8#define KPUBLICTRANSPORT_LINE_H
9
10#include "datatypes.h"
11#include "location.h"
12
13namespace KPublicTransport {
14
15class Line;
16class LinePrivate;
17
18/** A public transport line. */
19class KPUBLICTRANSPORT_EXPORT Line
20{
21 KPUBLICTRANSPORT_GADGET(Line)
22
23public:
24 /** Mode of transportation.
25 * @toto direct copy from Navitia, we maybe can reduce that a bit
26 */
27 enum Mode {
28 Unknown,
29 Air,
30 Boat,
31 Bus,
32 Coach,
33 Ferry,
34 Funicular,
35 LocalTrain,
36 LongDistanceTrain,
37 Metro,
38 RailShuttle, ///< rail shuttle service within a complex, as e.g. found at or around airports
39 RapidTransit,
40 Shuttle, ///< shuttle bus/coach services, e.g. to/from an airport
41 Taxi,
42 Train,
43 Tramway,
44 RideShare, ///< peer-to-peer ride sharing/car pooling
45 AerialLift, ///< aerial cable cars, gondolas, etc
46 };
47 Q_ENUM(Mode)
48
49 /** Name of the line. */
50 KPUBLICTRANSPORT_PROPERTY(QString, name, setName)
51 /** Color of the line. */
52 KPUBLICTRANSPORT_PROPERTY(QColor, color, setColor)
53 /** @c true if a line color is set. */
54 Q_PROPERTY(bool hasColor READ hasColor STORED false)
55 /** Text color to use on top of the line color. */
56 KPUBLICTRANSPORT_PROPERTY(QColor, textColor, setTextColor)
57 /** @c true if a text color is set. */
58 Q_PROPERTY(bool hasTextColor READ hasTextColor STORED false)
59 /** Type of transport. */
60 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Line::Mode, mode, setMode)
61 /** Human readable representation of the type of transport.
62 * This is not necessarily a simple 1:1 mapping from mode, but can contain
63 * e.g. a product name.
64 */
65 KPUBLICTRANSPORT_PROPERTY(QString, modeString, setModeString)
66 /** Path of a local file containing the line logo.
67 * A line logo is typically a simple icon containing the short line name
68 * and color.
69 * This is downloaded on demand, and therefore might not be available
70 * immediately.
71 */
72 Q_PROPERTY(QString logo READ logo STORED false)
73 /** @c true if the line has a logo. */
74 Q_PROPERTY(bool hasLogo READ hasLogo STORED false)
75
76 /** Path of a local file containing the line mode logo.
77 * A mode logo is the logo of the mode of transportation, or "product"
78 * this line belongs to, such as the general logo for a subway or metro
79 * service of this operator or in this city.
80 * This is downloaded on demand, and therefore might not be available
81 * immediately.
82 */
83 Q_PROPERTY(QString modeLogo READ modeLogo STORED false)
84 /** @c true if the line has a mode logo. */
85 Q_PROPERTY(bool hasModeLogo READ hasModeLogo STORED false)
86
87 /** Name of the operator running this line. */
88 KPUBLICTRANSPORT_PROPERTY(QString, operatorName, setOperatorName)
89
90 /** Generic icon for the line mode.
91 * @see modeIconName(Line::Mode)
92 */
93 Q_PROPERTY(QString modeIconName READ modeIconName STORED false)
94
95 /** The best available icon for this line.
96 * Either the line logo, mode logo or generic mode icon.
97 * Can be a file: or qrc: URI or a XDG icon name.
98 *
99 * @note Line and product logos are full-color, the generic ones
100 * are monochrome colorable Breeze SVG icons.
101 */
102 Q_PROPERTY(QString iconName READ iconName STORED false)
103
104 /** @c true if @p mode is bound to rail tracks. */
105 Q_PROPERTY(bool isRailBound READ isRailBound STORED false)
106public:
107 [[nodiscard]] bool hasColor() const;
108 [[nodiscard]] bool hasTextColor() const;
109 [[nodiscard]] QString logo() const;
110 [[nodiscard]] bool hasLogo() const;
111 [[nodiscard]] QString modeLogo() const;
112 [[nodiscard]] bool hasModeLogo() const;
113 [[nodiscard]] QString modeIconName() const;
114 [[nodiscard]] QString iconName() const;
115
116 /** Name of an icon to represent @p mode.
117 * Can be an qrc: URL or a icon name compatbile with QIcon::fromTheme.
118 */
119 Q_INVOKABLE [[nodiscard]] static QString modeIconName(KPublicTransport::Line::Mode mode);
120
121 /** @c true if @p mode is bound to rail tracks. */
122 [[nodiscard]] static bool modeIsRailBound(KPublicTransport::Line::Mode mode);
123 [[nodiscard]] bool isRailBound() const;
124
125 /** Look up line meta data and apply what is found.
126 * @param location A location on or close to the line.
127 * @param download When set to @c true, not yet locally present logo URLs are retrieved.
128 */
129 void applyMetaData(const Location &location, bool download);
130
131 /** Checks if to instances refer to the same line (which does not necessarily mean they are exactly equal). */
132 [[nodiscard]] static bool isSame(const Line &lhs, const Line &rhs);
133
134 /** Merge two Line instances.
135 * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
136 */
137 [[nodiscard]] static Line merge(const Line &lhs, const Line &rhs);
138
139 /** Serializes one object to JSON. */
140 [[nodiscard]] static QJsonObject toJson(const Line &l);
141 /** Deserialize an object from JSON.
142 * @note Line meta data isn't serialized, so you might need to call applyLineMetaData() again
143 * after loading a line.
144 */
145 [[nodiscard]] static Line fromJson(const QJsonObject &obj);
146};
147
148class RoutePrivate;
149
150/** A route of a public transport line. */
151class KPUBLICTRANSPORT_EXPORT Route
152{
153 KPUBLICTRANSPORT_GADGET(Route)
154 /** Line this route belongs to. */
155 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Line, line, setLine)
156 /** Direction of the route.
157 * The direction of the the route is what is displayed on front of a train for example.
158 * For directional lines it matches the destination. For circular lines there is no destination
159 * however, the direction is then clockwise" for example.
160 */
161 KPUBLICTRANSPORT_PROPERTY(QString, direction, setDirection)
162 /** Destination of the route.
163 * If this is set it should match the direction of the line. Circular lines for example do
164 * not have a destination location though.
165 */
166 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, destination, setDestination)
167
168 /** Name of the route.
169 * This is not to be confused with the name of the line, which is the much more commonly used
170 * value. Use this only if both are in use and you know which one is which, otherwise default
171 * to the line name.
172 * @see Line::name.
173 */
174 KPUBLICTRANSPORT_PROPERTY(QString, name, setName)
175
176public:
177 /** Checks if to instances refer to the same route (which does not necessarily mean they are exactly equal). */
178 [[nodiscard]] static bool isSame(const Route &lhs, const Route &rhs);
179
180 /** Merge two Route instances.
181 * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
182 */
183 [[nodiscard]] static Route merge(const Route &lhs, const Route &rhs);
184
185 /** Serializes one object to JSON. */
186 [[nodiscard]] static QJsonObject toJson(const Route &r);
187 /** Deserialize an object from JSON. */
188 [[nodiscard]] static Route fromJson(const QJsonObject &obj);
189};
190
191}
192
193Q_DECLARE_METATYPE(KPublicTransport::Line)
194Q_DECLARE_METATYPE(KPublicTransport::Route)
195
196#endif // KPUBLICTRANSPORT_LINE_H
A public transport line.
Definition line.h:20
KPublicTransport::Line::Mode mode
Type of transport.
Definition line.h:60
bool hasTextColor
true if a text color is set.
Definition line.h:58
static Line fromJson(const QJsonObject &obj)
Deserialize an object from JSON.
Definition line.cpp:245
QString name
Name of the line.
Definition line.h:50
QString modeString
Human readable representation of the type of transport.
Definition line.h:65
bool hasLogo
true if the line has a logo.
Definition line.h:74
static Line merge(const Line &lhs, const Line &rhs)
Merge two Line instances.
Definition line.cpp:200
bool hasColor
true if a line color is set.
Definition line.h:54
QString operatorName
Name of the operator running this line.
Definition line.h:88
QColor color
Color of the line.
Definition line.h:52
QString modeIconName
Generic icon for the line mode.
Definition line.h:93
void applyMetaData(const Location &location, bool download)
Look up line meta data and apply what is found.
Definition line.cpp:222
QString logo
Path of a local file containing the line logo.
Definition line.h:72
QString iconName
The best available icon for this line.
Definition line.h:102
QColor textColor
Text color to use on top of the line color.
Definition line.h:56
QString modeLogo
Path of a local file containing the line mode logo.
Definition line.h:83
static QJsonObject toJson(const Line &l)
Serializes one object to JSON.
Definition line.cpp:236
Mode
Mode of transportation.
Definition line.h:27
@ RideShare
peer-to-peer ride sharing/car pooling
Definition line.h:44
@ RailShuttle
rail shuttle service within a complex, as e.g. found at or around airports
Definition line.h:38
@ Shuttle
shuttle bus/coach services, e.g. to/from an airport
Definition line.h:40
@ AerialLift
aerial cable cars, gondolas, etc
Definition line.h:45
bool hasModeLogo
true if the line has a mode logo.
Definition line.h:85
bool isRailBound
true if mode is bound to rail tracks.
Definition line.h:105
static bool modeIsRailBound(KPublicTransport::Line::Mode mode)
true if mode is bound to rail tracks.
Definition line.cpp:139
static bool isSame(const Line &lhs, const Line &rhs)
Checks if to instances refer to the same line (which does not necessarily mean they are exactly equal...
Definition line.cpp:172
A route of a public transport line.
Definition line.h:152
KPublicTransport::Location destination
Destination of the route.
Definition line.h:166
QString direction
Direction of the route.
Definition line.h:161
static bool isSame(const Route &lhs, const Route &rhs)
Checks if to instances refer to the same route (which does not necessarily mean they are exactly equa...
Definition line.cpp:271
QString name
Name of the route.
Definition line.h:174
static QJsonObject toJson(const Route &r)
Serializes one object to JSON.
Definition line.cpp:291
static Route merge(const Route &lhs, const Route &rhs)
Merge two Route instances.
Definition line.cpp:281
KPublicTransport::Line line
Line this route belongs to.
Definition line.h:155
static Route fromJson(const QJsonObject &obj)
Deserialize an object from JSON.
Definition line.cpp:304
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-2025 The KDE developers.
Generated on Fri Apr 25 2025 11:47:05 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.