Removed unneeded includes, cleaned up code, added comments

apps/opencs/model/settings/connector.hpp

@@ -20,34 +20,46 @@ namespace CSMSettings {
 
         CSVSettings::View *mMasterView;
 
-        //map using the view pointer as a key to it's index value
+        ///map using the view pointer as a key to it's index value
         QList <CSVSettings::View *> mSlaveViews;
 
-        //list of proxy values for each master value.
+        ///list of proxy values for each master value.
-        //value list order is indexed to the master value index.
+        ///value list order is indexed to the master value index.
         QMap < QString, QList <QStringList> > mProxyListMap;
 
     public:
         explicit Connector(CSVSettings::View *master,
                                 QObject *parent = 0);
 
+        ///Set the view which acts as a proxy for other setting views
         void setMasterView (CSVSettings::View *view);
+
+        ///Add a view to be updated / update to the master
         void addSlaveView (CSVSettings::View *view,
                                      QList <QStringList> &masterProxyValues);
 
     private:
 
+        ///loosely matches lists of proxy values across registered slaves
+        ///against a proxy value list for a given master value
         bool proxyListsMatch (const QList <QStringList> &list1,
                               const QList <QStringList> &list2) const;
 
+        ///loosely matches two string lists
         bool stringListsMatch (const QStringList &list1,
                                const QStringList &list2) const;
 
+        ///retrieves current values of registered slave views
         QList <QStringList> getSlaveViewValues() const;
 
     public slots:
 
+        ///updates slave views with proxy values associated with current
+        ///master value
         void slotUpdateSlaves() const;
+
+        ///updates master value associated with the currently selected
+        ///slave values, if applicable.
         void slotUpdateMaster() const;
     };
 }

apps/opencs/model/settings/setting.hpp

