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 };