ground/openpilotgcs/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* qSettings, UAVConfigInfo *configInfo, QObject *parent) :
  52         IUAVGadgetConfiguration(classId, parent)
  53     {
  54         if ( ! qSettings )
  55             return;
  56
  57         if ( configInfo->version() == UAVConfigVersion() )
  58             configInfo->setVersion("1.0.0");
  59
  60         if ( !configInfo->standardVersionHandlingOK(CURRENT_VERSION))
  61             return;
  62
  63         ... read the config ...
  64     }
  65
  66     void MyGadgetConfiguration::saveConfig(QSettings* qSettings, Core::UAVConfigInfo *configInfo) const {
  67
  68         configInfo->setVersion(CURRENT_VERSION);
  69
  70         ... write the config ...
  71     }
  72
  73     \endcode
  74
  75
  76     \section1 Version Conventions
  77
  78     The Version numbers are in the form "major.minor.patch" (e.g. "3.1.4") with the
  79     following meaning:
  80     \list
  81     \o major: Differences in this number indicate completely incompatible formats. The
  82         config can't be imported.
  83     \o minor: Differences in this number indicate backwards compatible formats. Old
  84         configs can be imported or will be automatically migrated by the new program
  85         but configs written by this plugin can't be reasonably read by old versions of
  86         the plugin.
  87     \o patch: Differences in this number indicate backwards and forward compatible formats.
  88         Configs written by this plugin can be read by old versions of the plugin. Old configs
  89         are extended by defaults by the new plugin.
  90     \endlist
  91
  92     All parts (major, minor, patch) must be numeric values.
  93
  94     \section1 Utility Functions
  95
  96     \fn bool UAVConfigInfo::standardVersionHandlingOK(UAVConfigVersion programVersion)
  97     \brief Default version handling.
  98
  99     With this function the plugin can test compatiblility of the current version
 100     with the imported version. If there are differences, the user is asked whether
 101     he or she wants to import the settings or abort the import.
 102
 103     Returns true when the import should be done, false otherwise.
 104
 105  */
 106
 107 #include "uavconfiginfo.h"
 108 #include <QMessageBox>
 109
 110 #define VERSION_DEFAULT "0.0.0"
 111
 112 using namespace Core;
 113
 114 UAVConfigInfo::UAVConfigInfo(QObject *parent) :
 115     QObject(parent),
 116     m_version(VERSION_DEFAULT),
 117     m_locked(false),
 118     m_nameOfConfigurable("")
 119 {}
 120
 121 UAVConfigInfo::UAVConfigInfo(QSettings *qs, QObject *parent) :
 122     QObject(parent),
 123     m_version(VERSION_DEFAULT)
 124 {
 125     read(qs);
 126 }
 127
 128 UAVConfigInfo::UAVConfigInfo(UAVConfigVersion version, QString nameOfConfigurable, QObject *parent) :
 129     QObject(parent),
 130     m_version(version),
 131     m_locked(false),
 132     m_nameOfConfigurable(nameOfConfigurable)
 133 {}
 134
 135 UAVConfigInfo::UAVConfigInfo(IUAVGadgetConfiguration *config, QObject *parent) :
 136     QObject(parent)
 137 {
 138     m_locked = config->locked();
 139     m_nameOfConfigurable = config->classId() + "-" + config->name();
 140 }
 141
 142 void UAVConfigInfo::save(QSettings *qs)
 143 {
 144     qs->beginGroup("configInfo");
 145     qs->setValue("version", m_version.toString());
 146     qs->setValue("locked", m_locked);
 147     qs->endGroup();
 148 }
 149
 150 void UAVConfigInfo::read(QSettings *qs)
 151 {
 152     qs->beginGroup("configInfo");
 153     m_version = UAVConfigVersion(qs->value("version", VERSION_DEFAULT).toString());
 154     m_locked  = qs->value("locked", false).toBool();
 155     qs->endGroup();
 156 }
 157
 158 bool UAVConfigInfo::askToAbort(int compat, QString message)
 159 {
 160     QMessageBox msgBox;
 161
 162     msgBox.setInformativeText(tr("Do you want to continue the import?"));
 163     msgBox.setStandardButtons(QMessageBox::Ok | QMessageBox::Cancel);
 164
 165     int result = QMessageBox::Abort;
 166
 167     switch (compat) {
 168     case FullyCompatible:
 169         return false;
 170
 171     case MinorLossOfConfiguration:
 172         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."));
 173         msgBox.setDefaultButton(QMessageBox::Ok);
 174         result = msgBox.exec();
 175         break;
 176
 177     case MissingConfiguration:
 178         msgBox.setText(tr("WARNING: ") + message + tr(" Some configuration is missing in the imported config and will be replaced by default settings."));
 179         msgBox.setDefaultButton(QMessageBox::Ok);
 180         result = msgBox.exec();
 181         break;
 182
 183     case MajorLossOfConfiguration:
 184         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."));
 185         msgBox.setDefaultButton(QMessageBox::Cancel);
 186         result = msgBox.exec();
 187         break;
 188
 189     case NotCompatible:
 190         msgBox.setText("ERROR: " + message + tr(" The imported settings are not compatible with this plugin and won't be imported!"));
 191         msgBox.setInformativeText(tr(""));
 192         msgBox.setStandardButtons(QMessageBox::Ok);
 193         msgBox.exec();
 194         return true;
 195
 196     default:
 197         msgBox.setText("INTERNAL ERROR: " + message + tr(" Unknown compatibility level: %1").arg(compat));
 198     }
 199     if (result == QMessageBox::Ok) {
 200         return false;
 201     } else {
 202         return true;
 203     }
 204 }
 205
 206 void UAVConfigInfo::notify(QString message)
 207 {
 208     QMessageBox msgBox;
 209
 210     msgBox.setText(message);
 211     msgBox.exec();
 212 }
 213
 214 int UAVConfigInfo::checkCompatibilityWith(UAVConfigVersion programVersion)
 215 {
 216     if (m_version.majorNr != programVersion.majorNr) {
 217         return NotCompatible;
 218     }
 219     if (m_version.minorNr < programVersion.minorNr) {
 220         return MissingConfiguration;
 221     }
 222     if (m_version.minorNr > programVersion.minorNr) {
 223         return MajorLossOfConfiguration;
 224     }
 225     if (m_version.patchNr > programVersion.patchNr) {
 226         return MinorLossOfConfiguration;
 227     }
 228
 229     return FullyCompatible;
 230 }
 231
 232 bool UAVConfigInfo::standardVersionHandlingOK(UAVConfigVersion programVersion)
 233 {
 234     return !askToAbort(
 235         checkCompatibilityWith(programVersion),
 236         "(" + m_nameOfConfigurable + ")");
 237 }
 238
 239 UAVConfigVersion::UAVConfigVersion(int majorNum, int minorNum, int patchNum)
 240     : majorNr(majorNum)
 241     , minorNr(minorNum)
 242     , patchNr(patchNum)
 243 {}
 244
 245 UAVConfigVersion::UAVConfigVersion(QString versionString)
 246 {
 247     int begin;
 248     int end = 0;
 249
 250     begin   = end;
 251     end     = versionString.indexOf(".", begin);
 252     majorNr = versionString.mid(begin, end - begin).toInt();
 253
 254     begin   = end + 1;
 255     end     = versionString.indexOf(".", begin);
 256     minorNr = versionString.mid(begin, end - begin).toInt();
 257
 258     begin   = end + 1;
 259     patchNr = versionString.mid(begin).toInt();
 260 }
 261
 262 QString UAVConfigVersion::toString() const
 263 {
 264     return QString("%1.%2.%3").arg(majorNr).arg(minorNr).arg(patchNr);
 265 }
 266
 267 bool UAVConfigVersion::operator==(const UAVConfigVersion &other)
 268 {
 269     return toString() == other.toString();
 270 }
 271
 272 /**
 273  * @}
 274  * @}
 275  */