ground/gcs/src/plugins/coreplugin/uavconfiginfo.cpp

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       uavconfiginfo.cpp
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
   6  * @addtogroup GCSPlugins GCS Plugins
   7  * @{
   8  * @addtogroup CorePlugin Core Plugin
   9  * @{
  10  * @brief The Core GCS plugin
  11  *****************************************************************************/
  12 /*
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 3 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  21  * for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License along
  24  * with this program; if not, write to the Free Software Foundation, Inc.,
  25  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  26  */
  27 /*!
  28     \class Core::UAVConfigInfo
  29     \mainclass
  30
  31     \brief The Config Info is a helper-class to handle version changes in GCS
  32         configuration files.
  33
  34     The UAVConfigInfo provides version-information for the configuration-data
  35     and callback functions to ask the user how to handle incompatble
  36     (old or newer) configurations.
  37
  38     When the config is created from a \l{QSettings} instance, an UAVConfigInfo
  39     object is passed to the factory-method. With the version-data it can decide whether
  40     the presented config-data is compatible to the current implementation. It may
  41     migrate old data to the current format or abort the import.
  42
  43     When the config is written to the \l{QSettings} instance, an UAVConfigInfo object
  44     is passed to the writer-function. The version of the config-format should
  45     be written to the UAVConfigInfo object. This version will be passed to
  46     factory-method when creating the config-object from this configuration.
  47
  48
  49     Typically a plugin can handle version-changes like this:
  50     \code
  51     MyGadgetConfiguration::MyGadgetConfiguration(QString classId, QSettings &settings, UAVConfigInfo *configInfo, QObject *parent) :
  52         IUAVGadgetConfiguration(classId, parent)
  53     {
  54         if ( configInfo->version() == UAVConfigVersion() )
  55             configInfo->setVersion("1.0.0");
  56
  57         if ( !configInfo->standardVersionHandlingOK(CURRENT_VERSION))
  58             return;
  59
  60         ... read the config ...
  61     }
  62
  63     void MyGadgetConfiguration::saveConfig(QSettings &settings, Core::UAVConfigInfo *configInfo) const {
  64
  65         configInfo->setVersion(CURRENT_VERSION);
  66
  67         ... write the config ...
  68     }
  69
  70     \endcode
  71
  72
  73     \section1 Version Conventions
  74
  75     The Version numbers are in the form "major.minor.patch" (e.g. "3.1.4") with the
  76     following meaning:
  77     \list
  78     \o major: Differences in this number indicate completely incompatible formats. The
  79         config can't be imported.
  80     \o minor: Differences in this number indicate backwards compatible formats. Old
  81         configs can be imported or will be automatically migrated by the new program
  82         but configs written by this plugin can't be reasonably read by old versions of
  83         the plugin.
  84     \o patch: Differences in this number indicate backwards and forward compatible formats.
  85         Configs written by this plugin can be read by old versions of the plugin. Old configs
  86         are extended by defaults by the new plugin.
  87     \endlist
  88
  89     All parts (major, minor, patch) must be numeric values.
  90
  91     \section1 Utility Functions
  92
  93     \fn bool UAVConfigInfo::standardVersionHandlingOK(UAVConfigVersion programVersion)
  94     \brief Default version handling.
  95
  96     With this function the plugin can test compatiblility of the current version
  97     with the imported version. If there are differences, the user is asked whether
  98     he or she wants to import the settings or abort the import.
  99
 100     Returns true when the import should be done, false otherwise.
 101
 102  */
 103
 104 #include "uavconfiginfo.h"
 105 #include <QMessageBox>
 106
 107 #define VERSION_DEFAULT "0.0.0"
 108
 109 using namespace Core;
 110
 111 UAVConfigInfo::UAVConfigInfo(QObject *parent) :
 112     QObject(parent),
 113     m_version(VERSION_DEFAULT),
 114     m_locked(false),
 115     m_nameOfConfigurable("")
 116 {}
 117
 118 UAVConfigInfo::UAVConfigInfo(QSettings &settings, QObject *parent) :
 119     QObject(parent),
 120     m_version(VERSION_DEFAULT)
 121 {
 122     read(settings);
 123 }
 124
 125 UAVConfigInfo::UAVConfigInfo(UAVConfigVersion version, QString nameOfConfigurable, QObject *parent) :
 126     QObject(parent),
 127     m_version(version),
 128     m_locked(false),
 129     m_nameOfConfigurable(nameOfConfigurable)
 130 {}
 131
 132 UAVConfigInfo::UAVConfigInfo(IUAVGadgetConfiguration *config, QObject *parent) :
 133     QObject(parent)
 134 {
 135     m_locked = config->locked();
 136     m_nameOfConfigurable = config->classId() + "-" + config->name();
 137 }
 138
 139 void UAVConfigInfo::save(QSettings &settings) const
 140 {
 141     settings.beginGroup("configInfo");
 142     settings.setValue("version", m_version.toString());
 143     settings.setValue("locked", m_locked);
 144     settings.endGroup();
 145 }
 146
 147 void UAVConfigInfo::read(QSettings &settings)
 148 {
 149     settings.beginGroup("configInfo");
 150     m_version = UAVConfigVersion(settings.value("version", VERSION_DEFAULT).toString());
 151     m_locked  = settings.value("locked", false).toBool();
 152     settings.endGroup();
 153 }
 154
 155 bool UAVConfigInfo::askToAbort(int compat, QString message)
 156 {
 157     QMessageBox msgBox;
 158
 159     msgBox.setInformativeText(tr("Do you want to continue the import?"));
 160     msgBox.setStandardButtons(QMessageBox::Ok | QMessageBox::Cancel);
 161
 162     int result = QMessageBox::Abort;
 163
 164     switch (compat) {
 165     case FullyCompatible:
 166         return false;
 167
 168     case MinorLossOfConfiguration:
 169         msgBox.setText(tr("INFO: ") + message + tr(" Some of the configured features might not be supported by your version of the plugin. You might want to upgrade the plugin."));
 170         msgBox.setDefaultButton(QMessageBox::Ok);
 171         result = msgBox.exec();
 172         break;
 173
 174     case MissingConfiguration:
 175         msgBox.setText(tr("WARNING: ") + message + tr(" Some configuration is missing in the imported config and will be replaced by default settings."));
 176         msgBox.setDefaultButton(QMessageBox::Ok);
 177         result = msgBox.exec();
 178         break;
 179
 180     case MajorLossOfConfiguration:
 181         msgBox.setText(tr("ERROR: ") + message + tr(" Major features can't be imported by your version of the plugin. You should upgrade the plugin to import these settings."));
 182         msgBox.setDefaultButton(QMessageBox::Cancel);
 183         result = msgBox.exec();
 184         break;
 185
 186     case NotCompatible:
 187         msgBox.setText("ERROR: " + message + tr(" The imported settings are not compatible with this plugin and won't be imported!"));
 188         msgBox.setInformativeText(tr(""));
 189         msgBox.setStandardButtons(QMessageBox::Ok);
 190         msgBox.exec();
 191         return true;
 192
 193     default:
 194         msgBox.setText("INTERNAL ERROR: " + message + tr(" Unknown compatibility level: %1").arg(compat));
 195     }
 196     if (result == QMessageBox::Ok) {
 197         return false;
 198     } else {
 199         return true;
 200     }
 201 }
 202
 203 void UAVConfigInfo::notify(QString message)
 204 {
 205     QMessageBox msgBox;
 206
 207     msgBox.setText(message);
 208     msgBox.exec();
 209 }
 210
 211 int UAVConfigInfo::checkCompatibilityWith(UAVConfigVersion programVersion)
 212 {
 213     if (m_version.majorNr != programVersion.majorNr) {
 214         return NotCompatible;
 215     }
 216     if (m_version.minorNr < programVersion.minorNr) {
 217         return MissingConfiguration;
 218     }
 219     if (m_version.minorNr > programVersion.minorNr) {
 220         return MajorLossOfConfiguration;
 221     }
 222     if (m_version.patchNr > programVersion.patchNr) {
 223         return MinorLossOfConfiguration;
 224     }
 225
 226     return FullyCompatible;
 227 }
 228
 229 bool UAVConfigInfo::standardVersionHandlingOK(UAVConfigVersion programVersion)
 230 {
 231     return !askToAbort(
 232         checkCompatibilityWith(programVersion),
 233         "(" + m_nameOfConfigurable + ")");
 234 }
 235
 236 UAVConfigVersion::UAVConfigVersion(int majorNum, int minorNum, int patchNum)
 237     : majorNr(majorNum)
 238     , minorNr(minorNum)
 239     , patchNr(patchNum)
 240 {}
 241
 242 UAVConfigVersion::UAVConfigVersion(QString versionString)
 243 {
 244     int begin;
 245     int end = 0;
 246
 247     begin   = end;
 248     end     = versionString.indexOf(".", begin);
 249     majorNr = versionString.mid(begin, end - begin).toInt();
 250
 251     begin   = end + 1;
 252     end     = versionString.indexOf(".", begin);
 253     minorNr = versionString.mid(begin, end - begin).toInt();
 254
 255     begin   = end + 1;
 256     patchNr = versionString.mid(begin).toInt();
 257 }
 258
 259 QString UAVConfigVersion::toString() const
 260 {
 261     return QString("%1.%2.%3").arg(majorNr).arg(minorNr).arg(patchNr);
 262 }
 263
 264 bool UAVConfigVersion::operator==(const UAVConfigVersion &other)
 265 {
 266     return toString() == other.toString();
 267 }
 268
 269 /**
 270  * @}
 271  * @}
 272  */