summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kautoconfig.h
blob: de0df1436a7d2c9b61fe9500f05662269b8a5fb5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
/*
 *  This file is part of the KDE libraries
 *  Copyright (C) 2003 Benjamin C Meyer (ben+kdelibs at meyerhome dot net)
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 */
#ifndef KAUTOCONFIG_H
#define KAUTOCONFIG_H

#include <qobject.h>
#include <qptrlist.h>

#include "kopete_export.h"

class KConfig;
class QWidget;

/**
 * @short Provides a means of automatically retrieving, saving and resetting basic settings
 * 
 * The KAutoConfig class provides a means of automatically retrieving,
 * saving and resetting basic settings.  It also can emit signals when
 * settings have been changed (settings were saved) or modified (the
 * user changes a checkbox from on to off).
 *
 * When told to retrieve settings ( retrieveSettings()) KAutoConfig 
 * will traverse the specified widgets building a list of all known widgets
 * that have a name and havn't been marked to be ignored.
 * If a setting is marked immutable the value is loaded and the widget is
 * disabled.
 *
 * The name of the widget determines the name of the setting.  The initial
 * value of the widget also is the default value when the widget is reset.
 * If the widget does not have a name then it is ignored.
 *
 * When saveSettings() or resetSettings() is called KAutoConfig
 * goes through the list of known widgets and performs the operation on each
 * of them.
 *
 * If one of the widgets needs special treatment it can be specified to be
 * ignored using the ignoreSubWidget() function.  
 *
 * KAutoConfig uses the QSqlPropertyMap class to determine if it can do
 * anything to a widget.  Note that KAutoConfig doesn't  require a database,
 * it simply uses the functionality that is built into the QSqlPropertyMap
 * class.  New widgets can be added to the map using  
 * QSqlPropertyMap::installDefaultMap().  Note that you can't just add any
 * class.  The class must have a matching Q_PROPERTY(...) macro defined.
 * 
 * For example (note that KColorButton is already added and it doesn't need to 
 * manually added):
 *
 * kcolorbutton.h defines the following property:
 * \code
 * Q_PROPERTY( QColor color READ color WRITE setColor )
 * \endcode
 *
 * To add KColorButton the following code would be inserted in the main.
 * 
 * \code
 * QSqlPropertyMap *map = QSqlPropertyMap::defaultMap();
 * map.insert("KColorButton", "color");
 * QSqlPropertyMap::installDefaultMap(map);
 * \endcode
 *
 * If you add a new widget to the QSqlPropertyMap and wish to be notified when
 * it is modified you should add its signal using addWidgetChangedSignal().
 * If the Apply and Default buttons and enabled/disabled by KAutoConfigDialog
 * automatically then this must be done.
 *
 * @see KAutoConfigDialog
 * @since 3.2
 * @author Benjamin C Meyer <ben+kdelibs at meyerhome dot net>
 */ 
class KOPETE_EXPORT KAutoConfig : public QObject {

Q_OBJECT

signals:
  /**
   * One or more of the settings have been saved (such as when the user
   * clicks on the Apply button).  This is only emitted by saveSettings()
   * whenever one or more setting were changed and consequently saved.
   */ 
  void settingsChanged();

  /**
   * One or more of the settings have been changed.
   * @param widget - The widget group (pass in via addWidget()) that
   * contains the one or more modified setting.
   * @see settingsChanged()
   */
  void settingsChanged( QWidget *widget );

  /**
   * If retrieveSettings() was told to track changes then if
   * any known setting was changed this signal will be emitted.  Note
   * that a settings can be modified several times and might go back to the 
   * original saved state. hasChanged() will tell you if anything has
   * actually changed from the saved values.
   */
  void widgetModified();


public:
  /**
   * Constructor.
   * @param kconfig - KConfig to use when retrieving/saving the widgets
   * that KAutoConfig knows about.
   * @param parent - Parent object.
   * @param name - Object name.
   */ 
  KAutoConfig( KConfig *kconfig, QObject *parent=0, const char *name=0 );
 
  /**
   * Constructor.
   * Uses KGlobal::config() when retrieving/saving the widgets that
   * KAutoConfig knows about.
   * @param parent - Parent object.
   * @param name - Object name.
   */ 
  KAutoConfig( QObject *parent=0, const char *name=0 );

  /**
   * Destructor.  Deletes private class.
   */
  ~KAutoConfig();
  
