Quassel IRC  Pre-Release
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros
SettingsPage Class Reference

A SettingsPage is a page in the settings dialog. More...

#include </tmp/quassel/src/uisupport/settingspage.h>

Inheritance diagram for SettingsPage:

Public Slots

virtual void save ()
 Save settings to permanent storage.
virtual void load ()
 Load settings from permanent storage, overriding any changes the user might have made in the dialog.
virtual void defaults ()
 Restore defaults, overriding any changes the user might have made in the dialog.

Signals

void changed (bool hasChanged)
 Emitted whenever the widget state changes.

Public Member Functions

 SettingsPage (const QString &category, const QString &name, QWidget *parent=0)
virtual ~SettingsPage ()
virtual QString category () const
 The category of this settings page.
virtual QString title () const
 The title of this settings page.
virtual bool needsCoreConnection () const
 Whether the settingspage needs a core connection to be selectable.
virtual QString settingsKey () const
 The key this settings page stores its values under.
virtual bool hasDefaults () const
 Derived classes need to define this and return true if they have default settings.
bool hasChanged () const
 Check if there are changes in the page, compared to the state saved in permanent storage.
virtual bool aboutToSave ()
 Called immediately before save() is called.

Static Public Member Functions

static void load (QCheckBox *box, bool checked)
 sets checked state depending on and stores the value for later comparision
static bool hasChanged (QCheckBox *box)
static void load (QComboBox *box, int index)
static bool hasChanged (QComboBox *box)
static void load (QSpinBox *box, int value)
static bool hasChanged (QSpinBox *box)

Protected Slots

void changed ()
 Calling this slot is equivalent to calling setChangedState(true).
void setChangedState (bool hasChanged=true)
 This should be called whenever the widget state changes from unchanged to change or the other way round.

Protected Member Functions

void initAutoWidgets ()
virtual QVariant loadAutoWidgetValue (const QString &widgetName)
virtual void saveAutoWidgetValue (const QString &widgetName, const QVariant &value)

Private Slots

void autoWidgetHasChanged ()

Private Member Functions

void findAutoWidgets (QObject *parent, QObjectList *widgetList) const
QByteArray autoWidgetPropertyName (QObject *widget) const
QString autoWidgetSettingsKey (QObject *widget) const

Private Attributes

QString _category
QString _title
bool _changed
bool _autoWidgetsChanged
QObjectList _autoWidgets

Detailed Description

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.

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 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 defaultValue can be defined in child widgets as well.

For widgets requiring special ways for storing and saving, define the property settingsKey and leave it empty. In this case, the methods saveAutoWidgetValue() and loadAutoWidgetValue() will be called with the widget's objectName as parameter.

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:

  • QGroupBox (isChecked())
  • QAbstractButton (isChecked(), e.g. for QCheckBox and QRadioButton)
  • QLineEdit, QTextEdit (text())
  • QComboBox (currentIndex())
  • QSpinBox (value())

Definition at line 57 of file settingspage.h.

Constructor & Destructor Documentation

SettingsPage ( const QString &  category,
const QString &  name,
QWidget *  parent = 0 
)

Definition at line 30 of file settingspage.cpp.

virtual ~SettingsPage ( )
inlinevirtual

Definition at line 63 of file settingspage.h.

Member Function Documentation

virtual QString category ( ) const
inlinevirtual

The category of this settings page.

Definition at line 66 of file settingspage.h.

References _category.

Referenced by SettingsDlg::registerSettingsPage().

virtual QString title ( ) const
inlinevirtual

The title of this settings page.

Definition at line 69 of file settingspage.h.

References _title.

Referenced by SettingsDlg::registerSettingsPage(), and SettingsPageDlg::SettingsPageDlg().

virtual bool needsCoreConnection ( ) const
inlinevirtual

Whether the settingspage needs a core connection to be selectable.

This is a hint for the settingspage dialog. Do not rely on the settingspage not being visible if disconnected, and care about disabling it yourself.

Reimplemented in IgnoreListSettingsPage, NetworksSettingsPage, IdentitiesSettingsPage, AliasesSettingsPage, and ConnectionSettingsPage.

Definition at line 75 of file settingspage.h.

Referenced by SettingsDlg::setItemState().

virtual QString settingsKey ( ) const
inlinevirtual

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 settingsKey property set, and should also provide a 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 /.

Reimplemented in BacklogSettingsPage.

Definition at line 85 of file settingspage.h.

Referenced by autoWidgetSettingsKey().

virtual bool aboutToSave ( )
inlinevirtual

Called immediately before save() is called.

