home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / ksettings / dialog.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  7.9 KB  |  225 lines
  1. /*  This file is part of the KDE project
  2.     Copyright (C) 2003 Matthias Kretz <kretz@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License version 2 as published by the Free Software Foundation.
  7.  
  8.     This library is distributed in the hope that it will be useful,
  9.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.     Library General Public License for more details.
  12.  
  13.     You should have received a copy of the GNU Library General Public License
  14.     along with this library; see the file COPYING.LIB.  If not, write to
  15.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.     Boston, MA 02110-1301, USA.
  17.  
  18. */
  19.  
  20. #ifndef KSETTINGS_DIALOG_H
  21. #define KSETTINGS_DIALOG_H
  22.  
  23. #include <qobject.h>
  24. #include <kservice.h>
  25.  
  26. template<class T> class QValueList;
  27. class KPluginInfo;
  28. class KCMultiDialog;
  29. class KCModuleInfo;
  30.  
  31. namespace KSettings
  32. {
  33.  
  34. /**
  35.  * @ingroup main
  36.  * @ingroup settings
  37.  * @short Generic configuration dialog that even works over component boundaries
  38.  *
  39.  * For more information see \ref KSettings.
  40.  *
  41.  * This class aims to standardize the use of configuration dialogs in KDE
  42.  * applications. Especially when using KParts and/or Plugins you face problems
  43.  * creating a consistent config dialog.
  44.  *
  45.  * To show a configuration dialog you only have to call the show method and be
  46.  * done with it. A code example:
  47.  *
  48.  * You initialize \p m_cfgdlg with
  49.  * \code
  50.  * m_cfgdlg = new Dialog( Dialog::Static, this );
  51.  * \endcode
  52.  * If you use a KPart that was not especially designed for your app you can use
  53.  * the second constructor:
  54.  * \code
  55.  * QStringList kpartslist;
  56.  * for( all my kparts )
  57.  *   kpartslist += m_mypart->instance().instanceName();
  58.  * m_cfgdlg = new Dialog( kpartslist, this );
  59.  * \endcode
  60.  * and the action for the config dialog is connected to the show slot:
  61.  * \code
  62.  * KStdAction::preferences( m_cfgdlg, SLOT( show() ), actionCollection() );
  63.  * \endcode
  64.  *
  65.  * If you need to be informed when the config was changed and applied in the
  66.  * dialog you might want to take a look at Dispatcher.
  67.  *
  68.  * For more information see \ref KSettings.
  69.  *
  70.  * @author Matthias Kretz <kretz@kde.org>
  71.  * @since 3.2
  72.  */
  73. class KUTILS_EXPORT Dialog : public QObject
  74. {
  75.     friend class PageNode;
  76.     Q_OBJECT
  77.     public:
  78.         /**
  79.          * Tells the dialog whether the entries in the listview are all static
  80.          * or whether it should add a Configure... button to select which parts
  81.          * of the optional functionality should be active or not.
  82.          */
  83.         enum ContentInListView
  84.         {
  85.             /**
  86.              * Static listview, while running no entries are added or deleted
  87.              */
  88.             Static,
  89.             /**
  90.              * Configurable listview. The user can select what functionality he
  91.              * wants.
  92.              */
  93.             Configurable
  94.         };
  95.  
  96.         /**
  97.          * Construct a new Preferences Dialog for the application. It uses all
  98.          * KCMs with X-KDE-ParentApp set to KGlobal::instance()->instanceName().
  99.          *
  100.          * @param parent       The parent is only used as the parent for the
  101.          *                     dialog - centering the dialog over the parent
  102.          *                     widget.
  103.          * @param name         name
  104.          */
  105.         Dialog( QWidget * parent = 0, const char * name = 0 );
  106.  
  107.         /**
  108.          * Construct a new Preferences Dialog for the application. It uses all
  109.          * KCMs with X-KDE-ParentApp set to KGlobal::instance()->instanceName().
  110.          *
  111.          * @param content      Select whether you want a static or configurable
  112.          *                     config dialog.
  113.          * @param parent       The parent is only used as the parent for the
  114.          *                     dialog - centering the dialog over the parent
  115.          *                     widget.
  116.          * @param name         name
  117.          */
  118.         Dialog( ContentInListView content = Static, QWidget * parent = 0,
  119.                 const char * name = 0 );
  120.  
  121.         /**
  122.          * Construct a new Preferences Dialog with the pages for the selected
  123.          * instance names. For example if you want to have the configuration
  124.          * pages for the kviewviewer KPart you would pass a
  125.          * QStringList consisting of only the name of the part "kviewviewer".
  126.          *
  127.          * @param components   A list of the names of the components that your
  128.          *                     config dialog should merge the config pages in.
  129.          * @param parent       The parent is only used as the parent for the
  130.          *                     dialog - centering the dialog over the parent
  131.          *                     widget.
  132.          * @param name         name
  133.          */
  134.         Dialog( const QStringList & components, QWidget * parent = 0,
  135.                 const char * name = 0 );
  136.  
  137.         /**
  138.          * Construct a new Preferences Dialog with the pages for the selected
  139.          * instance names. For example if you want to have the configuration
  140.          * pages for the kviewviewer KPart you would pass a
  141.          * QStringList consisting of only the name of the part "kviewviewer".
  142.          *
  143.          * @param components   A list of the names of the components that your
  144.          *                     config dialog should merge the config pages in.
  145.          * @param content      Select whether you want a static or configurable
  146.          *                     config dialog.
  147.          * @param parent       The parent is only used as the parent for the
  148.          *                     dialog - centering the dialog over the parent
  149.          *                     widget.
  150.          * @param name         name
  151.          */
  152.         Dialog( const QStringList & components, ContentInListView
  153.                 content, QWidget * parent = 0, const char * name = 0 );
  154.  
  155.         ~Dialog();
  156.  
  157.         /**
  158.          * If you use a Configurable dialog you need to pass KPluginInfo
  159.          * objects that the dialog should configure.
  160.          */
  161.         void addPluginInfos( const QValueList<KPluginInfo*> & plugininfos );
  162.  
  163.         KCMultiDialog * dialog();
  164.  
  165.     public slots:
  166.         /**
  167.          * Show the config dialog. The slot immediatly returns since the dialog
  168.          * is non-modal.
  169.          */
  170.         void show();
  171.  
  172.     signals:
  173.         /**
  174.          * If you use the dialog in Configurable mode and want to be notified
  175.          * when the user changes the plugin selections use this signal. It's
  176.          * emitted if the selection has changed and the user pressed Apply or
  177.          * Ok. In the slot you would then load and unload the plugins as
  178.          * requested.
  179.          */
  180.         void pluginSelectionChanged();
  181.  
  182.     protected slots:
  183.         void configureTree();
  184.         void updateTreeList();
  185.  
  186.     private:
  187.         /**
  188.          * @internal
  189.          * Check whether the plugin associated with this KCM is enabled.
  190.          */
  191.         bool isPluginForKCMEnabled( KCModuleInfo * ) const;
  192.  
  193.         QValueList<KService::Ptr> instanceServices() const;
  194.         QValueList<KService::Ptr> parentComponentsServices(
  195.                 const QStringList & ) const;
  196.         /**
  197.          * @internal
  198.          * Read the .setdlg file and add it to the groupmap
  199.          */
  200.         void parseGroupFile( const QString & );
  201.  
  202.         /**
  203.          * @internal
  204.          * If this module is put into a TreeList hierarchy this will return a
  205.          * list of the names of the parent modules.
  206.          */
  207.         QStringList parentModuleNames( KCModuleInfo * );
  208.  
  209.         /**
  210.          * @internal
  211.          * This method is called only once. The KCMultiDialog is not created
  212.          * until it's really needed. So if some method needs to access d->dlg it
  213.          * checks for 0 and if it's not created this method will do it.
  214.          */
  215.         void createDialogFromServices();
  216.  
  217.         class DialogPrivate;
  218.         DialogPrivate * d;
  219. };
  220.  
  221. }
  222.  
  223. // vim: sw=4 sts=4 et
  224. #endif // KSETTINGS_DIALOG_H
  225.