X-Git-Url: https://git.quassel-irc.org/?p=quassel.git;a=blobdiff_plain;f=src%2Fuisupport%2Fsettingspage.h;h=f58cb3779562ff3ff430c34fc92b83ca6d73e0cd;hp=926d4d71492d57ac9d0020aee96cbe417ebcdd10;hb=aa40491595ffec54ba340a9850d99dc14d920eb3;hpb=8699dd758516d0ded076811e8ea656adc95e69d0

diff --git a/src/uisupport/settingspage.h b/src/uisupport/settingspage.h
index 926d4d71..f58cb377 100644
--- a/src/uisupport/settingspage.h
+++ b/src/uisupport/settingspage.h
@@ -24,31 +24,62 @@
 #include <QWidget>
 
 //! A SettingsPage is a page in the settings dialog.
+/** 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.
+ */
 class SettingsPage : public QWidget {
   Q_OBJECT
 
   public:
     SettingsPage(const QString &category, const QString &name, QWidget *parent = 0);
     virtual ~SettingsPage() {};
+
+    //! The category of this settings page.
     virtual QString category() const;
+
+    //! The title of this settings page.
     virtual QString title() const;
 
-    virtual bool hasChanged() const = 0;
+    //! 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.
+     *
+     * The default implementation returns false.
+     */
+    virtual bool hasDefaults() const;
+
+    //! Check if there are changes in the page, compared to the state saved in permanent storage.
+    bool hasChanged() const;
+
+    //! 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.
+     */
+    virtual bool aboutToSave();
 
   public slots:
+    //! Save settings to permanent storage.
     virtual void save() = 0;
+
+    //! Load settings from permanent storage, overriding any changes the user might have made in the dialog.
     virtual void load() = 0;
-    virtual void defaults() = 0;
+
+    //! Restore defaults, overriding any changes the user might have made in the dialog.
+    /** The default implementation does nothing.
+     */
+    virtual void defaults();
 
   protected slots:
-    //! Calling this slot is equivalent to emitting changed(true).
+    //! Calling this slot is equivalent to calling setChangedState(true).
     void changed();
 
   protected:
     //! This should be called whenever the widget state changes from unchanged to change or the other way round.
-    void changeState(bool hasChanged = true);
+    void setChangedState(bool hasChanged = true);
 
   signals:
+    //! Emitted whenever the widget state changes.
     void changed(bool hasChanged);
 
   private: