summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kcautoconfigmodule.h
blob: 9102f2b4f4b47e793bb34f59038138985d9433ab (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
/*  This file is part of the KDE project
    Copyright (C) 2003 Olivier Goffart <ogoffart @ kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License version 2 as published by the Free Software Foundation.

    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 KCAUTOCONFIGMODULE_H
#define KCAUTOCONFIGMODULE_H

#include <kcmodule.h>

#include "kopete_export.h"

class KAutoConfig;
class KConfig;


/**
 * @short Convenience KCModule for creating config page handled with KAutoConfig
 *
 * This class makes it very easy to create a configuration page using KAutoConfig.
 * All you need to do is create a class that is derived from KCAutoConfigModule, create your
 * config page with TQDesigner, and add it to the module
 * This can be  done using the setMainWidget() method:
 * \code
 * typedef KGenericFactory<MyPageConfig, TQWidget> MyPageConfigFactory;
 * K_EXPORT_COMPONENT_FACTORY( kcm_mypageconfig, MyPageConfigFactory( "kcm_mypageconfig" ) )
 *
 * MyPageConfig( TQWidget * parent, const char *, const TQStringList & args )
 *     : KCAutoConfigModule( MyPageConfigFactory::instance(), parent, args )
 * {
 *       setMainWidget( new MyPageConfigBase(this) , "MyGroup" );
 * }
 * \endcode
 *
 *
 * @author Olivier Goffart <ogoffart(@)tisclinet.be>
 * @since 3.2
 */
class KOPETE_EXPORT KCAutoConfigModule : public KCModule
{
	Q_OBJECT
  TQ_OBJECT
	public:
		/**
		* Standard KCModule constructor.  Use KGlobal::config()
		*/
		KCAutoConfigModule( TQWidget * parent = 0, const char * name = 0, const TQStringList & args = TQStringList() );

		/**
		* Standard KCModule constructor.  Use KGlobal::config()
		*/
		KCAutoConfigModule( KInstance * instance, TQWidget * parent = 0, const TQStringList & args = TQStringList() );

		/**
		*  Constructor.
		*  @param config the KConfig to use
		*  @param instance KInstance object for this KCM
		*  @param parent parent widget
		*  @param args special arguments for this KCM
		*
		*  @todo document what the args mean (inherited from KCModule?)
		*/
		KCAutoConfigModule(KConfig* config, KInstance * instance, TQWidget * parent = 0, const TQStringList & args = TQStringList() );

		/**
		*  Constructor, much like the one above, except with
		*  no instance and with a name.
		*  @param config the KConfig to use
		*  @param parent parent widget
		*  @param name name of the object
		*  @param args special arguments for this KCM
		*/
		KCAutoConfigModule(KConfig* config, TQWidget * parent = 0, const char * name=0 , const TQStringList & args = TQStringList() );


		~KCAutoConfigModule();

		/**
		 * Set the main widget. @p widget will be lay out to take all available place in the module.
		 * @p widget must have this module as parent.
		 *
		 * This method automatically call KAutoConfig::addWidget() and KAutoConfig::retrieveSettings()
		 *
		 * @param widget the widget to place on the page and to add in the KAutoConfig
		 * @param group the name of the group where settings are stored in the config file
		 */
		void setMainWidget(TQWidget *widget, const TQString& group);

		/**
		 * @brief a reference to the KAutoConfig
		 *
		 * You can add or remove manually some widget from the KAutoWidget.
		 * If you choose to don't add the main widget with setMainWidget() , you need
		 * to call  KAutoConfig::retrieveSettings(true) yourself
		 *
		 * @return a reference to the KAutoConfig
		 */
		KAutoConfig *autoConfig();

		/**
		 * Reload the config from the configfile.
		 *
		 * You can also reimplement this method, but you should always call the parent KCModule::load()
		 * be sure you know what you are doing
		 */
		virtual void load();

		/**
		 * Save the config to the configfile.
		 *
		 * You can also reimplement this method, but you should always call the parent KCModule::save()
		 * be sure you know what you are doing
		 */
		virtual void save();

		/**
		 * Reload the default config
		 *
		 * You can also reimplement this method, but you should always call the parent KCModule::defaults()
		 * be sure you know what you are doing
		 */
		virtual void defaults();


	protected slots:
		/**
		 * Some setting was modified, updates buttons
		 */
		virtual void slotWidgetModified();

	private:
		class KCAutoConfigModulePrivate;
		KCAutoConfigModulePrivate * d;
};


#endif