/* This file is part of the KDE libraries SPDX-FileCopyrightText: 2003 Benjamin C Meyer SPDX-FileCopyrightText: 2003 Waldo Bastian SPDX-License-Identifier: LGPL-2.0-or-later */ #ifndef KCONFIGDIALOG_H #define KCONFIGDIALOG_H #include #include #include "kconfigwidgets_export.h" class KConfig; class KCoreConfigSkeleton; class KConfigDialogManager; /** * @class KConfigDialog kconfigdialog.h KConfigDialog * * \short Standard %KDE configuration dialog class * * The KConfigDialog class provides an easy and uniform means of displaying * a settings dialog using KPageDialog, 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, resetting 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(QStringLiteral("settings"))) { * return; * } * KConfigDialog *dialog = new KConfigDialog(this, QStringLiteral("settings"), MySettings::self()); * dialog->setFaceType(KPageDialog::List); * dialog->addPage(new General(0, "General"), i18n("General")); * dialog->addPage(new Appearance(0, "Style"), i18n("Appearance")); * connect(dialog, &KConfigDialog::settingsChanged, mainWidget, &Bar::loadSettings); * connect(dialog, &KConfigDialog::settingsChanged, this, &Foo::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. * * For dialog appearance options (like buttons, default button, ...) please see * @ref KPageDialog. * * @see KConfigSkeleton * @author Waldo Bastian */ class KCONFIGWIDGETS_EXPORT KConfigDialog : public KPageDialog { Q_OBJECT Q_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. * @param dialogName the name of the dialog. */ void settingsChanged(const QString &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 config - Config object containing settings. */ KConfigDialog(QWidget *parent, const QString &name, KCoreConfigSkeleton *config); /** * Deconstructor, removes name from the list of open dialogs. * Deletes private class. * @see exists() */ ~KConfigDialog() override; /** * Adds page to the dialog and to KConfigDialogManager. When an * application is done adding pages show() should be called to * display 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 icon that should be used, if needed, when * displaying the page. The string may either be the name of a themed * icon (e.g. "document-save"), which the internal icon loader will be * used to retrieve, or an absolute path to the pixmap on disk. * @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. * @returns The KPageWidgetItem associated with the page. */ KPageWidgetItem * addPage(QWidget *page, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString(), 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. * @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 icon that should be used, if needed, when * displaying the page. The string may either be the name of a themed * icon (e.g. "document-save"), which the internal icon loader will be * used to retrieve, or an absolute path to the pixmap on disk. * @param header - Header text use in the list modes. Ignored in Tabbed * mode. If empty, the itemName text is used when needed. * @returns The KPageWidgetItem associated with the page. */ KPageWidgetItem * addPage(QWidget *page, KCoreConfigSkeleton *config, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString()); /** * 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 QString &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 QString &name); protected Q_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(); /** * Updates the Apply and Default buttons. * Connect to this slot if you implement your own hasChanged() * or isDefault() methods for widgets not managed by KConfig. * @since 4.3 */ void updateButtons(); /** * Some setting was changed. Emit the signal with the dialogs name. * Connect to this slot if there are widgets not managed by KConfig. * @since 4.3 */ void settingsChangedSlot(); /** * Sets the help path and topic. * * The HTML file will be found using the X-DocPath entry in the application's desktop file. * It can be either a relative path, or a website URL. * * @param anchor This has to be a defined anchor in your * docbook sources or website. If empty the main index * is loaded. * @param appname This allows you to specify the .desktop file to get the help path from. * If empty the QCoreApplication::applicationName() is used. */ void setHelp(const QString &anchor, const QString &appname = QString()); /** * Displays help for this config dialog. * @since 5.0 */ virtual void showHelp(); protected: /** * Returns whether the current state of the dialog is * different from the current configuration. * Virtual function for custom additions. */ virtual bool hasChanged(); /** * Returns whether the current state of the dialog is * the same as the default configuration. */ virtual bool isDefault(); /** * @internal */ void showEvent(QShowEvent *e) override; private Q_SLOTS: /** * Slot which cleans up the KConfigDialogManager of the page. * */ KCONFIGWIDGETS_NO_EXPORT void onPageRemoved(KPageWidgetItem *item); private: friend class KConfigDialogPrivate; std::unique_ptr const d; Q_DISABLE_COPY(KConfigDialog) }; #endif // KCONFIGDIALOG_H