X-Git-Url: https://git.quassel-irc.org/?p=quassel.git;a=blobdiff_plain;f=src%2Fuisupport%2Fsettingspage.h;h=d3db08a83e792dd9583d1dfc3d8c3f7c84ab93af;hp=7a5bcc6ac641b2c607207bd07ca7de4671f92655;hb=61e73ddfdd22418890102c44166483ddb28e1c93;hpb=26bdd4f29a13a635cfb73000e38a17f01c5982ce

diff --git a/src/uisupport/settingspage.h b/src/uisupport/settingspage.h
index 7a5bcc6a..d3db08a8 100644
--- a/src/uisupport/settingspage.h
+++ b/src/uisupport/settingspage.h
@@ -31,6 +31,24 @@ class QSpinBox;
 /** The SettingsDlg provides suitable standard buttons, such as Ok, Apply, Cancel, Restore Defaults and Reset.
  *  Some pages might also be used in standalone dialogs or other containers. A SettingsPage provides suitable
  *  slots and signals to allow interaction with the container.
+ *
+ *  A derived class needs to keep track of its changed state. Whenever a child widget changes, it needs to be
+ *  compared to its value in permanent storage, and the changed state updated accordingly by calling setChangedState().
+ *  For most standard widgets, SettingsPage can do this automatically if desired. Such a child widget needs to have
+ *  a dynamic property \c settingsKey that maps to the key in the client configuration file. This key is appended
+ *  to settingsKey(), which must be set to a non-null value in a derived class. If the widget's key starts with '/',
+ *  its key is treated as a global path starting from the root, rather than from settingsKey().
+ *  A second dynamic property \c defaultValue can be defined in child widgets as well.
+ *
+ *  SettingsPage manages loading, saving, setting to default and setting the changed state for all automatic child widgets.
+ *  Derived classes must be sure to call initAutoWidgets() *after* setupUi(); they also need to call the baseclass implementations
+ *  of load(), save() and defaults() (preferably at the end of the derived function, since they call setChangedState(false)).
+ *
+ *  The following widgets can be handled for now:
+ *    - QAbstractButton (isChecked(), e.g. for QCheckBox and QRadioButton)
+ *    - QLineEdit, QTextEdit (text())
+ *    - QComboBox (currentIndex())
+ *    - QSpinBox (value())
  */
 class SettingsPage : public QWidget {
   Q_OBJECT
@@ -38,13 +56,23 @@ class SettingsPage : public QWidget {
 public:
   SettingsPage(const QString &category, const QString &name, QWidget *parent = 0);
   virtual ~SettingsPage() {};
-  
+
   //! The category of this settings page.
   inline virtual QString category() const { return _category; }
-  
+
   //! The title of this settings page.
   inline virtual QString title() const { return _title; }
-  
+
+  //! The key this settings page stores its values under
+  /** This needs to be overriden to enable automatic loading/saving/hasChanged checking of widgets.
+   *  The child widgets' values will be stored in client settings under this key. Every widget that
+   *  should be automatically handled needs to have a \c settingsKey property set, and should also provide
+   *  a \c defaultValue property.
+   *  You can return an empty string (as opposed to a null string) to use the config root as a base, and
+   *  you can override this key for individual widgets by prefixing their SettingsKey with /.
+   */
+  inline virtual QString settingsKey() const { return QString(); }
+
   //! Derived classes need to define this and return true if they have default settings.
   /** If this method returns true, the "Restore Defaults" button in the SettingsDlg is
    *  enabled. You also need to provide an implementation of defaults() then.
@@ -52,10 +80,10 @@ public:
    * The default implementation returns false.
      */
   inline virtual bool hasDefaults() const { return false; }
-  
+
   //! Check if there are changes in the page, compared to the state saved in permanent storage.
-  inline bool hasChanged() const { return _changed; }
-  
+  inline bool hasChanged() const { return _changed || _autoWidgetsChanged; }
+
   //! Called immediately before save() is called.
   /** Derived classes should return false if saving is not possible (e.g. the current settings are invalid).
    *  \return false, if the SettingsPage cannot be saved in its current state.
@@ -72,30 +100,49 @@ public:
 
 public slots:
   //! Save settings to permanent storage.
-  virtual void save() = 0;
-  
+  /** This baseclass implementation saves the autoWidgets, so be sure to call it if you use
+   *  this feature in your settingsPage!
+   */
+  virtual void save();
+
   //! Load settings from permanent storage, overriding any changes the user might have made in the dialog.
-  virtual void load() = 0;
+  /** This baseclass implementation loads the autoWidgets, so be sure to call it if you use
+   *  this feature in your settingsPage!
+   */
+  virtual void load();
 
   //! Restore defaults, overriding any changes the user might have made in the dialog.
-  /** The default implementation does nothing.
+  /** This baseclass implementation loads the defaults of the autoWidgets (if available), so be sure
+   *  to call it if you use this feature in your settingsPage!
    */
-  inline virtual void defaults() {}
-			 
+  virtual void defaults();
+
 protected slots:
   //! Calling this slot is equivalent to calling setChangedState(true).
   inline void changed() { setChangedState(true); }
-  
+
   //! This should be called whenever the widget state changes from unchanged to change or the other way round.
   void setChangedState(bool hasChanged = true);
-  
+
+protected:
+  void initAutoWidgets();
+
 signals:
   //! Emitted whenever the widget state changes.
   void changed(bool hasChanged);
-  
+
+private slots:
+  // for auto stuff
+  void autoWidgetHasChanged();
+
 private:
+  void findAutoWidgets(QObject *parent, QObjectList *widgetList) const;
+  QByteArray autoWidgetPropertyName(QObject *widget) const;
+  QString autoWidgetSettingsKey(QObject *widget) const;
+
   QString _category, _title;
-  bool _changed;
+  bool _changed, _autoWidgetsChanged;
+  QObjectList _autoWidgets;
 };