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 / kconfigdialog.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  9.5 KB  |  280 lines
  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (C) 2003 Benjamin C Meyer (ben+kdelibs at meyerhome dot net)
  4.  *  Copyright (C) 2003 Waldo Bastian <bastian@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. #ifndef KCONFIGDIALOG_H
  22. #define KCONFIGDIALOG_H
  23.  
  24. class KConfig;
  25. class KConfigSkeleton;
  26. class KConfigDialogManager;
  27. #include <kdialogbase.h>
  28. #include <qasciidict.h>
  29.  
  30. /**
  31.  * \short Standard %KDE configuration dialog class
  32.  *
  33.  * The KConfigDialog class provides an easy and uniform means of displaying
  34.  * a settings dialog using KDialogBase, KConfigDialogManager and a
  35.  * KConfigSkeleton derived settings class.
  36.  *
  37.  * KConfigDialog handles the enabling and disabling of buttons, creation
  38.  * of the dialog, and deletion of the widgets.  Because of
  39.  * KConfigDialogManager, this class also manages: restoring
  40.  * the settings, reseting them to the default values, and saving them. This
  41.  * requires that the names of the widgets corresponding to configuration entries
  42.  * have to have the same name plus an additional "kcfg_" prefix. For example the
  43.  * widget named "kcfg_MyOption" would be associated with the configuration entry
  44.  * "MyOption".
  45.  *
  46.  * Here is an example usage of KConfigDialog:
  47.  *
  48.  * \code
  49.  * void KCoolApp::showSettings(){
  50.  *   if(KConfigDialog::showDialog("settings"))
  51.  *     return;
  52.  *   KConfigDialog *dialog = new KConfigDialog(this, "settings", MySettings::self(), KDialogBase::IconList);
  53.  *   dialog->addPage(new General(0, "General"), i18n("General") );
  54.  *   dialog->addPage(new Appearance(0, "Style"), i18n("Appearance") );
  55.  *   connect(dialog, SIGNAL(settingsChanged()), mainWidget, SLOT(loadSettings()));
  56.  *   connect(dialog, SIGNAL(settingsChanged()), this, SLOT(loadSettings()));
  57.  *   dialog->show();
  58.  * }
  59.  * \endcode
  60.  *
  61.  * Other than the above code, each class that has settings in the dialog should
  62.  * have a loadSettings() type slot to read settings and perform any
  63.  * necessary changes.
  64.  *
  65.  * Please note that using the setMainWidget method inherited from KDialogBase
  66.  * currently yields broken behaviour at runtime; use @ref addPage() instead.
  67.  *
  68.  * @see KConfigSkeleton
  69.  * @author Waldo Bastian <bastian@kde.org>
  70.  * @since 3.2
  71.  */
  72. class KDEUI_EXPORT KConfigDialog : public KDialogBase {
  73. Q_OBJECT
  74.  
  75. signals:
  76.   /**
  77.    * A widget in the dialog was modified.
  78.    */
  79.   void widgetModified();
  80.  
  81.   /**
  82.    * One or more of the settings have been permanently changed such as if
  83.    * the user clicked on the Apply or Ok button.
  84.    */
  85.   void settingsChanged();
  86.  
  87.   /**
  88.    * One or more of the settings have been permanently changed such as if
  89.    * the user clicked on the Apply or Ok button.
  90.    * This signal is useful when using KConfigDialog to configure
  91.    * items in a list.  When emitted the main class would then know what
  92.    * item in the list was actually changed.
  93.    * @param dialogName the name of the dialog.
  94.    */
  95.   void settingsChanged(const char *dialogName);
  96.  
  97. public:
  98.   /**
  99.    * @param parent - The parent of this object.  Even though the class
  100.    * deletes itself the parent should be set so the dialog can be centered
  101.    * with the application on the screen.
  102.    *
  103.    * @param name - The name of this object.  The name is used in determining if
  104.    * there can be more than one dialog at a time.  Use names such as:
  105.    * "Font Settings" or "Color Settings" and not just "Settings" in
  106.    * applications where there is more than one dialog.
  107.    *
  108.    * @param dialogType - Type used in creating the dialog.  See KDialogBase
  109.    *
  110.    * @param config - Config object containing settings.
  111.    *
  112.    * @param dialogButtons - Buttons that should show up on the dialog.
  113.    *
  114.    * @param defaultButton default button that is choosen by hitting the enter key.
  115.    *
  116.    * @param modal - Whether the dialog should be modal. To prevent more than one
  117.    * non-modal settings dialog from showing the static function showDialog() can be
  118.    * used in determining if the settings dialog already exists before creating
  119.    * a new KConfigDialog object.
  120.    */
  121.   // KDE4: Add the "separator" parameter as in KDialogBase
  122.   //       Make "dialogType" an int
  123.   KConfigDialog( QWidget *parent, const char *name,
  124.                  KConfigSkeleton *config,
  125.                  DialogType dialogType = IconList,
  126.                  int dialogButtons = Default|Ok|Apply|Cancel|Help,
  127.                  ButtonCode defaultButton = Ok,
  128.                  bool modal=false );
  129.  
  130.   /**
  131.    * Deconstructor, removes name from the list of open dialogs.
  132.    * Deletes private class.
  133.    * @see exists()
  134.    */
  135.   ~KConfigDialog();
  136.  
  137.   /**
  138.    * Adds page to the dialog and to KConfigDialogManager.  When an
  139.    * application is done adding pages show() should be called to
  140.    * display the dialog.
  141.    * Note that after you call show() you can not add any more pages
  142.    * to the dialog.
  143.    * @param page - Pointer to the page that is to be added to the dialog.
  144.    * This object is reparented.
  145.    * @param itemName - Name of the page.
  146.    * @param pixmapName - Name of the pixmap that should be used if needed.
  147.    * @param header - Header text use in the list modes. Ignored in Tabbed
  148.    *        mode. If empty, the itemName text is used when needed.
  149.    * @param manage - Whether KConfigDialogManager should manage the page or not.
  150.    */
  151.   // KDE4: Add a default value for itemName & pixmapName
  152.   void addPage( QWidget *page, const QString &itemName,
  153.                 const QString &pixmapName,
  154.                 const QString &header=QString::null,
  155.                 bool manage=true );
  156.  
  157.   /**
  158.    * Adds page to the dialog that is managed by a custom KConfigDialogManager.
  159.    * This is useful for dialogs that contain settings spread over more than
  160.    * one configuration file and thus have/need more than one KConfigSkeleton.
  161.    * When an application is done adding pages show() should be called to
  162.    * display the dialog.
  163.    * Note that after you call show() you can not add any more pages
  164.    * to the dialog.
  165.    * @param page - Pointer to the page that is to be added to the dialog.
  166.    * This object is reparented.
  167.    * @param config - Config object containing corresponding settings.
  168.    * @param itemName - Name of the page.
  169.    * @param pixmapName - Name of the pixmap that should be used if needed.
  170.    * @param header - Header text use in the list modes. Ignored in Tabbed
  171.    *        mode. If empty, the itemName text is used when needed.
  172.    */
  173.   // KDE4: Add a default value for itemName & pixmapName
  174.   void addPage( QWidget *page, KConfigSkeleton *config,
  175.                 const QString &itemName,
  176.                 const QString &pixmapName,
  177.                 const QString &header=QString::null );
  178.  
  179.   /**
  180.    * See if a dialog with the name 'name' already exists.
  181.    * @see showDialog()
  182.    * @param name - Dialog name to look for.
  183.    * @return Pointer to widget or NULL if it does not exist.
  184.    */
  185.   static KConfigDialog* exists( const char* name );
  186.  
  187.   /**
  188.    * Attempts to show the dialog with the name 'name'.
  189.    * @see exists()
  190.    * @param name - The name of the dialog to show.
  191.    * @return True if the dialog 'name' exists and was shown.
  192.    */
  193.   static bool showDialog( const char* name );
  194.  
  195.   /**
  196.    * Show the dialog.
  197.    */
  198.   virtual void show();
  199.  
  200. protected slots:
  201.   /**
  202.    * Update the settings from the dialog.
  203.    * Virtual function for custom additions.
  204.    *
  205.    * Example use: User clicks Ok or Apply button in a configure dialog.
  206.    */
  207.   virtual void updateSettings();
  208.  
  209.   /**
  210.    * Update the dialog based on the settings.
  211.    * Virtual function for custom additions.
  212.    *
  213.    * Example use: Initialisation of dialog.
  214.    * Example use: User clicks Reset button in a configure dialog.
  215.    */
  216.   virtual void updateWidgets();
  217.  
  218.   /**
  219.    * Update the dialog based on the default settings.
  220.    * Virtual function for custom additions.
  221.    *
  222.    * Example use: User clicks Defaults button in a configure dialog.
  223.    */
  224.   virtual void updateWidgetsDefault();
  225.  
  226. protected:
  227.  
  228.   /**
  229.    * Returns whether the current state of the dialog is
  230.    * different from the current configutation.
  231.    * Virtual function for custom additions.
  232.    */
  233.   virtual bool hasChanged() { return false; }
  234.  
  235.   /**
  236.    * Returns whether the current state of the dialog is
  237.    * the same as the default configuration.
  238.    */
  239.   virtual bool isDefault() { return true; }
  240.  
  241. protected slots:
  242.   /**
  243.    * Updates the Apply and Default buttons.
  244.    */
  245.   void updateButtons();
  246.  
  247.   /**
  248.    * Some setting was changed. Emit the signal with the dialogs name
  249.    */
  250.   void settingsChangedSlot();
  251.  
  252. private:
  253.   /**
  254.    * Internal function with common addPage code.
  255.    */
  256.   void addPageInternal(QWidget *page, const QString &itemName,
  257.                            const QString &pixmapName, const QString &header);
  258.  
  259.   /**
  260.    * Sets the connections from a manager to the dialog (and the other
  261.    * way round) up.
  262.    */
  263.   void setupManagerConnections(KConfigDialogManager *manager);
  264.  
  265. private:
  266.   /**
  267.    * The list of existing dialogs.
  268.    */
  269.   static QAsciiDict<KConfigDialog> openDialogs;
  270.  
  271.   class KConfigDialogPrivate;
  272.   /**
  273.    * Private class.
  274.    */
  275.   KConfigDialogPrivate *d;
  276. };
  277.  
  278. #endif //KCONFIGDIALOG_H
  279.  
  280.