[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: [publictransport] /: Update documentation, split to separate files
From: Friedrich_Karl_Tilman_Pülz <fpuelz () gmx ! de>
Date: 2012-11-30 20:36:58
Message-ID: 20121130203658.A4563A60EA () git ! kde ! org
[Download RAW message or body]
Git commit e98eb5c341e97f3d81e086441cea33437129d9e2 by Friedrich Karl Tilman Pülz.
Committed on 30/11/2012 at 21:23.
Pushed by fkpulz into branch 'master'.
Update documentation, split to separate files
Use separate files (...-doc.h) for general documentation,
eg. @mainpage or @defgroup.
Rename scripting doxygen group to scriptApi.
Use the @{, @} doxygen commands to add script API classes
to the scriptApi group, instead of @ingroup everywhere.
Fix meta type for Tabs class, generate .moc file.
Fix deprecated documentation, doxygen references, etc.
A +328 -0 applet/applet-doc.h [License: LGPL (v2+)]
M +1 -311 applet/publictransport.h
A +1026 -0 engine/engine-doc.h [License: LGPL (v2+)]
M +114 -43 engine/enums.h
A +50 -0 engine/gtfs/gtfs-doc.h [License: LGPL (v2+)]
M +1 -953 engine/publictransportdataengine.h
A +38 -0 engine/script/script-doc.h [License: LGPL (v2+)]
M +0 -2 engine/script/script_thread.h
A +315 -0 engine/script/scriptapi-doc.h [License: LGPL (v2+)]
M +23 -314 engine/script/scripting.h
M +12 -11 engine/script/serviceproviderscript.h
M +2 -1 engine/timetablemate/src/CMakeLists.txt
M +2 -1 engine/timetablemate/src/tabs/CMakeLists.txt
M +3 -1 engine/timetablemate/src/tabs/tabs.h
M +1 -0 engine/timetablemate/src/tests/CMakeLists.txt
M +1 -1 libpublictransporthelper/CMakeLists.txt
http://commits.kde.org/publictransport/e98eb5c341e97f3d81e086441cea33437129d9e2
diff --git a/applet/applet-doc.h b/applet/applet-doc.h
new file mode 100644
index 0000000..09bd3c5
--- /dev/null
+++ b/applet/applet-doc.h
@@ -0,0 +1,328 @@
+/*
+* Copyright 2012 Friedrich Pülz <fpuelz@gmx.de>
+*
+* This program is free software; you can redistribute it and/or modify
+* it under the terms of the GNU Library General Public License as
+* published by the Free Software Foundation; either version 2 or
+* (at your option) any later version.
+*
+* This program is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+* GNU General Public License for more details
+*
+* You should have received a copy of the GNU Library General Public
+* License along with this program; if not, write to the
+* Free Software Foundation, Inc.,
+* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** @mainpage Public Transport Applet
+@section intro_applet_sec Introduction
+This applet shows a departure / arrival board for public transport, trains, ferries \
and planes. +Journeys can also be searched for. It uses the public transport data \
engine and has some advanced +configuration possibilities like filters, alarms and a \
flexible appearance. +
+@see models for more information about how the applet interacts with the \
PublicTransport data + engine and how the data is stored in models.
+@see filterSystem for more information about how the filters work.
+
+@section install_applet_sec Installation
+To install this applet type the following commands:<br>
+\> cd /path-to-extracted-applet-sources/build<br>
+\> cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..<br>
+\> make<br>
+\> make install<br>
+<br>
+After installation do the following to use the applet in your plasma desktop:
+Restart plasma to load the applet:<br>
+\> kquitapp plasma-desktop<br>
+\> plasma-desktop<br>
+<br>
+or test it with:<br>
+\> plasmoidviewer publictransport<br>
+<br>
+You might need to run kbuildsycoca4 in order to get the .desktop file recognized.
+*/
+
+/**
+* @defgroup models Models
+@brief Data gets retrieved from data engines, processed in a thread and stored in \
models. +
+The models used for storing public transport data are: @ref DepartureModel for \
departures/arrivals +and @ref JourneyModel for journeys. They are both based on @ref \
PublicTransportModel. +
+The applet uses five data engines: <em>publictransport</em>, <em>geolocation</em>,
+<em>openstreetmap</em> (to get stops near the user) and <em>favicons</em> (to get \
favicons from the +service providers).
+The publictransport data engine expects data source names in a specific format, \
which is explained +in detail in it's documentation. Here are some examples of what \
source names the applet generates +(based on the settings):
+@par
+<em>"Departures de_db|stop=Leipzig|timeOffset=5"</em> for departures from the \
service provider with +the ID "de_db", a stop named "Leipzig" and an offset (from \
now) in minutes for the first departure +of 5.
+@par
+<em>"Journeys de_db|originStop=Leipzig|targetStop=Bremen"</em> for journeys from the \
service +provider with the ID "de_db", an origin stop named "Leipzig" and a target \
stop named "Bremen". +
+@note The service provider ID <em>"de_db"</em> can be left away to use a default \
service provider + for the users country (from KDE's global settings).
+
+The format of the data structure returned from the data engine is again explained in \
detail in the +data engine's documentation (@ref pageUsage). It arrives in the slot
+@ref PublicTransport::dataUpdated. From there one of the following functions is \
called, based on +the data returned by the data engine:
+@par
+@ref PublicTransport::handleDataError, if the "error" key of the data structure is \
true, ie. there +was an error while running the query in the data engine (eg. server \
not reachable or an error in +the service provider while trying to parse the document \
from the server), +@par
+@ref PublicTransport::processStopSuggestions, if the "stops" key of the data \
structure contains +data, which can also happen if eg. "Departures" were queried for, \
but the stop name is ambigous, +@par
+@ref DepartureProcessor::processJourneys, @ref DepartureProcessor::processDepartures \
if there's +a "journeys", "departures" or "arrivals" key respectively. A new
+job is added to the background thread. The thread then reads the data and creates \
data structures +of type @ref DepartureInfo for departures/arrivals or @ref \
JourneyInfo for journeys. It also checks +for alarms and applies filters. That way \
complex filters and or many alarms applied to many +departures/arrivals won't freeze \
the applet. +
+Before beginning a new departure/arrival/journey job the thread emits a signal that \
is connected +to @ref PublicTransport::beginDepartureProcessing / @ref \
PublicTransport::beginJourneyProcessing. +Once a chunk of departures/arrivals is \
ready @ref PublicTransport::departuresProcessed gets called +through a signal/slot \
connection. In that function the processed departures are cached based on +the source \
name (but with date and time values stripped) and then the departure/arrival model \
gets +filled with them in @ref PublicTransport::fillModel. If journeys are ready
+@ref PublicTransport::journeysProcessed gets called by the thread, which calls
+@ref PublicTransport::fillModelJourney. If filter settings are changed the thread is \
used again to +run filters on the current data. Once the filter job is ready it calls
+@ref PublicTransport::departuresFiltered.
+
+The @ref PublicTransport::fillModel and @ref PublicTransport::fillModelJourney \
functions add, +update and/or remove items in the models. Both the departure/arrival \
and the journey model have +functions called @ref DepartureModel::indexFromInfo / \
@ref JourneyModel::indexFromInfo, which use +a hash generated from the data items \
(@ref DepartureInfo / @ref JourneyInfo) to quickly check, if +there already is an \
item in the model for a given data item. Hashes are generated automatically in +the \
constructors and can be retrieved using @ref PublicTransportInfo::hash. Two data \
items don't +have to be exactly equal to generade an equal hash. That is important to \
also find +departures/arrivals/journeys which data has changed since the last update, \
eg. departures with a +changed delay.
+
+@see filterSystem
+*/
+
+/**
+* @defgroup filterSystem Filter System
+@brief The applet has the possibility to filter departures/arrivals based on various \
constraints. +
+Those constraints are combined to filters using logical AND. Filters on the other \
hand can be +combined to filter lists using logical OR. The filter system is also \
used to match alarms. +
+The filtering is performed in classes described under @ref filter_classes_sec, while \
those filters +can be setup using widgets described under @ref filter_widgets_sec.
+
+@n
+@section filter_classes_sec Classes That Perform Filtering
+The lowest class in the hierarchy of filter classes is @ref Constraint, which \
describes a single +constraint which should match the departures/arrivals to be \
shown/hidden. One step higher +in the hierarchy comes the class @ref Filter, which is \
a list of constraints (combined using +logical AND). Another step higher comes @ref \
FilterList, which is a list of filters (combined +using logical OR). A @ref \
FilterList is wrapped by an object of type @ref FilterSettings together +with the \
@ref FilterAction (show or hide matching departures/arrivals), name and affected \
stops +for that filter configuration.
+
+Each @ref Constraint has a @ref FilterType, ie. what to filter with this constraint. \
For example +a constraint can filter departures/arrivals by the used vehicle type \
using @ref FilterByVehicleType. +Each @ref Constraint also has a @ref FilterVariant, \
eg. equals / doesn't equal. The used +@ref FilterVariant affects the way a constraint \
matches specific departures/arrivals. Last but not +least each @ref Constraint has a \
value. +So for example a constraint can be assembled like this: Filter by vehicle \
type, match +departures/arrivals that have the same value as stored in the \
constraint. +
+Filters can be serialized using toData() / fromData() methods.
+Filter widgets described in the next section can be easily created from these filter \
classes. +
+@n
+@section filter_widgets_sec Widgets for Editing Filters
+There are accompanying QWidget based classes for the filter classes from the \
previous section: +@par
+@ref ConstraintWidget for @ref Constraint, @ref FilterWidget for @ref Filter and
+@ref FilterListWidget for @ref FilterList. Filter widgets can be constructed from \
the filter +classes of the previous section.
+
+For each constraint data type there is a separate constraint widget class:
+@par
+@ref ConstraintListWidget to select values of a given list of values (eg. a list of \
vehicle types), +@par
+@ref ConstraintStringWidget to enter a string for matching (eg. matching \
intermediate stops), +@par
+@ref ConstraintIntWidget to enter an integer for matching and
+@par
+@ref ConstraintTimeWidget to enter a time for matching (eg. a departure time, used \
for alarms). +
+@ref FilterWidget uses @ref AbstractDynamicLabeledWidgetContainer as base class to \
allow dynamic +adding / removing of constraints. @ref FilterListWidget uses @ref \
AbstractDynamicWidgetContainer +to do the same with filters. Those base classes \
automatically add buttons to let the user +add / remove widgets. They are pretty \
flexible and will maybe end up in a library later for +reuse in other projects (like \
the publictransport runner). +*/
+
+/** @page pageClassDiagram Class Diagram
+@dot
+digraph publicTransportDataEngine {
+ ratio="compress";
+ size="10,100";
+ concentrate="true";
+ // rankdir="LR";
+ clusterrank=local;
+
+ node [
+ shape=record
+ fontname=Helvetica, fontsize=10
+ style=filled
+ fillcolor="#eeeeee"
+ ];
+
+ applet [
+ fillcolor="#ffdddd"
+ label="{PublicTransportApplet|Shows a departure / arrival list or a list of \
journeys.\l|+ dataUpdated( QString, Data ) : void\l# createTooltip() : void\l# \
updatePopupIcon() : void\l# processData( Data ) : void\l}" + URL="\ref \
PublicTransport" + ];
+
+ subgraph clusterWidgets {
+ label="Widgets";
+ style="rounded, filled";
+ color="#cceeee";
+ node [ fillcolor="#ccffff" ];
+
+ timetableWidget [
+ label="{TimetableWidget|Represents the departure/arrial board.\l}"
+ URL="\ref TimetableWidget"
+ ];
+
+ departureGraphicsItem [
+ label="{DepartureGraphicsItem|Represents one item in the departure/arrial \
board.\l}" + URL="\ref DepartureGraphicsItem"
+ ];
+
+ journeyTimetableWidget [
+ label="{JourneyTimetableWidget|Represents the journey board.\l}"
+ URL="\ref JourneyTimetableWidget"
+ ];
+
+ journeyGraphicsItem [
+ label="{JourneyGraphicsItem|Represents one item in the journey board.\l}"
+ URL="\ref JourneyGraphicsItem"
+ ];
+
+ titleWidget [
+ label="{TitleWidget|Represents the title of the applet.\l}"
+ URL="\ref TitleWidget"
+ ];
+
+ routeGraphicsItem [
+ label="{RouteGraphicsItem|Represents the route item in a departure/arrival \
item.\l}" + URL="\ref RouteGraphicsItem"
+ ];
+
+ journeyRouteGraphicsItem [
+ label="{JourneyRouteGraphicsItem|Represents the route item in a journey \
item.\l}" + URL="\ref JourneyRouteGraphicsItem"
+ ];
+ };
+
+ subgraph thread {
+ label="Background Thread";
+ style="rounded, filled";
+ color="#ffcccc";
+ node [ fillcolor="#ffdfdf" ];
+
+ departureProcessor [
+ label="{DepartureProcessor|Processes data from the data engine and applies \
filters/alarms.\l}" + URL="\ref DepartureProcessor"
+ ];
+ };
+
+ subgraph clusterSettings {
+ label="Settings";
+ style="rounded, filled";
+ color="#ccccff";
+ node [ fillcolor="#dfdfff" ];
+
+ settings [
+ label="{PublicTransportSettings|Manages the settings of the applet.\l}"
+ URL="\ref PublicTransportSettings"
+ ];
+
+ dataSourceTester [
+ label="{DataSourceTester|Tests a departure / arrival or journey data \
source \lat the public transport data engine.\l|+ setTestSource( QString ) : void\l+ \
testResult( TestResult, QVariant ) : void [signal] }" + URL="\ref \
DataSourceTester" + ];
+ };
+
+ subgraph clusterModels {
+ label="Models";
+ style="rounded, filled";
+ color="#ccffcc";
+ node [ fillcolor="#dfffdf" ];
+ rank="sink";
+
+ departureModel [
+ label="{DepartureModel|Stores information about a departures / \
arrivals.\l}" + URL="\ref DepartureModel"
+ ];
+
+ journeyModel [
+ label="{JourneyModel|Stores information about a journeys.\l}"
+ URL="\ref JourneyModel"
+ ];
+
+ departureItem [
+ label="{DepartureItem|Wraps DepartureInfo objects for \
DepartureModel.\l}" + URL="\ref DepartureItem"
+ ];
+
+ journeyItem [
+ label="{JourneyItem|Wraps JourneyInfo objects for JourneyModel.\l}"
+ URL="\ref JourneyItem"
+ ];
+
+ departureInfo [
+ label="{DepartureInfo|Stores information about a single departure / \
arrival.\l}" + URL="\ref DepartureInfo"
+ ];
+
+ journeyInfo [
+ label="{JourneyInfo|Stores information about a single journey.\l}"
+ URL="\ref JourneyInfo"
+ ];
+ };
+
+ edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="darkgray", + taillabel="", headlabel="0..*" ];
+ timetableWidget -> departureGraphicsItem [ label="uses" ];
+ journeyTimetableWidget -> journeyGraphicsItem [ label="uses" ];
+ departureModel -> departureItem [ label="uses" ];
+ journeyModel -> journeyItem [ label="uses" ];
+
+ edge [ dir=forward, arrowhead="none", arrowtail="normal", style="dashed", \
fontcolor="darkgray", + taillabel="1", headlabel="" ];
+ departureProcessor -> applet [ label="m_departureProcessor" ];
+ settings -> applet [ label="m_settings" ];
+ dataSourceTester -> settings [ label="m_dataSourceTester" ];
+
+ edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="darkgray", + taillabel="", headlabel="1" ];
+ applet -> timetableWidget [ label="m_timetable" ];
+ applet -> journeyTimetableWidget [ label="m_journeyTimetable" ];
+ applet -> titleWidget [ label="m_titleWidget" ];
+ applet -> departureModel [ label="m_model" ];
+ applet -> journeyModel [ label="m_modelJourneys" ];
+ departureItem -> departureInfo [ label="uses" ];
+ journeyItem -> journeyInfo [ label="uses" ];
+ departureGraphicsItem -> routeGraphicsItem [ label="uses" ];
+ journeyGraphicsItem -> journeyRouteGraphicsItem [ label="uses" ];
+}
+@enddot
+*/
diff --git a/applet/publictransport.h b/applet/publictransport.h
index 9a9604b..683f81b 100644
--- a/applet/publictransport.h
+++ b/applet/publictransport.h
@@ -631,314 +631,4 @@ private:
K_EXPORT_PLASMA_APPLET( publictransport, PublicTransportApplet )
#endif
-
-/** @mainpage Public Transport Applet
-@section intro_applet_sec Introduction
-This applet shows a departure / arrival board for public transport, trains, ferries \
and planes.
-Journeys can also be searched for. It uses the public transport data engine and has \
some advanced
-configuration possibilities like filters, alarms and a flexible appearance.
-
-@see models for more information about how the applet interacts with the \
PublicTransport data engine and how the data is stored in models.
-@see filterSystem for more information about how the filters work.
-
-@section install_applet_sec Installation
-To install this applet type the following commands:<br>
-\> cd /path-to-extracted-applet-sources/build<br>
-\> cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..<br>
-\> make<br>
-\> make install<br>
-<br>
-After installation do the following to use the applet in your plasma desktop:
-Restart plasma to load the applet:<br>
-\> kquitapp plasma-desktop<br>
-\> plasma-desktop<br>
-<br>
-or test it with:<br>
-\> plasmoidviewer publictransport<br>
-<br>
-You might need to run kbuildsycoca4 in order to get the .desktop file recognized.
-*/
-
-/**
-* @defgroup models Models
-@brief Data is retrieved from data engines (like the publictransport data engine), \
processed in a thread and stored in models.
-
-The models used for storing public transport data are: @ref DepartureModel for \
departures/arrivals
-and @ref JourneyModel for journeys. They are both based on @ref \
PublicTransportModel.
-
-The applet uses five data engines: <em>publictransport</em>, <em>geolocation</em>,
-<em>openstreetmap</em> (to get stops near the user), <em>favicons</em> (to get \
favicons from the
-service providers) and <em>network</em> (to check the network status).
-The publictransport data engine expects data source names in a specific format, \
which is explained
-in detail in it's documentation. Here are some examples of what source names the \
applet generates
-(based on the settings):
-@par
-<em>"Departures de_db|stop=Leipzig|timeOffset=5"</em> for departures from the \
service provider with
-the ID "de_db", a stop named "Leipzig" and an offset (from now) in minutes for the \
first departure
-of 5.
-@par
-<em>"Journeys de_db|originStop=Leipzig|targetStop=Bremen"</em> for journeys from the \
service
-provider with the ID "de_db", an origin stop named "Leipzig" and a target stop named \
"Bremen".
-
-@note The service provider ID <em>"de_db"</em> can be left away to use a default \
service provider
-for the users country (from KDE's global settings).
-
-The format of the data structure returned from the data engine is again explained in \
detail in the
-data engine's documentation (@ref pageUsage). It arrives in the slot
-@ref PublicTransport::dataUpdated. From there one of the following functions is \
called, based on
-the data returned by the data engine:
-@par
-@ref PublicTransport::handleDataError, if the "error" key of the data structure is \
true, ie. there
-was an error while running the query in the data engine (eg. server not reachable or \
an error in
-the service provider while trying to parse the document from the server),
-@par
-@ref PublicTransport::processStopSuggestions, if the "stops" key of the data \
structure contains data,
-which can also happen if eg. "Departures" were queried for, but the stop name is \
ambigous,
-@par
-@ref DepartureProcessor::processJourneys, @ref DepartureProcessor::processDepartures \
if there's
-a "journeys", "departures" or "arrivals" key respectively. A new
-job is added to the background thread. The thread then reads the data and creates \
data structures
-of type @ref DepartureInfo for departures/arrivals or @ref JourneyInfo for journeys. \
It also checks
-for alarms and applies filters. That way complex filters and or many alarms applied \
to many
-departures/arrivals won't freeze the applet.
-
-Before beginning a new departure/arrival/journey job the thread emits a signal that \
is connected
-to @ref PublicTransport::beginDepartureProcessing / @ref \
PublicTransport::beginJourneyProcessing.
-Once a chunk of departures/arrivals is ready @ref \
PublicTransport::departuresProcessed gets called
-through a signal/slot connection. In that function the processed departures are \
cached based on
-the source name (but with date and time values stripped) and then the \
departure/arrival model gets
-filled with them in @ref PublicTransport::fillModel. If journeys are ready
-@ref PublicTransport::journeysProcessed gets called by the thread, which calls
-@ref PublicTransport::fillModelJourney. If filter settings are changed the thread is \
used again to
-run filters on the current data. Once the filter job is ready it calls
-@ref PublicTransport::departuresFiltered.
-
-The @ref PublicTransport::fillModel and @ref PublicTransport::fillModelJourney \
functions add,
-update and/or remove items in the models. Both the departure/arrival and the journey \
model have
-functions called @ref DepartureModel::indexFromInfo / @ref \
JourneyModel::indexFromInfo, which use
-a hash generated from the data items (@ref DepartureInfo / @ref JourneyInfo) to \
quickly check, if
-there already is an item in the model for a given data item. Hashes are generated \
automatically in
-the constructors and can be retrieved using @ref PublicTransportInfo::hash. Two data \
items don't
-have to be exactly equal to generade an equal hash. That is important to also find
-departures/arrivals/journeys which data has changed since the last update, eg. \
departures with a
-changed delay.
-
-@see filterSystem
-*/
-
-/**
-* @defgroup filterSystem Filter System
-@brief The applet has the possibility to filter departures/arrivals based on various \
constraints.
-
-Those constraints are combined to filters using logical AND. Filters on the other \
hand can be
-combined to filter lists using logical OR. The filter system is also used to match \
alarms.
-
-The filtering is performed in classes described under @ref filter_classes_sec, while \
those filters
-can be setup using widgets described under @ref filter_widgets_sec.
-
-@n
-@section filter_classes_sec Classes That Perform Filtering
-The lowest class in the hierarchy of filter classes is @ref Constraint, which \
describes a single
-constraint which should match the departures/arrivals to be shown/hidden. One step \
higher
-in the hierarchy comes the class @ref Filter, which is a list of constraints \
(combined using
-logical AND). Another step higher comes @ref FilterList, which is a list of filters \
(combined
-using logical OR). A @ref FilterList is wrapped by an object of type @ref \
FilterSettings together
-with the @ref FilterAction (show or hide matching departures/arrivals), name and \
affected stops
-for that filter configuration.
-
-Each @ref Constraint has a @ref FilterType, ie. what to filter with this constraint. \
For example
-a constraint can filter departures/arrivals by the used vehicle type using @ref \
FilterByVehicleType.
-Each @ref Constraint also has a @ref FilterVariant, eg. equals / doesn't equal. The \
used
-@ref FilterVariant affects the way a constraint matches specific \
departures/arrivals. Last but not
-least each @ref Constraint has a value.
-So for example a constraint can be assembled like this: Filter by vehicle type, \
match
-departures/arrivals that have the same value as stored in the constraint.
-
-Filters can be serialized using toData() / fromData() methods.
-Filter widgets described in the next section can be easily created from these filter \
classes.
-
-@n
-@section filter_widgets_sec Widgets for Editing Filters
-There are accompanying QWidget based classes for the filter classes from the \
previous section:
-@par
-@ref ConstraintWidget for @ref Constraint, @ref FilterWidget for @ref Filter and
-@ref FilterListWidget for @ref FilterList. Filter widgets can be constructed from \
the filter
-classes of the previous section.
-
-For each constraint data type there is a separate constraint widget class:
-@par
-@ref ConstraintListWidget to select values of a given list of values (eg. a list of \
vehicle types),
-@par
-@ref ConstraintStringWidget to enter a string for matching (eg. matching \
intermediate stops),
-@par
-@ref ConstraintIntWidget to enter an integer for matching and
-@par
-@ref ConstraintTimeWidget to enter a time for matching (eg. a departure time, used \
for alarms).
-
-@ref FilterWidget uses @ref AbstractDynamicLabeledWidgetContainer as base class to \
allow dynamic
-adding / removing of constraints. @ref FilterListWidget uses @ref \
AbstractDynamicWidgetContainer
-to do the same with filters. Those base classes automatically add buttons to let the \
user
-add / remove widgets. They are pretty flexible and will maybe end up in a library \
later for
-reuse in other projects (like the publictransport runner).
-*/
-
-/** @page pageClassDiagram Class Diagram
-@dot
-digraph publicTransportDataEngine {
- ratio="compress";
- size="10,100";
- concentrate="true";
- // rankdir="LR";
- clusterrank=local;
-
- node [
- shape=record
- fontname=Helvetica, fontsize=10
- style=filled
- fillcolor="#eeeeee"
- ];
-
- applet [
- fillcolor="#ffdddd"
- label="{PublicTransportApplet|Shows a departure / arrival list or a list of \
journeys.\l|+ dataUpdated( QString, Data ) : void\l# createTooltip() : void\l# \
updatePopupIcon() : void\l# processData( Data ) : void\l}"
- URL="\ref PublicTransport"
- ];
-
- subgraph clusterWidgets {
- label="Widgets";
- style="rounded, filled";
- color="#cceeee";
- node [ fillcolor="#ccffff" ];
-
- timetableWidget [
- label="{TimetableWidget|Represents the departure/arrial board.\l}"
- URL="\ref TimetableWidget"
- ];
-
- departureGraphicsItem [
- label="{DepartureGraphicsItem|Represents one item in the departure/arrial \
board.\l}"
- URL="\ref DepartureGraphicsItem"
- ];
-
- journeyTimetableWidget [
- label="{JourneyTimetableWidget|Represents the journey board.\l}"
- URL="\ref JourneyTimetableWidget"
- ];
-
- journeyGraphicsItem [
- label="{JourneyGraphicsItem|Represents one item in the journey board.\l}"
- URL="\ref JourneyGraphicsItem"
- ];
-
- titleWidget [
- label="{TitleWidget|Represents the title of the applet.\l}"
- URL="\ref TitleWidget"
- ];
-
- routeGraphicsItem [
- label="{RouteGraphicsItem|Represents the route item in a departure/arrival \
item.\l}"
- URL="\ref RouteGraphicsItem"
- ];
-
- journeyRouteGraphicsItem [
- label="{JourneyRouteGraphicsItem|Represents the route item in a journey \
item.\l}"
- URL="\ref JourneyRouteGraphicsItem"
- ];
- };
-
- subgraph thread {
- label="Background Thread";
- style="rounded, filled";
- color="#ffcccc";
- node [ fillcolor="#ffdfdf" ];
-
- departureProcessor [
- label="{DepartureProcessor|Processes data from the data engine and applies \
filters/alarms.\l}"
- URL="\ref DepartureProcessor"
- ];
- };
-
- subgraph clusterSettings {
- label="Settings";
- style="rounded, filled";
- color="#ccccff";
- node [ fillcolor="#dfdfff" ];
-
- settings [
- label="{PublicTransportSettings|Manages the settings of the applet.\l}"
- URL="\ref PublicTransportSettings"
- ];
-
- dataSourceTester [
- label="{DataSourceTester|Tests a departure / arrival or journey data \
source \lat the public transport data engine.\l|+ setTestSource( QString ) : void\l+ \
testResult( TestResult, QVariant ) : void [signal] }"
- URL="\ref DataSourceTester"
- ];
- };
-
- subgraph clusterModels {
- label="Models";
- style="rounded, filled";
- color="#ccffcc";
- node [ fillcolor="#dfffdf" ];
- rank="sink";
-
- departureModel [
- label="{DepartureModel|Stores information about a departures / \
arrivals.\l}"
- URL="\ref DepartureModel"
- ];
-
- journeyModel [
- label="{JourneyModel|Stores information about a journeys.\l}"
- URL="\ref JourneyModel"
- ];
-
- departureItem [
- label="{DepartureItem|Wraps DepartureInfo objects for \
DepartureModel.\l}"
- URL="\ref DepartureItem"
- ];
-
- journeyItem [
- label="{JourneyItem|Wraps JourneyInfo objects for JourneyModel.\l}"
- URL="\ref JourneyItem"
- ];
-
- departureInfo [
- label="{DepartureInfo|Stores information about a single departure / \
arrival.\l}"
- URL="\ref DepartureInfo"
- ];
-
- journeyInfo [
- label="{JourneyInfo|Stores information about a single journey.\l}"
- URL="\ref JourneyInfo"
- ];
- };
-
- edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="darkgray",
- taillabel="", headlabel="0..*" ];
- timetableWidget -> departureGraphicsItem [ label="uses" ];
- journeyTimetableWidget -> journeyGraphicsItem [ label="uses" ];
- departureModel -> departureItem [ label="uses" ];
- journeyModel -> journeyItem [ label="uses" ];
-
- edge [ dir=forward, arrowhead="none", arrowtail="normal", style="dashed", \
fontcolor="darkgray",
- taillabel="1", headlabel="" ];
- departureProcessor -> applet [ label="m_departureProcessor" ];
- settings -> applet [ label="m_settings" ];
- dataSourceTester -> settings [ label="m_dataSourceTester" ];
-
- edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="darkgray",
- taillabel="", headlabel="1" ];
- applet -> timetableWidget [ label="m_timetable" ];
- applet -> journeyTimetableWidget [ label="m_journeyTimetable" ];
- applet -> titleWidget [ label="m_titleWidget" ];
- applet -> departureModel [ label="m_model" ];
- applet -> journeyModel [ label="m_modelJourneys" ];
- departureItem -> departureInfo [ label="uses" ];
- journeyItem -> journeyInfo [ label="uses" ];
- departureGraphicsItem -> routeGraphicsItem [ label="uses" ];
- journeyGraphicsItem -> journeyRouteGraphicsItem [ label="uses" ];
-}
-@enddot
-*/
-
-#endif
+#endif // Multiple inclusion guard
diff --git a/engine/engine-doc.h b/engine/engine-doc.h
new file mode 100644
index 0000000..8a8136c
--- /dev/null
+++ b/engine/engine-doc.h
@@ -0,0 +1,1026 @@
+/*
+* Copyright 2012 Friedrich Pülz <fpuelz@gmx.de>
+*
+* This program is free software; you can redistribute it and/or modify
+* it under the terms of the GNU Library General Public License as
+* published by the Free Software Foundation; either version 2 or
+* (at your option) any later version.
+*
+* This program is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+* GNU General Public License for more details
+*
+* You should have received a copy of the GNU Library General Public
+* License along with this program; if not, write to the
+* Free Software Foundation, Inc.,
+* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** @mainpage Public Transport Data Engine
+@section intro_dataengine_sec Introduction
+The public transport data engine provides timetable data for public transport, \
trains, ships, +ferries and planes. It can get departures/arrivals, journeys and stop \
suggestions. +There are different plugins (eg. scripts) used to get timetable data \
from the different +service providers. Currently there are two classes of service \
providers: One uses scripts to +do the work, the other one uses GTFS \
(GeneralTransitFeedSpecification). All are using information +from \
ServiceProviderData, which reads information data from "*.pts" files (XML files with \
mime type +"application-x-publictransport-serviceprovider").
+
+<br />
+@section install_sec Installation
+To install this data engine type the following commands:<br />
+@verbatim
+> cd /path-to-extracted-engine-sources/build
+> cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..
+> make
+> make install
+@endverbatim
+@note Do not forget the ".." at the end of the second line!
+
+After installation do the following to use the data engine in your plasma desktop:
+Restart plasma to load the data engine:<br />
+@verbatim
+> kquitapp plasma-desktop
+> plasma-desktop
+@endverbatim
+<br />
+or test it with:<br />
+@verbatim
+> plasmaengineexplorer --engine publictransport
+@endverbatim
+<br />
+You might need to run kbuildsycoca4 in order to get the .desktop file recognized.
+<br />
+
+<br />
+
+@section index_sec Other Pages
+@par
+ @li @ref pageUsage
+ @li @ref pageServiceProviders
+ @li @ref pageClassDiagram
+*/
+
+/** @page pageUsage Usage
+
+@par Sections
+<ul><li>@ref usage_introduction_sec </li>
+ <li>@ref usage_serviceproviders_sec </li>
+ <li>@ref usage_vehicletypes_sec </li>
+ <li>@ref usage_departures_sec </li>
+ <ul><li>@ref usage_departures_datastructure_sec </li></ul>
+ <li>@ref usage_journeys_sec </li>
+ <ul><li>@ref usage_journeys_datastructure_sec </li></ul>
+ <li>@ref usage_stopList_sec </li>
+ <ul><li>@ref usage_stopList_datastructure_sec </li></ul>
+ <li>@ref usage_service_sec </li>
+ <ul><li>@ref usage_service_manual_update </li>
+ <li>@ref usage_service_additional_data </li>
+ <li>@ref usage_service_later_items </li>
+ </ul>
+</ul>
+
+<br />
+
+@section usage_introduction_sec Introduction
+To use this data engine in an applet you need to connect it to a data source of the \
public +transport data engine. There are data sources which provide information about \
the available +service providers (@ref usage_serviceproviders_sec) or supported \
countries. Other data sources +contain departures/arrivals (@ref \
usage_departures_sec), journeys (@ref usage_journeys_sec) or +stop suggestions (@ref \
usage_stopList_sec).<br /> +The engine provides services for all timetable data \
sources (departures, journeys, ...). It offers +operations to manually request \
updates, request earlier/later timetable items or to request +additional data for \
specific timetable items (@ref usage_service_sec).<br /> +@note Since version 0.11 \
the engine will only match data source names with correct case, ie. \
+"serviceproViders" will not work any longer, but "ServiceProviders" will. All \
parameter names in +data source names need to be completely lower case. This is to \
prevent ambiguities, each variant +would get it's own data source object in the data \
engine, duplicating the data. To update a data +source all connected source name \
variants would need to be updated. Only accepting source names +case sensitive makes \
it much easier for the engine. The only thing left that can make two identic +data \
sources ambiguous is their parameter order, which gets handled using \
disambiguateSourceName(). +<br />
+The following enumeration can be used in your applet if you don't want to use
+libpublictransporthelper which exports this enumaration as @ref \
PublicTransport::VehicleType. +Don't change the numbers, as they need to match the \
ones in the data engine, which uses a similar +enumeration.
+@code
+// The type of the vehicle used for a public transport line.
+// The numbers here must match the ones in the data engine!
+enum VehicleType {
+ Unknown = 0, // The vehicle type is unknown
+
+ Tram = 1, // The vehicle is a tram
+ Bus = 2, // The vehicle is a bus
+ Subway = 3, // The vehicle is a subway
+ InterurbanTrain = 4, // The vehicle is an interurban train
+ Metro = 5, // The vehicle is a metro
+ TrolleyBus = 6, // A trolleybus (also known as trolley bus, trolley coach, \
trackless trolley, + // trackless tram or trolley) is an electric bus that \
draws its electricity from + // overhead wires (generally suspended from \
roadside posts) using spring-loaded + // trolley poles
+
+ RegionalTrain = 10, // The vehicle is a regional train
+ RegionalExpressTrain = 11, // The vehicle is a region express
+ InterregionalTrain = 12, // The vehicle is an interregional train
+ IntercityTrain = 13, // The vehicle is a intercity / eurocity train
+ HighspeedTrain = 14, // The vehicle is an intercity express (ICE, TGV?, ...?)
+
+ Ferry = 100, // The vehicle is a ferry
+ Ship = 101, // The vehicle is a ship
+
+ Plane = 200 // The vehicle is an aeroplane
+};
+@endcode
+
+<br />
+@section usage_serviceproviders_sec Receiving a List of Available Service Providers
+You can view this data source in @em plasmaengineexplorer, it's name is
+@em "ServiceProviders", but you can also use <em>"ServiceProvider [providerId]"</em> \
with the ID +of a service provider to get information only for that service provider.
+For each available service provider the data source contains a key with the display \
name of the +service provider. These keys point to the service provider information, \
stored as a QHash with +the following keys:
+<br />
+<table>
+<tr><td><i>id</i></td> <td>QString</td> <td>The ID of the service provider \
plugin.</td></tr> +<tr><td><i>fileName</i></td> <td>QString</td> <td>The file name of \
the XML file containing the +service provider information.</td> </tr>
+<tr><td><i>name</i></td> <td>QString</td> <td>The name of the service \
provider.</td></tr> +<tr><td><i>type</i></td> <td>QString</td> <td>The type of the \
provider plugin, may currently be +"GTFS", "Scripted" or "Invalid".</td></tr>
+<tr><td><i>feedUrl</i></td> <td>QString</td> <td><em>(only for type "GTFS")</em> The \
url to the +(latest) GTFS feed.</td></tr>
+<tr><td><i>scriptFileName</i></td> <td>QString</td> <td><em>(only for type \
"Scripted")</em> +The file name of the script used to parse documents from the \
service provider, if any.</td></tr> +<tr><td><i>url</i></td> <td>QString</td>
+<td>The url to the home page of the service provider.</td></tr>
+<tr><td><i>shortUrl</i></td> <td>QString</td> <td>A short version of the url to the \
home page +of the service provider. This can be used to display short links, while \
using "url" as the url +of that link.</td></tr>
+<tr><td><i>country</i></td> <td>QString</td> <td>The country the service provider is \
(mainly) +designed for.</td></tr>
+<tr><td><i>cities</i></td> <td>QStringList</td>
+<td>A list of cities the service provider supports.</td></tr>
+<tr><td><i>credit</i></td> <td>QString</td>
+<td>The ones who run the service provider (companies).</td></tr>
+<tr><td><i>useSeparateCityValue</i></td> <td>bool</td> <td>Wheather or not the \
service provider +needs a separate city value. If this is @c true, you need to \
specify a "city" parameter in data +source names for @ref usage_departures_sec and \
@ref usage_journeys_sec .</td></tr> +<tr><td><i>onlyUseCitiesInList</i></td> \
<td>bool</td> <td>Wheather or not the service provider +only accepts cities that are \
in the "cities" list.</td></tr> +<tr><td><i>features</i></td> <td>QStringList</td> \
<td>A list of strings, each string stands +for a feature of the service \
provider.</td></tr> +<tr><td><i>featureNames</i></td> <td>QStringList</td> <td>A list \
of localized names describing +which features the service provider offers.</td></tr>
+<tr><td><i>author</i></td> <td>QString</td> <td>The author of the service provider \
plugin.</td></tr> +<tr><td><i>email</i></td> <td>QString</td> <td>The email address \
of the author of the +service provider plugin.</td></tr>
+<tr><td><i>description</i></td> <td>QString</td>
+<td>A description of the service provider.</td></tr>
+<tr><td><i>version</i></td> <td>QString</td>
+<td>The version of the service provider plugin.</td></tr>
+
+<tr><td><i>error</i></td> <td>bool</td> <td>Whether or not the provider plugin has \
errors. +If this is @c true, the other fields except @em id are not available, \
instead a field +@em errorMessage is available explaining the error. If this if @c \
false, the provider did not +encounter any errors. But the provider may still not be \
ready to use, if the @em state field +contains a state string other than @em "ready". \
If no @em state field is available, the provider +can also be considered to be \
ready.</td></tr> +
+<tr><td><i>errorMessage</i></td> <td>QString</td> <td>A string explaining the error,
+only available if @em error is @c true. </td></tr>
+
+<tr><td><i>state</i></td> <td>QString</td>
+<td>A string to identify different provider states. Currently these states are \
available: +@em "ready" (the provider is ready to use), @em "gtfs_import_pending" (a \
GTFS +provider is waiting for the GTFS feed to get imported), @em \
"importing_gtfs_feed" (a GTFS +provider currently downloads and imports it's GTFS \
feed).<br /> +A provider can only be used to query for departures/arrivals, etc. if \
it's state is @em "ready" +and @em error is @c false.
+</td></tr>
+
+<tr><td><i>stateData</i></td> <td>QVariantHash</td> <td>Contains more information \
about the +current provider state in a QVariantHash. At least a @em statusMessage \
field is contained, +with a human readable string explaining the current state. There \
may also be a +@em statusMessageRich field with a formatted version of @em \
statusMessage. +Depending on the @em state additional fields may be available. For \
example with the +@em "importing_gtfs_feed" state a field @em progress is available.
+GTFS providers that are @em "ready" also offer these fields as state data:
+@em gtfsDatabasePath (the path to the GTFS database file), @em gtfsDatabaseSize
+(the size in bytes of the GTFS database).</td></tr>
+</table>
+<br />
+Here is an example of how to get service provider information for all available
+service providers:
+@code
+Plasma::DataEngine::Data data = \
dataEngine("publictransport")->query("ServiceProviders"); +foreach( QString \
serviceProviderName, data.keys() ) +{
+ QHash<QString, QVariant> serviceProviderData = \
data.value(serviceProviderName).toHash(); + int id = \
serviceProviderData["id"].toInt(); + // The name is already available in \
serviceProviderName + QString name = serviceProviderData["name"].toString();
+ QString country = serviceProviderData["country"].toString();
+ QStringList features = serviceProviderData["features"].toStringList();
+ bool useSeparateCityValue = \
serviceProviderData["useSeparateCityValue"].toBool(); + QString state = \
serviceProviderData["state"].toString(); +}
+@endcode
+
+There is also data source named <em>"ServiceProvider \
\<country-code|service-provider-id\>"</em> +to get information about the default \
service provider for the given country or about the given +provider with the given \
ID. +
+<br />
+@section usage_vehicletypes_sec Receiving Information About Available Vehicle Types
+Information about all available vehicle types can be retrieved from the data source
+@em "VehicleTypes". It stores vehicle type information by vehicle type ID, which \
matches +the values of the Enums::VehicleType (engine) and \
PublicTransport::VehicleType +(libpublictransporthelper) enumerations. The \
information stored in this data source can also be +retrieved from \
PublicTransport::VehicleType using libpublictransporthelper, ie. the static \
+functions of PublicTransport::Global. +For each vehicle type there are the following \
key/value pairs: +<br />
+<table>
+<tr><td><i>id</i></td> <td>QString</td> <td>An untranslated unique string \
identifying the vehicle +type. These strings match the names of the \
Enums::VehicleType enumerables.</td> </tr> +<tr><td><i>name</i></td> <td>QString</td> \
<td>The translated name of the vehicle type.</td></tr> \
+<tr><td><i>namePlural</i></td> <td>QString</td> <td>Like <i>name</i> but in plural \
form.</td></tr> +<tr><td><i>iconName</i></td> <td>QString</td> <td>The name of the \
icon associated with the +vehicle type. This name can be used as argument for the \
QIcon contructor.</td></tr> +</table>
+<br />
+Here is an example of how to get more information for a specific vehicle type by \
it's (integer) ID: +@code
+// This value can be retrieved from eg. a departures data source
+const int vehicleType;
+
+// Query the data engine for information about all available vehicle types
+Plasma::DataEngine::Data allVehicleTypes = \
dataEngine("publictransport")->query("VehicleTypes"); +
+// Extract the information
+const QVariantHash vehicleData = allVehicleTypes[ QString::number(vehicleType) \
].toHash(); +QString id = vehicleData["id"].toString();
+QString name = vehicleData["name"].toString();
+QString namePlural = vehicleData["namePlural"].toString();
+KIcon icon = KIcon( vehicleData["iconName"].toString() );
+@endcode
+
+<br />
+@section usage_departures_sec Receiving Departures or Arrivals
+To get a list of departures/arrivals you need to construct the name of the data \
source. For +departures it begins with "Departures", for arrivals it begins with \
"Arrivals". Next comes a +space (" "), then the ID of the service provider to use, \
e.g. "de_db" for db.de, a service provider +for germany ("Deutsche Bahn"). The \
following parameters are separated by "|" and start with the +parameter name followed \
by "=" and the value. The sorting of the additional parameters doesn't +matter. The \
parameter <i>stop</i> is needed and can be the stop name or the stop ID. If the \
service +provider has useSeparateCityValue set to @c true (see @ref \
usage_serviceproviders_sec), the +parameter <i>city</i> is also needed (otherwise it \
is ignored). +You can leave the service provider ID away, the data engine then uses \
the default service provider +for the users country.<br />
+@note All parameter names need to be completely lower case.
+The following parameters are allowed:<br />
+<table>
+<tr><td><i>stop</i></td> <td>The name or ID of the stop to get departures/arrivals \
for.</td></tr> +<tr><td><i>city</i></td> <td>The city to get departures/arrivals for, \
if needed.</td></tr> +<tr><td><i>count</i></td> <td>The number of departures/arrivals \
to get. + @note This is just a hint for the provider.</td></tr>
+<tr><td><i>timeoffset</i></td> <td>The offset in minutes from now for the first \
departure / +arrival to get.</td></tr>
+<tr><td><i>time</i></td> <td>The time of the first departure/arrival to get \
("hh:mm"). This uses +the current date. To use another date use 'datetime'.</td></tr>
+<tr><td><i>datetime</i></td> <td>The date and time of the first departure/arrival to \
get (use +QDateTime::toString()).</td></tr>
+</table>
+<br />
+
+<b>Examples:</b><br />
+<b>"Departures de_db|stop=Pappelstraße, Bremen"</b><br />
+Gets departures for the stop "Pappelstraße, Bremen" using the service provider \
db.de.<br /><br /> +
+<b>"Arrivals de_db|stop=Leipzig|timeoffset=5|count=99"</b><br />
+Gets arrivals for the stop "Leipzig" using db.de, the first possible arrival is in \
five minutes +from now, the maximum arrival count is 99.<br /><br />
+
+<b>"Departures de_rmv|stop=Frankfurt (Main) Speyerer Straße|time=08:00"</b><br />
+Gets departures for the stop "Frankfurt (Main) Speyerer Straße" using rmv.de, the \
first possible +departure is at eight o'clock.<br /><br />
+
+<b>"Departures de_rmv|stop=3000019|count=20|timeoffset=1"</b><br />
+Gets departures for the stop with the ID "3000019", the first possible departure is \
in one minute +from now, the maximum departure count is 20.<br /><br />
+
+<b>"Departures stop=Hauptbahnhof"</b><br />
+Gets departures for the stop "Hauptbahnhof" using the default service provider for \
the users +country, if there is one.<br /><br />
+
+Once you have the data source name, you can connect your applet to that data source \
from the data +engine. Here is an example of how to do this:
+@code
+class Applet : public Plasma::Applet {
+public:
+ Applet(QObject *parent, const QVariantList &args) : AppletWithState(parent, \
args) { + dataEngine("publictransport")->connectSource( "Departures \
de_db|stop=Köln, Hauptbahnhof", + \
this, 60 * 1000 ); + };
+
+public slots:
+ void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data \
&data ) { + if ( data.value("error").toBool() ) {
+ // Handle errors
+ } else if ( data.contains("stops") ) {
+ // Possible stop list received, because the given stop name is ambiguous
+ // See section "Receiving Stop Lists"
+ } else {
+ // Departures / arrivals received.
+ QVariantList departures = data.contains("departures")
+ ? data["departures"].toList() : data["arrivals"].toList();
+
+ foreach ( const QVariant &departureData, departures ) {
+ QHash<QString, QVariant> departure = departureData.toHash();
+ QString line = departure["TransportLine"].toString();
+ // For arrival lists this is the origin
+ QString target = departure["Target"].toString();
+ QDateTime departure = departure["DepartureDateTime"].toDateTime();
+ }
+ }
+ };
+};
+@endcode
+<br />
+@subsection usage_departures_datastructure_sec Departure Data Source Structure
+The data received from the data engine always contains these keys:<br />
+<table>
+<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr> +<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if \
@em error is @c true), +an error message string.</td></tr>
+<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code. + Error code 1 means, that there was a problem downloading a source \
file. + Error code 2 means, that parsing a source file failed.
+ Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it. + Use the @ref PublicTransportService to start and monitor the \
import.</td></tr> +<tr><td><i>receivedData</i></td> <td>QString</td> \
<td>"departures", "journeys", "stopList" or +"nothing" if there was an \
error.</td></tr> +<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and \
time when the data source was +last updated.</td></tr>
+<tr><td><i>nextAutomaticUpdate</i></td> <td>QDateTime</td> <td>The date and time of \
the next +automatic update of the data source.</td></tr>
+<tr><td><i>minManualUpdateTime</i></td> <td>QDateTime</td> <td>The minimal date and \
time to request +an update using the "requestUpdate" operation of the timetable \
service.</td></tr> +<tr><td><i>departures</i> or <i>arrivals</i></td> \
<td>QVariantList</td> +<td>A list of all found departures/arrivals.</td></tr>
+</table>
+<br />
+
+Each departure/arrival in the data received from the data engine (departureData in \
the code +example) has the following keys:<br />
+<table>
+<tr><td><i>TransportLine</i></td> <td>QString</td> <td>The name of the public \
transport line, +e.g. "S1", "6", "1E", "RB 24155".</td></tr>
+<tr><td><i>Target</i></td> <td>QString</td> <td>The name of the target / origin of \
the public +transport line.</td></tr>
+<tr><td><i>DepartureDateTime</i></td> <td>QDateTime</td> <td>The date and time of \
the +departure / arrival.</td></tr>
+<tr><td><i>TypeOfVehicle</i></td> <td>int</td> <td>An integer containing the ID of \
the vehicle type +used for the departure/arrival. When you are using \
libpublictransporthelper, you can cast this ID +to PublicTransport::VehicleType and \
get more information about the vehicle type using the static +functions of \
PublicTransport::Global. Alternatively you can use the "VehicleTypes" data source, \
+it stores vehicle type information in a hash with vehicle type ID's as keys. +See \
also @ref usage_vehicletypes_sec. </td></tr> +<tr><td><i>Nightline</i></td> \
<td>bool</td> <td>Wheather or not the public transport line +is a night \
line.</td></tr> +<tr><td><i>Expressline</i></td> <td>bool</td> <td>Wheather or not \
the public transport line +is an express line.</td></tr>
+<tr><td><i>Platform</i></td> <td>QString</td> <td>The platform from/at which the \
vehicle +departs/arrives.</td></tr>
+<tr><td><i>Delay</i></td> <td>int</td> <td>The delay in minutes, 0 means 'on \
schedule', +-1 means 'no delay information available'.</td></tr>
+<tr><td><i>DelayReason</i></td> <td>QString</td> <td>The reason of a \
delay.</td></tr> +<tr><td><i>Status</i></td> <td>QString</td> <td>The status of the \
departure, if available.</td></tr> +<tr><td><i>JourneyNews</i></td> <td>QString</td> \
<td>News for the journey.</td></tr> +<tr><td><i>Operator</i></td> <td>QString</td>
+<td>The company that is responsible for the journey.</td></tr>
+<tr><td><i>RouteStops</i></td> <td>QStringList</td> <td>A list of stops of the \
departure/arrival +to it's destination stop or a list of stops of the journey from \
it's start to it's destination stop. +If 'routeStops' and 'routeTimes' are both set, \
they contain the same number of elements. +And elements with equal indices are \
associated (the times at which the vehicle is at the stops). +</td></tr>
+<tr><td><i>RouteTimes</i></td> <td>QList< QTime > (stored as QVariantList)</td>
+<td>A list of times of the departure/arrival to it's destination stop. If \
'routeStops' and +'routeTimes' are both set, they contain the same number of \
elements. And elements with +equal indices are associated (the times at which the \
vehicle is at the stops).</td></tr> +<tr><td><i>RouteExactStops</i></td> <td>int</td> \
<td>The number of exact route stops. +The route stop list is not complete from the \
last exact route stop.</td></tr> +</table>
+
+@note The service provider may not load all data by default. To load missing data
+ ("additional data"), use the timetable service's operation \
"requestAdditionalData", + @ref usage_service_sec.
+
+<br />
+@section usage_journeys_sec Receiving Journeys from A to B
+To get a list of journeys from one stop to antoher you need to construct the name of \
the data +source (much like the data source for departures / arrivals). The data \
source name begins with +"Journeys". Next comes a space (" "), then the ID of the \
service provider to use, e.g. "de_db" +for db.de, a service provider for germany \
("Deutsche Bahn"). +The following parameters are separated by "|" and start with the \
parameter name followed by "=". +The sorting of the additional parameters doesn't \
matter. The parameters <i>originstop</i> and +<i>targetstop</i> are needed and can be \
the stop names or the stop IDs. If the service provider +has useSeparateCityValue set \
to @c true (see @ref usage_serviceproviders_sec), the parameter +<i>city</i> is also \
needed (otherwise it is ignored).<br /> +@note All parameter names need to be \
completely lower case. +The following parameters are allowed:<br />
+<table>
+<tr><td><i>originstop</i></td> <td>The name or ID of the origin stop.</td></tr>
+<tr><td><i>targetstop</i></td> <td>The name or ID of the target stop.</td></tr>
+<tr><td><i>city</i></td> <td>The city to get journeys for, if needed.</td></tr>
+<tr><td><i>count</i></td> <td>The number of journeys to get.
+ @note This is just a hint for the provider</td></tr>
+<tr><td><i>timeoffset</i></td>
+<td>The offset in minutes from now for the first journey to get.</td></tr>
+<tr><td><i>time</i></td> <td>The time for the first journey to get (in format \
"hh:mm").</td></tr> +<tr><td><i>datetime</i></td> <td>The date and time for the first \
journey to get +(QDateTime::fromString() is used with default parameters to parse the \
date).</td></tr> +</table>
+<br />
+
+<b>Examples:</b><br />
+<b>"Journeys de_db|originstop=Pappelstraße, Bremen|targetstop=Kirchweg, \
Bremen"</b><br /> +Gets journeys from stop "Pappelstraße, Bremen" to stop "Kirchweg, \
Bremen" +using the service provider db.de.<br /><br />
+
+<b>"Journeys de_db|originstop=Leipzig|targetstop=Hannover|timeoffset=5|count=99"</b><br \
/> +Gets journeys from stop "Leipzig" to stop "Hannover" using db.de, the first
+possible journey departs in five minutes from now, the maximum journey count is \
99.<br /><br /> +
+Once you have the data source name, you can connect your applet to that
+data source from the data engine. Here is an example of how to do this:
+@code
+class Applet : public Plasma::Applet {
+public:
+ Applet(QObject *parent, const QVariantList &args) : AppletWithState(parent, \
args) { + dataEngine("publictransport")->connectSource(
+ "Journeys de_db|originstop=Pappelstraße, \
Bremen|targetstop=Kirchweg, Bremen", + this, 60 * 1000 );
+ };
+
+public slots:
+ void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data \
&data ) { + if ( data.value("error").toBool() ) {
+ // Handle errors
+ } else if ( data.contains("stops") ) {
+ // Possible stop list received, because the given stop name is ambiguous
+ // See section "Receiving Stop Lists"
+ } else {
+ // Journeys received.
+ QVariantList journeysData = data["journeys"].toList();
+ foreach ( const QVariant &journeyData, journeysData ) {
+ QHash<QString, QVariant> journey = journeyData.toHash();
+
+ // Get vehicle type list
+ QVariantList = journey["TypesOfVehicleInJourney"].toList();
+ QList< PublicTransport::VehicleType > vehicleTypes;
+ foreach( QVariant vehicleType, vehicleTypesVariant ) {
+ vehicleTypes.append(
+ static_cast< PublicTransport::VehicleType >( \
vehicleType.toInt() ) ); + }
+
+ QString target = journey["StartStopName"].toString();
+ QDateTime departure = journey["DepartureDateTime"].toDateTime();
+ int duration = journey["Duration"].toInt(); // Duration in minutes
+ }
+ }
+ };
+};
+@endcode
+<br />
+@subsection usage_journeys_datastructure_sec Journey Data Source Structure
+The data received from the data engine always contains these keys:<br />
+<table>
+<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr> +<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if \
@em error is @c true), +an error message string.</td></tr>
+<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code. + Error code 1 means, that there was a problem downloading a source \
file. + Error code 2 means, that parsing a source file failed.
+ Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it. + Use the @ref PublicTransportService to start and monitor the \
import.</td></tr> +<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and \
time when the data source was +last updated.</td></tr>
+<tr><td><i>journeys</i></td> <td>QVariantList</td> <td>A list of all found \
journeys.</td></tr> +</table>
+<br />
+Each journey in the data received from the data engine (journeyData in the code
+example) has the following keys:<br />
+<i>vehicleTypes</i>: A QVariantList containing a list of vehicle type ID's \
(integers) of vehicles +used in the journey. You can cast the list to \
QList<PublicTransport::VehicleType> as seen in the +code example above \
(QVariantList), if you use libpublictransporthelper. Alternatively the \
+"VehicleTypes" data source can be used to get more information about the vehicle \
types. +See also @ref usage_vehicletypes_sec. <br />
+<table>
+<tr><td><i>ArrivalDateTime</i></td> <td>QDateTime</td> <td>The date and time of the \
arrival +at the target stop.</td></tr>
+<tr><td><i>DepartureDateTime</i></td> <td>QDateTime</td> <td>The date and time of \
the departure +from the origin stop.</td></tr>
+<tr><td><i>Duration</i></td> <td>int</td> <td>The duration in minutes of the \
journey.</td></tr> +<tr><td><i>Changes</i></td> <td>int</td>
+<td>The changes between vehicles needed for the journey.</td></tr>
+<tr><td><i>Pricing</i></td> <td>QString</td>
+<td>Information about the pricing of the journey.</td></tr>
+<tr><td><i>JourneyNews</i></td> <td>QString</td> <td>News for the journey.</td></tr>
+<tr><td><i>StartStopName</i></td> <td>QString</td> <td>The name or ID of the origin \
stop.</td></tr> +<tr><td><i>TargetStopName</i></td> <td>QString</td>
+<td>The name or ID of the target stop (QString).</td></tr>
+<tr><td><i>Operator</i></td> <td>QString</td>
+<td>The company that is responsible for the journey.</td></tr>
+<tr><td><i>RouteStops</i></td> <td>QStringList</td> <td>A list of stops of the \
journey +from it's start to it's destination stop. If 'routeStops' and 'routeTimes' \
are both set, +they contain the same number of elements. And elements with equal \
indices are associated +(the times at which the vehicle is at the stops).</td></tr>
+<tr><td><i>RouteNews</i></td> <td>QStringList</td> <td>A list of news/comments for \
sub-journeys. +If 'RouteStops' and 'RouteNews' are both set, the latter contains one \
element less +(one news/comment string for each sub-journey between two stop from \
'RouteStops').</td></tr> +<tr><td><i>RouteTimesDeparture</i></td> <td>QList< QTime > \
(stored as QVariantList)</td> +<td>A list of departure times of the journey to it's \
destination stop. If 'routeStops' and +'routeTimesDeparture' are both set, the latter \
contains one element less (because the last stop +has no departure, only an arrival \
time). Elements with equal indices are associated +(the times at which the vehicle \
departs from the stops).</td></tr> +<tr><td><i>RouteTimesArrival</i></td> <td>QList< \
QTime > (stored as QVariantList)</td> +<td>A list of arrival times of the journey to \
it's destination stop. If 'routeStops' and +'routeTimesArrival' are both set, the \
latter contains one element less (because the last stop +has no departure, only an \
arrival time). Elements with equal indices are associated +(the times at which the \
vehicle departs from the stops).</td></tr> +<tr><td><i>RouteExactStops</i></td> \
<td>int</td> <td>The number of exact route stops. +The route stop list isn't complete \
from the last exact route stop.</td></tr> +<tr><td><i>RouteTypesOfVehicles</i></td> \
<td>QList< int > (stored as QVariantList)</td> +<td>A list of vehicle type ID's \
(integers) of vehicles used for each "sub-journey" in the journey. +See the \
<i>vehicleTypes</i> field or @ref usage_vehicletypes_sec for more information. \
</td></tr> +<tr><td><i>RouteTransportLines</i></td> <td>QStringList</td>
+<td>A list of transport lines used for each "sub-journey" in the journey.</td></tr>
+<tr><td><i>RoutePlatformsDeparture</i></td> <td>QStringList</td>
+<td>A list of platforms of the departure used for each stop in the \
journey.</td></tr> +<tr><td><i>RoutePlatformsArrival</i></td> <td>QStringList</td>
+<td>A list of platforms of the arrival used for each stop in the journey.</td></tr>
+<tr><td><i>RouteTimesDepartureDelay</i></td> <td>QList< int > (stored as \
QVariantList)</td> +<td>A list of delays in minutes of the departures at each stop in \
the journey. A value of 0 means, +that the vehicle is on schedule, -1 means, that \
there's no information about delays.</td></tr> \
+<tr><td><i>RouteTimesArrivalDelay</i></td> <td>QList< int > (stored as \
QVariantList)</td> +<td>A list of delays in minutes of the arrivals at each stop in \
the journey. A value of 0 means, +that the vehicle is on schedule, -1 means, that \
there's no information about delays.</td></tr> +<tr><td><i>RouteSubJourneys</i></td> \
<td>QList< QVariantMap ></td> <td>A list of data maps for +all sub-journeys between \
two connecting stops. If 'RouteStops' and 'RouteSubJourneys' are both set, +the \
latter contains one element less (one sub-journey between two stops from \
'RouteStops'). +Each map in the list contains route data for the sub journey. These \
TimetableInformation values +can be used inside this map: RouteStops, RouteNews, \
RouteTimesDeparture, RouteTimesArrival, +RouteTimesDepartureDelay, \
RouteTimesArrivalDelay, RoutePlatformsDeparture and RoutePlatformsArrival. +Each list \
should contain the same number of elements here (no origin or target included here, \
+only intermediate stops).</td></tr> +</table>
+
+<br />
+@section usage_stopList_sec Receiving Stop Lists
+To get a list of stop suggestions use the data source
+@verbatim "Stops <service-provider-id>|stop=<stop-name-part>" @endverbatim
+If the provider supports the @em ProvidesStopsByGeoPosition feature, the following \
parameters can +be used to get stops at a specific geo position:
+@verbatim "Stops <service-provider-id>|latitude=<decimal-latitude>|longitude=<decimal-longitude>" \
@endverbatim +
+In your dataUpdated-slot you should first check, if a stop list was received by \
checking if a +key "stops" exists in the data object from the data engine. Then you \
get the stop data, which is +stored in the key "stops" and contains a list of data \
sets, one for each stop. They have at least +a <i>StopName</i> key (containing the \
stop name). They <b>may</b> additionally contain a +<i>StopID</i> (a non-ambiguous ID \
for the stop, if available, otherwise it is empty), +<i>StopWeight</i> (the weight of \
the suggestion), a <i>StopCity</i> (the city the stop is in) +and a \
<i>StopCountryCode</i> (the code of the country in with the stop is). If the provider \
+supports the ProvidesStopGeoPosition feature they also contain <i>StopLatitude</i> \
and +<i>StopLongitude</i>.
+
+@code
+void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data &data ) \
{ + if ( data.contains("stops").toBool() ) {
+ QStringList possibleStops;
+ QVariantList stops = data["stops"].toList();
+ foreach ( const QVariant &stopData, stops ) {
+ QVariantHash stop = stopData.toHash();
+
+ // Get the name
+ QString stopName = stop["StopName"].toString();
+
+ // Get other values
+ if ( stopData.contains("StopID") ) {
+ QString stopID = stop["StopID"].toString();
+ }
+ QString stopCity = stop["StopCity"].toString();
+ QString stopCityCode = stop["StopCountryCode"].toString();
+ }
+ }
+}
+@endcode
+
+@subsection usage_stopList_datastructure_sec Stop Data Source Structure
+The data received from the data engine contains these keys:<br />
+<table>
+<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr> +<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if \
@em error is @c true), +an error message string.</td></tr>
+<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code. + Error code 1 means, that there was a problem downloading a source \
file. + Error code 2 means, that parsing a source file failed.
+ Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it. + Use the @ref PublicTransportService to start and monitor the \
import.</td></tr> +<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and \
time when the data source was +last updated.</td></tr>
+<tr><td><i>stops</i></td> <td>QVariantList</td> <td>A list of all found \
stops.</td></tr> +</table>
+<br />
+Each stop in the data received from the data engine has the following keys:<br />
+<table>
+<tr><td><i>StopName</i></td> <td>QString</td> <td>The name of the stop.</td></tr>
+<tr><td><i>StopID</i></td> <td>QString</td> <td>A unique ID for the stop, if \
available.</td></tr> +<tr><td><i>StopWeight</i></td> <td>int</td>
+<td>The weight of the stop as a suggestion, if available.</td></tr>
+<tr><td><i>StopCity</i></td> <td>QString</td>
+<td>The name of the city the stop is in, if available.</td></tr>
+<tr><td><i>StopCountryCode</i></td> <td>QString</td> <td>The code of the country in \
with +the stop is, if available.</td></tr>
+<tr><td><i>StopLatitude</i></td> <td>qreal</td> <td>The decimal latitude of the \
stop. +Only available if the provider supports the ProvidesStopGeoPosition \
feature.</td></tr> +<tr><td><i>StopLongitude</i></td> <td>qreal</td> <td>The decimal \
longitude of the stop. +Only available if the provider supports the \
ProvidesStopGeoPosition feature.</td></tr> +</table>
+
+<br />
+@section usage_service_sec Using the Timetable Service
+This service is available for all timetable data sources, ie. departure, arrival and \
journey +data sources. It can be retrieved using DataEngine::serviceForSource() with \
the name of the +timetable data source. The service offers some operations on \
timetable data sources and allows +to change it's contents, ie. update or extend it \
with new data. +
+@subsection usage_service_manual_update Manual updates
+Manual updates can be requested for timetable data sources using the @b \
requestUpdate operation. +They may be rejected if the last update was not long enough \
ago (see the @em minManualUpdateTime +field of the data source). Manual updates are \
allowed more often than automatic updates. +Does not need any parameters.
+The following code example shows how to use the service to request a manual update:
+@code
+// Get a pointer to the service for the used data source,
+// use Plasma::Applet::dataEngine() to get a pointer to the engine,
+// alternatively Plasma::DataEngineManager can be used
+Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName ); +
+// Start the "requestUpdate" operation (no parameters)
+KConfigGroup op = service->operationDescription("requestUpdate");
+Plasma::ServiceJob *updateJob = service->startOperationCall( op );
+
+// Connect to the finished() slot if needed
+connect( updateJob, SIGNAL(finished(KJob*)), this, \
SLOT(updateRequestFinished(KJob*)) ); +@endcode
+
+@subsection usage_service_additional_data Request additional data
+Additional data (eg. route data) can be requested for specific timetable items. \
There are two +operations @b "requestAdditionalData" and @b \
"requestAdditionalDataRange", the latter one should +be used if additional data gets \
requested for multiple items at once to save data source updates +in the engine. Uses \
an "itemnumber" or "itemnumberbegin"/"itemnumberend" parameters to identify +the \
timetable item(s) to get additional data for. +@code
+// Get a pointer to the service for the used data source, like in example 1
+Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName ); +
+// Start the "requestAdditionalData" operation
+// with an "itemnumber" parameter, 0 to get additional data for the first item
+KConfigGroup op = service->operationDescription("requestAdditionalData");
+op.writeEntry( "itemnumber", 0 );
+Plasma::ServiceJob *additionalDataJob = service->startOperationCall( op );
+@endcode
+
+@subsection usage_service_later_items Request earlier/later items
+Use the operations @b "requestEarlierItems" and @b "requestLaterItems" to get more \
timetable items +for a data source. This is currently only used for journeys. The \
difference between these operation +and simply requesting more journeys with an \
earlier/later time is that the provider may benefit +from data stored for the request \
at the provider's server (if any) when using this operation. +Another difference is \
that the data source will contain both the old and the earlier/later +journeys after \
using this operation. +
+These operations need the used service provider to support the @em \
ProvidesMoreJourneys feature. +Does not need any parameters.
+@code
+// Get a pointer to the service for the used data source, like in example 1
+Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName ); +
+// Start the "requestLaterItems" operation (no parameters)
+KConfigGroup op = service->operationDescription("requestLaterItems");
+Plasma::ServiceJob *laterItemsJob = service->startOperationCall( op );
+@endcode
+*/
+
+/** @page pageServiceProviders Add Support for new Service Providers
+@par Sections
+<ul>
+ <li>@ref provider_plugin_format_version </li>
+ <li>@ref provider_plugin_types </li>
+ <li>@ref provider_plugin_pts </li>
+ <li>@ref provider_plugin_script </li>
+ <li>@ref examples </li>
+ <ul>
+ <li>@ref examples_xml_gtfs </li>
+ <li>@ref examples_xml_script </li>
+ <li>@ref examples_script </li>
+ </ul>
+</ul>
+@n
+
+@n
+@section provider_plugin_format_version Provider Plugin Format Version
+New versions of the data engine may require provider plugins to use a new version of \
the provider +plugin format. The format version to use gets specified in the @em \
\<serviceProvider\> +XML tag of the .pts file, see @ref provider_plugin_pts. Version \
1.0 is no longer supported, +because the new script API requires the scripts to be \
updated and GTFS providers were not supported +in that version. Later updates should \
be backwards compatible. +
+New plugins should use the newest version, currently 0.11. An older version can be \
used to also +support older versions of the data engine, if the update only affects a \
not used provider type. +
+<table>
+ <tr><td><b>PublicTransport<br/> Engine Version</b></td>
+ <td><b>Required Provider Plugin<br /> Format Version</b></td>
+ <td><b>Changes</b></td></tr>
+ <tr><td>until 0.10</td><td>1.0</td><td>(first version)</td></tr>
+ <tr><td>0.11</td><td>1.1</td><td>New provider type @em "gtfs",<br />
+ New script API (see @ref scriptApi),<br />
+ New XML tags: \<samples\>, \<notes\>, \<feedUrl\>, \
\<realtimeTripUpdateUrl\>, + \<realtimeAlertsUrl\>, \<timeZone\>
+ </td>
+ </tr>
+</table>
+@n
+
+@section provider_plugin_types Provider Plugin Types
+Currently two provider plugin types are supported: @em "script" and @em "gtfs".
+
+GTFS providers are very easy, all you need is an URL to the GTFS feed zip file and \
general +information about the provider and the plugin. The GTFS feed then can be \
imported into a local +database using the GTFS service of the data engine. \
GTFS-realtime is also supported, but not +used widely among the currently supported \
GTFS providers. See @ref gtfsProviders for more +information.
+
+Scripted providers need a script file to execute requests. There is an API for such \
scripts, +see @ref scriptApi. For providers using the HAFAS API this is quite easy, \
as most script logic +is already implemented in a base script. A base script for the \
EFA API does not exist yet. +See @ref scriptProviders for more information.
+@n
+
+@n
+@section provider_plugin_pts Provider Plugin .pts File Structure
+To add support for a new service provider you need to create a service provider \
plugin for the +PublicTransport engine, which is essentially an XML file with \
information about the service +provider. This XML file contains a name, description, \
changelog, etc. for the service provider +plugin and uses the mime type \
"application-x-publictransport-serviceprovider" (*.pts). +It can also contain a \
reference to a script to parse documents from the provider to process +requests from \
the data engine. There are many helper functions available for scripts to parse HTML \
+documents, QtXML is available to parse XML documents (as extension). +The filename \
of the XML file starts with the country code or "international"/"unknown", followed \
+by "_" and a short name for the service provider, e.g. "de_db.pts", "ch_sbb.pts", \
"sk_atlas.pts", +"international_flightstats.pts". The base file name (without \
extension) is the service provider ID. +<br />
+There is also a nice tool called @em TimetableMate. It's a little IDE to create \
service +provider plugins for the PublicTransport data engine. The GUI is similiar to \
the GUI of KDevelop, +it also has docks for projects, breakpoints, backtraces, \
variables, a console, script output and +so on. TimetableMate also shows a nice \
dashboard for the service provider plugin projects. It +features script editing, \
syntax checking, code-completion for the engine's script API, automatic +tests, web \
page viewer, network request/reply viewer with some filters, a Plasma preview etc.<br \
/> +
+Here is an overview of the allowed tags in the XML file (required child tags of the \
serviceProvider +tag are <span style="background-color: \
#ffdddd;">highlighted</span>): +<table>
+<tr style="background-color: #bbbbbb; font-weight: bold;"><td>Tag</td> <td>Parent \
Tag</td> +<td>Optional?</td> <td>Description</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<?xml version="1.0" encoding="UTF-8"?\></b></td>
+<td>Root</td> <td>Required</td><td>XML declaration.</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<serviceProvider fileVersion="1.1" version=@em "plugin-version" type=@em \
"provider-type" \> </b></td> +<td>Root</td> <td>Required</td> <td>This is the root \
item. The only currently supported provider +plugin format version is 1.1 and gets \
written as 'fileVersion' attribute. The 'version' attribute +contains the version of \
the plugin itself and the 'type' attribute specifies the type of the +plugin, which \
can currently be either @em "script" or @em "gtfs". +@see @ref \
provider_plugin_format_version, @ref provider_plugin_types +</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<name\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
+<td>The name of the service provider (plugin). If it provides data for international \
stops it +should begin with "International", if it's specific for a country or city \
it should begin with the +name of that country or city. That should be followed by a \
short url to the service provider. +</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<description\> </b></td><td>\<serviceProvider\> </td> <td>Required</td>
+<td>A description of the service provider (plugin). You don't need to list the \
features +supported by the service provider here, the feature list is generated \
automatically.</td></tr> +
+<tr style="background-color: #ffdddd;"><td style="color:#888800">
+<b>\<author\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
+<td>Contains information about the author of the service provider plugin.</td></tr>
+
+<tr style="background-color: #ffdddd;"><td style="color:#666600">
+<b>\<fullname\> </b></td><td style="color:#888800">\<author\></td> <td>Required</td>
+<td>The full name of the author of the service provider plugin.</td></tr>
+
+<tr><td style="color:#666600">
+<b>\<short\> </b></td><td style="color:#888800">\<author\></td> <td>(Optional)</td>
+<td>A short name for the author of the service provider plugin (eg. the \
initials).</td></tr> +
+<tr><td style="color:#666600">
+<b>\<email\> </b></td><td style="color:#888800">\<author\></td> <td>(Optional)</td> \
<td> +The email address of the author of the service provider plugin.</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<version\> </b></td><td>\<serviceProvider\> </td> <td>Required</td>
+<td>The version of the service provider plugin, should start with "1.0".</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<url\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
+<td>An url to the service provider home page.</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<shortUrl\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
+<td>A short version of the url, used as link text.</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<script\> </b></td><td>\<serviceProvider\></td>
+<td>(Required only with "script" @em type)</td>
+<td>Contains the filename of the script to be used to parse timetable documents.
+The script must be in the same directory as the XML file. Always use "Script" as \
type when +using a script. Can have an "extensions" attribute with a comma separated \
list of QtScript +extensions to load when executing the script.</td></tr>
+
+<tr><td style="color:#00bb00">
+<b>\<cities\> </b></td><td>\<serviceProvider\></td> <td>(Optional)</td>
+<td>A list of cities the service provider has data for (with surrounding \
\<city\>-tags).</td></tr> +
+<tr><td style="color:#007700">
+<b>\<city\> </b></td><td style="color:#00bb00">\<cities\></td> <td>(Optional)</td>
+<td>A city in the list of cities (\<cities\>). Can have an attribute "replaceWith",
+to replace city names with values used by the service provider.</td></tr>
+
+<tr><td><b>\<notes> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
+<td>Custom notes for the service provider plugin. Can be a to do list.</td></tr>
+
+<tr><td><b>\<fallbackCharset\> </b></td><td>\<serviceProvider\> </td> \
<td>(Optional)</td> +<td>The charset of documents to be downloaded. Depending on the \
used service provider this might +be needed or not. Scripts can use this \
value.</td></tr> +
+<tr><td><b>\<credit\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
+<td>A courtesy string that is required to be shown to the user when showing the \
timetable data +of the GTFS feed. If this tag is not given, a short default string is \
used, +eg. "data by: www.provider.com" or only the link (depending on available \
space). +Please check the license agreement for using the GTFS feed for such a string \
and include it here. +</td></tr>
+
+<tr style="background-color: #ffdddd;">
+<td><b>\<feedUrl\> </b></td><td>\<serviceProvider\> </td>
+<td>(Required only with "gtfs" @em type)</td>
+<td>An URL to the GTFS feed to use. Use an URL to the latest available \
feed.</td></tr> +
+<tr><td><b>\<realtimeTripUpdateUrl\> </b></td><td>\<serviceProvider\> </td>
+<td>(Optional, only used with "GTFS" type)</td>
+<td>An URL to a GTFS-realtime data source with trip updates. If this tag is not \
present delay +information will not be available.</td></tr>
+
+<tr><td><b>\<realtimeAlertsUrl\> </b></td><td>\<serviceProvider\> </td>
+<td>(Optional, only used with "GTFS" type)</td>
+<td>An URL to a GTFS-realtime data source with alerts. If this tag is not present \
journey news +will not be available.</td></tr>
+
+<tr><td><b>\<timeZone> </b></td><td>\<serviceProvider\> </td>
+<td>(Optional)</td>
+<td>The name of the timezone of times from the service provider, eg. \
"America/Los_Angeles" +(Pacific Time). GTFS providers use this to calculate local \
time values. +@see KSystemTimeZones::zones() for a list of available time zones.
+</td></tr>
+
+<tr><td style="color:#00bb00;">
+<b>\<changelog\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
+<td>Contains changelog entries for this service provider plugin.</td></tr>
+
+<tr><td style="color:#007700;">
+<b>\<entry\> </b></td><td style="color:#00bb00;">\<changelog\> </td> \
<td>(Optional)</td> +<td>Contains a changelog entry for this service provider plugin. \
The entry description is read +from the contents of the \<entry\> tag. Attributes @em \
version (the plugin version where +this change was applied) and @em engineVersion \
(the version of the publictransport +data engine this plugin was first released with) \
can be added.</td></tr> +
+<tr><td style="color:#880088;">
+<b>\<samples\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
+<td>Contains child tags \<stop\> and \<city\> with sample stop/city names. These \
samples are used +eg. in TimetableMate for automatic tests.</td></tr>
+
+<tr><td style="color:#660066;">
+<b>\<stop\> </b></td><td style="color:#880088;">\<samples\> </td> \
<td>(Optional)</td> +<td>A sample stop name.</td></tr>
+
+<tr><td style="color:#660066;">
+<b>\<city\> </b></td><td style="color:#880088;">\<samples\> </td> \
<td>(Optional)</td> +<td>A sample city name.</td></tr>
+</table>
+@n
+
+@section provider_plugin_script Script File Structure
+Scripts are executed using QtScript (JavaScript), which can make use of Kross if \
other script +languages should be used, eg. Python or Ruby. JavaScript is tested, the \
other languages may also +work. There are functions with special names that get \
called by the data engine when needed: +@n
+getTimetable(), getStopSuggestions(), getJourneys() and features()
+@n
+
+@n
+@section examples Service Provider Plugin Examples
+@n
+@subsection examples_xml_script A Simple Script Provider Plugin
+Here is an example of a simple service provider plugin which uses a script to parse \
data from +the service provider:
+@verbinclude ch_sbb.pts
+
+@subsection examples_xml_gtfs A Simple GTFS Provider Plugin
+The simplest provider XML can be written when using a GTFS feed. This example also \
contains tags +for GTFS-realtime support, which is optional.
+@verbinclude us_bart.pts
+
+@n
+@subsection examples_script A Simple Parsing-Script
+This is an example of a script used to parse data from the service provider. The \
script uses the +base script class for HAFAS providers, which already has quite \
flexible implementations +for the script.
+@include ch_sbb.js
+*/
+
+/** @page pageClassDiagram Class Diagram
+\dot
+digraph publicTransportDataEngine {
+ ratio="compress";
+ size="10,100";
+ // concentrate="true";
+ // rankdir="LR";
+ clusterrank=local;
+
+ node [
+ shape=record
+ fontname=Helvetica, fontsize=10
+ style=filled
+ fillcolor="#eeeeee"
+ ];
+
+ engine [
+ label="{PublicTransportEngine|The main class of the public transport data \
engine.\l}" + URL="\ref PublicTransportEngine"
+ style=filled
+ fillcolor="#ffdddd"
+ ];
+
+ providerScript [
+ label="{ServiceProviderScript|Parses timetable documents (eg. HTML) using \
scripts.}" + URL="\ref ServiceProviderScript"
+ fillcolor="#dfdfff"
+ ];
+
+ providerGtfs [
+ label="{ServiceProviderGtfs|Imports GTFS feeds into a local database.}"
+ URL="\ref ServiceProviderGtfs"
+ fillcolor="#dfdfff"
+ ];
+
+ provider [
+ label="{ServiceProvider|Loads timetable data from service providers.\lIt \
uses ServiceProviderData to get needed information.\l|# requestDepartures()\l# \
requestJourneys()\l# requestStopSuggestions()\l# requestStopsByGeoPosition()\l# \
requestAdditionData()\l# requestMoreItems()\l+ data() : ServiceProviderData\l}" + \
URL="\ref ServiceProvider" + fillcolor="#dfdfff"
+ ];
+
+ timetableData [
+ label="{TimetableData|Typedef for QHash with TimetableInformation keys and \
QVariant values.\lCan be used to describe a departure, arrival, journey or stop.}" + \
URL="\ref TimetableData" + ];
+
+ serviceProviderData [
+ label="{ServiceProviderData|Information about the service provider.\l|+ \
name() : QString\l+ description() : QString\l+ features() : QStringList\l... }" + \
URL="\ref ServiceProviderData" + ];
+
+ { rank=same; provider providerScript providerGtfs }
+
+ edge [ arrowhead="empty", arrowtail="none", style="solid" ];
+ providerScript -> provider;
+ providerGtfs -> provider;
+
+ edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="gray", taillabel="", headlabel="0..*" ]; + engine -> provider [ \
label=""uses ]; + provider -> timetableData [ label="uses" ];
+ provider -> serviceProviderData [ label="uses" ];
+
+ edge [ dir=both, arrowhead="normal", arrowtail="normal", color="gray", \
fontcolor="gray", style="dashed", headlabel="" ]; + serviceProviderData -> \
provider [ label="friend" ]; +}
+@enddot
+*/
diff --git a/engine/enums.h b/engine/enums.h
index 038fbd2..2ec0dc4 100644
--- a/engine/enums.h
+++ b/engine/enums.h
@@ -86,11 +86,19 @@ enum GtfsServiceError {
* trying to delete the GTFS database. */
};
+/**
+ * @brief Contains enumerables which are also made available to scripts.
+ *
+ * Scripts can access the enumerables in this class in the @em PublicTransport \
script object, + * eg. @em PublicTransport.ProvidesArrivals.
+ * This class only contains enumerables and static functions.
+ **/
class Enums : public QObject {
Q_OBJECT
- Q_ENUMS( TimetableInformation ServiceProviderType ProviderFeature VehicleType
- LineService MoreItemsDirection )
+ // NOTE The ';' at the end is needed for doxygen, otherwise the enumarables get \
skipped + Q_ENUMS( TimetableInformation ServiceProviderType ProviderFeature
+ VehicleType LineService MoreItemsDirection );
public:
/**
* @brief Different types of timetable information.
@@ -351,86 +359,149 @@ public:
};
/**
- * @brief The type of the vehicle used for a public transport line.
+ * @brief Types of vehicles.
*
- * Scripts can use the names (case insensitive) of these enumerables as vehicle \
types. + * Scripts can access these enumerables in the @em PublicTransport script \
object, + * eg. @em PublicTransport.Bus.
* @code
- * result.addData({ TypeOfVehicle: "Bus" });
- * result.addData({ TypeOfVehicle: "traM" });
- * result.addData({ TypeOfVehicle: "RegionalExpressTrain" });
+ * result.addData({ TypeOfVehicle: PublicTransport.Bus, ... });
+ * result.addData({ TypeOfVehicle: PublicTransport.Tram, ... });
+ * result.addData({ TypeOfVehicle: PublicTransport.RegionalExpressTrain, ... });
* @endcode
**/
enum VehicleType {
InvalidVehicleType = -1, /**< Invalid vehicle type. */
UnknownVehicleType = 0, /**< The type of the vehicle is unknown. */
- Tram = 1, /**< @image html hi16-app-vehicle_type_tram.png A tram / \
streetcar. */
- Bus = 2, /**< @image html hi16-app-vehicle_type_bus.png A bus. */
- Subway = 3, /**< @image html hi16-app-vehicle_type_subway.png A subway. */
+ /**
+ * <table style="boder:1;"><tr><td>@image html \
hi16-app-vehicle_type_tram.png + * </td><td>
+ * A tram / streetcar.
+ * </td></tr></table>
+ **/
+ Tram = 1,
+
+ /**
+ * <table style="boder:0;"><tr><td>@image html hi16-app-vehicle_type_bus.png
+ * </td><td>
+ * A bus.
+ * </td></tr></table>
+ **/
+ Bus = 2,
+
+ /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_subway.png + * </td><td>
+ * A subway.
+ * </td></tr></table>
+ **/
+ Subway = 3,
- /** @image html hi16-app-vehicle_type_train_interurban.png An interurban \
train. */ + /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_interurban.png + * </td><td>
+ * An interurban train.
+ * </td></tr></table>
+ **/
InterurbanTrain = 4,
- Metro = 5, /**< @image html hi16-app-vehicle_type_metro.png A metro. */
+ /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_metro.png + * </td><td>
+ * A metro.
+ * </td></tr></table>
+ **/
+ Metro = 5,
/**
- * @image html hi16-app-vehicle_type_trolleybus.png
- * A trolleybus (also known as trolley bus, trolley coach, trackless trolley, \
trackless tram
- * or trolley) is an electric bus that draws its electricity from overhead \
wires (generally
- * suspended from roadside posts) using spring-loaded trolley poles.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_trolleybus.png + * </td><td>
+ * A trolleybus (also known as trolley bus, trolley coach, trackless \
trolley, trackless tram + * or trolley) is an electric bus that draws its \
electricity from overhead wires (generally + * suspended from roadside posts) \
using spring-loaded trolley poles. + * </td></tr></table>
+ **/
TrolleyBus = 6,
/**
- * @image html hi16-app-vehicle_type_train_regional.png
- * A regional train. Stops at many small stations, slow.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_regional.png + * </td><td>
+ * A regional train. Stops at many small stations, slow.
+ * </td></tr></table>
+ **/
RegionalTrain = 10,
/**
- * @image html hi16-app-vehicle_type_train_regional.png
- * A regional express train. Stops at less small stations than RegionalTrain \
but is faster.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_regional.png + * </td><td>
+ * A regional express train. Stops at less small stations than RegionalTrain \
but is faster. + * </td></tr></table>
+ **/
RegionalExpressTrain = 11,
/**
- * @image html hi16-app-vehicle_type_train_interregional.png
- * An inter-regional train. Higher distances and faster than RegionalTrain \
and
- * RegionalExpressTrain.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_interregional.png + * </td><td>
+ * An inter-regional train. Higher distances and faster than RegionalTrain \
and + * RegionalExpressTrain.
+ * </td></tr></table>
+ **/
InterregionalTrain = 12,
/**
- * @image html hi16-app-vehicle_type_train_intercity.png
- * An intercity / eurocity train. Connects cities.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_intercity.png + * </td><td>
+ * An intercity / eurocity train. Connects cities.
+ * </td></tr></table>
+ **/
IntercityTrain = 13,
/**
- * @image html hi16-app-vehicle_type_train_highspeed.png
- * A highspeed train, eg. an ICE (intercity express) or TGV.
- * Trains at > 250 km/h, high distances.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_train_highspeed.png + * </td><td>
+ * A highspeed train, eg. an ICE (intercity express) or TGV.
+ * Trains at > 250 km/h, high distances.
+ * </td></tr></table>
+ **/
HighSpeedTrain = 14,
/**
- * @image html hi16-app-vehicle_type_feet.png
- * By feet, ie. no vehicle. Used for journeys, eg. from platform A to \
platform B when changing
- * the vehicle.
- **/
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_feet.png + * </td><td>
+ * By feet, ie. no vehicle. Used for journeys, eg. from platform A to \
platform B when changing + * the vehicle.
+ * </td></tr></table>
+ **/
Footway = 50,
- Feet = Footway, /**< DEPRECATED */
+ Feet = Footway, /**< @deprecated Use Footway instead. */
- /** @image html hi16-app-vehicle_type_ferry.png A ferry. */
+ /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_ferry.png + * </td><td>
+ * A ferry.
+ * </td></tr></table>
+ **/
Ferry = 100,
- /** @image html hi16-app-vehicle_type_ferry.png A ship, but not a ferry. */
+ /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_ferry.png + * </td><td>
+ * A ship, but not a ferry.
+ * </td></tr></table>
+ **/
Ship = 101,
- /** @image html hi16-app-vehicle_type_plane.png An aeroplane. */
+ /**
+ * <table style="boder:0;"><tr><td>@image html \
hi16-app-vehicle_type_plane.png + * </td><td>
+ * An aeroplane.
+ * </td></tr></table>
+ **/
Plane = 200,
- /** A spacecraft. @todo Currently unused. */
+ /**
+ * A spacecraft. @todo Currently unused.
+ **/
Spacecraft = 300
};
diff --git a/engine/gtfs/gtfs-doc.h b/engine/gtfs/gtfs-doc.h
new file mode 100644
index 0000000..a855829
--- /dev/null
+++ b/engine/gtfs/gtfs-doc.h
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2012 Friedrich Pülz <fpuelz@gmx.de>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this program; if not, write to the
+ * Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/**
+ * @defgroup gtfsProviders GTFS Provider Plugins
+ *
+ * GTFS providers first need to download and import a GTFS feed into a local \
database. Depending + * on the feed that database can get quite big (eg. ~300MB for a \
bigger area). After having the + * feed imported it will be checked for updates from \
time to time. GTFS providers can then be used + * without an internet connection and \
are very fast. While internet is available realtime data + * like delays or news can \
be updated using GTFS-realtime without changing the database. + *
+ * Departures/arrivals with route information, stop suggestions and stops by \
geolocation are + * supported by all GTFS provider plugins. Delays and news are \
supported, if GTFS-realtime is + * supported. Journeys are currently not supported, \
routing would need to be done locally. + *
+ * Support for GTFS providers can be added with only a .pts file, see @ref \
provider_plugin_pts. + * The type of the provider needs to be @em "gtfs". \
TimetableMate can be used to easily create new + * valid GTFS provider plugins. Most \
important is the \<feedUrl\> tag in the .pts file, which + * points to the GTFS feed \
zip file. To use GTFS-realtime simply add the used GTFS-realtime URLs + * to the .pts \
file, ie. \<realtimeTripUpdateUrl\> and/or \<realtimeAlertsUrl\>. + *
+ * There are provider states specific to GTFS provider plugins: @em \
"gtfs_feed_import_pending" + * (first start the GTFS feed import before the provider \
plugin can be used) and + * @em "importing_gtfs_feed" (the GTFS feed currently gets \
imported). After the feed was + * successfully imported the state gets set to @em \
"ready". The current state can be determined + * using the @em "ServiceProviders" \
data source. + *
+ * The first GTFS feed import is @em not done automatically, only updates are done \
when available. + * To start the first import, the GTFS service of the data engine \
can be used. That service also + * allows to delete the database again or to manually \
request to check for feed updates. + *
+ * @see GtfsService, @ref provider_plugin_types
+ **/
diff --git a/engine/publictransportdataengine.h b/engine/publictransportdataengine.h
index 27626c8..7ccfb52 100644
--- a/engine/publictransportdataengine.h
+++ b/engine/publictransportdataengine.h
@@ -729,956 +729,4 @@ private:
QStringList m_runningSources; // Sources which are currently being processed
};
-/** @mainpage Public Transport Data Engine
-@section intro_dataengine_sec Introduction
-The public transport data engine provides timetable data for public transport, \
trains, ships,
-ferries and planes. It can get departures/arrivals, journeys and stop suggestions.
-There are different plugins (eg. scripts) used to get timetable data from the \
different
-service providers. Currently there are two classes of service providers: One uses \
scripts to
-do the work, the other one uses GTFS (GeneralTransitFeedSpecification). All are \
using information
-from ServiceProviderData, which reads information data from "*.pts" files (XML files \
with mime type
-"application-x-publictransport-serviceprovider").
-
-<br />
-@section install_sec Installation
-To install this data engine type the following commands:<br />
-@verbatim
-> cd /path-to-extracted-engine-sources/build
-> cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..
-> make
-> make install
-@endverbatim
-@note Do not forget the ".." at the end of the second line!
-
-After installation do the following to use the data engine in your plasma desktop:
-Restart plasma to load the data engine:<br />
-@verbatim
-> kquitapp plasma-desktop
-> plasma-desktop
-@endverbatim
-<br />
-or test it with:<br />
-@verbatim
-> plasmaengineexplorer --engine publictransport
-@endverbatim
-<br />
-You might need to run kbuildsycoca4 in order to get the .desktop file recognized.
-<br />
-
-<br />
-
-@section index_sec Other Pages
-@par
- @li @ref pageUsage
- @li @ref pageServiceProviders
- @li @ref pageClassDiagram
-*/
-
-/** @page pageUsage Usage
-
-@par Sections
-<ul><li>@ref usage_introduction_sec </li>
- <li>@ref usage_serviceproviders_sec </li>
- <li>@ref usage_vehicletypes_sec </li>
- <li>@ref usage_departures_sec </li>
- <ul><li>@ref usage_departures_datastructure_sec </li></ul>
- <li>@ref usage_journeys_sec </li>
- <ul><li>@ref usage_journeys_datastructure_sec </li></ul>
- <li>@ref usage_stopList_sec </li>
- <ul><li>@ref usage_stopList_datastructure_sec </li></ul>
- <li>@ref usage_service_sec </li>
- <ul><li>@ref usage_service_manual_update </li>
- <li>@ref usage_service_additional_data </li>
- <li>@ref usage_service_later_items </li>
- </ul>
-</ul>
-
-<br />
-
-@section usage_introduction_sec Introduction
-To use this data engine in an applet you need to connect it to a data source of the \
public
-transport data engine. There are data sources which provide information about the \
available
-service providers (@ref usage_serviceproviders_sec) or supported countries. Other \
data sources
-contain departures/arrivals (@ref usage_departures_sec), journeys (@ref \
usage_journeys_sec) or
-stop suggestions (@ref usage_stopList_sec).<br />
-The engine provides services for all timetable data sources (departures, journeys, \
...). It offers
-operations to manually request updates, request earlier/later timetable items or to \
request
-additional data for specific timetable items (@ref usage_service_sec).<br />
-@note Since version 0.11 the engine will only match data source names with correct \
case, ie.
-"serviceproViders" will not work any longer, but "ServiceProviders" will. All \
parameter names in
-data source names need to be completely lower case. This is to prevent ambiguities, \
each variant
-would get it's own data source object in the data engine, duplicating the data. To \
update a data
-source all connected source name variants would need to be updated. Only accepting \
source names
-case sensitive makes it much easier for the engine. The only thing left that can \
make two identic
-data sources ambiguous is their parameter order, which gets handled using \
disambiguateSourceName().
-<br />
-The following enumeration can be used in your applet if you don't want to use
-libpublictransporthelper which exports this enumaration as @ref \
PublicTransport::VehicleType.
-Don't change the numbers, as they need to match the ones in the data engine, which \
uses a similar
-enumeration.
-@code
-// The type of the vehicle used for a public transport line.
-// The numbers here must match the ones in the data engine!
-enum VehicleType {
- Unknown = 0, // The vehicle type is unknown
-
- Tram = 1, // The vehicle is a tram
- Bus = 2, // The vehicle is a bus
- Subway = 3, // The vehicle is a subway
- InterurbanTrain = 4, // The vehicle is an interurban train
- Metro = 5, // The vehicle is a metro
- TrolleyBus = 6, // A trolleybus (also known as trolley bus, trolley coach, \
trackless trolley,
- // trackless tram or trolley) is an electric bus that draws its \
electricity from
- // overhead wires (generally suspended from roadside posts) using \
spring-loaded
- // trolley poles
-
- RegionalTrain = 10, // The vehicle is a regional train
- RegionalExpressTrain = 11, // The vehicle is a region express
- InterregionalTrain = 12, // The vehicle is an interregional train
- IntercityTrain = 13, // The vehicle is a intercity / eurocity train
- HighspeedTrain = 14, // The vehicle is an intercity express (ICE, TGV?, ...?)
-
- Ferry = 100, // The vehicle is a ferry
- Ship = 101, // The vehicle is a ship
-
- Plane = 200 // The vehicle is an aeroplane
-};
-@endcode
-
-<br />
-@section usage_serviceproviders_sec Receiving a List of Available Service Providers
-You can view this data source in @em plasmaengineexplorer, it's name is
-@em "ServiceProviders", but you can also use <em>"ServiceProvider [providerId]"</em> \
with the ID
-of a service provider to get information only for that service provider.
-For each available service provider the data source contains a key with the display \
name of the
-service provider. These keys point to the service provider information, stored as a \
QHash with
-the following keys:
-<br />
-<table>
-<tr><td><i>id</i></td> <td>QString</td> <td>The ID of the service provider \
plugin.</td></tr>
-<tr><td><i>fileName</i></td> <td>QString</td> <td>The file name of the XML file \
containing the
-service provider information.</td> </tr>
-<tr><td><i>name</i></td> <td>QString</td> <td>The name of the service \
provider.</td></tr>
-<tr><td><i>type</i></td> <td>QString</td> <td>The type of the provider plugin, may \
currently be
-"GTFS", "Scripted" or "Invalid".</td></tr>
-<tr><td><i>feedUrl</i></td> <td>QString</td> <td><em>(only for type "GTFS")</em> The \
url to the
-(latest) GTFS feed.</td></tr>
-<tr><td><i>scriptFileName</i></td> <td>QString</td> <td><em>(only for type \
"Scripted")</em>
-The file name of the script used to parse documents from the service provider, if \
any.</td></tr>
-<tr><td><i>url</i></td> <td>QString</td>
-<td>The url to the home page of the service provider.</td></tr>
-<tr><td><i>shortUrl</i></td> <td>QString</td> <td>A short version of the url to the \
home page
-of the service provider. This can be used to display short links, while using "url" \
as the url
-of that link.</td></tr>
-<tr><td><i>country</i></td> <td>QString</td> <td>The country the service provider is \
(mainly)
-designed for.</td></tr>
-<tr><td><i>cities</i></td> <td>QStringList</td>
-<td>A list of cities the service provider supports.</td></tr>
-<tr><td><i>credit</i></td> <td>QString</td>
-<td>The ones who run the service provider (companies).</td></tr>
-<tr><td><i>useSeparateCityValue</i></td> <td>bool</td> <td>Wheather or not the \
service provider
-needs a separate city value. If this is @c true, you need to specify a "city" \
parameter in data
-source names for @ref usage_departures_sec and @ref usage_journeys_sec .</td></tr>
-<tr><td><i>onlyUseCitiesInList</i></td> <td>bool</td> <td>Wheather or not the \
service provider
-only accepts cities that are in the "cities" list.</td></tr>
-<tr><td><i>features</i></td> <td>QStringList</td> <td>A list of strings, each string \
stands
-for a feature of the service provider.</td></tr>
-<tr><td><i>featureNames</i></td> <td>QStringList</td> <td>A list of localized names \
describing
-which features the service provider offers.</td></tr>
-<tr><td><i>author</i></td> <td>QString</td> <td>The author of the service provider \
plugin.</td></tr>
-<tr><td><i>email</i></td> <td>QString</td> <td>The email address of the author of \
the
-service provider plugin.</td></tr>
-<tr><td><i>description</i></td> <td>QString</td>
-<td>A description of the service provider.</td></tr>
-<tr><td><i>version</i></td> <td>QString</td>
-<td>The version of the service provider plugin.</td></tr>
-
-<tr><td><i>error</i></td> <td>bool</td> <td>Whether or not the provider plugin has \
errors.
-If this is @c true, the other fields except @em id are not available, instead a \
field
-@em errorMessage is available explaining the error. If this if @c false, the \
provider did not
-encounter any errors. But the provider may still not be ready to use, if the @em \
state field
-contains a state string other than @em "ready". If no @em state field is available, \
the provider
-can also be considered to be ready.</td></tr>
-
-<tr><td><i>errorMessage</i></td> <td>QString</td> <td>A string explaining the error,
-only available if @em error is @c true. </td></tr>
-
-<tr><td><i>state</i></td> <td>QString</td>
-<td>A string to identify different provider states. Currently these states are \
available:
-@em "ready" (the provider is ready to use), @em "gtfs_import_pending" (a GTFS
-provider is waiting for the GTFS feed to get imported), @em "importing_gtfs_feed" (a \
GTFS
-provider currently downloads and imports it's GTFS feed).<br />
-A provider can only be used to query for departures/arrivals, etc. if it's state is \
@em "ready"
-and @em error is @c false.
-</td></tr>
-
-<tr><td><i>stateData</i></td> <td>QVariantHash</td> <td>Contains more information \
about the
-current provider state in a QVariantHash. At least a @em statusMessage field is \
contained,
-with a human readable string explaining the current state. There may also be a
-@em statusMessageRich field with a formatted version of @em statusMessage.
-Depending on the @em state additional fields may be available. For example with the
-@em "importing_gtfs_feed" state a field @em progress is available.
-GTFS providers that are @em "ready" also offer these fields as state data:
-@em gtfsDatabasePath (the path to the GTFS database file), @em gtfsDatabaseSize
-(the size in bytes of the GTFS database).</td></tr>
-</table>
-<br />
-Here is an example of how to get service provider information for all available
-service providers:
-@code
-Plasma::DataEngine::Data data = \
dataEngine("publictransport")->query("ServiceProviders");
-foreach( QString serviceProviderName, data.keys() )
-{
- QHash<QString, QVariant> serviceProviderData = \
data.value(serviceProviderName).toHash();
- int id = serviceProviderData["id"].toInt();
- // The name is already available in serviceProviderName
- QString name = serviceProviderData["name"].toString();
- QString country = serviceProviderData["country"].toString();
- QStringList features = serviceProviderData["features"].toStringList();
- bool useSeparateCityValue = \
serviceProviderData["useSeparateCityValue"].toBool();
- QString state = serviceProviderData["state"].toString();
-}
-@endcode
-
-There is also data source named <em>"ServiceProvider \
\<country-code|service-provider-id\>"</em>
-to get information about the default service provider for the given country or about \
the given
-provider with the given ID.
-
-<br />
-@section usage_vehicletypes_sec Receiving Information About Available Vehicle Types
-Information about all available vehicle types can be retrieved from the data source
-@em "VehicleTypes". It stores vehicle type information by vehicle type ID, which \
matches
-the values of the Enums::VehicleType (engine) and PublicTransport::VehicleType
-(libpublictransporthelper) enumerations. The information stored in this data source \
can also be
-retrieved from PublicTransport::VehicleType using libpublictransporthelper, ie. the \
static
-functions of PublicTransport::Global.
-For each vehicle type there are the following key/value pairs:
-<br />
-<table>
-<tr><td><i>id</i></td> <td>QString</td> <td>An untranslated unique string \
identifying the vehicle
-type. These strings match the names of the Enums::VehicleType enumerables.</td> \
</tr>
-<tr><td><i>name</i></td> <td>QString</td> <td>The translated name of the vehicle \
type.</td></tr>
-<tr><td><i>namePlural</i></td> <td>QString</td> <td>Like <i>name</i> but in plural \
form.</td></tr>
-<tr><td><i>iconName</i></td> <td>QString</td> <td>The name of the icon associated \
with the
-vehicle type. This name can be used as argument for the QIcon contructor.</td></tr>
-</table>
-<br />
-Here is an example of how to get more information for a specific vehicle type by \
it's (integer) ID:
-@code
-// This value can be retrieved from eg. a departures data source
-const int vehicleType;
-
-// Query the data engine for information about all available vehicle types
-Plasma::DataEngine::Data allVehicleTypes = \
dataEngine("publictransport")->query("VehicleTypes");
-
-// Extract the information
-const QVariantHash vehicleData = allVehicleTypes[ QString::number(vehicleType) \
].toHash();
-QString id = vehicleData["id"].toString();
-QString name = vehicleData["name"].toString();
-QString namePlural = vehicleData["namePlural"].toString();
-KIcon icon = KIcon( vehicleData["iconName"].toString() );
-@endcode
-
-<br />
-@section usage_departures_sec Receiving Departures or Arrivals
-To get a list of departures/arrivals you need to construct the name of the data \
source. For
-departures it begins with "Departures", for arrivals it begins with "Arrivals". Next \
comes a
-space (" "), then the ID of the service provider to use, e.g. "de_db" for db.de, a \
service provider
-for germany ("Deutsche Bahn"). The following parameters are separated by "|" and \
start with the
-parameter name followed by "=" and the value. The sorting of the additional \
parameters doesn't
-matter. The parameter <i>stop</i> is needed and can be the stop name or the stop ID. \
If the service
-provider has useSeparateCityValue set to @c true (see @ref \
usage_serviceproviders_sec), the
-parameter <i>city</i> is also needed (otherwise it is ignored).
-You can leave the service provider ID away, the data engine then uses the default \
service provider
-for the users country.<br />
-@note All parameter names need to be completely lower case.
-The following parameters are allowed:<br />
-<table>
-<tr><td><i>stop</i></td> <td>The name or ID of the stop to get departures/arrivals \
for.</td></tr>
-<tr><td><i>city</i></td> <td>The city to get departures/arrivals for, if \
needed.</td></tr>
-<tr><td><i>count</i></td> <td>The number of departures/arrivals to get.
- @note This is just a hint for the provider.</td></tr>
-<tr><td><i>timeoffset</i></td> <td>The offset in minutes from now for the first \
departure /
-arrival to get.</td></tr>
-<tr><td><i>time</i></td> <td>The time of the first departure/arrival to get \
("hh:mm"). This uses
-the current date. To use another date use 'datetime'.</td></tr>
-<tr><td><i>datetime</i></td> <td>The date and time of the first departure/arrival to \
get (use
-QDateTime::toString()).</td></tr>
-</table>
-<br />
-
-<b>Examples:</b><br />
-<b>"Departures de_db|stop=Pappelstraße, Bremen"</b><br />
-Gets departures for the stop "Pappelstraße, Bremen" using the service provider \
db.de.<br /><br />
-
-<b>"Arrivals de_db|stop=Leipzig|timeoffset=5|count=99"</b><br />
-Gets arrivals for the stop "Leipzig" using db.de, the first possible arrival is in \
five minutes
-from now, the maximum arrival count is 99.<br /><br />
-
-<b>"Departures de_rmv|stop=Frankfurt (Main) Speyerer Straße|time=08:00"</b><br />
-Gets departures for the stop "Frankfurt (Main) Speyerer Straße" using rmv.de, the \
first possible
-departure is at eight o'clock.<br /><br />
-
-<b>"Departures de_rmv|stop=3000019|count=20|timeoffset=1"</b><br />
-Gets departures for the stop with the ID "3000019", the first possible departure is \
in one minute
-from now, the maximum departure count is 20.<br /><br />
-
-<b>"Departures stop=Hauptbahnhof"</b><br />
-Gets departures for the stop "Hauptbahnhof" using the default service provider for \
the users
-country, if there is one.<br /><br />
-
-Once you have the data source name, you can connect your applet to that data source \
from the data
-engine. Here is an example of how to do this:
-@code
-class Applet : public Plasma::Applet {
-public:
- Applet(QObject *parent, const QVariantList &args) : AppletWithState(parent, \
args) {
- dataEngine("publictransport")->connectSource( "Departures de_db|stop=Köln, \
Hauptbahnhof",
- this, 60 * 1000 );
- };
-
-public slots:
- void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data \
&data ) {
- if ( data.value("error").toBool() ) {
- // Handle errors
- } else if ( data.contains("stops") ) {
- // Possible stop list received, because the given stop name is ambiguous
- // See section "Receiving Stop Lists"
- } else {
- // Departures / arrivals received.
- QVariantList departures = data.contains("departures")
- ? data["departures"].toList() : data["arrivals"].toList();
-
- foreach ( const QVariant &departureData, departures ) {
- QHash<QString, QVariant> departure = departureData.toHash();
- QString line = departure["TransportLine"].toString();
- // For arrival lists this is the origin
- QString target = departure["Target"].toString();
- QDateTime departure = departure["DepartureDateTime"].toDateTime();
- }
- }
- };
-};
-@endcode
-<br />
-@subsection usage_departures_datastructure_sec Departure Data Source Structure
-The data received from the data engine always contains these keys:<br />
-<table>
-<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr>
-<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if @em error is @c \
true),
-an error message string.</td></tr>
-<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code.
- Error code 1 means, that there was a problem downloading a source file.
- Error code 2 means, that parsing a source file failed.
- Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it.
- Use the @ref PublicTransportService to start and monitor the import.</td></tr>
-<tr><td><i>receivedData</i></td> <td>QString</td> <td>"departures", "journeys", \
"stopList" or
-"nothing" if there was an error.</td></tr>
-<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and time when the data \
source was
-last updated.</td></tr>
-<tr><td><i>nextAutomaticUpdate</i></td> <td>QDateTime</td> <td>The date and time of \
the next
-automatic update of the data source.</td></tr>
-<tr><td><i>minManualUpdateTime</i></td> <td>QDateTime</td> <td>The minimal date and \
time to request
-an update using the "requestUpdate" operation of the timetable service.</td></tr>
-<tr><td><i>departures</i> or <i>arrivals</i></td> <td>QVariantList</td>
-<td>A list of all found departures/arrivals.</td></tr>
-</table>
-<br />
-
-Each departure/arrival in the data received from the data engine (departureData in \
the code
-example) has the following keys:<br />
-<table>
-<tr><td><i>TransportLine</i></td> <td>QString</td> <td>The name of the public \
transport line,
-e.g. "S1", "6", "1E", "RB 24155".</td></tr>
-<tr><td><i>Target</i></td> <td>QString</td> <td>The name of the target / origin of \
the public
-transport line.</td></tr>
-<tr><td><i>DepartureDateTime</i></td> <td>QDateTime</td> <td>The date and time of \
the
-departure / arrival.</td></tr>
-<tr><td><i>TypeOfVehicle</i></td> <td>int</td> <td>An integer containing the ID of \
the vehicle type
-used for the departure/arrival. When you are using libpublictransporthelper, you can \
cast this ID
-to PublicTransport::VehicleType and get more information about the vehicle type \
using the static
-functions of PublicTransport::Global. Alternatively you can use the "VehicleTypes" \
data source,
-it stores vehicle type information in a hash with vehicle type ID's as keys.
-See also @ref usage_vehicletypes_sec. </td></tr>
-<tr><td><i>Nightline</i></td> <td>bool</td> <td>Wheather or not the public transport \
line
-is a night line.</td></tr>
-<tr><td><i>Expressline</i></td> <td>bool</td> <td>Wheather or not the public \
transport line
-is an express line.</td></tr>
-<tr><td><i>Platform</i></td> <td>QString</td> <td>The platform from/at which the \
vehicle
-departs/arrives.</td></tr>
-<tr><td><i>Delay</i></td> <td>int</td> <td>The delay in minutes, 0 means 'on \
schedule',
--1 means 'no delay information available'.</td></tr>
-<tr><td><i>DelayReason</i></td> <td>QString</td> <td>The reason of a \
delay.</td></tr>
-<tr><td><i>Status</i></td> <td>QString</td> <td>The status of the departure, if \
available.</td></tr>
-<tr><td><i>JourneyNews</i></td> <td>QString</td> <td>News for the journey.</td></tr>
-<tr><td><i>Operator</i></td> <td>QString</td>
-<td>The company that is responsible for the journey.</td></tr>
-<tr><td><i>RouteStops</i></td> <td>QStringList</td> <td>A list of stops of the \
departure/arrival
-to it's destination stop or a list of stops of the journey from it's start to it's \
destination stop.
-If 'routeStops' and 'routeTimes' are both set, they contain the same number of \
elements.
-And elements with equal indices are associated (the times at which the vehicle is at \
the stops).
-</td></tr>
-<tr><td><i>RouteTimes</i></td> <td>QList< QTime > (stored as QVariantList)</td>
-<td>A list of times of the departure/arrival to it's destination stop. If \
'routeStops' and
-'routeTimes' are both set, they contain the same number of elements. And elements \
with
-equal indices are associated (the times at which the vehicle is at the \
stops).</td></tr>
-<tr><td><i>RouteExactStops</i></td> <td>int</td> <td>The number of exact route \
stops.
-The route stop list is not complete from the last exact route stop.</td></tr>
-</table>
-
-@note The service provider may not load all data by default. To load missing data
- ("additional data"), use the timetable service's operation \
"requestAdditionalData",
- @ref usage_service_sec.
-
-<br />
-@section usage_journeys_sec Receiving Journeys from A to B
-To get a list of journeys from one stop to antoher you need to construct the name of \
the data
-source (much like the data source for departures / arrivals). The data source name \
begins with
-"Journeys". Next comes a space (" "), then the ID of the service provider to use, \
e.g. "de_db"
-for db.de, a service provider for germany ("Deutsche Bahn").
-The following parameters are separated by "|" and start with the parameter name \
followed by "=".
-The sorting of the additional parameters doesn't matter. The parameters \
<i>originstop</i> and
-<i>targetstop</i> are needed and can be the stop names or the stop IDs. If the \
service provider
-has useSeparateCityValue set to @c true (see @ref usage_serviceproviders_sec), the \
parameter
-<i>city</i> is also needed (otherwise it is ignored).<br />
-@note All parameter names need to be completely lower case.
-The following parameters are allowed:<br />
-<table>
-<tr><td><i>originstop</i></td> <td>The name or ID of the origin stop.</td></tr>
-<tr><td><i>targetstop</i></td> <td>The name or ID of the target stop.</td></tr>
-<tr><td><i>city</i></td> <td>The city to get journeys for, if needed.</td></tr>
-<tr><td><i>count</i></td> <td>The number of journeys to get.
- @note This is just a hint for the provider</td></tr>
-<tr><td><i>timeoffset</i></td>
-<td>The offset in minutes from now for the first journey to get.</td></tr>
-<tr><td><i>time</i></td> <td>The time for the first journey to get (in format \
"hh:mm").</td></tr>
-<tr><td><i>datetime</i></td> <td>The date and time for the first journey to get
-(QDateTime::fromString() is used with default parameters to parse the \
date).</td></tr>
-</table>
-<br />
-
-<b>Examples:</b><br />
-<b>"Journeys de_db|originstop=Pappelstraße, Bremen|targetstop=Kirchweg, \
Bremen"</b><br />
-Gets journeys from stop "Pappelstraße, Bremen" to stop "Kirchweg, Bremen"
-using the service provider db.de.<br /><br />
-
-<b>"Journeys de_db|originstop=Leipzig|targetstop=Hannover|timeoffset=5|count=99"</b><br \
/>
-Gets journeys from stop "Leipzig" to stop "Hannover" using db.de, the first
-possible journey departs in five minutes from now, the maximum journey count is \
99.<br /><br />
-
-Once you have the data source name, you can connect your applet to that
-data source from the data engine. Here is an example of how to do this:
-@code
-class Applet : public Plasma::Applet {
-public:
- Applet(QObject *parent, const QVariantList &args) : AppletWithState(parent, \
args) {
- dataEngine("publictransport")->connectSource(
- "Journeys de_db|originstop=Pappelstraße, \
Bremen|targetstop=Kirchweg, Bremen",
- this, 60 * 1000 );
- };
-
-public slots:
- void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data \
&data ) {
- if ( data.value("error").toBool() ) {
- // Handle errors
- } else if ( data.contains("stops") ) {
- // Possible stop list received, because the given stop name is ambiguous
- // See section "Receiving Stop Lists"
- } else {
- // Journeys received.
- QVariantList journeysData = data["journeys"].toList();
- foreach ( const QVariant &journeyData, journeysData ) {
- QHash<QString, QVariant> journey = journeyData.toHash();
-
- // Get vehicle type list
- QVariantList = journey["TypesOfVehicleInJourney"].toList();
- QList< PublicTransport::VehicleType > vehicleTypes;
- foreach( QVariant vehicleType, vehicleTypesVariant ) {
- vehicleTypes.append(
- static_cast< PublicTransport::VehicleType >( \
vehicleType.toInt() ) );
- }
-
- QString target = journey["StartStopName"].toString();
- QDateTime departure = journey["DepartureDateTime"].toDateTime();
- int duration = journey["Duration"].toInt(); // Duration in minutes
- }
- }
- };
-};
-@endcode
-<br />
-@subsection usage_journeys_datastructure_sec Journey Data Source Structure
-The data received from the data engine always contains these keys:<br />
-<table>
-<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr>
-<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if @em error is @c \
true),
-an error message string.</td></tr>
-<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code.
- Error code 1 means, that there was a problem downloading a source file.
- Error code 2 means, that parsing a source file failed.
- Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it.
- Use the @ref PublicTransportService to start and monitor the import.</td></tr>
-<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and time when the data \
source was
-last updated.</td></tr>
-<tr><td><i>journeys</i></td> <td>QVariantList</td> <td>A list of all found \
journeys.</td></tr>
-</table>
-<br />
-Each journey in the data received from the data engine (journeyData in the code
-example) has the following keys:<br />
-<i>vehicleTypes</i>: A QVariantList containing a list of vehicle type ID's \
(integers) of vehicles
-used in the journey. You can cast the list to QList<PublicTransport::VehicleType> as \
seen in the
-code example above (QVariantList), if you use libpublictransporthelper. \
Alternatively the
-"VehicleTypes" data source can be used to get more information about the vehicle \
types.
-See also @ref usage_vehicletypes_sec. <br />
-<table>
-<tr><td><i>ArrivalDateTime</i></td> <td>QDateTime</td> <td>The date and time of the \
arrival
-at the target stop.</td></tr>
-<tr><td><i>DepartureDateTime</i></td> <td>QDateTime</td> <td>The date and time of \
the departure
-from the origin stop.</td></tr>
-<tr><td><i>Duration</i></td> <td>int</td> <td>The duration in minutes of the \
journey.</td></tr>
-<tr><td><i>Changes</i></td> <td>int</td>
-<td>The changes between vehicles needed for the journey.</td></tr>
-<tr><td><i>Pricing</i></td> <td>QString</td>
-<td>Information about the pricing of the journey.</td></tr>
-<tr><td><i>JourneyNews</i></td> <td>QString</td> <td>News for the journey.</td></tr>
-<tr><td><i>StartStopName</i></td> <td>QString</td> <td>The name or ID of the origin \
stop.</td></tr>
-<tr><td><i>TargetStopName</i></td> <td>QString</td>
-<td>The name or ID of the target stop (QString).</td></tr>
-<tr><td><i>Operator</i></td> <td>QString</td>
-<td>The company that is responsible for the journey.</td></tr>
-<tr><td><i>RouteStops</i></td> <td>QStringList</td> <td>A list of stops of the \
journey
-from it's start to it's destination stop. If 'routeStops' and 'routeTimes' are both \
set,
-they contain the same number of elements. And elements with equal indices are \
associated
-(the times at which the vehicle is at the stops).</td></tr>
-<tr><td><i>RouteNews</i></td> <td>QStringList</td> <td>A list of news/comments for \
sub-journeys.
-If 'RouteStops' and 'RouteNews' are both set, the latter contains one element less
-(one news/comment string for each sub-journey between two stop from \
'RouteStops').</td></tr>
-<tr><td><i>RouteTimesDeparture</i></td> <td>QList< QTime > (stored as \
QVariantList)</td>
-<td>A list of departure times of the journey to it's destination stop. If \
'routeStops' and
-'routeTimesDeparture' are both set, the latter contains one element less (because \
the last stop
-has no departure, only an arrival time). Elements with equal indices are associated
-(the times at which the vehicle departs from the stops).</td></tr>
-<tr><td><i>RouteTimesArrival</i></td> <td>QList< QTime > (stored as \
QVariantList)</td>
-<td>A list of arrival times of the journey to it's destination stop. If 'routeStops' \
and
-'routeTimesArrival' are both set, the latter contains one element less (because the \
last stop
-has no departure, only an arrival time). Elements with equal indices are associated
-(the times at which the vehicle departs from the stops).</td></tr>
-<tr><td><i>RouteExactStops</i></td> <td>int</td> <td>The number of exact route \
stops.
-The route stop list isn't complete from the last exact route stop.</td></tr>
-<tr><td><i>RouteTypesOfVehicles</i></td> <td>QList< int > (stored as \
QVariantList)</td>
-<td>A list of vehicle type ID's (integers) of vehicles used for each "sub-journey" \
in the journey.
-See the <i>vehicleTypes</i> field or @ref usage_vehicletypes_sec for more \
information. </td></tr>
-<tr><td><i>RouteTransportLines</i></td> <td>QStringList</td>
-<td>A list of transport lines used for each "sub-journey" in the journey.</td></tr>
-<tr><td><i>RoutePlatformsDeparture</i></td> <td>QStringList</td>
-<td>A list of platforms of the departure used for each stop in the \
journey.</td></tr>
-<tr><td><i>RoutePlatformsArrival</i></td> <td>QStringList</td>
-<td>A list of platforms of the arrival used for each stop in the journey.</td></tr>
-<tr><td><i>RouteTimesDepartureDelay</i></td> <td>QList< int > (stored as \
QVariantList)</td>
-<td>A list of delays in minutes of the departures at each stop in the journey. A \
value of 0 means,
-that the vehicle is on schedule, -1 means, that there's no information about \
delays.</td></tr>
-<tr><td><i>RouteTimesArrivalDelay</i></td> <td>QList< int > (stored as \
QVariantList)</td>
-<td>A list of delays in minutes of the arrivals at each stop in the journey. A value \
of 0 means,
-that the vehicle is on schedule, -1 means, that there's no information about \
delays.</td></tr>
-<tr><td><i>RouteSubJourneys</i></td> <td>QList< QVariantMap ></td> <td>A list of \
data maps for
-all sub-journeys between two connecting stops. If 'RouteStops' and \
'RouteSubJourneys' are both set,
-the latter contains one element less (one sub-journey between two stops from \
'RouteStops').
-Each map in the list contains route data for the sub journey. These \
TimetableInformation values
-can be used inside this map: RouteStops, RouteNews, RouteTimesDeparture, \
RouteTimesArrival,
-RouteTimesDepartureDelay, RouteTimesArrivalDelay, RoutePlatformsDeparture and \
RoutePlatformsArrival.
-Each list should contain the same number of elements here (no origin or target \
included here,
-only intermediate stops).</td></tr>
-</table>
-
-<br />
-@section usage_stopList_sec Receiving Stop Lists
-To get a list of stop suggestions use the data source
-@verbatim "Stops <service-provider-id>|stop=<stop-name-part>" @endverbatim
-If the provider supports the @em ProvidesStopsByGeoPosition feature, the following \
parameters can
-be used to get stops at a specific geo position:
-@verbatim "Stops <service-provider-id>|latitude=<decimal-latitude>|longitude=<decimal-longitude>" \
@endverbatim
-
-In your dataUpdated-slot you should first check, if a stop list was received by \
checking if a
-key "stops" exists in the data object from the data engine. Then you get the stop \
data, which is
-stored in the key "stops" and contains a list of data sets, one for each stop. They \
have at least
-a <i>StopName</i> key (containing the stop name). They <b>may</b> additionally \
contain a
-<i>StopID</i> (a non-ambiguous ID for the stop, if available, otherwise it is \
empty),
-<i>StopWeight</i> (the weight of the suggestion), a <i>StopCity</i> (the city the \
stop is in)
-and a <i>StopCountryCode</i> (the code of the country in with the stop is). If the \
provider
-supports the ProvidesStopGeoPosition feature they also contain <i>StopLatitude</i> \
and
-<i>StopLongitude</i>.
-
-@code
-void dataUpdated( const QString &sourceName, const Plasma::DataEngine::Data &data ) \
{
- if ( data.contains("stops").toBool() ) {
- QStringList possibleStops;
- QVariantList stops = data["stops"].toList();
- foreach ( const QVariant &stopData, stops ) {
- QVariantHash stop = stopData.toHash();
-
- // Get the name
- QString stopName = stop["StopName"].toString();
-
- // Get other values
- if ( stopData.contains("StopID") ) {
- QString stopID = stop["StopID"].toString();
- }
- QString stopCity = stop["StopCity"].toString();
- QString stopCityCode = stop["StopCountryCode"].toString();
- }
- }
-}
-@endcode
-
-@subsection usage_stopList_datastructure_sec Stop Data Source Structure
-The data received from the data engine contains these keys:<br />
-<table>
-<tr><td><i>error</i></td> <td>bool</td> <td>True, if an error occurred while \
parsing.</td></tr>
-<tr><td><i>errorMessage</i></td> <td>QString</td> <td>(only if @em error is @c \
true),
-an error message string.</td></tr>
-<tr><td><i>errorCode</i></td> <td>int</td> <td>(only if @em error is @c true), an \
error code.
- Error code 1 means, that there was a problem downloading a source file.
- Error code 2 means, that parsing a source file failed.
- Error code 3 means that a GTFS feed needs to be imorted into the database before \
using it.
- Use the @ref PublicTransportService to start and monitor the import.</td></tr>
-<tr><td><i>updated</i></td> <td>QDateTime</td> <td>The date and time when the data \
source was
-last updated.</td></tr>
-<tr><td><i>stops</i></td> <td>QVariantList</td> <td>A list of all found \
stops.</td></tr>
-</table>
-<br />
-Each stop in the data received from the data engine has the following keys:<br />
-<table>
-<tr><td><i>StopName</i></td> <td>QString</td> <td>The name of the stop.</td></tr>
-<tr><td><i>StopID</i></td> <td>QString</td> <td>A unique ID for the stop, if \
available.</td></tr>
-<tr><td><i>StopWeight</i></td> <td>int</td>
-<td>The weight of the stop as a suggestion, if available.</td></tr>
-<tr><td><i>StopCity</i></td> <td>QString</td>
-<td>The name of the city the stop is in, if available.</td></tr>
-<tr><td><i>StopCountryCode</i></td> <td>QString</td> <td>The code of the country in \
with
-the stop is, if available.</td></tr>
-<tr><td><i>StopLatitude</i></td> <td>qreal</td> <td>The decimal latitude of the \
stop.
-Only available if the provider supports the ProvidesStopGeoPosition \
feature.</td></tr>
-<tr><td><i>StopLongitude</i></td> <td>qreal</td> <td>The decimal longitude of the \
stop.
-Only available if the provider supports the ProvidesStopGeoPosition \
feature.</td></tr>
-</table>
-
-<br />
-@section usage_service_sec Using the Timetable Service
-This service is available for all timetable data sources, ie. departure, arrival and \
journey
-data sources. It can be retrieved using DataEngine::serviceForSource() with the name \
of the
-timetable data source. The service offers some operations on timetable data sources \
and allows
-to change it's contents, ie. update or extend it with new data.
-
-@subsection usage_service_manual_update Manual updates
-Manual updates can be requested for timetable data sources using the @b \
requestUpdate operation.
-They may be rejected if the last update was not long enough ago (see the @em \
minManualUpdateTime
-field of the data source). Manual updates are allowed more often than automatic \
updates.
-Does not need any parameters.
-The following code example shows how to use the service to request a manual update:
-@code
-// Get a pointer to the service for the used data source,
-// use Plasma::Applet::dataEngine() to get a pointer to the engine,
-// alternatively Plasma::DataEngineManager can be used
-Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName );
-
-// Start the "requestUpdate" operation (no parameters)
-KConfigGroup op = service->operationDescription("requestUpdate");
-Plasma::ServiceJob *updateJob = service->startOperationCall( op );
-
-// Connect to the finished() slot if needed
-connect( updateJob, SIGNAL(finished(KJob*)), this, \
SLOT(updateRequestFinished(KJob*)) );
-@endcode
-
-@subsection usage_service_additional_data Request additional data
-Additional data (eg. route data) can be requested for specific timetable items. \
There are two
-operations @b "requestAdditionalData" and @b "requestAdditionalDataRange", the \
latter one should
-be used if additional data gets requested for multiple items at once to save data \
source updates
-in the engine. Uses an "itemnumber" or "itemnumberbegin"/"itemnumberend" parameters \
to identify
-the timetable item(s) to get additional data for.
-@code
-// Get a pointer to the service for the used data source, like in example 1
-Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName );
-
-// Start the "requestAdditionalData" operation
-// with an "itemnumber" parameter, 0 to get additional data for the first item
-KConfigGroup op = service->operationDescription("requestAdditionalData");
-op.writeEntry( "itemnumber", 0 );
-Plasma::ServiceJob *additionalDataJob = service->startOperationCall( op );
-@endcode
-
-@subsection usage_service_later_items Request earlier/later items
-Use the operations @b "requestEarlierItems" and @b "requestLaterItems" to get more \
timetable items
-for a data source. This is currently only used for journeys. The difference between \
these operation
-and simply requesting more journeys with an earlier/later time is that the provider \
may benefit
-from data stored for the request at the provider's server (if any) when using this \
operation.
-Another difference is that the data source will contain both the old and the \
earlier/later
-journeys after using this operation.
-
-These operations need the used service provider to support the @em \
ProvidesMoreJourneys feature.
-Does not need any parameters.
-@code
-// Get a pointer to the service for the used data source, like in example 1
-Plasma::Service *service = dataEngine("publictransport")->serviceForSource( \
sourceName );
-
-// Start the "requestLaterItems" operation (no parameters)
-KConfigGroup op = service->operationDescription("requestLaterItems");
-Plasma::ServiceJob *laterItemsJob = service->startOperationCall( op );
-@endcode
-*/
-
-/** @page pageServiceProviders Add Support for new Service Providers
-@par Sections
- @li @ref provider_infos_xml
- @li @ref provider_infos_script
- @li @ref examples
- @li @ref examples_xml_gtfs
- @li @ref examples_xml_script
- @li @ref examples_script
-<br />
-
-@section provider_infos_xml XML file structure
-To add support for a new service provider you need to create a service provider \
plugin for the
-PublicTransport engine, which is essentially an XML file with information about the \
service
-provider. This XML file contains a name, description, changelog, etc. for the \
service provider
-plugin.
-It can also contain a reference to a script to parse documents from the provider to \
process
-requests from the data engine. There are many helper functions available for scripts \
to parse HTML
-documents, QtXML is available to parse XML documents (as extension).
-The filename of the XML file starts with the country code or \
"international"/"unknown", followed
-by "_" and a short name for the service provider, e.g. "de_db.pts", "ch_sbb.pts", \
"sk_atlas.pts",
-"international_flightstats.pts". The base file name (without extension) is the \
service provider ID.
-<br />
-There is also a nice tool called @em TimetableMate. It's a little IDE to create \
service
-provider plugins for the PublicTransport data engine. The GUI is similiar to the GUI \
of KDevelop,
-it also has docks for projects, breakpoints, backtraces, variables, a console, \
script output and
-so on. TimetableMate also shows a nice dashboard for the service provider plugin \
projects. It
-features script editing, syntax checking, code-completion for the engine's script \
API, automatic
-tests, web page viewer, network request/reply viewer with some filters, a Plasma \
preview etc.<br />
-
-Here is an overview of the allowed tags in the XML file (required child tags of the \
serviceProvider
-tag are <span style="background-color: #ffdddd;">highlighted</span>):
-<table>
-<tr style="background-color: #bbbbbb; font-weight: bold;"><td>Tag</td> <td>Parent \
Tag</td>
-<td>Optional?</td> <td>Description</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<?xml version="1.0" encoding="UTF-8"?\></b></td>
-<td>Root</td> <td>Required</td><td>XML declaration.</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<serviceProvider fileVersion="1.1" version=@em "plugin-version" type=@em \
"provider-type" \> </b></td>
-<td>Root</td> <td>Required</td> <td>This is the root item. The only currently \
supported provider
-plugin format version is 1.1 and gets written as 'fileVersion' attribute. The \
'version' attribute
-contains the version of the plugin itself and the 'type' attribute specifies the \
type of the
-plugin, which can currently be either @em "script" or @em "gtfs".</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<name\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
-<td>The name of the service provider (plugin). If it provides data for international \
stops it
-should begin with "International", if it's specific for a country or city it should \
begin with the
-name of that country or city. That should be followed by a short url to the service \
provider.
-</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<description\> </b></td><td>\<serviceProvider\> </td> <td>Required</td>
-<td>A description of the service provider (plugin). You don't need to list the \
features
-supported by the service provider here, the feature list is generated \
automatically.</td></tr>
-
-<tr style="background-color: #ffdddd;"><td style="color:#888800">
-<b>\<author\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
-<td>Contains information about the author of the service provider plugin.</td></tr>
-
-<tr><td style="color:#666600">
-<b>\<fullname\> </b></td><td style="color:#888800">\<author\></td> <td>Required</td>
-<td>The full name of the author of the service provider plugin.</td></tr>
-
-<tr><td style="color:#666600">
-<b>\<short\> </b></td><td style="color:#888800">\<author\></td> <td>(Optional)</td>
-<td>A short name for the author of the service provider plugin (eg. the \
initials).</td></tr>
-
-<tr><td style="color:#666600">
-<b>\<email\> </b></td><td style="color:#888800">\<author\></td> <td>(Optional)</td> \
<td>
-The email address of the author of the service provider plugin.</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<version\> </b></td><td>\<serviceProvider\> </td> <td>Required</td>
-<td>The version of the service provider plugin, should start with "1.0".</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<url\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
-<td>An url to the service provider home page.</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<shortUrl\> </b></td><td>\<serviceProvider\></td> <td>Required</td>
-<td>A short version of the url, used as link text.</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<script\> </b></td><td>\<serviceProvider\></td>
-<td>Required for script provider plugins</td>
-<td>Contains the filename of the script to be used to parse timetable documents.
-The script must be in the same directory as the XML file. Always use "Script" as \
type when
-using a script. Can have an "extensions" attribute with a comma separated list of \
QtScript
-extensions to load when executing the script.</td></tr>
-
-<tr><td style="color:#00bb00">
-<b>\<cities\> </b></td><td>\<serviceProvider\></td> <td>(Optional)</td>
-<td>A list of cities the service provider has data for (with surrounding \
\<city\>-tags).</td></tr>
-
-<tr><td style="color:#007700">
-<b>\<city\> </b></td><td style="color:#00bb00">\<cities\></td> <td>(Optional)</td>
-<td>A city in the list of cities (\<cities\>). Can have an attribute "replaceWith",
-to replace city names with values used by the service provider.</td></tr>
-
-<tr><td><b>\<notes> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
-<td>Custom notes for the service provider plugin. Can be a to do list.</td></tr>
-
-<tr><td><b>\<fallbackCharset\> </b></td><td>\<serviceProvider\> </td> \
<td>Optional</td>
-<td>The charset of documents to be downloaded. Depending on the used service \
provider this might
-be needed or not. Scripts can use this value.</td></tr>
-
-<tr><td><b>\<credit\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
-<td>A courtesy string that is required to be shown to the user when showing the \
timetable data
-of the GTFS feed. If this tag is not given, a short default string is used,
-eg. "data by: www.provider.com" or only the link (depending on available space).
-Please check the license agreement for using the GTFS feed for such a string and \
include it here.
-</td></tr>
-
-<tr style="background-color: #ffdddd;">
-<td><b>\<feedUrl\> </b></td><td>\<serviceProvider\> </td> <td>(Required only with \
"GTFS" type)</td>
-<td>An URL to the GTFS feed to use. Use an URL to the latest available \
feed.</td></tr>
-
-<tr><td><b>\<realtimeTripUpdateUrl\> </b></td><td>\<serviceProvider\> </td>
-<td>(Optional, only used with "GTFS" type)</td>
-<td>An URL to a GTFS-realtime data source with trip updates. If this tag is not \
present delay
-information will not be available.</td></tr>
-
-<tr><td><b>\<realtimeAlertsUrl\> </b></td><td>\<serviceProvider\> </td>
-<td>(Optional, only used with "GTFS" type)</td>
-<td>An URL to a GTFS-realtime data source with alerts. If this tag is not present \
journey news
-will not be available.</td></tr>
-
-<tr><td style="color:#00bb00;">
-<b>\<changelog\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
-<td>Contains changelog entries for this service provider plugin.</td></tr>
-
-<tr><td style="color:#007700;">
-<b>\<entry\> </b></td><td style="color:#00bb00;">\<changelog\> </td> \
<td>(Optional)</td>
-<td>Contains a changelog entry for this service provider plugin. The entry \
description is read
-from the contents of the \<entry\> tag. Attributes @em version (the plugin version \
where
-this change was applied) and @em engineVersion (the version of the publictransport
-data engine this plugin was first released with) can be added.</td></tr>
-
-<tr><td style="color:#880088;">
-<b>\<samples\> </b></td><td>\<serviceProvider\> </td> <td>(Optional)</td>
-<td>Contains child tags \<stop\> and \<city\> with sample stop/city names. These \
samples are used
-eg. in TimetableMate for automatic tests.</td></tr>
-
-<tr><td style="color:#660066;">
-<b>\<stop\> </b></td><td style="color:#880088;">\<samples\> </td> \
<td>(Optional)</td>
-<td>A sample stop name.</td></tr>
-
-<tr><td style="color:#660066;">
-<b>\<city\> </b></td><td style="color:#880088;">\<samples\> </td> \
<td>(Optional)</td>
-<td>A sample city name.</td></tr>
-</table>
-
-@section provider_infos_script Script file structure
-Scripts are executed using QtScript (JavaScript), which can make use of Kross if \
other script
-languages should be used, eg. Python or Ruby. JavaScript is tested, the other \
languages may also
-work. There are functions with special names that get called by the data engine when \
needed:
-@n
-getTimetable(), getStopSuggestions(), getJourneys() and features()
-@n
-
-@n
-@section examples Service Provider Plugin Examples
-@n
-@subsection examples_xml_script A Simple Script Provider Plugin
-Here is an example of a simple service provider plugin which uses a script to parse \
data from
-the service provider:
-@verbinclude ch_sbb.pts
-
-@subsection examples_xml_gtfs A Simple GTFS Provider Plugin
-The simplest provider XML can be written when using a GTFS feed. This example also \
contains tags
-for GTFS-realtime support, which is optional.
-@verbinclude us_bart.pts
-
-@n
-@subsection examples_script A Simple Parsing-Script
-This is an example of a script used to parse data from the service provider. The \
script uses the
-base script class for HAFAS providers, which already has quite flexible \
implementations
-for the script.
-@include ch_sbb.js
-*/
-
-/** @page pageClassDiagram Class Diagram
-\dot
-digraph publicTransportDataEngine {
- ratio="compress";
- size="10,100";
- // concentrate="true";
- // rankdir="LR";
- clusterrank=local;
-
- node [
- shape=record
- fontname=Helvetica, fontsize=10
- style=filled
- fillcolor="#eeeeee"
- ];
-
- engine [
- label="{PublicTransportEngine|The main class of the public transport data \
engine.\l}"
- URL="\ref PublicTransportEngine"
- style=filled
- fillcolor="#ffdddd"
- ];
-
- providerScript [
- label="{ServiceProviderScript|Parses timetable documents (eg. HTML) using \
scripts.}"
- URL="\ref ServiceProviderScript"
- fillcolor="#dfdfff"
- ];
-
- providerGtfs [
- label="{ServiceProviderGtfs|Imports GTFS feeds into a local database.}"
- URL="\ref ServiceProviderGtfs"
- fillcolor="#dfdfff"
- ];
-
- provider [
- label="{ServiceProvider|Loads timetable data from service providers.\lIt \
uses ServiceProviderData to get needed information.\l|# requestDepartures()\l# \
requestJourneys()\l# requestStopSuggestions()\l# requestStopsByGeoPosition()\l# \
requestAdditionData()\l# requestMoreItems()\l+ data() : \
ServiceProviderData\l}"
- URL="\ref ServiceProvider"
- fillcolor="#dfdfff"
- ];
-
- timetableData [
- label="{TimetableData|Typedef for QHash with TimetableInformation keys and \
QVariant values.\lCan be used to describe a departure, arrival, \
journey or stop.}"
- URL="\ref TimetableData"
- ];
-
- serviceProviderData [
- label="{ServiceProviderData|Information about the service provider.\l|+ \
name() : QString\l+ description() : QString\l+ features() : \
QStringList\l... }"
- URL="\ref ServiceProviderData"
- ];
-
- { rank=same; provider providerScript providerGtfs }
-
- edge [ arrowhead="empty", arrowtail="none", style="solid" ];
- providerScript -> provider;
- providerGtfs -> provider;
-
- edge [ dir=back, arrowhead="normal", arrowtail="none", style="dashed", \
fontcolor="gray", taillabel="", headlabel="0..*" ];
- engine -> provider [ label=""uses ];
- provider -> timetableData [ label="uses" ];
- provider -> serviceProviderData [ label="uses" ];
-
- edge [ dir=both, arrowhead="normal", arrowtail="normal", color="gray", \
fontcolor="gray", style="dashed", headlabel="" ];
- serviceProviderData -> provider [ label="friend" ];
-}
-@enddot
-*/
-
-#endif
-
-struct JourneyRequest;
+#endif // Multiple inclusion guard
diff --git a/engine/script/script-doc.h b/engine/script/script-doc.h
new file mode 100644
index 0000000..86df298
--- /dev/null
+++ b/engine/script/script-doc.h
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2012 Friedrich Pülz <fpuelz@gmx.de>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this program; if not, write to the
+ * Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/**
+ * @defgroup scriptProviders Script Provider Plugins
+ *
+ * Script provider plugins implement execution of timetable data requests in a \
script. The script + * file to use gets referenced in the .pts file in the \<script\> \
tag, see @ref provider_plugin_pts. + * Script extensions that are needed inside the \
script (eg. @em qt.xml) can be specified in an + * @em extensions attribute for that \
tag. The script can use the @ref scriptApi, which provides + * ways to start network \
requests synchronously and asynchronously, helper functions to parse + * HTML, a \
Storage to cache/save information etc. + *
+ * Currently all included script providers need a network connection to work and \
directly get the + * state @em ready if there are no errors in the script. If a \
provider instead requires to download + * all timetable data at once and could then \
execute requests offline, this provider plugin type + * is not the right one. If you \
want to add support for a GTFS provider, use @ref gtfsProviders. + * Otherwise a new \
plugin type could be created with different request strategies, state handling, + * \
error checking and maybe an own data engine service. + *
+ * @see scriptApi, @ref provider_plugin_types
+ **/
diff --git a/engine/script/script_thread.h b/engine/script/script_thread.h
index 4110d17..7222794 100644
--- a/engine/script/script_thread.h
+++ b/engine/script/script_thread.h
@@ -114,8 +114,6 @@ bool importExtension( QScriptEngine *engine, const QString \
&extension );
/**
* @brief Executes a script.
- *
- * @ingroup scripting
**/
class ScriptJob : public ThreadWeaver::Job {
Q_OBJECT
diff --git a/engine/script/scriptapi-doc.h b/engine/script/scriptapi-doc.h
new file mode 100644
index 0000000..13d883d
--- /dev/null
+++ b/engine/script/scriptapi-doc.h
@@ -0,0 +1,315 @@
+/*
+ * Copyright 2012 Friedrich Pülz <fpuelz@gmx.de>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this program; if not, write to the
+ * Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/**
+ * @defgroup scriptApi Provider Plugin Script API
+ *
+ * These classes get exposed to scripts or are used by scripted service provider \
plugins. + * Each call to a script from the data engine creates a new thread using \
ThreadWeaver. Each thread + * uses it's own QScriptEngine instance to execute the \
script. + *
+ * Scripts are written in ECMAScript, but they can access Kross to support other \
languages, ie. + * Python or Ruby. Kross needs to be imported explicitly. That can be \
done by adding an + * @em "extensions" attribute to the @em \<script\> tag in the XML \
file, like this: + * @verbatim<script \
extensions="kross">file.js</script>@endverbatim. Other extensions can also be + * \
imported, eg. "qt.core" to use classes provided by the "qt.core" bindings. + *
+ * To use eg. Python code in the script, the following code can then be used in a \
script: + * @code
+ * // Create Kross action
+ * var action = Kross.action( "MyPythonScript" );
+ *
+ * // Propagate action to the Python script
+ * action.addQObject( action, "MyAction" );
+ *
+ * // Set the interpreter to use, eg. "python", "ruby"
+ * action.setInterpreter( "python" );
+ *
+ * // Set the code to execute and trigger execution
+ * action.setCode("import MyAction ; print 'This is Python. \
name=>',MyAction.interpreter()"); + * action.trigger();
+ * @endcode
+ * @todo If needed a later version might make this simpler by examining the file \
type of the script + * file and automatically insert the contents of the script \
file into the setCode() function + * like above.
+ *
+ * @n
+ *
+ * @section script_exposed Classes Exposed to Scripts
+ *
+ * Scripts can access some objects that represent classes mentioned here. Only one \
instance of + * these classes is available in a script.
+ * @li @em ResultObject Stores results, ie. parsed data for departures, arrivals, \
journeys or + * stop suggestions. Available for scripts under the name @b result.
+ * @li @em Network Provides network access to scripts and is available for scripts \
under + * the name @b network. This class can create objects of type NetworkRequest \
using + * Network::createRequest() for asynchronous requests. NetworkRequest \
objects have signals + * that scripts can connect to, ie. \
NetworkRequest::finished() to indicate a finished request. + * @li @em Storage Stores \
data between script calls. Can store data in memory or persistently, + * ie. on \
disk. An object of this class is available for scripts under the name @b storage. + * \
The storage object gets shared between calls to the same script (for the same service \
+ * provider) and can be use by multiple script instances at the same time. + * @li \
@em Helper Provides some helper functions to scripts, available under the name @b \
helper. + *
+ * @n
+ *
+ * @section script_functions Script Functions to be Implemented
+ *
+ * There should be specially named functions in the script, that get called by the \
data engine. + * Only the @em getTimetable function @em must be implemented.
+ *
+ * There is a flexible base script available for providers using the HAFAS API.
+ * See @ref examples_script.
+ *
+ * @subsection script_functions_gettimetable getTimetable( values )
+ * This function @em must be implemented (but that may change).
+ * @note This function gets called to get departures @em or arrivals, depending on \
the + * @em dataType property of the parameter. If arrivals are supported add the
+ * Enums::ProvidesArrivals feature to the return value of the \
<em>features()</em> script + * function.
+ *
+ * The only argument contains information about the request with these properties:
+ * @li @em stop: The name/ID of the stop to get departures/arrivals for.
+ * @li @em dateTime: A Date object with the date and time of the earliest \
departure/arrival to get. + * @li @em dataType: This can be "arrivals" or \
"departures". + * @li @em city: If used, this contains the city name to get \
departures/arrivals for. Only some + * service providers need a separate city \
value, most are happy with a stop name/stop ID. + * @li @em count: The number of \
departures/arrivals to get. + *
+ * @subsection script_functions_getstopsuggestions getStopSuggestions( values )
+ * Gets called to request stop suggestions. Since it may be called very often it \
should be fast, + * ie. the downloaded data should be as small as possible.
+ * @note There are two types of stop requests:
+ * <em>stop suggestions</em> get requested with the parameters @em stop, @em \
city and @em count, + * while <em>stops by geolocation</em> get requested with \
@em longitude, @em latitude, + * @em distance and @em count and require the \
Enums::ProvidesStopsByGeoPosition feature to be + * returned by the \
<em>features()</em> script function. + *
+ * @li @em stop: A part of a stop name to get suggestions for. This is what users \
can type in, eg. + * the beginning of the complete stop name.
+ * @li @em city: If used, this contains the city name to get stop suggestions for. \
Only some + * service providers need a separate city value, most are happy with a \
part of the stop name. + * @li @em longitude: Used together with @em latitude and \
@em distance for stop requests by + * geolocation, which is given by @em \
longitude and @em latitude. + * @li @em latitude: Used together with @em longitude \
and @em distance for stop requests by + * geolocation, which is given by @em \
longitude and @em latitude. + * @li @em distance: The distance in meters around the \
geolocation given with @em longitude and + * @em latitude where to search for \
stops. + * @li @em count: The number of stop suggestions to get.
+ *
+ * @subsection script_functions_getjourneys getJourneys( values )
+ * Gets called to request journeys (trips from stop A to stop B).
+ * @note Journey requests are also used to get more journeys after a previous \
request. In this + * case the properties @em moreItemsDirection and @em \
requestData are available and + * @em moreItemsDirection does not equal to @em \
PublicTransport.RequestedItems. + * The result currently also needs to include \
the first received set of journeys. + *
+ * The only argument contains information about the request with these properties:
+ * @li @em originStop: The name/ID of the start/origin stop, also available as \
'stop' property. + * @li @em targetStop: The name/ID of the target/destination \
stop. + * @li @em dateTime: A Date object with the date and time of the earliest \
journey to get. + * @li @em dataType: This can be "journeys"/"journeysDep" \
(journeys departing at the given @em dateTime) + * or "journeysArr" (journeys \
arriving at the given @em dateTime). + * @li @em city: If used, this contains the \
city name to get journeys for. Only some + * service providers need a separate \
city value, most are happy with a stop name/stop ID. + * @li @em count: The number \
of journeys to get. + * @li @em moreItemsDirection If this is undefined or @em \
PublicTransport.RequestedItems this + * is a normal journey request. Otherwise \
this is a following journey request to get more + * journeys and is @em \
PublicTransport.EarlierItems or @em PublicTransport.LaterItems. + * See \
Enums::MoreItemsDirection. In this case the field @em requestData is also available. \
+ * @li @em requestData This contains data that was stored by the script in the \
first journeys + * request as @em PublicTransport.RequestData. If this is not a \
following journey request + * this property is not used. It can be used to eg. \
store a request ID. + *
+ * @subsection script_functions_getadditionaldata getAdditionalData( values )
+ * Gets called to request additional data for an already received timetable item \
(eg. a + * departure). The provider itself decides what additional data actually \
is. For example the + * HAFAS base script uses this to get route information for \
departures/arrivals, which are not + * available otherwise. The only argument \
contains information about the timetable item for which + * to get additional data \
for and has these properties: + * @li @em stop: The name/ID of the stop, that was \
used to get the timetable item. + * @li @em city: If used, this contains the city \
name that was used to get the timetable item. + * Only some service providers \
need a separate city value, most are happy with a stop + * name/stop ID.
+ * @li @em dataType: The type of data that was requested to get the timetable \
item, eg. + * "departures", "arrivals", etc.
+ * @li @em dateTime: A Date object with the date and time of the timetable item,
+ * eg. it's departure.
+ * @li @em transportLine: The transport line of the timetable item.
+ * @li @em target: The target of the timetable item.
+ * @li @em routeDataUrl: An URL to a document that contains route information, ie. \
additional + * data. If this is empty it needs to be found out somehow. For \
example HAFAS providers load + * the departure board again but in a different \
format that includes these URLs (and caches + * URLs for multiple timetable items \
for later use). To do so and to find the correct timetable + * item in the other \
format, the other properties like @em dateTime, @em transportLine and + * @em \
target get used. + *
+ * @subsection script_functions_features features()
+ * Can be implemented to make the data engine aware of supported features.
+ * See Enums::ProviderFeature for a list of available features. Those enumerables \
are available + * to scripts in the @em PublicTransport object.
+ *
+ * Some features like @em PublicTransport.ProvidesJourneys are detected \
automatically + * (<em>getJourneys()</em> function implemented?). Others are only \
used to inform the user, + * eg. @em PublicTransport.ProvidesPricing. Some features \
are also required in the returned + * list of this function for those features to \
actually work, + * eg. @em PublicTransport.ProvidesStopGeoPosition.
+ *
+ * @n
+ *
+ * @section script_collecting_items Collecting Parsed Items
+ * The object @b result (ResultObject) gets used by scripts to collect parsed \
departures/ + * arrivals/journeys/stop suggestions. It provides a function \
ResultObject::addData(), which + * accepts an object with properties that have \
special names. A simple departure item can be added + * to the result object like \
this: + * @code
+ * result.addData({ DepartureDateTime: new Date(),
+ * VehicleType: PublicTransport.Bus,
+ * Target: "SomeTarget" });
+ * @endcode
+ *
+ * Another possibility is to assign the properties when they get parsed, like this:
+ * @code
+ * var departure = {};
+ * departure.DepartureDateTime = new Date();
+ * departure.VehicleType = PublicTransport.Bus;
+ * departure.Target = "SomeTarget";
+ * result.addData( departure );
+ * @endcode
+ *
+ * You can also use enumerable values to store data (available in @em \
PublicTransport): + * @code
+ * var departure = {};
+ * departure[ PublicTransport.DepartureDateTime ] = new Date();
+ * departure[ PublicTransport.VehicleType ] = PublicTransport.Bus;
+ * departure[ PublicTransport.Target ] = "SomeTarget";
+ * result.addData( departure );
+ * @endcode
+ *
+ * The names of the properties are important, but upper or lower case does not \
matter. + * All entries in the Enums::TimetableInformation enumerable can be used to \
add information, look + * there fore more detailed information. This enumerable is a \
central point of the Public Transport + * data engine and gets used by all service \
provider plugin types to store information about results. + *
+ * @n
+ * @subsection script_collecting_items_departures Information Types Used for \
Departures/Arrivals + * @em DepartureDateTime, @em DepartureDate, @em DepartureTime, \
@em TypeOfVehicle, + * @em TransportLine, @em FlightNumber (alias for @em \
TransportLine), @em Target, + * @em TargetShortened, @em Platform, @em Delay, @em \
DelayReason, @em JourneyNews, + * @em JourneyNewsOther, @em JourneyNewsLink, @em \
Operator, @em Status, @em RouteStops, + * @em RouteStopsShortened, @em RouteTimes, \
@em RouteTimesDeparture, @em RouteTimesArrival, + * @em RouteExactStops, @em \
RouteTypesOfVehicles, @em RouteTransportLines, + * @em RoutePlatformsDeparture, @em \
RoutePlatformsArrival, @em RouteTimesDepartureDelay, + * @em RouteTimesArrivalDelay, \
@em IsNightLine (currently unused). + * @note At least these information types are \
needed to form a valid departure/arrival object: + * @em DepartureDateTime or @em \
DepartureTime (the date can be omitted, but that can produce + * wrong guessed \
dates), @em TypeOfVehicle and @em TransportLine. + * @note When arrivals are \
requested, @em DepartureDateTime, @em DepartureDate and + * @em DepartureTime stand \
actually for the arrival date/time. The names that start with @em Arrival are + * \
used for journeys only. + * @todo This might change, allowing both for arrivals.
+ * @see Enums::TimetableInformation
+ *
+ * @n
+ * @subsection script_collecting_items_journeys Information Types Used for Journeys
+ * @em DepartureDateTime, @em DepartureDate, @em DepartureTime, @em Duration, @em \
StartStopName, + * @em StartStopID, @em TargetStopName, @em TargetStopID, @em \
ArrivalDateTime, @em ArrivalDate, + * @em ArrivalTime, @em Changes, @em \
TypesOfVehicleInJourney, @em Pricing, @em RouteStops, + * @em RouteStopsShortened, \
@em RouteTimes, @em RouteTimesDeparture, @em RouteTimesArrival, + * @em \
RouteExactStops, @em RouteTypesOfVehicles, @em RouteTransportLines, + * @em \
RoutePlatformsDeparture, @em RoutePlatformsArrival, @em RouteTimesDepartureDelay, + * \
@em RouteTimesArrivalDelay. + * @note At least these information types are needed to \
form a valid journey object: + * @em DepartureDateTime or @em DepartureTime, @em \
ArrivalDateTime or @em ArrivalTime, + * @em StartStopName and @em TargetStopName.
+ * @see Enums::TimetableInformation
+ *
+ * @n
+ * @subsection script_collecting_items_journeys Information Types Used for Stop \
Suggestions + * @em StopName, @em StopID, @em StopWeight, @em StopCity, @em \
StopCountryCode. + * @note Only @em StopName is required to form a valid stop \
suggestion object. + * @see Enums::TimetableInformation
+ *
+ * @n
+ * @subsection script_collecting_items_vehicletypes Vehicle Types
+ *
+ * Vehicle types can be given as enumerable values or names (in @em TypeOfVehicle,
+ * @em RouteTypesOfVehicles, @em TypesOfVehicleInJourney), see @ref \
Enums::VehicleType. @n + *
+ * These are the enumerables of currently supported vehicle types (the names without
+ * "PublicTransport." can also be used as vehicle type):@n
+ * <table>
+ * <tr><td></td><td>PublicTransport.Unknown</td>
+ * <tr><td>@image html hi16-app-vehicle_type_tram.png
+ * </td><td>PublicTransport.Tram</td>
+ * <tr><td>@image html hi16-app-vehicle_type_bus.png
+ * </td><td>PublicTransport.Bus</td>
+ * <tr><td>@image html hi16-app-vehicle_type_subway.png
+ * </td><td>PublicTransport.Subway</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_interurban.png
+ * </td><td>PublicTransport.InterurbanTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_metro.png
+ * </td><td>PublicTransport.Metro</td>
+ * <tr><td>@image html hi16-app-vehicle_type_trolleybus.png
+ * </td><td>PublicTransport.TrolleyBus</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_regional.png
+ * </td><td>PublicTransport.RegionalTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_regional.png
+ * </td><td>PublicTransport.RegionalExpressTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_interregional.png
+ * </td><td>PublicTransport.InterregionalTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_intercity.png
+ * </td><td>PublicTransport.IntercityTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_train_highspeed.png
+ * </td><td>PublicTransport.HighSpeedTrain</td>
+ * <tr><td>@image html hi16-app-vehicle_type_feet.png
+ * </td><td>PublicTransport.Footway" (for journeys to walk from one intermediate \
stop to the next)</td> + * <tr><td>@image html hi16-app-vehicle_type_ferry.png
+ * </td><td>PublicTransport.Ferry</td>
+ * <tr><td>@image html hi16-app-vehicle_type_ferry.png
+ * </td><td>PublicTransport.Ship</td>
+ * <tr><td>@image html hi16-app-vehicle_type_plane.png
+ * </td><td>PublicTransport.Plane</td>
+ * </table>
+ *
+ * @see Enums::TimetableInformation
+ * @see Enums::VehicleType
+ *
+ * @n
+ *
+ * @section script_advanced Advanced Features
+ *
+ * Scripts can use some additional features. For example the Storage can be used to \
store data + * that would otherwise have to be downloaded and parsed over and over \
again. Data can be stored + * in memory (for the current session only) or \
persistently on disk (using KConfig). + * @see Storage
+ *
+ * @n
+ *
+ * The ResultObject class has additional functions other than \
ResultObject::addData(). For example + * the ResultObject::publish() function can be \
used to tell the data engine to publish the items + * parsed so far to \
visualizations. A good use case is to call publish() when a document + * has been \
read but for more results another document needs to be downloaded first. + * @note By \
default data is automatically published after the first few items to provide + * \
visualizations with data as soon as possible. Use ResultObject::enableFeature() to \
change + * this behaviour.
+ *
+ * There is also a Hint enumeration to give hints to the data engine. Use \
ResultObject::giveHint() + * to give a hint.
+ **/
diff --git a/engine/script/scripting.h b/engine/script/scripting.h
index 5f059ea..04a62c2 100644
--- a/engine/script/scripting.h
+++ b/engine/script/scripting.h
@@ -52,274 +52,13 @@ namespace Scripting {
class Network;
-/**
- * @defgroup scripting Classes Used for Scripts
- *
- * These classes get exposed to scripts or are used by scripted service provider \
plugins.
- * Each call to a script from the data engine creates a new thread using \
ThreadWeaver. Each thread
- * uses it's own QScriptEngine instance to execute the script.
- *
- * Scripts are written in ECMAScript, but they can access Kross to support other \
languages, ie.
- * Python or Ruby. Kross needs to be imported explicitly. That can be done by adding \
an
- * @em "extensions" attribute to the @em \<script\> tag in the XML file, like this:
- * @verbatim<script extensions="kross">file.js</script>@endverbatim. Other \
extensions can also be
- * imported, eg. "qt.core" to use classes provided by the "qt.core" bindings.
- *
- * To use eg. Python code in the script, the following code can then be used in a \
script:
- * @code
- * // Create Kross action
- * var action = Kross.action( "MyPythonScript" );
- *
- * // Propagate action to the Python script
- * action.addQObject( action, "MyAction" );
- *
- * // Set the interpreter to use, eg. "python", "ruby"
- * action.setInterpreter( "python" );
- *
- * // Set the code to execute and trigger execution
- * action.setCode("import MyAction ; print 'This is Python. \
name=>',MyAction.interpreter()");
- * action.trigger();
- * @endcode
- * @todo If needed a later version might make this simpler by examining the file \
type of the script
- * file and automatically insert the contents of the script file into the \
setCode() function
- * like above.
- *
- * @n
- *
- * @section script_exposed Classes Exposed to Scripts
- *
- * Scripts can access some objects that represent classes mentioned here. Only one \
instance of
- * these classes is available in a script.
- * @li @em ResultObject Stores results, ie. parsed data for departures, arrivals, \
journeys or
- * stop suggestions. Available for scripts under the name @b result.
- * @li @em Network Provides network access to scripts and is available for scripts \
under
- * the name @b network. This class can create objects of type NetworkRequest using
- * Network::createRequest() for asynchronous requests. NetworkRequest objects have \
signals
- * that scripts can connect to, ie. NetworkRequest::finished() to indicate a \
finished request.
- * @li @em Storage Stores data between script calls. Can store data in memory or \
persistently,
- * ie. on disk. An object of this class is available for scripts under the name @b \
storage.
- * The storage object gets shared between calls to the same script (for the same \
service
- * provider) and can be use by multiple script instances at the same time.
- * @li @em Helper Provides some helper functions to scripts, available under the \
name @b helper.
- *
- * @n
- *
- * @section script_functions Script Functions to be Implemented
- *
- * There should be specially named functions in the script, that get called by the \
data engine.
- * Only the @em getTimetable function @em must be implemented.
- *
- * @subsection script_functions_gettimetable getTimetable( values )
- * This function @em must be implemented (but that may change). Gets called to \
request
- * departures/arrivals. The only argument contains information about the request \
with these
- * properties:
- * @li @em stop: The name/ID of the stop to get departures/arrivals for.
- * @li @em dateTime: A Date object with the date and time of the earliest \
departure/arrival to get.
- * @li @em maxCount: The maximal number of departures/arrivals to get.
- * @li @em dataType: This can be "arrivals" or "departures".
- * @li @em city: If used, this contains the city name to get departures/arrivals \
for. Only some
- * service providers need a separate city value, most are happy with a stop \
name/stop ID.
- *
- * @subsection script_functions_getstopsuggestions getStopSuggestions( values )
- * Gets called to request stop suggestions. Since it may be called very often it \
should be fast,
- * ie. the downloaded data should be as small as possible. The only argument \
contains information
- * about the request with these properties:
- * @li @em stop: A part of a stop name to get suggestions for. This is what users \
can type in, eg.
- * the beginning of the complete stop name.
- * @li @em maxCount: The maximal number of stop suggestions to get.
- * @li @em city: If used, this contains the city name to get stop suggestions for. \
Only some
- * service providers need a separate city value, most are happy with a part of \
the stop name.
- *
- * @subsection script_functions_getjourneys getJourneys( values )
- * Gets called to request journeys (trips from stop A to stop B). The only \
argument contains
- * information about the request with these properties:
- * @li @em originStop: The name/ID of the start/origin stop, also available as \
'stop' property.
- * @li @em targetStop: The name/ID of the target/destination stop.
- * @li @em dateTime: A Date object with the date and time of the earliest journey \
to get.
- * @li @em maxCount: The maximal number of journeys to get.
- * @li @em dataType: This can be "journeys"/"journeysDep" (journeys departing at \
the given @em dateTime)
- * or "journeysArr" (journeys arriving at the given @em dateTime).
- * @li @em city: If used, this contains the city name to get journeys for. Only \
some
- * service providers need a separate city value, most are happy with a stop \
name/stop ID.
- *
- * @subsection script_functions_features features()
- * Can be implemented to provide information about what information types the \
script can return.
- * This can be done by simply returning a list of strings, where each string is \
the name of a
- * type of information. Only optional information that the script provides needs \
to be returned
- * by this function. This list gets used for the feature list of scripted service \
provider plugins.
- * @li @b Arrivals The script can parse arrivals
- * @li @b Delay The script can parse delay information
- * @li @b DelayReason The script can also parse a string describing the reason of \
a delay
- * @li @b Platform The platform where a departure/arrival happens can be parsed
- * @li @b JourneyNews Additional information in text form about \
departures/arrivals/journeys
- * can be parsed
- * @li @b StopID Stop IDs can be parsed and used instead of stop names to prevent \
ambiguities
- * @li @b Pricing Pricing information can be parsed for journeys
- * @li @b Changes The number of changes in a journey can be parsed
- * @li @b RouteStops A list of stop names on the route can be parsed
- * @li @b RouteTimes A list of times at which the vehicle passes the stops in \
RouteStops can
- * be parsed
- * @li @b RoutePlatformsDeparture A list of platforms in the route where the \
vehicle departs
- * can be parsed
- * @li @b RoutePlatformsArrival A list of platforms in the route where the vehicle \
arrives
- * can be parsed
- * @li @b RouteTimesDeparture A list of times at which the vehicle departs from \
the stops
- * in RouteStops can be parsed, eg. for journeys
- * @li @b RouteTimesArrival A list of times at which the vehicle arrives from the \
stops
- * in RouteStops can be parsed, eg. for journeys
- * @li @b RouteTypesOfVehicles A list of vehicle types used for subtrips in a \
journey (between
- * stops in RouteStops)
- * @li @b RouteTransportLines A list of transport line strings of vehicles used \
for subtrips
- * in a journy
- *
- * @see TimetableInformation
- *
- * @n
- *
- * @section script_collecting_items Collecting Parsed Items
- * The object @b result (ResultObject) gets used by scripts to collect parsed \
departures/
- * arrivals/journeys/stop suggestions. It provides a function \
ResultObject::addData(), which
- * accepts an object with properties that have special names. A simple departure \
item can be added
- * to the result object like this:
- * @code
- * result.addData({ DepartureDateTime: new Date(),
- * VehicleType: PublicTransport.Bus,
- * Target: "SomeTarget" });
- * @endcode
- *
- * Another possibility is to assign the properties when they get parsed, like this:
- * @code
- * var departure = {};
- * departure.DepartureDateTime = new Date();
- * departure.VehicleType = PublicTransport.Bus;
- * departure.Target = "SomeTarget";
- * result.addData( departure );
- * @endcode
- *
- * You can also use enumerable values to store data (available in \
"PublicTransport"):
- * @code
- * var departure = {};
- * departure[ PublicTransport.DepartureDateTime ] = new Date();
- * departure[ PublicTransport.VehicleType ] = PublicTransport.Bus;
- * departure[ PublicTransport.Target ] = "SomeTarget";
- * result.addData( departure );
- * @endcode
- *
- * The names of the properties are important, but upper or lower case does not \
matter.
- * All entries in the TimetableInformation enumerable can be used to add \
information, look
- * there fore more detailed information. This enumerable is a central point of the \
Public Transport
- * data engine and gets used by all service provider plugin types to store \
information about results.
- *
- * @n
- * @subsection script_collecting_items_departures Information Types Used for \
Departures/Arrivals
- * @em DepartureDateTime, @em DepartureDate, @em DepartureTime, @em TypeOfVehicle,
- * @em TransportLine, @em FlightNumber (alias for @em TransportLine), @em Target,
- * @em TargetShortened, @em Platform, @em Delay, @em DelayReason, @em JourneyNews,
- * @em JourneyNewsOther, @em JourneyNewsLink, @em Operator, @em Status, @em \
RouteStops,
- * @em RouteStopsShortened, @em RouteTimes, @em RouteTimesDeparture, @em \
RouteTimesArrival,
- * @em RouteExactStops, @em RouteTypesOfVehicles, @em RouteTransportLines,
- * @em RoutePlatformsDeparture, @em RoutePlatformsArrival, @em \
RouteTimesDepartureDelay,
- * @em RouteTimesArrivalDelay, @em IsNightLine (currently unused).
- * @note At least these information types are needed to form a valid \
departure/arrival object:
- * @em DepartureDateTime or @em DepartureTime (the date can be omitted, but that \
can produce
- * wrong guessed dates), @em TypeOfVehicle and @em TransportLine.
- * @note When arrivals are requested, @em DepartureDateTime, @em DepartureDate and
- * @em DepartureTime stand actually for the arrival date/time. The names that \
start with @em Arrival are
- * used for journeys only.
- * @todo This might change, allowing both for arrivals.
- *
- * @n
- * @subsection script_collecting_items_journeys Information Types Used for Journeys
- * @em DepartureDateTime, @em DepartureDate, @em DepartureTime, @em Duration, @em \
StartStopName,
- * @em StartStopID, @em TargetStopName, @em TargetStopID, @em ArrivalDateTime, @em \
ArrivalDate,
- * @em ArrivalTime, @em Changes, @em TypesOfVehicleInJourney, @em Pricing, @em \
RouteStops,
- * @em RouteStopsShortened, @em RouteTimes, @em RouteTimesDeparture, @em \
RouteTimesArrival,
- * @em RouteExactStops, @em RouteTypesOfVehicles, @em RouteTransportLines,
- * @em RoutePlatformsDeparture, @em RoutePlatformsArrival, @em \
RouteTimesDepartureDelay,
- * @em RouteTimesArrivalDelay.
- * @note At least these information types are needed to form a valid journey object:
- * @em DepartureDateTime or @em DepartureTime, @em ArrivalDateTime or @em \
ArrivalTime,
- * @em StartStopName and @em TargetStopName.
- *
- * @n
- * @subsection script_collecting_items_journeys Information Types Used for Stop \
Suggestions
- * @em StopName, @em StopID, @em StopWeight, @em StopCity, @em StopCountryCode.
- * @note Only @em StopName is required to form a valid stop suggestion object.
- *
- * @n
- * @subsection script_collecting_items_vehicletypes Vehicle Types
- *
- * Vehicle types can be given as enumerable values or names (in @em TypeOfVehicle,
- * @em RouteTypesOfVehicles, @em TypesOfVehicleInJourney), see @ref \
Enums::VehicleType. @n
- *
- * These are the enumerables of currently supported vehicle types (the names without
- * "PublicTransport." can also be used as vehicle type):@n
- * <table>
- * <tr><td></td><td>PublicTransport.Unknown</td>
- * <tr><td>@image html hi16-app-vehicle_type_tram.png
- * </td><td>PublicTransport.Tram</td>
- * <tr><td>@image html hi16-app-vehicle_type_bus.png
- * </td><td>PublicTransport.Bus</td>
- * <tr><td>@image html hi16-app-vehicle_type_subway.png
- * </td><td>PublicTransport.Subway</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_interurban.png
- * </td><td>PublicTransport.InterurbanTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_metro.png
- * </td><td>PublicTransport.Metro</td>
- * <tr><td>@image html hi16-app-vehicle_type_trolleybus.png
- * </td><td>PublicTransport.TrolleyBus</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_regional.png
- * </td><td>PublicTransport.RegionalTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_regional.png
- * </td><td>PublicTransport.RegionalExpressTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_interregional.png
- * </td><td>PublicTransport.InterregionalTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_intercity.png
- * </td><td>PublicTransport.IntercityTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_train_highspeed.png
- * </td><td>PublicTransport.HighSpeedTrain</td>
- * <tr><td>@image html hi16-app-vehicle_type_feet.png
- * </td><td>PublicTransport.Feet" (for journeys to walk from one intermediate stop \
to the next)</td>
- * <tr><td>@image html hi16-app-vehicle_type_ferry.png
- * </td><td>PublicTransport.Ferry</td>
- * <tr><td>@image html hi16-app-vehicle_type_ferry.png
- * </td><td>PublicTransport.Ship</td>
- * <tr><td>@image html hi16-app-vehicle_type_plane.png
- * </td><td>PublicTransport.Plane</td>
- * </table>
- *
- * @see TimetableInformation
- * @see VehicleType
- *
- * @n
- *
- * @section script_advanced Advanced Features
- *
- * Scripts can use some additional features. For example the Storage can be used to \
store data
- * that would otherwise have to be downloaded and parsed over and over again. Data \
can be stored
- * in memory (for the current session only) or persistently on disk (using KConfig).
- * @see Storage
- *
- * @n
- *
- * The ResultObject class has additional functions other than \
ResultObject::addData(). For example
- * the ResultObject::publish() function can be used to tell the data engine to \
publish the items
- * parsed so far to visualizations. A good use case is to call publish() when a \
document
- * has been read but for more results another document needs to be downloaded first.
- * @note By default data is automatically published after the first few items to \
provide
- * visualizations with data as soon as possible. Use ResultObject::enableFeature() \
to change
- * this behaviour.
- *
- * There is also a Hint enumeration to give hints to the data engine. Use \
ResultObject::giveHint()
- * to give a hint.
- **/
-
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief Represents one asynchronous request, created with \
Network::createRequest().
*
* To get notified about new data, connect to either the finished() or the \
readyRead() signal.
*
- * @ingroup scripting
* @since 0.10
**/
class NetworkRequest : public QObject {
@@ -349,7 +88,6 @@ public:
* @brief The URL of this request.
*
* @note The URL can not be changed, a request object is only used for @em one \
request.
- * @ingroup scripting
**/
QString url() const;
@@ -363,13 +101,11 @@ public:
/**
* @brief Whether or not the request is currently running.
- * @ingroup scripting
**/
bool isRunning() const;
/**
* @brief Whether or not the request is finished (successful or not), ie. was \
running.
- * @ingroup scripting
**/
bool isFinished() const;
@@ -394,7 +130,6 @@ public:
* default) the "ContentType" header gets used if it was set using \
setHeader(). Otherwise
* utf8 gets used.
* @see isRunning()
- * @ingroup scripting
**/
Q_INVOKABLE void setPostData( const QString &postData, const QString &charset = \
QString() );
@@ -416,7 +151,6 @@ public:
* string (the default) the "ContentType" header gets used if it was set using \
setHeader().
* Otherwise utf8 gets used.
* @see isRunning()
- * @ingroup scripting
**/
Q_INVOKABLE void setHeader( const QString &header, const QString &value,
const QString &charset = QString() );
@@ -435,14 +169,12 @@ public Q_SLOTS:
Q_SIGNALS:
/**
* @brief Emitted when this request was started.
- * @ingroup scripting
**/
void started();
/**
* @brief Emitted when this request got aborted or timed out.
* @param timedOut Whether or not the request was aborted because of a timeout.
- * @ingroup scripting
**/
void aborted( bool timedOut = false );
@@ -454,7 +186,6 @@ Q_SIGNALS:
* @param errorString A human readable description of the error if @p error is \
@c true.
* @param statusCode The HTTP status code that was received or -1 if there was \
an error.
* @param size The size in bytes of the received data.
- * @ingroup scripting
**/
void finished( const QByteArray &data = QByteArray(), bool error = false,
const QString &errorString = QString(), int statusCode = -1, int \
size = 0 ); @@ -463,7 +194,6 @@ Q_SIGNALS:
* @brief Emitted when new data is available for this request.
*
* @param data New downloaded data for this request.
- * @ingroup scripting
**/
void readyRead( const QByteArray &data );
@@ -493,7 +223,10 @@ private:
QByteArray m_postData;
quint32 m_uncompressedSize;
};
+/** \} */ // @ingroup scriptApi
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief Provides network access to scripts.
*
@@ -537,7 +270,6 @@ private:
* @note One request object created with createRequest() can not be used multiple \
times in
* parallel. To start another request create a new request object.
*
- * @ingroup scripting
* @since 0.10
**/
class Network : public QObject, public QScriptable {
@@ -596,14 +328,12 @@ public:
* at the requested URL, but eg. in XML format.
* @param timeout Maximum time in milliseconds to wait for the reply to finish.
* If smaller than 0, no timeout gets used.
- * @ingroup scripting
**/
Q_INVOKABLE QByteArray getSynchronous( const QString &url, const QString \
&userUrl = QString(),
int timeout = DEFAULT_TIMEOUT );
/**
* @brief This is an alias for getSynchronous().
- * @ingroup scripting
**/
Q_INVOKABLE inline QByteArray downloadSynchronous( const QString &url,
const QString &userUrl = \
QString(), @@ -618,7 +348,6 @@ public:
* @note Each NetworkRequest object can only be used once for one download.
*
* @see get, download, post, head
- * @ingroup scripting
**/
Q_INVOKABLE NetworkRequest *createRequest( const QString &url,
const QString &userUrl = QString() );
@@ -629,7 +358,6 @@ public:
* @param request The NetworkRequest object created with createRequest().
* @param timeout Maximum time in milliseconds to wait for the reply to finish.
* If smaller than 0, no timeout gets used.
- * @ingroup scripting
**/
Q_INVOKABLE void get( NetworkRequest *request, int timeout = DEFAULT_TIMEOUT );
@@ -639,7 +367,6 @@ public:
* @param request The NetworkRequest object created with createRequest().
* @param timeout Maximum time in milliseconds to wait for the reply to finish.
* If smaller than 0, no timeout gets used.
- * @ingroup scripting
**/
Q_INVOKABLE void post( NetworkRequest *request, int timeout = DEFAULT_TIMEOUT );
@@ -647,13 +374,11 @@ public:
* @brief Perform the network @p request asynchronously, but only get headers.
*
* @param request The NetworkRequest object created with createRequest().
- * @ingroup scripting
**/
Q_INVOKABLE void head( NetworkRequest *request, int timeout = DEFAULT_TIMEOUT );
/**
* @brief This is an alias for get().
- * @ingroup scripting
**/
Q_INVOKABLE inline void download( NetworkRequest *request, int timeout = \
DEFAULT_TIMEOUT ) { get( request, timeout );
@@ -662,7 +387,6 @@ public:
/**
* @brief Returns whether or not there are asynchronous requests running in the \
background.
* @see runningRequests
- * @ingroup scripting
**/
Q_INVOKABLE bool hasRunningRequests() const;
@@ -671,7 +395,6 @@ public:
*
* If hasRunningRequests() returns @c false, this will return an empty list.
* @see hasRunningRequests
- * @ingroup scripting
**/
Q_INVOKABLE QList< NetworkRequest::Ptr > runningRequests() const;
@@ -693,7 +416,6 @@ Q_SIGNALS:
*
* This signal is @em not emitted if the network gets accessed synchronously.
* @param request The request that has been started.
- * @ingroup scripting
* @see synchronousRequestStarted()
**/
void requestStarted( const NetworkRequest::Ptr &request );
@@ -709,7 +431,6 @@ Q_SIGNALS:
* @param timestamp The date and time on which the request was finished.
* @param statusCode The HTTP status code received.
* @param size The size in bytes of the received data.
- * @ingroup scripting
* @see synchronousRequestFinished()
**/
void requestFinished( const NetworkRequest::Ptr &request,
@@ -726,7 +447,6 @@ Q_SIGNALS:
*
* This signal is @em not emitted if the network gets accessed asynchronously.
* @param url The URL of the request that has been started.
- * @ingroup scripting
* @see requestStarted()
**/
void synchronousRequestStarted( const QString &url );
@@ -741,7 +461,6 @@ Q_SIGNALS:
* @param statusCode The HTTP status code if @p cancelled is @c false.
* @param waitTime The time spent waiting for the download to finish.
* @param size The size in bytes of the received data.
- * @ingroup scripting
* @see requestFinished()
**/
void synchronousRequestFinished( const QString &url, const QByteArray &data = \
QByteArray(), @@ -753,7 +472,6 @@ Q_SIGNALS:
*
* This signal is @em not emitted if the network gets accessed asynchronously.
* @param url The URL of the request that has been redirected.
- * @ingroup scripting
* @see requestRedirected()
**/
void synchronousRequestRedirected( const QString &url );
@@ -763,7 +481,6 @@ Q_SIGNALS:
*
* This signal gets emitted just after emitting requestFinished(), if there are \
no more running
* requests.
- * @ingroup scripting
**/
void allRequestsFinished();
@@ -772,14 +489,12 @@ Q_SIGNALS:
*
* This signal is @em not emitted if the network gets accessed synchronously.
* @param request The request that was aborted.
- * @ingroup scripting
**/
void requestAborted( const NetworkRequest::Ptr &request );
public Q_SLOTS:
/**
* @brief Aborts all running (asynchronous) downloads.
- * @ingroup scripting
**/
void abortAllRequests();
@@ -806,7 +521,10 @@ private:
QList< NetworkRequest::Ptr > m_requests;
QList< NetworkRequest::Ptr > m_finishedRequests;
};
+/** \} */ // @ingroup scriptApi
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief A helper class for scripts.
*
@@ -830,18 +548,17 @@ private:
*
* helper.debug("Debug message, eg. something unexpected happened");
* @endcode
- *
- * @ingroup scripting
**/
class Helper : public QObject, protected QScriptable {
Q_OBJECT
Q_ENUMS( ErrorSeverity )
public:
+ /** @brief The severity of an error. */
enum ErrorSeverity {
- Information,
- Warning,
- Fatal
+ Information, /**< The message is only an information. */
+ Warning, /**< The message is a warning. */
+ Fatal /**< The message describes a fatal error. */
};
/**
@@ -1318,7 +1035,10 @@ private:
QString m_lastErrorMessage;
int m_errorMessageRepetition;
};
+/** \} */ // @ingroup scriptApi
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief This class is used by scripts to store results in, eg. departures.
*
@@ -1329,8 +1049,6 @@ private:
* // Add stop suggestion data to result set
* result.addData({ StopName: "Name" });
* @endcode
- *
- * @ingroup scripting
**/
class ResultObject : public QObject, protected QScriptable {
Q_OBJECT
@@ -1578,7 +1296,6 @@ Q_SIGNALS:
public Q_SLOTS:
/**
* @brief Clears the list of stored TimetableData objects.
- * @ingroup scripting
**/
void clear();
@@ -1622,10 +1339,13 @@ private:
Features m_features;
Hints m_hints;
};
+/** \} */ // @ingroup scriptApi
Q_DECLARE_OPERATORS_FOR_FLAGS( ResultObject::Features );
Q_DECLARE_OPERATORS_FOR_FLAGS( ResultObject::Hints );
class StoragePrivate;
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief Used by scripts to store data between calls.
*
@@ -1693,14 +1413,13 @@ class StoragePrivate;
* @endcode
*
* @warning Since the script can run multiple times simultanously in different \
threads which share
- * the same Storage object, the stored values are also shared . If you want to \
store a value for + * the same Storage object, the stored values are also shared. \
If you want to store a value for
* the current job of the script only (eg. getting departures and remember a value \
after an
* asynchronous request), you should store the value in a global script variable \
instead.
* Otherwise one departure request job might use the value stored by another one, \
which is
* probably not what you want. Scripts can not not access the Storage object of \
other scripts
* (for other service providers).
*
- * @ingroup scripting
* @since 0.10
**/
class Storage : public QObject {
@@ -1748,31 +1467,26 @@ public:
/**
* @brief Whether or not a data entry with @p name exists in memory.
- * @ingroup scripting
**/
Q_INVOKABLE bool hasData( const QString &name ) const;
/**
* @brief Whether or not a data entry with @p name exists in persistent memory.
- * @ingroup scripting
**/
Q_INVOKABLE bool hasPersistentData( const QString &name ) const;
/**
* @brief Reads all data stored in memory.
- * @ingroup scripting
**/
Q_INVOKABLE QVariantMap read();
/**
* @brief Reads data stored in memory with @p name.
- * @ingroup scripting
**/
Q_INVOKABLE QVariant read( const QString &name, const QVariant& defaultData = \
QVariant() );
/**
* @brief Reads the lifetime remaining for data written using writePersistent() \
with @p name.
- * @ingroup scripting
**/
Q_INVOKABLE int lifetime( const QString &name );
@@ -1784,7 +1498,6 @@ public:
* If you use another default value than the default invalid QVariant, the \
type must match
* the type of the stored value. Otherwise an invalid QVariant gets returned.
* @see lifetime()
- * @ingroup scripting
**/
Q_INVOKABLE QVariant readPersistent( const QString &name,
const QVariant& defaultData = QVariant() );
@@ -1799,7 +1512,6 @@ public:
public Q_SLOTS:
/**
* @brief Stores @p data in memory with @p name.
- * @ingroup scripting
**/
void write( const QString &name, const QVariant &data );
@@ -1808,19 +1520,16 @@ public Q_SLOTS:
*
* @param data The data to write to disk. This can be a script object.
* @overload
- * @ingroup scripting
**/
void write( const QVariantMap &data );
/**
* @brief Removes data stored in memory with @p name.
- * @ingroup scripting
**/
void remove( const QString &name );
/**
* @brief Clears all data stored in memory.
- * @ingroup scripting
**/
void clear();
@@ -1834,7 +1543,6 @@ public Q_SLOTS:
* @param lifetime The lifetime in days of the data. Limited to 30 days and \
defaults to 7 days.
*
* @see lifetime
- * @ingroup scripting
**/
void writePersistent( const QString &name, const QVariant &data,
uint lifetime = DEFAULT_LIFETIME );
@@ -1851,7 +1559,6 @@ public Q_SLOTS:
*
* @see lifetime
* @overload
- * @ingroup scripting
**/
void writePersistent( const QVariantMap &data, uint lifetime = DEFAULT_LIFETIME \
);
@@ -1860,7 +1567,6 @@ public Q_SLOTS:
*
* @note Scripts do not need to remove data written persistently, ie. to disk, \
because each
* data entry has a lifetime, which is currently limited to 30 days and \
defaults to 7 days.
- * @ingroup scripting
**/
void removePersistent( const QString &name );
@@ -1869,7 +1575,6 @@ public Q_SLOTS:
*
* @note Scripts do not need to remove data written persistently, ie. to disk, \
because each
* data entry has a lifetime, which is currently limited to 30 days and \
defaults to 7 days.
- * @ingroup scripting
**/
void clearPersistent();
@@ -1881,7 +1586,10 @@ private:
StoragePrivate *d;
};
+/** \} */ // @ingroup scriptApi
+/** @ingroup scriptApi
+ * @{ */
/**
* @brief A data stream class to be used in scripts.
*
@@ -1955,6 +1663,7 @@ private:
QDataStream *thisDataStream() const;
QSharedPointer< QDataStream > m_dataStream;
};
+/** \} */ // @ingroup scriptApi
typedef DataStreamPrototype* DataStreamPrototypePtr;
QScriptValue constructStream( QScriptContext *context, QScriptEngine *engine );
diff --git a/engine/script/serviceproviderscript.h \
b/engine/script/serviceproviderscript.h index 87f080f..baaa417 100644
--- a/engine/script/serviceproviderscript.h
+++ b/engine/script/serviceproviderscript.h
@@ -49,18 +49,19 @@ using namespace Scripting;
/**
* @brief The base class for all scripted service providers.
*
- * Scripts are executed in a separate thread and do network requests synchronously
- * from withing the script. Scripts are written in ECMAScript (QScript), but the \
"kross" extension
- * gets loaded automatically, so that you can also use other languages supported by \
Kross. + * Scripts are executed in separate threads and can start \
synchronous/asynchronous network requests. + * Scripts are written in QtScript, ie. \
ECMAScript/JavaScript. See @ref scriptApi for more + * information.
*
- * To use eg. Python code in the script, the following code can be used:
- * @code
- * var action = Kross.action( "MyPythonScript" ); // Create Kross action
- * action.addQObject( action, "MyAction" ); // Propagate action to itself
- * action.setInterpreter( "python" ); // Set the interpreter to use, eg. "python", \
"ruby"
- * action.setCode("import MyAction ; print 'This is Python. \
name=>',MyAction.interpreter()");
- * action.trigger(); // Run the script
- * @endcode
+ * @note Other script languages supported by Kross can be used, the "kross" \
extension is then + * needed. To use eg. Python code in the script, the following \
code can be used: + * @code
+ * var action = Kross.action( "MyPythonScript" ); // Create Kross action
+ * action.addQObject( action, "MyAction" ); // Propagate action to itself
+ * action.setInterpreter( "python" ); // Set the interpreter to use, eg. \
"python", "ruby" + * action.setCode("import MyAction ; print 'This is Python. \
name=>',MyAction.interpreter()"); + * action.trigger(); // Run the script
+ * @endcode
*/
class ServiceProviderScript : public ServiceProvider {
Q_OBJECT
diff --git a/engine/timetablemate/src/CMakeLists.txt \
b/engine/timetablemate/src/CMakeLists.txt index 27beb22..6513abb 100644
--- a/engine/timetablemate/src/CMakeLists.txt
+++ b/engine/timetablemate/src/CMakeLists.txt
@@ -59,7 +59,7 @@ add_custom_command( OUTPUT \
${CMAKE_CURRENT_BINARY_DIR}/javascriptcompletiongener \
${CMAKE_CURRENT_SOURCE_DIR}/../../publictransportdataengine.h
${CMAKE_BINARY_DIR}/engine/timetablemate/completiongenerator/completiongenerator \
)
-qt4_wrap_cpp( timetablemate_MOC_SRCS ../../enums.h )
+qt4_wrap_cpp( timetablemate_MOC_SRCS ../../enums.h tabs/tabs.h )
set( timetablemate_SRCS
main.cpp
timetablemate.cpp
@@ -89,6 +89,7 @@ set( timetablemate_SRCS
../../serviceproviderglobal.cpp
${timetablemate_MOC_SRCS}
)
+qt4_automoc( timetablemate_SRCS )
if ( BUILD_PROVIDER_TYPE_SCRIPT )
set ( timetablemate_SRCS ${timetablemate_SRCS}
diff --git a/engine/timetablemate/src/tabs/CMakeLists.txt \
b/engine/timetablemate/src/tabs/CMakeLists.txt index 999501e..e0ce34f 100644
--- a/engine/timetablemate/src/tabs/CMakeLists.txt
+++ b/engine/timetablemate/src/tabs/CMakeLists.txt
@@ -6,6 +6,7 @@ set( tab_SRCS
tabs/webtab.cpp
tabs/plasmapreviewtab.cpp
tabs/plasmapreview.cpp
+ tabs/tabs.h
)
if ( BUILD_PROVIDER_TYPE_SCRIPT )
@@ -26,4 +27,4 @@ install( FILES dashboard.qml ActionButton.qml ActionToolButton.qml
if ( BUILD_PROVIDER_TYPE_GTFS )
install( FILES gtfs_dashboard.qml
DESTINATION ${DATA_INSTALL_DIR}/timetablemate )
-endif ( BUILD_PROVIDER_TYPE_GTFS )
\ No newline at end of file
+endif ( BUILD_PROVIDER_TYPE_GTFS )
diff --git a/engine/timetablemate/src/tabs/tabs.h \
b/engine/timetablemate/src/tabs/tabs.h index 69a0df6..b5a9713 100644
--- a/engine/timetablemate/src/tabs/tabs.h
+++ b/engine/timetablemate/src/tabs/tabs.h
@@ -23,8 +23,10 @@
// Qt includes
#include <QObject>
+/** @brief Provides an enumeration of tab types. */
class Tabs : public QObject {
- Q_ENUMS( TabType )
+ Q_OBJECT
+ Q_ENUMS( Type )
public:
/** @brief Types of tabs. */
diff --git a/engine/timetablemate/src/tests/CMakeLists.txt \
b/engine/timetablemate/src/tests/CMakeLists.txt index 8b376e6..9e00f5f 100644
--- a/engine/timetablemate/src/tests/CMakeLists.txt
+++ b/engine/timetablemate/src/tests/CMakeLists.txt
@@ -52,6 +52,7 @@ if ( BUILD_PROVIDER_TYPE_SCRIPT )
../debugger/breakpointmodel.h
../debugger/variablemodel.h
+ ../tabs/tabs.h
../tabs/abstracttab.h
../tabs/projectsourcetab.h
../tabs/scripttab.h
diff --git a/libpublictransporthelper/CMakeLists.txt \
b/libpublictransporthelper/CMakeLists.txt index a569ba7..e002e73 100644
--- a/libpublictransporthelper/CMakeLists.txt
+++ b/libpublictransporthelper/CMakeLists.txt
@@ -110,7 +110,7 @@ endif ( MARBLE_FOUND )
target_link_libraries( ${libraries} )
set_target_properties( publictransporthelper
- PROPERTIES VERSION 0 SOVERSION 10
+ PROPERTIES VERSION 0 SOVERSION 11
)
install( TARGETS publictransporthelper
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic