/* * 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., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef KAUTOCONFIG_H #define KAUTOCONFIG_H #include <tqobject.h> #include <tqptrlist.h> #include "kopete_export.h" class KConfig; class TQWidget; /** * @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 TQSqlPropertyMap 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 TQSqlPropertyMap * class. New widgets can be added to the map using * TQSqlPropertyMap::installDefaultMap(). Note that you can't just add any * class. The class must have a matching TQ_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 * TQ_PROPERTY( TQColor color READ color WRITE setColor ) * \endcode * * To add KColorButton the following code would be inserted in the main. * * \code * TQSqlPropertyMap *map = TQSqlPropertyMap::defaultMap(); * map.insert("KColorButton", "color"); * TQSqlPropertyMap::installDefaultMap(map); * \endcode * * If you add a new widget to the TQSqlPropertyMap 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 TQObject { Q_OBJECT TQ_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( TQWidget *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 tqparent - Parent object. * @param name - Object name. */ KAutoConfig( KConfig *kconfig, TQObject *tqparent=0, const char *name=0 ); /** * Constructor. * Uses KGlobal::config() when retrieving/saving the widgets that * KAutoConfig knows about. * @param tqparent - Parent object. * @param name - Object name. */ KAutoConfig( TQObject *tqparent=0, const char *name=0 ); /** * Destructor. Deletes private class. */ ~KAutoConfig(); /** * Adds a widget to the list of widgets that should be parsed for any * tqchildren 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( TQWidget *widget, const TQString &group ); /** * Ignore the specified child widget when performing an action. Doesn't * effect widgets that were added with addWidget() only their tqchildren. 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( TQWidget *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( "TQCheckbox", TQT_SIGNAL(stateChanged(int)) ); * \endcode * * This is generally used in conjunction with the addition of a class * to TQSqlPropertyMap so KAutoConfig can get/set its values. * * @param widgetName - The class name of the widget (className()). * @param signal - The signal (with "TQT_SIGNAL()" wrapper) that should be called. */ inline void addWidgetChangedSignal( const TQString &widgetName, const TQCString &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. */ TQMap<TQString, TQCString> changedMap; /** * Recursive function that finds all known tqchildren. * Goes through the tqchildren 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 tqchildren to look at. * @param currentGroup - Place to store known tqchildren of widget. * @param trackChanges - If true then tracks any changes to the tqchildren of * widget that are known. * @return bool - If a widget was set to something other then its default. * @see retrieveSettings() */ bool parseChildren( const TQWidget *widget, TQPtrList<TQWidget>¤tGroup, bool trackChanges ); private: class KAutoConfigPrivate; /** * KAutoConfig Private class. */ KAutoConfigPrivate *d; }; #endif // KAUTOCONFIG_H