  /**
   * Adds a widget to the list of widgets that should be parsed for any 
   * children that KAutoConfig might know when retrieveSettings() is
   * called.  All calls to this function should be made before calling
   * retrieveSettings().
   * @param widget - Pointer to the widget to add.
   * @param group - Name of the group from which all of the settings for this
   * widget will be located.  If a child of 'widget' needs to be in a separate
   * group it should be added separately and also ignored.
   * @see ignoreSubWidget()
   */ 
  void addWidget( QWidget *widget, const QString &group );

  /**
   * Ignore the specified child widget when performing an action.  Doesn't
   * effect widgets that were added with addWidget() only their children. All
   * calls to this function should be made before calling retrieveSettings().
   * @param widget - Pointer to the widget that should be ignored.
   * Note: Widgets that don't have a name are ignored automatically.
   **/ 
  void ignoreSubWidget( QWidget *widget );

  /**
   * Traverse the specified widgets to see if anything is different then the
   * current settings. retrieveSettings() must be called before this 
   * function to build the list of known widgets and default values.
   * @return bool - True if any settings are different then the stored values.
   */
  bool hasChanged() const;

  /**
   * Traverse the specified widgets to see if anything is different then the
   * default. retrieveSettings() must be called before this function to
   * build the list of known widgets and default values.
   * @return bool - True if all of the settings are their default values.
   */
  bool isDefault() const;

  /**
   * Adds a widget and its signal to the internal list so that when
   * KAutoConfig finds widgetName in retrieveSettings() it will know
   * how to connect its signal that it has changed to KAutoConfig's signal
   * widgetModified().  This function should be called before 
   *
   * Example:
   * \code
   * addWidgetChangedSignal( "QCheckbox", SIGNAL(stateChanged(int)) );
   * \endcode
   *
   * This is generally used in conjunction with the addition of a class
   * to QSqlPropertyMap so KAutoConfig can get/set its values.
   *
   * @param widgetName - The class name of the widget (className()).
   * @param signal - The signal (with "SIGNAL()" wrapper) that should be called.
   */ 
  inline void addWidgetChangedSignal( const QString &widgetName,
                                      const QCString &signal ){
    changedMap.insert( widgetName, signal );
  }

  /**
   * Traverse the specified widgets, retrieving the settings for all known
   * widgets that aren't being ignored and storing the default values.
   * @param trackChanges - If any changes by the widgets should be tracked
   * set true.  This causes the emitting the modified() signal when
   * something changes.
   * @return bool - True if any setting was changed from the default.
   */ 
  bool retrieveSettings( bool trackChanges=false );
  
public slots:
  /**
   * Traverse the specified widgets, saving the settings for all known
   * widgets that aren't being ignored. retrieveSettings() must be called
   * before this function to build the list of known widgets and default values.
   * @return bool - True if any settings were changed.
   *
   * Example use: User clicks Ok or Apply button in a configure dialog.
   */ 
  bool saveSettings();

  /**
   * Traverse the specified widgets, reseting the widgets to their default
   * values for all known widgets that aren't being ignored.
   * retrieveSettings() must be called before this function to build
   * the list of known widgets and default values.
   *
   * Example use: User clicks Default button in a configure dialog.
   */
  void resetSettings() const;

  /**
   * Traverse the specified widgets, reloading the settings for all known
   * widgets that aren't being ignored.
   * retrieveSettings() must be called before this function to build
   * the list of known widgets and default values.
   *
   * Example use: User clicks Reset button in a configure dialog.
   */
  void reloadSettings() const; 

protected:
  /**
   * KConfigBase object used to get/save values.
   */
  KConfig *config;
  /**
   * Map of the classes and the signals that they emit when changed. 
   */
  QMap<QString, QCString> changedMap;

  /**
   * Recursive function that finds all known children.
   * Goes through the children of widget and if any are known and not being 
   * ignored, stores them in currentGroup.  Also checks if the widget
   * should be disabled because it is set immutable.
   * @param widget - Parent of the children to look at.
   * @param currentGroup - Place to store known children of widget.
   * @param trackChanges - If true then tracks any changes to the children of
   * widget that are known.
   * @return bool - If a widget was set to something other then its default.
   * @see retrieveSettings()
   */ 
  bool parseChildren( const QWidget *widget,
                      QPtrList<QWidget>&currentGroup, bool trackChanges );

private:
  class KAutoConfigPrivate;
  /**
   * KAutoConfig Private class.
   */ 
  KAutoConfigPrivate *d;

};

#endif // KAUTOCONFIG_H