@@ -7,11 +7,17 @@
 
 namespace CSMSettings
 {
-    //Maps setting id ("page.name") to a list of corresponding proxy values.
+    //QString is the setting id in the form of "page/name"
-    //Order of proxy value stringlists corresponds to order of master proxy's
+    //QList is  a list of stringlists of proxy values.
-    //values in it's declared value list
+    //Order is important!  Proxy stringlists are matched against
+    //master values by their position in the QList.
     typedef QMap <QString, QList <QStringList> > ProxyValueMap;
 
+    ///Setting class is the interface for the User Settings.  It contains
+    ///a great deal of boiler plate to provide the core API functions, as
+    ///well as the property() functions which use enumeration to be iterable.
+    ///This makes the Setting class capable of being manipulated by script.
+    ///See CSMSettings::support.hpp for enumerations / string values.
     class Setting
     {
         QList <QStringList> mProperties;
@@ -19,10 +25,6 @@ namespace CSMSettings
 
         bool mIsEditorSetting;
 
-        //QString is the setting id in the form of "page.name"
-        //QList is  a list of stringlists of proxy values.
-        //Order is important!  Proxy stringlists are matched against
-        //master values by their position in the QList.
         ProxyValueMap mProxies;
 
     public:

apps/opencs/model/settings/support.hpp

@@ -7,22 +7,10 @@
 #include <QVariant>
 #include <QStringList>
 
-//Typedefs
-namespace CSMSettings
-{
-    // Definition / Declaration model typedefs
-    // "Pair" = Setting name and specific data
-    // "ListItem" = Page name and associated setting pair
-
-    typedef QPair <QString, QString> StringPair;
-    typedef QPair <QString, QStringList> StringListPair;
-    typedef QList <StringListPair> StringListPairs;
-
-}
-
 //Enums
 namespace CSMSettings
 {
+    ///Enumerated properties for scripting
     enum SettingProperty
     {
         Property_Name = 0,
@@ -55,6 +43,7 @@ namespace CSMSettings
         Property_Proxies = 25
     };
 
+    ///Basic setting widget types.
     enum SettingType
     {
         /*
@@ -82,16 +71,11 @@ namespace CSMSettings
         Type_Undefined = 40
     };
 
-    enum MergeMethod
-    {
-        Merge_Accept,
-        Merge_Ignore,
-        Merge_Overwrite
-    };
 }
 
 namespace CSVSettings
 {
+    ///Categorical view types which encompass the setting widget types
     enum ViewType
     {
         ViewType_Boolean = 0,
@@ -100,18 +84,12 @@ namespace CSVSettings
         ViewType_Text = 3,
         ViewType_Undefined = 4
     };
-
-    enum Alignment
-    {
-        Align_Left    = Qt::AlignLeft,
-        Align_Center  = Qt::AlignHCenter,
-        Align_Right   = Qt::AlignRight
-    };
 }
 
 
 namespace CSMSettings
 {
+    ///used to construct default settings in the Setting class
     struct PropertyDefaultValues
     {
         int id;
@@ -119,6 +97,9 @@ namespace CSMSettings
         QVariant value;
     };
 
+    ///strings which correspond to setting values.  These strings represent
+    ///the script language keywords which would be used to declare setting
+    ///views for 3rd party addons
     const QString sPropertyNames[] =
     {
         "name", "page", "setting_type", "is_multi_value",
@@ -129,6 +110,7 @@ namespace CSMSettings
         "defaults", "declarations", "definitions", "proxies"
     };
 
+    ///Default values for a setting.  Used in setting creation.
     const QString sPropertyDefaults[] =
     {
         "",         //name

apps/opencs/model/settings/usersettings.cpp

@@ -1,16 +1,7 @@
 #include "usersettings.hpp"
 
-#include <QTextStream>
-#include <QDir>
-#include <QString>
-#include <QRegExp>
-#include <QMap>
-#include <QMessageBox>
-#include <QTextCodec>
 #include <QSettings>
-
 #include <QFile>
-#include <QSortFilterProxyModel>
 
 #include <components/files/configurationmanager.hpp>
 #include <boost/version.hpp>
@@ -44,14 +35,6 @@ CSMSettings::UserSettings::UserSettings()
 
     mSettingDefinitions = 0;
 
-    mReadWriteMessage = QObject::tr("<br><b>Could not open or create file for \
-                        writing</b><br><br> Please make sure you have the right\
-                         permissions and try again.<br>");
-
-    mReadOnlyMessage = QObject::tr("<br><b>Could not open file for \
-                        reading</b><br><br> Please make sure you have the \
-                        right permissions and try again.<br>");
-
     buildSettingModelDefaults();
 }
 
@@ -318,32 +301,7 @@ CSMSettings::UserSettings::~UserSettings()
 {
     mUserSettingsInstance = 0;
 }
-/*
-void CSMSettings::UserSettings::displayFileErrorMessage
-                                                (const QString &userpath,
-                                                 const QString &globalpath,
-                                                 const QString &localpath) const
-{
-    QString message = QObject::tr("<br><b>An error was encountered loading \
-            user settings files.</b><br><br> One or several files could not \
-            be read.  This may be caused by a missing configuration file, \
-            incorrect file permissions or a corrupted installation of \
-            OpenCS.<br>");
 
-    message += QObject::tr("<br>Global filepath: ") + globalpath;
-    message += QObject::tr("<br>Local filepath: ") + localpath;
-    message += QObject::tr("<br>User filepath: ") + userpath;
-
-    QMessageBox msgBox;
-
-    msgBox.setWindowTitle(QObject::tr("OpenCS configuration file I/O error"));
-    msgBox.setIcon(QMessageBox::Critical);
-    msgBox.setStandardButtons(QMessageBox::Ok);
-
-    msgBox.setText (mReadWriteMessage + message);
-    msgBox.exec();
-}
-*/
 void CSMSettings::UserSettings::loadSettings (const QString &fileName)
 {
     QString userFilePath = QString::fromUtf8
@@ -352,28 +310,16 @@ void CSMSettings::UserSettings::loadSettings (const QString &fileName)
     QString globalFilePath = QString::fromUtf8
                                 (mCfgMgr.getGlobalPath().string().c_str());
 
-    QString localFilePath = QString::fromUtf8
-                                (mCfgMgr.getLocalPath().string().c_str());
-
-    bool isUser = QFile (userFilePath + fileName).exists();
-    bool isSystem = QFile (globalFilePath + fileName).exists();
-
     QString otherFilePath = globalFilePath;
 
     //test for local only if global fails (uninstalled copy)
-    if (!isSystem)
+    if (!QFile (globalFilePath + fileName).exists())
     {
-        isSystem = QFile (localFilePath + fileName).exists();
+        //if global is invalid, use the local path
-        otherFilePath = localFilePath;
+        otherFilePath = QString::fromUtf8
+                                    (mCfgMgr.getLocalPath().string().c_str());
     }
-/*
+
-    //error condition - notify and return
-    if (!isUser || !isSystem)
-    {
-        displayFileErrorMessage (userFilePath, globalFilePath, localFilePath);
-        return;
-    }
-*/
     QSettings::setPath
                 (QSettings::IniFormat, QSettings::UserScope, userFilePath);
 

apps/opencs/model/settings/usersettings.hpp

@@ -1,7 +1,7 @@
 #ifndef USERSETTINGS_HPP
 #define USERSETTINGS_HPP
 
-#include <QTextStream>
+#include <QList>
 #include <QStringList>
 #include <QString>
 #include <QMap>
@@ -32,8 +32,6 @@ namespace CSMSettings {
         static UserSettings *mUserSettingsInstance;
         Files::ConfigurationManager mCfgMgr;
 
-        QString mReadOnlyMessage;
-        QString mReadWriteMessage;
         QSettings *mSettingDefinitions;
         QList <Setting *> mSettings;
 

apps/opencs/view/settings/dialog.cpp

@@ -76,22 +76,9 @@ void CSVSettings::Dialog::buildPages()
         mStackedWidget->addWidget (&dynamic_cast<QWidget &>(*(page)));
     }
 
-    addDebugPage();
-
     resize (mStackedWidget->sizeHint());
 }
 
-void CSVSettings::Dialog::addDebugPage()
-{
-    /*
-  QTreeView *tree = new QTreeView();
-
-  //tree->setModel( &CSMSettings::UserSettings::instance().model() );
-
-  mStackedWidget->addWidget(tree);
-     new QListWidgetItem ("Standard Item Model", mPageListWidget);*/
-}
-
 void CSVSettings::Dialog::buildPageListWidget (QWidget *centralWidget)
 {
     mPageListWidget = new QListWidget (centralWidget);

apps/opencs/view/settings/dialog.hpp

@@ -41,7 +41,6 @@ namespace CSVSettings {
         void buildPages();
         void buildPageListWidget (QWidget *centralWidget);
         void buildStackedWidget (QWidget *centralWidget);
-        void addDebugPage();
 
     public slots:
 

apps/opencs/view/settings/frame.hpp

@@ -44,11 +44,13 @@ namespace CSVSettings
         void setHLayout()           { mIsHorizontal = true; }
         void setVLayout()           { mIsHorizontal = false; }
 
+        ///show / hide widgets (when stacked widget page changes)
         void showWidgets();
         void hideWidgets();
 
     private:
 
+        ///functions which return the index for the next layout row / column
         int getNextColumn() const;
         int getNextRow() const;
 

apps/opencs/view/settings/page.hpp

@@ -1,7 +1,6 @@
 #ifndef CSVSETTINGS_PAGE_HPP
 #define CSVSETTINGS_PAGE_HPP
 
-#include <QSizePolicy>
 #include <QWidget>
 #include <QMap>
 #include <QList>
@@ -40,6 +39,7 @@ namespace CSVSettings
         ///and returns it.
         View *findView (const QString &page, const QString &setting) const;
 
+        ///returns the list of views associated with the page
         const QList <View *> &views () const              { return mViews; }
 
     private:

apps/opencs/view/settings/rangeview.cpp

@@ -1,6 +1,3 @@
-#include <QHBoxLayout>
-#include <QVBoxLayout>
-#include <QGroupBox>
 #include <QSpinBox>
 #include <QDoubleSpinBox>
 #include <QAbstractSpinBox>

apps/opencs/view/settings/rangeview.hpp

@@ -21,13 +21,19 @@ namespace CSVSettings
                               Page *parent);
 
     protected:
+
+        ///virtual function called through View
         void updateView (bool signalUpdate = true) const;
 
+        ///construct a slider-based view
         void buildSlider (CSMSettings::Setting *setting);
+
+        ///construct a spinbox-based view
         void buildSpinBox (CSMSettings::Setting *setting);
 
     private slots:
 
+        ///responds to valueChanged signals
         void slotUpdateView (int value);
         void slotUpdateView (double value);
 

apps/opencs/view/settings/resizeablestackedwidget.hpp

@@ -14,8 +14,10 @@ namespace CSVSettings
     public:
         explicit ResizeableStackedWidget(QWidget *parent = 0);
 
+        ///add a widget to the stacked widget
         void addWidget(QWidget* pWidget);
 
+        ///called whenever the stacked widget page is changed
         void changePage (int, int);
     };
 }

apps/opencs/view/settings/settingwindow.hpp

@@ -28,20 +28,28 @@ namespace CSVSettings {
     public:
         explicit SettingWindow(QWidget *parent = 0);
 
+        ///retrieve a reference to a view based on it's page and setting name
         View *findView (const QString &pageName, const QString &setting);
+
+        ///set the model the view uses (instance of UserSettings)
         void setModel (CSMSettings::UserSettings &model)  { mModel = &model; }
 
     protected:
 
         virtual void closeEvent (QCloseEvent *event);
 
+        ///construct the pages to be displayed in the dialog
         void createPages();
 
+        ///return the list of constructed pages
         const PageList &pages() const     { return mPages; }
 
+        ///save settings from the GUI to file
         void saveSettings();
 
     private:
+
+        ///create connections between settings (used for proxy settings)
         void createConnections (const QList <CSMSettings::Setting *> &list);
     };
 }

apps/opencs/view/settings/spinbox.cpp

@@ -1,6 +1,5 @@
 #include "spinbox.hpp"
 
-#include <QSpinBox>
 #include <QLineEdit>
 
 CSVSettings::SpinBox::SpinBox(QWidget *parent)
@@ -14,7 +13,7 @@ QString CSVSettings::SpinBox::textFromValue(int val) const
     if (mValueList.isEmpty())
         return QVariant (val).toString();
 
-    QString value = "";
+    QString value;
 
     if (val < mValueList.size())
         value = mValueList.at (val);

apps/opencs/view/settings/spinbox.hpp

@@ -16,15 +16,22 @@ namespace CSVSettings
     public:
         explicit SpinBox(QWidget *parent = 0);
 
-        void setObjectName (const QString &name);
+        ///set the value displayed in the spin box
-
         void setValue (const QString &value);
+
+        ///set the stringlist that's used as a list of pre-defined values
+        ///to be displayed as the user scrolls
         void setValueList (const QStringList &list);
+
+        ///returns the pre-defined value list.
         const QStringList &valueList() const            { return mValueList; }
 
     protected:
 
+        ///converts an index value to corresponding text to be displayed
         QString textFromValue (int val) const;
+
+        ///converts a text value to a corresponding index
         int valueFromText (const QString &text) const;
     };
 }

