workspace/plasma/dataengines/weather/ions/ion.h

   1 /***************************************************************************
   2  *   Copyright (C) 2007 by Shawn Starr <shawn.starr@rogers.com>            *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA          *
  18  ***************************************************************************/
  19
  20 #ifndef _ION_H
  21 #define _ION_H
  22
  23 #include <QObject>
  24 #include <KGenericFactory>
  25 #include <plasma/dataengine.h>
  26
  27 #include "ion_export.h"
  28
  29 /**
  30 * @author Shawn Starr
  31 * This is the base class to be used to implement new ions for the WeatherEngine.
  32 * 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.
  33 *
  34 * Basically an ion is a Plasma::DataEngine, which is queried by the WeatherEngine instead of some applet.
  35 */
  36 class ION_EXPORT IonInterface : public Plasma::DataEngine
  37 {
  38     Q_OBJECT
  39     Q_PROPERTY(QString timezone READ timezone WRITE setTimezoneFormat)
  40     Q_PROPERTY(QString unit READ metricUnit WRITE setMeasureUnit)
  41
  42 public:
  43     typedef QHash<QString, IonInterface*> IonDict; // Define Dict as a QHash for Ions
  44
  45     /**
  46      * Constructor for the ion
  47      * @param parent The parent object.
  48      */
  49     explicit IonInterface(QObject *parent = 0);
  50     /**
  51      * Destructor for the ion
  52      */
  53     virtual ~IonInterface() {}
  54
  55     /**
  56      * Reimplement to do the initialization of the ion.
  57      * For example fetching the list of available cities or weather data sources should be fetched here.
  58      */
  59     virtual void init(void) = 0;
  60
  61     /**
  62      * Increment ion counter. This is used to check if the ion is being used.
  63      */
  64     void ref();
  65
  66     /**
  67      * Decrement ion counter. Called when ion is destroyed/unloaded.
  68      */
  69     void deref();
  70
  71     /**
  72      * Returns whether the ion is being used.
  73      * @return true if the ion is being used, false otherwise
  74      */
  75     bool isUsed() const;
  76
  77     /**
  78      * Reimplement to check whether the measurement is metric or not.
  79      * @return true if metric is used, false if not.
  80      */
  81     virtual bool metricUnit(void) = 0;
  82
  83     /**
  84      * Reimplement to check if timeformat is UTC or not.
  85      * @return true if UTC, false if local time.
  86      */
  87     virtual bool timezone(void) = 0;
  88
  89 public slots:
  90
  91     /**
  92      * Reimplemented from Plasma::DataEngine
  93      * @param source the name of the datasource to be updated
  94      */
  95     bool updateSource(const QString& source);
  96
  97 protected:
  98     /**
  99      * Call this method to flush waiting source requests that may be pending
 100      * initialization
 101      *
 102      * @arg initialized whether or not the ion is currently ready to fetch data
 103      */
 104     void setInitialized(bool initialized);
 105
 106     /**
 107      * Reimplemented from Plasma::DataEngine
 108      * @param source The datasource being requested
 109      */
 110     bool sourceRequested(const QString &source);
 111
 112     /**
 113      * Reimplement to fetch the data from the ion.
 114      * @arg source the name of the datasource.
 115      * @return true if update was successful, false if failed
 116      */
 117     virtual bool updateIonSource(const QString &source) = 0;
 118
 119     friend class WeatherEngine;
 120
 121 private:
 122     /**
 123      * Sets the measurement unit from KGlobal::locale()->measureSystem This is internally set by the WeatherEngine itself.
 124      * @arg measureType the measurement type
 125      */
 126     virtual void setMeasureUnit(const QString& measureType) = 0;
 127
 128     /**
 129      * Sets the system default for UTC from KDateTime::currentDateTime This is internally set by the WeatherEngine itself.
 130      * @arg isUtc The UTC state, maybe 0 or 1.
 131      */
 132     virtual void setTimezoneFormat(const QString& isUtc) = 0;
 133
 134     class Private;
 135     Private* const d;
 136 };
 137
 138 #define K_EXPORT_PLASMA_ION(name, classname) \
 139     K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 140     K_EXPORT_PLUGIN(factory("ion_" #name))
 141 #endif