kutils/kcmultidialog.h

   1 /*
   2    Copyright (c) 2000 Matthias Elter <elter@kde.org>
   3    Copyright (c) 2003 Daniel Molkentin <molkentin@kde.org>
   4    Copyright (c) 2003,2006 Matthias Kretz <kretz@kde.org>
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Library General Public
   8    License as published by the Free Software Foundation; either
   9    version 2 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Library General Public License for more details.
  15
  16    You should have received a copy of the GNU Library General Public License
  17    along with this library; see the file COPYING.LIB.  If not, write to
  18    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19    Boston, MA 02110-1301, USA.
  20
  21 */
  22
  23 #ifndef KCMULTIDIALOG_H
  24 #define KCMULTIDIALOG_H
  25
  26 #include <kcmoduleinfo.h>
  27 #include <kpagedialog.h>
  28
  29 class KCMultiDialogPrivate;
  30
  31 /**
  32  * @short A class that offers a KPageDialog containing arbitrary
  33  *        KControl Modules.
  34  *
  35  * @author Matthias Elter <elter@kde.org>, Daniel Molkentin <molkentin@kde.org>
  36  */
  37 class KUTILS_EXPORT KCMultiDialog : public KPageDialog
  38 {
  39   Q_OBJECT
  40     Q_DECLARE_PRIVATE(KCMultiDialog)
  41
  42   public:
  43     /**
  44      * Constructs a new KCMultiDialog
  45      *
  46      * @param parent The parent widget
  47      **/
  48     KCMultiDialog( QWidget *parent = 0 );
  49
  50
  51     /**
  52      * Destructor
  53      **/
  54    virtual ~KCMultiDialog();
  55
  56     /**
  57      * Add a module.
  58      *
  59      * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
  60      * the module will appear. Lighter modules on top, heavier modules at the bottom.
  61      *
  62      * @param module Specify the name of the module that is to be added
  63      *               to the list of modules the dialog will show.
  64      *
  65      * @param args The arguments that should be given to the KCModule when it is created
  66      *
  67      * @returns The @see KPageWidgetItem associated with the new dialog page.
  68      **/
  69     KPageWidgetItem* addModule( const QString& module, const QStringList&
  70                                 args = QStringList() );
  71
  72     /**
  73      * Add a module.
  74      *
  75      * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
  76      * the module will appear. Lighter modules on top, heavier modules at the bottom.
  77      *
  78      * @param moduleinfo Pass a KCModuleInfo object which will be
  79      *                   used for creating the module. It will be added
  80      *                   to the list of modules the dialog will show.
  81      *
  82      * @param parent The @see KPageWidgetItem that should appear as parents
  83      *               in the tree view or a 0 pointer if there is no parent.
  84      *
  85      * @param args The arguments that should be given to the KCModule when it is created
  86      **/
  87     KPageWidgetItem* addModule( const KCModuleInfo& moduleinfo, KPageWidgetItem *parent = 0,
  88                                 const QStringList& args = QStringList() );
  89
  90     /**
  91      * Removes all modules from the dialog.
  92      */
  93     void clear();
  94
  95   Q_SIGNALS:
  96     /**
  97      * Emitted after all KCModules have been told to save their configuration.
  98      *
  99      * The applyClicked and okClicked signals are emitted before the
 100      * configuration is saved.
 101      */
 102     void configCommitted();
 103
 104     /**
 105      * Emitted after the KCModules have been told to save their configuration.
 106      * It is emitted once for every instance the KCMs that were changed belong
 107      * to.
 108      *
 109      * You can make use of this if you have more than one component in your
 110      * application. componentName tells you the instance that has to reload its
 111      * configuration.
 112      *
 113      * The applyClicked and okClicked signals are emitted before the
 114      * configuration is saved.
 115      *
 116      * @param componentName The name of the instance that needs to reload its
 117      *                     configuration.
 118      */
 119     void configCommitted( const QByteArray & componentName );
 120
 121     protected:
 122         /**
 123          * This constructor can be used by subclasses to provide a custom KPageWidget.
 124          */
 125         KCMultiDialog(KPageWidget *pageWidget, QWidget *parent, Qt::WFlags flags = 0);
 126         KCMultiDialog(KCMultiDialogPrivate &dd, KPageWidget *pageWidget, QWidget *parent, Qt::WFlags flags = 0);
 127
 128   protected Q_SLOTS:
 129     /**
 130      * This slot is called when the user presses the "Default" Button.
 131      * You can reimplement it if needed.
 132      *
 133      * @note Make sure you call the original implementation.
 134      **/
 135     void slotDefaultClicked();
 136
 137     /**
 138      * This slot is called when the user presses the "Reset" Button.
 139      * You can reimplement it if needed.
 140      *
 141      * @note Make sure you call the original implementation.
 142      */
 143     void slotUser1Clicked();
 144
 145     /**
 146      * This slot is called when the user presses the "Apply" Button.
 147      * You can reimplement it if needed.
 148      *
 149      * @note Make sure you call the original implementation.
 150      **/
 151     void slotApplyClicked();
 152
 153     /**
 154      * This slot is called when the user presses the "OK" Button.
 155      * You can reimplement it if needed.
 156      *
 157      * @note Make sure you call the original implementation.
 158      **/
 159     void slotOkClicked();
 160
 161     /**
 162      * This slot is called when the user presses the "Help" Button.
 163      * It reads the X-DocPath field of the currently selected KControl
 164      * module's .desktop file to find the path to the documentation,
 165      * which it then attempts to load.
 166      *
 167      * You can reimplement this slot if needed.
 168      *
 169      * @note Make sure you call the original implementation.
 170      **/
 171     void slotHelpClicked();
 172
 173     private:
 174         Q_PRIVATE_SLOT(d_func(), void _k_slotCurrentPageChanged(KPageWidgetItem *))
 175         Q_PRIVATE_SLOT(d_func(), void _k_clientChanged())
 176         Q_PRIVATE_SLOT(d_func(), void _k_dialogClosed())
 177 };
 178
 179 #endif