File indexing completed on 2024-06-16 05:10:13

 /*
     SPDX-FileCopyrightText: 2007-2009 Shawn Starr <shawn.starr@rogers.com>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #pragma once
 
 #include <Plasma5Support/DataEngine>
 
 #include "ion_export.h"
 
 /**
  * @author Shawn Starr
  * This is the base class to be used to implement new ions for the WeatherEngine.
  * 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
  * data from.
  *
  * Basically an ion is a Plasma5Support::DataEngine, which is queried by the WeatherEngine instead of some applet.
  *
  *
  * Find following the currently used entries of the data for a "SOMEION|weather|SOMEPLACE" source.
  * Any free text strings should be translated by the dataengine if possible,
  * as any dataengine user has less knowledge about the meaning of the strings.
  *
  * Data about the weather station:
  * "Station": string, id of the location of the weather station with the service, required, TODO: ensure it's id
  * "Place": string, display name of the location of the weather station, required, TODO: what details here, country?
  * "Country": string, display name of country of the weather station, optional
  * "Latitude": float, latitude of the weather station in decimal degrees, optional
  * "Longitude": float, longitude of the weather station in decimal degrees, optional
  *
  * Data about last observation:
  * "Observation Period": string, free text string for time of observation, optional
  * "Observation Timestamp": datetime (with timezone), time of observation, optional
  * "Current Conditions": string, free text string for current weather observation, optional
  * "Condition Icon": string, xdg icon name for current weather observation, optional
  * "Temperature": float, using general temperature unit, optional
  * "Windchill": float, felt temperature due to wind, using general temperature unit, optional
  * "Heat Index": float, using general temperature unit, optional
  * "Humidex": int, humidity index (not to be mixed up with heat index), optional
  * "Wind Speed": float, average wind speed, optional TODO: fix "Calm" strings injected on dataengine side, it's a display thing?
  * "Wind Speed Unit": int, kunitconversion enum number for the unit with all wind speed values, required if wind speeds are given
  * "Wind Gust": float, max wind gust speed, optional
  * "Wind Direction": string, wind direction in cardinal directions (up to secondary-intercardinal + VR), optional
  * "Visibility": float, visibility in distance, optional
  * "Visibility Unit": int, kunitconversion enum number for the unit with all visibility values, required if visibilities are given
  * "Pressure": float, air pressure, optional
  * "Pressure Tendency": string, "rising", "falling", "steady", optional TODO: turn into enum/string id set, currently passed as string
  * "Pressure Unit": int, kunitconversion enum number for the unit with all pressure values, required if pressures are given
  * "UV Index": int, value in UV index UN standard, optional
  * "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,
  * so needed? "Humidity": float, humidity of the air, optional "Humidity Unit": int, kunitconversion enum number for the unit with all humidity values, required
  * if humidities are given TODO: any other unit than percent expected? "Dewpoint": string, temperature where water condensates given other conditions, optional
  *
  * Data about current day:
  * "Normal High": float, average highest temperature measured at location, optional
  * "Normal Low": float, average lowest temperature measured at location, optional
  * "Record High Temperature": float, highest temperature ever measured at location, optional
  * "Record Low Temperature": float, lowest temperature ever measured at location, optional
  * "Record Rainfall": float, highest height of rain (precipitation?) ever measured at location, optional
  * "Record Rainfall Unit": int, kunitconversion enum number for the unit with all rainfall values, required if rainfalls are given
  * "Record Snowfall": float, highest height of snow ever measured at location, optional
  * "Record Snowfall Unit": int, kunitconversion enum number for the unit with Record Snowfall, required if snowfall is given
  *
  * Data about last day:
  * "Yesterday High": float, highest temperature at location, optional
  * "Yesterday Low": float, lowest temperature at location, optional
  * "Yesterday Precip Total": float, total precipitation over day, optional TODO: "Trace" injected, should be dealt with at display side?
  * "Yesterday Precip Unit": int, kunitconversion enum number for the unit with recip, required if precipitation is given
  *
  * Data about next days:
  * "Total Weather Days": int
  * "Short Forecast Day %1": string, 6 fields separated by |, %1 number in list, required
  *     fields are (optional means empty string possible):
  *     period: time of, required, TODO: have standardized to allow better processing
  *     condition icon: xdg icon name for current weather observation, optional,
  *     condition: free text string for weather condition, optional
  *     temperature high: number of highest temperature (using general unit), optional
  *     temperature low: number of lowest temperature (using general unit), optional
  *     probability: chance of conditions to happen, optional
  *     TODO: this should be rather a QVariantList if possible
  *
  * Data about warnings:
  * "Total Warnings Issued": int, number of warnings, there should be matching "Watch * "+number data
  * "Warning Description " + number, string, free text string, optional
  * "Warning Info " + number, string, free text string, optional
  * "Warning Priority " + number, string, free text string, optional TODO: get standardized enum
  * "Warning Timestamp " + number, string, free text string, optional TODO: get standardized datetime
  *
  * Data about the data:
  * "Temperature Unit": int, kunitconversion enum number for the unit with all temperature values, required if temperatures are given
  *
  * "Credit": string, credit line for the data, required
  * "Credit Url": string, url related to the credit for the data (can be also webpage with more forecast), optional
  */
 class ION_EXPORT IonInterface : public Plasma5Support::DataEngine
 {
     Q_OBJECT
 
 public:
     enum ConditionIcons {
         ClearDay = 1,
         ClearWindyDay,
         FewCloudsDay,
         FewCloudsWindyDay,
         PartlyCloudyDay,
         PartlyCloudyWindyDay,
         Overcast,
         OvercastWindy,
         Rain,
         LightRain,
         Showers,
         ChanceShowersDay,
         Thunderstorm,
         Hail,
         Snow,
         LightSnow,
         Flurries,
         FewCloudsNight,
         FewCloudsWindyNight,
         ChanceShowersNight,
         PartlyCloudyNight,
         PartlyCloudyWindyNight,
         ClearNight,
         ClearWindyNight,
         Mist,
         Haze,
         FreezingRain,
         RainSnow,
         FreezingDrizzle,
         ChanceThunderstormDay,
         ChanceThunderstormNight,
         ChanceSnowDay,
         ChanceSnowNight,
         NotAvailable,
     };
 
     enum WindDirections {
         N,
         NNE,
         NE,
         ENE,
         E,
         SSE,
         SE,
         ESE,
         S,
         NNW,
         NW,
         WNW,
         W,
         SSW,
         SW,
         WSW,
         VR,
     };
 
     /**
      * Constructor for the ion
      * @param parent The parent object.
      * @Param args The argument list.
      */
     explicit IonInterface(QObject *parent);
     /**
      * Destructor for the ion
      */
     ~IonInterface() override;
 
     /**
      * Returns weather icon filename to display in applet.
      * @param condition the current condition being reported.
      * @return icon name
      */
     QString getWeatherIcon(ConditionIcons condition) const;
 
     /**
      * Returns weather icon filename to display in applet.
      * @param conditionList a QList map pair of icons mapped to a enumeration of conditions.
      * @param condition the current condition being reported.
      * @return icon name
      */
     QString getWeatherIcon(const QMap<QString, ConditionIcons> &conditionList, const QString &condition) const;
 
     /**
      * Returns wind icon element to display in applet.
      * @param windDirList a QList map pair of wind directions mapped to a enumeration of directions.
      * @param windDirection the current wind direction.
      * @return svg element for wind direction
      */
     QString getWindDirectionIcon(const QMap<QString, WindDirections> &windDirList, const QString &windDirection) const;
 
 public Q_SLOTS:
 
     /**
      * Reimplemented from Plasma5Support::DataEngine
      * @param source the name of the datasource to be updated
      */
     bool updateSourceEvent(const QString &source) override;
 
     /**
      * Reimplement for ion to reload data if network status comes back up
      */
     virtual void reset() = 0;
 
 Q_SIGNALS:
     void forceUpdate(IonInterface *ion, const QString &source);
 
 protected:
     /**
      * Call this method to flush waiting source requests that may be pending
      * initialization
      *
      * @arg initialized whether or not the ion is currently ready to fetch data
      */
     void setInitialized(bool initialized);
 
     /**
      * Reimplemented from Plasma5Support::DataEngine
      * @param source The datasource being requested
      */
     bool sourceRequestEvent(const QString &source) override;
 
     /**
      * Reimplement to fetch the data from the ion.
      * @arg source the name of the datasource.
      * @return true if update was successful, false if failed
      */
     virtual bool updateIonSource(const QString &source) = 0;
 
     friend class WeatherEngine;
 
 private:
     class Private;
     Private *const d;
 };