Derived classes should return false if saving is not possible (e.g. the current settings are invalid).

Returns
false, if the SettingsPage cannot be saved in its current state.

Reimplemented in NetworksSettingsPage, and IdentitiesSettingsPage.

Definition at line 102 of file settingspage.h.

void load ( QCheckBox *  box,
bool  checked 
)
static

sets checked state depending on and stores the value for later comparision

Definition at line 51 of file settingspage.cpp.

Referenced by NotificationsSettingsPage::load(), SettingsPageDlg::reload(), SettingsDlg::reload(), SettingsPageDlg::SettingsPageDlg(), SettingsPageDlg::undoChanges(), and SettingsDlg::undoChanges().

bool hasChanged ( QCheckBox *  box)
static

Definition at line 58 of file settingspage.cpp.

void load ( QComboBox *  box,
int  index 
)
static

Definition at line 64 of file settingspage.cpp.

bool hasChanged ( QComboBox *  box)
static

Definition at line 71 of file settingspage.cpp.

void load ( QSpinBox *  box,
int  value 
)
static

Definition at line 77 of file settingspage.cpp.

bool hasChanged ( QSpinBox *  box)
static

Definition at line 84 of file settingspage.cpp.

void load ( )
virtualslot

Load settings from permanent storage, overriding any changes the user might have made in the dialog.

This baseclass implementation loads the autoWidgets, so be sure to call it if you use this feature in your settingsPage!

Reimplemented in IndicatorNotificationBackend::ConfigWidget, SnoreNotificationBackend::ConfigWidget, SystrayNotificationBackend::ConfigWidget, DockManagerNotificationBackend::ConfigWidget, KNotificationBackend::ConfigWidget, PhononNotificationBackend::ConfigWidget, TaskbarNotificationBackend::ConfigWidget, and OSXNotificationBackend::ConfigWidget.

Definition at line 187 of file settingspage.cpp.

References _autoWidgets, _autoWidgetsChanged, _changed, autoWidgetPropertyName(), autoWidgetSettingsKey(), changed(), hasChanged(), loadAutoWidgetValue(), and UiSettings::value().

void defaults ( )
virtualslot

Restore defaults, overriding any changes the user might have made in the dialog.

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!

Reimplemented in IndicatorNotificationBackend::ConfigWidget, SnoreNotificationBackend::ConfigWidget, SystrayNotificationBackend::ConfigWidget, DockManagerNotificationBackend::ConfigWidget, PhononNotificationBackend::ConfigWidget, TaskbarNotificationBackend::ConfigWidget, and OSXNotificationBackend::ConfigWidget.

Definition at line 228 of file settingspage.cpp.

References _autoWidgets, autoWidgetHasChanged(), and autoWidgetPropertyName().

Referenced by NotificationsSettingsPage::defaults(), SettingsPageDlg::loadDefaults(), and SettingsDlg::loadDefaults().

QVariant loadAutoWidgetValue ( const QString &  widgetName)
protectedvirtual

Definition at line 238 of file settingspage.cpp.

Referenced by load().

void saveAutoWidgetValue ( const QString &  widgetName,
const QVariant &  value 
)
protectedvirtual

Definition at line 245 of file settingspage.cpp.

Referenced by save().

void changed ( bool  hasChanged)
signal

Emitted whenever the widget state changes.

void autoWidgetHasChanged ( )
privateslot
void findAutoWidgets ( QObject *  parent,
QObjectList *  widgetList 
) const
private

Definition at line 119 of file settingspage.cpp.

Referenced by initAutoWidgets().

QByteArray autoWidgetPropertyName ( QObject *  widget) const
private

Definition at line 129 of file settingspage.cpp.

Referenced by autoWidgetHasChanged(), defaults(), load(), and save().

QString autoWidgetSettingsKey ( QObject *  widget) const
private

Definition at line 151 of file settingspage.cpp.

References settingsKey().

Referenced by load(), and save().

Member Data Documentation

QString _category
private

Definition at line 156 of file settingspage.h.

Referenced by category().

QString _title
private

Definition at line 156 of file settingspage.h.

Referenced by title().

bool _changed
private

Definition at line 157 of file settingspage.h.

Referenced by hasChanged(), load(), save(), and setChangedState().

bool _autoWidgetsChanged
private

Definition at line 157 of file settingspage.h.

Referenced by autoWidgetHasChanged(), hasChanged(), load(), and save().

QObjectList _autoWidgets
private

Definition at line 158 of file settingspage.h.

Referenced by autoWidgetHasChanged(), defaults(), initAutoWidgets(), load(), and save().


The documentation for this class was generated from the following files: