diff options
Diffstat (limited to 'tdeui/kconfigdialog.h')
| -rw-r--r-- | tdeui/kconfigdialog.h | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/tdeui/kconfigdialog.h b/tdeui/kconfigdialog.h new file mode 100644 index 000000000..6c2061e88 --- /dev/null +++ b/tdeui/kconfigdialog.h @@ -0,0 +1,279 @@ +/* + * This file is part of the KDE libraries + * Copyright (C) 2003 Benjamin C Meyer (ben+kdelibs at meyerhome dot net) + * Copyright (C) 2003 Waldo Bastian <bastian@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 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 KCONFIGDIALOG_H +#define KCONFIGDIALOG_H + +class KConfig; +class KConfigSkeleton; +class KConfigDialogManager; +#include <kdialogbase.h> +#include <tqasciidict.h> + +/** + * \short Standard %KDE configuration dialog class + * + * The KConfigDialog class provides an easy and uniform means of displaying + * a settings dialog using KDialogBase, KConfigDialogManager and a + * KConfigSkeleton derived settings class. + * + * KConfigDialog handles the enabling and disabling of buttons, creation + * of the dialog, and deletion of the widgets. Because of + * KConfigDialogManager, this class also manages: restoring + * the settings, reseting them to the default values, and saving them. This + * requires that the names of the widgets corresponding to configuration entries + * have to have the same name plus an additional "kcfg_" prefix. For example the + * widget named "kcfg_MyOption" would be associated with the configuration entry + * "MyOption". + * + * Here is an example usage of KConfigDialog: + * + * \code + * void KCoolApp::showSettings(){ + * if(KConfigDialog::showDialog("settings")) + * return; + * KConfigDialog *dialog = new KConfigDialog(this, "settings", MySettings::self(), KDialogBase::IconList); + * dialog->addPage(new General(0, "General"), i18n("General") ); + * dialog->addPage(new Appearance(0, "Style"), i18n("Appearance") ); + * connect(dialog, TQT_SIGNAL(settingsChanged()), mainWidget, TQT_SLOT(loadSettings())); + * connect(dialog, TQT_SIGNAL(settingsChanged()), this, TQT_SLOT(loadSettings())); + * dialog->show(); + * } + * \endcode + * + * Other than the above code, each class that has settings in the dialog should + * have a loadSettings() type slot to read settings and perform any + * necessary changes. + * + * Please note that using the setMainWidget method inherited from KDialogBase + * currently yields broken behaviour at runtime; use @ref addPage() instead. + * + * @see KConfigSkeleton + * @author Waldo Bastian <bastian@kde.org> + * @since 3.2 + */ +class KDEUI_EXPORT KConfigDialog : public KDialogBase { +Q_OBJECT + +signals: + /** + * A widget in the dialog was modified. + */ + void widgetModified(); + + /** + * One or more of the settings have been permanently changed such as if + * the user clicked on the Apply or Ok button. + */ + void settingsChanged(); + + /** + * One or more of the settings have been permanently changed such as if + * the user clicked on the Apply or Ok button. + * This signal is useful when using KConfigDialog to configure + * items in a list. When emitted the main class would then know what + * item in the list was actually changed. + * @param dialogName the name of the dialog. + */ + void settingsChanged(const char *dialogName); + +public: + /** + * @param parent - The parent of this object. Even though the class + * deletes itself the parent should be set so the dialog can be centered + * with the application on the screen. + * + * @param name - The name of this object. The name is used in determining if + * there can be more than one dialog at a time. Use names such as: + * "Font Settings" or "Color Settings" and not just "Settings" in + * applications where there is more than one dialog. + * + * @param dialogType - Type used in creating the dialog. See KDialogBase + * + * @param config - Config object containing settings. + * + * @param dialogButtons - Buttons that should show up on the dialog. + * + * @param defaultButton default button that is choosen by hitting the enter key. + * + * @param modal - Whether the dialog should be modal. To prevent more than one + * non-modal settings dialog from showing the static function showDialog() can be + * used in determining if the settings dialog already exists before creating + * a new KConfigDialog object. + */ + // KDE4: Add the "separator" parameter as in KDialogBase + // Make "dialogType" an int + KConfigDialog( TQWidget *parent, const char *name, + KConfigSkeleton *config, + DialogType dialogType = IconList, + int dialogButtons = Default|Ok|Apply|Cancel|Help, + ButtonCode defaultButton = Ok, + bool modal=false ); + + /** + * Deconstructor, removes name from the list of open dialogs. + * Deletes private class. + * @see exists() + */ + ~KConfigDialog(); + + /** + * Adds page to the dialog and to KConfigDialogManager. When an + * application is done adding pages show() should be called to + * display the dialog. + * Note that after you call show() you can not add any more pages + * to the dialog. + * @param page - Pointer to the page that is to be added to the dialog. + * This object is reparented. + * @param itemName - Name of the page. + * @param pixmapName - Name of the pixmap that should be used if needed. + * @param header - Header text use in the list modes. Ignored in Tabbed + * mode. If empty, the itemName text is used when needed. + * @param manage - Whether KConfigDialogManager should manage the page or not. + */ + // KDE4: Add a default value for itemName & pixmapName + void addPage( TQWidget *page, const TQString &itemName, + const TQString &pixmapName, + const TQString &header=TQString::null, + bool manage=true ); + + /** + * Adds page to the dialog that is managed by a custom KConfigDialogManager. + * This is useful for dialogs that contain settings spread over more than + * one configuration file and thus have/need more than one KConfigSkeleton. + * When an application is done adding pages show() should be called to + * display the dialog. + * Note that after you call show() you can not add any more pages + * to the dialog. + * @param page - Pointer to the page that is to be added to the dialog. + * This object is reparented. + * @param config - Config object containing corresponding settings. + * @param itemName - Name of the page. + * @param pixmapName - Name of the pixmap that should be used if needed. + * @param header - Header text use in the list modes. Ignored in Tabbed + * mode. If empty, the itemName text is used when needed. + */ + // KDE4: Add a default value for itemName & pixmapName + void addPage( TQWidget *page, KConfigSkeleton *config, + const TQString &itemName, + const TQString &pixmapName, + const TQString &header=TQString::null ); + + /** + * See if a dialog with the name 'name' already exists. + * @see showDialog() + * @param name - Dialog name to look for. + * @return Pointer to widget or NULL if it does not exist. + */ + static KConfigDialog* exists( const char* name ); + + /** + * Attempts to show the dialog with the name 'name'. + * @see exists() + * @param name - The name of the dialog to show. + * @return True if the dialog 'name' exists and was shown. + */ + static bool showDialog( const char* name ); + + /** + * Show the dialog. + */ + virtual void show(); + +protected slots: + /** + * Update the settings from the dialog. + * Virtual function for custom additions. + * + * Example use: User clicks Ok or Apply button in a configure dialog. + */ + virtual void updateSettings(); + + /** + * Update the dialog based on the settings. + * Virtual function for custom additions. + * + * Example use: Initialisation of dialog. + * Example use: User clicks Reset button in a configure dialog. + */ + virtual void updateWidgets(); + + /** + * Update the dialog based on the default settings. + * Virtual function for custom additions. + * + * Example use: User clicks Defaults button in a configure dialog. + */ + virtual void updateWidgetsDefault(); + +protected: + + /** + * Returns whether the current state of the dialog is + * different from the current configutation. + * Virtual function for custom additions. + */ + virtual bool hasChanged() { return false; } + + /** + * Returns whether the current state of the dialog is + * the same as the default configuration. + */ + virtual bool isDefault() { return true; } + +protected slots: + /** + * Updates the Apply and Default buttons. + */ + void updateButtons(); + + /** + * Some setting was changed. Emit the signal with the dialogs name + */ + void settingsChangedSlot(); + +private: + /** + * Internal function with common addPage code. + */ + void addPageInternal(TQWidget *page, const TQString &itemName, + const TQString &pixmapName, const TQString &header); + + /** + * Sets the connections from a manager to the dialog (and the other + * way round) up. + */ + void setupManagerConnections(KConfigDialogManager *manager); + +private: + /** + * The list of existing dialogs. + */ + static TQAsciiDict<KConfigDialog> openDialogs; + + class KConfigDialogPrivate; + /** + * Private class. + */ + KConfigDialogPrivate *d; +}; + +#endif //KCONFIGDIALOG_H + |