apps/opencs/view/settings/textview.hpp

@@ -20,6 +20,7 @@ namespace CSVSettings
 
     protected:
 
+        /// virtual function called through View
         void updateView (bool signalUpdate = true) const;
 
     protected slots:

apps/opencs/view/settings/view.cpp

@@ -1,7 +1,8 @@
-#include <QStringListModel>
+#include <QStandardItemModel>
-#include <QSortFilterProxyModel>
 #include <QStandardItem>
 #include <QApplication>
+#include <QItemSelectionModel>
+#include <QStringListModel>
 
 #include "view.hpp"
 #include "../../model/settings/support.hpp"
@@ -42,24 +43,22 @@ void CSVSettings::View::buildModel (const CSMSettings::Setting *setting)
 
 void CSVSettings::View::buildFixedValueModel (const QStringList &values)
 {
+    //fixed value models are simple string list models, since they are read-only
     mDataModel = new QStringListModel (values, this);
 }
 
 void CSVSettings::View::buildUpdatableValueModel (const QStringList &values)
 {
+    //updateable models are standard item models because they support
+    //replacing entire columns
     QList <QStandardItem *> itemList;
 
     foreach (const QString &value, values)
         itemList.append (new QStandardItem(value));
 
-//        QSortFilterProxyModel *filter = new QSortFilterProxyModel (this);
     QStandardItemModel *model = new QStandardItemModel (this);
     model->appendColumn (itemList);
 
-//      filter->setSourceModel (model);
- /*   filter->setFilterRegExp ("*");
-    filter->setFilterKeyColumn (0);
-    filter->setFilterRole (Qt::DisplayRole);*/
     mDataModel = model;
 }
 
