File indexing completed on 2024-06-09 05:31:17

0001 /*
0002     SPDX-FileCopyrightText: 2007-2009 Shawn Starr <shawn.starr@rogers.com>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #pragma once
0008 
0009 #include <Plasma5Support/DataEngine>
0010 
0011 #include "ion_export.h"
0012 
0013 /**
0014  * @author Shawn Starr
0015  * This is the base class to be used to implement new ions for the WeatherEngine.
0016  * The idea is that you can have multiple ions which provide weather information from different services to the engine from which an applet will request the
0017  * data from.
0018  *
0019  * Basically an ion is a Plasma5Support::DataEngine, which is queried by the WeatherEngine instead of some applet.
0020  *
0021  *
0022  * Find following the currently used entries of the data for a "SOMEION|weather|SOMEPLACE" source.
0023  * Any free text strings should be translated by the dataengine if possible,
0024  * as any dataengine user has less knowledge about the meaning of the strings.
0025  *
0026  * Data about the weather station:
0027  * "Station": string, id of the location of the weather station with the service, required, TODO: ensure it's id
0028  * "Place": string, display name of the location of the weather station, required, TODO: what details here, country?
0029  * "Country": string, display name of country of the weather station, optional
0030  * "Latitude": float, latitude of the weather station in decimal degrees, optional
0031  * "Longitude": float, longitude of the weather station in decimal degrees, optional
0032  *
0033  * Data about last observation:
0034  * "Observation Period": string, free text string for time of observation, optional
0035  * "Observation Timestamp": datetime (with timezone), time of observation, optional
0036  * "Current Conditions": string, free text string for current weather observation, optional
0037  * "Condition Icon": string, xdg icon name for current weather observation, optional
0038  * "Temperature": float, using general temperature unit, optional
0039  * "Windchill": float, felt temperature due to wind, using general temperature unit, optional
0040  * "Heat Index": float, using general temperature unit, optional
0041  * "Humidex": int, humidity index (not to be mixed up with heat index), optional
0042  * "Wind Speed": float, average wind speed, optional TODO: fix "Calm" strings injected on dataengine side, it's a display thing?
0043  * "Wind Speed Unit": int, kunitconversion enum number for the unit with all wind speed values, required if wind speeds are given
0044  * "Wind Gust": float, max wind gust speed, optional
0045  * "Wind Direction": string, wind direction in cardinal directions (up to secondary-intercardinal + VR), optional
0046  * "Visibility": float, visibility in distance, optional
0047  * "Visibility Unit": int, kunitconversion enum number for the unit with all visibility values, required if visibilities are given
0048  * "Pressure": float, air pressure, optional
0049  * "Pressure Tendency": string, "rising", "falling", "steady", optional TODO: turn into enum/string id set, currently passed as string
0050  * "Pressure Unit": int, kunitconversion enum number for the unit with all pressure values, required if pressures are given
0051  * "UV Index": int, value in UV index UN standard, optional
0052  * "UV Rating": string, grouping in which UV index is: "Low"0</"Moderate"3</"High"6</"Very high"8</"Extreme"11<, optional TODO: can be calculated from UV Index,
0053  * so needed? "Humidity": float, humidity of the air, optional "Humidity Unit": int, kunitconversion enum number for the unit with all humidity values, required
0054  * if humidities are given TODO: any other unit than percent expected? "Dewpoint": string, temperature where water condensates given other conditions, optional
0055  *
0056  * Data about current day:
0057  * "Normal High": float, average highest temperature measured at location, optional
0058  * "Normal Low": float, average lowest temperature measured at location, optional
0059  * "Record High Temperature": float, highest temperature ever measured at location, optional
0060  * "Record Low Temperature": float, lowest temperature ever measured at location, optional
0061  * "Record Rainfall": float, highest height of rain (precipitation?) ever measured at location, optional
0062  * "Record Rainfall Unit": int, kunitconversion enum number for the unit with all rainfall values, required if rainfalls are given
0063  * "Record Snowfall": float, highest height of snow ever measured at location, optional
0064  * "Record Snowfall Unit": int, kunitconversion enum number for the unit with Record Snowfall, required if snowfall is given
0065  *
0066  * Data about last day:
0067  * "Yesterday High": float, highest temperature at location, optional
0068  * "Yesterday Low": float, lowest temperature at location, optional
0069  * "Yesterday Precip Total": float, total precipitation over day, optional TODO: "Trace" injected, should be dealt with at display side?
0070  * "Yesterday Precip Unit": int, kunitconversion enum number for the unit with recip, required if precipitation is given
0071  *
0072  * Data about next days:
0073  * "Total Weather Days": int
0074  * "Short Forecast Day %1": string, 6 fields separated by |, %1 number in list, required
0075  *     fields are (optional means empty string possible):
0076  *     period: time of, required, TODO: have standardized to allow better processing
0077  *     condition icon: xdg icon name for current weather observation, optional,
0078  *     condition: free text string for weather condition, optional
0079  *     temperature high: number of highest temperature (using general unit), optional
0080  *     temperature low: number of lowest temperature (using general unit), optional
0081  *     probability: chance of conditions to happen, optional
0082  *     TODO: this should be rather a QVariantList if possible
0083  *
0084  * Data about warnings:
0085  * "Total Warnings Issued": int, number of warnings, there should be matching "Watch * "+number data
0086  * "Warning Description " + number, string, free text string, optional
0087  * "Warning Info " + number, string, free text string, optional
0088  * "Warning Priority " + number, string, free text string, optional TODO: get standardized enum
0089  * "Warning Timestamp " + number, string, free text string, optional TODO: get standardized datetime
0090  *
0091  * Data about the data:
0092  * "Temperature Unit": int, kunitconversion enum number for the unit with all temperature values, required if temperatures are given
0093  *
0094  * "Credit": string, credit line for the data, required
0095  * "Credit Url": string, url related to the credit for the data (can be also webpage with more forecast), optional
0096  */
0097 class ION_EXPORT IonInterface : public Plasma5Support::DataEngine
0098 {
0099     Q_OBJECT
0100 
0101 public:
0102     enum ConditionIcons {
0103         ClearDay = 1,
0104         ClearWindyDay,
0105         FewCloudsDay,
0106         FewCloudsWindyDay,
0107         PartlyCloudyDay,
0108         PartlyCloudyWindyDay,
0109         Overcast,
0110         OvercastWindy,
0111         Rain,
0112         LightRain,
0113         Showers,
0114         ChanceShowersDay,
0115         Thunderstorm,
0116         Hail,
0117         Snow,
0118         LightSnow,
0119         Flurries,
0120         FewCloudsNight,
0121         FewCloudsWindyNight,
0122         ChanceShowersNight,
0123         PartlyCloudyNight,
0124         PartlyCloudyWindyNight,
0125         ClearNight,
0126         ClearWindyNight,
0127         Mist,
0128         Haze,
0129         FreezingRain,
0130         RainSnow,
0131         FreezingDrizzle,
0132         ChanceThunderstormDay,
0133         ChanceThunderstormNight,
0134         ChanceSnowDay,
0135         ChanceSnowNight,
0136         NotAvailable,
0137     };
0138 
0139     enum WindDirections {
0140         N,
0141         NNE,
0142         NE,
0143         ENE,
0144         E,
0145         SSE,
0146         SE,
0147         ESE,
0148         S,
0149         NNW,
0150         NW,
0151         WNW,
0152         W,
0153         SSW,
0154         SW,
0155         WSW,
0156         VR,
0157     };
0158 
0159     /**
0160      * Constructor for the ion
0161      * @param parent The parent object.
0162      * @Param args The argument list.
0163      */
0164     explicit IonInterface(QObject *parent);
0165     /**
0166      * Destructor for the ion
0167      */
0168     ~IonInterface() override;
0169 
0170     /**
0171      * Returns weather icon filename to display in applet.
0172      * @param condition the current condition being reported.
0173      * @return icon name
0174      */
0175     QString getWeatherIcon(ConditionIcons condition) const;
0176 
0177     /**
0178      * Returns weather icon filename to display in applet.
0179      * @param conditionList a QList map pair of icons mapped to a enumeration of conditions.
0180      * @param condition the current condition being reported.
0181      * @return icon name
0182      */
0183     QString getWeatherIcon(const QMap<QString, ConditionIcons> &conditionList, const QString &condition) const;
0184 
0185     /**
0186      * Returns wind icon element to display in applet.
0187      * @param windDirList a QList map pair of wind directions mapped to a enumeration of directions.
0188      * @param windDirection the current wind direction.
0189      * @return svg element for wind direction
0190      */
0191     QString getWindDirectionIcon(const QMap<QString, WindDirections> &windDirList, const QString &windDirection) const;
0192 
0193 public Q_SLOTS:
0194 
0195     /**
0196      * Reimplemented from Plasma5Support::DataEngine
0197      * @param source the name of the datasource to be updated
0198      */
0199     bool updateSourceEvent(const QString &source) override;
0200 
0201     /**
0202      * Reimplement for ion to reload data if network status comes back up
0203      */
0204     virtual void reset() = 0;
0205 
0206 Q_SIGNALS:
0207     void forceUpdate(IonInterface *ion, const QString &source);
0208 
0209 protected:
0210     /**
0211      * Call this method to flush waiting source requests that may be pending
0212      * initialization
0213      *
0214      * @arg initialized whether or not the ion is currently ready to fetch data
0215      */
0216     void setInitialized(bool initialized);
0217 
0218     /**
0219      * Reimplemented from Plasma5Support::DataEngine
0220      * @param source The datasource being requested
0221      */
0222     bool sourceRequestEvent(const QString &source) override;
0223 
0224     /**
0225      * Reimplement to fetch the data from the ion.
0226      * @arg source the name of the datasource.
0227      * @return true if update was successful, false if failed
0228      */
0229     virtual bool updateIonSource(const QString &source) = 0;
0230 
0231     friend class WeatherEngine;
0232 
0233 private:
0234     class Private;
0235     Private *const d;
0236 };