@@ -151,9 +150,6 @@ void CSVSettings::View::setSelectedValues (const QStringList &list,
     }
     select (selection);
 
-    //push changes to model side
-
-
     //update the view if the selection was set from the model side, not by the
     //user
     if (doViewUpdate)
@@ -192,7 +188,6 @@ bool CSVSettings::View::stringListsMatch (
 QList <QStandardItem *> CSVSettings::View::toStandardItemList
                                                 (const QStringList &list) const
 {
-
     QList <QStandardItem *> itemList;
 
     foreach (const QString &value, list)
@@ -212,12 +207,12 @@ QString CSVSettings::View::value (int row) const
     if (row > -1 && row < mDataModel->rowCount())
         return mDataModel->data (mDataModel->index(row, 0)).toString();
 
-    return "";
+    return QString();
 }
 
 int CSVSettings::View::widgetWidth(int characterCount) const
 {
-    QString widthToken = QString().fill ('P', characterCount);
+    QString widthToken = QString().fill ('m', characterCount);
     QFontMetrics fm (QApplication::font());
 
     return (fm.width (widthToken));

apps/opencs/view/settings/view.hpp

@@ -11,8 +11,6 @@ class QGroupBox;
 class QStringList;
 class QStandardItem;
 class QItemSelection;
-class QStringListModel;
-class QStandardItemModel;
 class QAbstractItemModel;
 class QItemSelectionModel;
 
@@ -52,9 +50,6 @@ namespace CSVSettings
 
         explicit View (CSMSettings::Setting *setting, Page *parent);
 
-        ///Physical frame in which the view UI is contained
-        void addViewWidget (QWidget *widget, int row = -1, int col = -1) const;
-
         ///Returns the index / row of the passed value, -1 if not found.
         int currentIndex () const;