File indexing completed on 2024-03-03 04:01:18

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2003 Benjamin C Meyer <ben+kdelibs at meyerhome dot net>
0004     SPDX-FileCopyrightText: 2003 Waldo Bastian <bastian@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KCONFIGDIALOG_H
0010 #define KCONFIGDIALOG_H
0011 
0012 #include <KPageDialog>
0013 #include <memory>
0014 
0015 #include "kconfigwidgets_export.h"
0016 
0017 class KConfig;
0018 class KCoreConfigSkeleton;
0019 class KConfigDialogManager;
0020 
0021 /**
0022  * @class KConfigDialog kconfigdialog.h KConfigDialog
0023  *
0024  * \short Standard %KDE configuration dialog class
0025  *
0026  * The KConfigDialog class provides an easy and uniform means of displaying
0027  * a settings dialog using KPageDialog, KConfigDialogManager and a
0028  * KConfigSkeleton derived settings class.
0029  *
0030  * KConfigDialog handles the enabling and disabling of buttons, creation
0031  * of the dialog, and deletion of the widgets.  Because of
0032  * KConfigDialogManager, this class also manages: restoring
0033  * the settings, resetting them to the default values, and saving them. This
0034  * requires that the names of the widgets corresponding to configuration entries
0035  * have to have the same name plus an additional "kcfg_" prefix. For example the
0036  * widget named "kcfg_MyOption" would be associated with the configuration entry
0037  * "MyOption".
0038  *
0039  * Here is an example usage of KConfigDialog:
0040  *
0041  * @code
0042  * void KCoolApp::showSettings(){
0043  *     if (KConfigDialog::showDialog(QStringLiteral("settings"))) {
0044  *       return;
0045  *     }
0046  *     KConfigDialog *dialog = new KConfigDialog(this, QStringLiteral("settings"), MySettings::self());
0047  *     dialog->setFaceType(KPageDialog::List);
0048  *     dialog->addPage(new General(0, "General"), i18n("General"));
0049  *     dialog->addPage(new Appearance(0, "Style"), i18n("Appearance"));
0050  *     connect(dialog, &KConfigDialog::settingsChanged, mainWidget, &Bar::loadSettings);
0051  *     connect(dialog, &KConfigDialog::settingsChanged, this, &Foo::loadSettings);
0052  *     dialog->show();
0053  * }
0054  * @endcode
0055  *
0056  * Other than the above code, each class that has settings in the dialog should
0057  * have a loadSettings() type slot to read settings and perform any
0058  * necessary changes.
0059  *
0060  * For dialog appearance options (like buttons, default button, ...) please see
0061  * @ref KPageDialog.
0062  *
0063  * @see KConfigSkeleton
0064  * @author Waldo Bastian <bastian@kde.org>
0065  */
0066 class KCONFIGWIDGETS_EXPORT KConfigDialog : public KPageDialog
0067 {
0068     Q_OBJECT
0069 
0070 Q_SIGNALS:
0071     /**
0072      * A widget in the dialog was modified.
0073      */
0074     void widgetModified();
0075 
0076     /**
0077      * One or more of the settings have been permanently changed such as if
0078      * the user clicked on the Apply or Ok button.
0079      * @param dialogName the name of the dialog.
0080      */
0081     void settingsChanged(const QString &dialogName);
0082 
0083 public:
0084     /**
0085      * @param parent - The parent of this object.  Even though the class
0086      * deletes itself the parent should be set so the dialog can be centered
0087      * with the application on the screen.
0088      *
0089      * @param name - The name of this object.  The name is used in determining if
0090      * there can be more than one dialog at a time.  Use names such as:
0091      * "Font Settings" or "Color Settings" and not just "Settings" in
0092      * applications where there is more than one dialog.
0093      *
0094      * @param config - Config object containing settings.
0095      */
0096     KConfigDialog(QWidget *parent, const QString &name, KCoreConfigSkeleton *config);
0097 
0098     /**
0099      * Deconstructor, removes name from the list of open dialogs.
0100      * Deletes private class.
0101      * @see exists()
0102      */
0103     ~KConfigDialog() override;
0104 
0105     /**
0106      * Adds page to the dialog and to KConfigDialogManager.  When an
0107      * application is done adding pages show() should be called to
0108      * display the dialog.
0109      * @param page - Pointer to the page that is to be added to the dialog.
0110      * This object is reparented.
0111      * @param itemName - Name of the page.
0112      * @param pixmapName - Name of the icon that should be used, if needed, when
0113      *        displaying the page. The string may either be the name of a themed
0114      *        icon (e.g. "document-save"), which the internal icon loader will be
0115      *        used to retrieve, or an absolute path to the pixmap on disk.
0116      * @param header - Header text use in the list modes. Ignored in Tabbed
0117      *        mode. If empty, the itemName text is used when needed.
0118      * @param manage - Whether KConfigDialogManager should manage the page or not.
0119      * @returns The KPageWidgetItem associated with the page.
0120      */
0121     KPageWidgetItem *
0122     addPage(QWidget *page, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString(), bool manage = true);
0123 
0124     /**
0125      * Adds page to the dialog that is managed by a custom KConfigDialogManager.
0126      * This is useful for dialogs that contain settings spread over more than
0127      * one configuration file and thus have/need more than one KConfigSkeleton.
0128      * When an application is done adding pages show() should be called to
0129      * display the dialog.
0130      * @param page - Pointer to the page that is to be added to the dialog.
0131      * This object is reparented.
0132      * @param config - Config object containing corresponding settings.
0133      * @param itemName - Name of the page.
0134      * @param pixmapName - Name of the icon that should be used, if needed, when
0135      *        displaying the page. The string may either be the name of a themed
0136      *        icon (e.g. "document-save"), which the internal icon loader will be
0137      *        used to retrieve, or an absolute path to the pixmap on disk.
0138      * @param header - Header text use in the list modes. Ignored in Tabbed
0139      *        mode. If empty, the itemName text is used when needed.
0140      * @returns The KPageWidgetItem associated with the page.
0141      */
0142     KPageWidgetItem *
0143     addPage(QWidget *page, KCoreConfigSkeleton *config, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString());
0144 
0145     /**
0146      * See if a dialog with the name 'name' already exists.
0147      * @see showDialog()
0148      * @param name - Dialog name to look for.
0149      * @return Pointer to widget or NULL if it does not exist.
0150      */
0151     static KConfigDialog *exists(const QString &name);
0152 
0153     /**
0154      * Attempts to show the dialog with the name 'name'.
0155      * @see exists()
0156      * @param name - The name of the dialog to show.
0157      * @return True if the dialog 'name' exists and was shown.
0158      */
0159     static bool showDialog(const QString &name);
0160 
0161 protected Q_SLOTS:
0162     /**
0163      * Update the settings from the dialog.
0164      * Virtual function for custom additions.
0165      *
0166      * Example use: User clicks Ok or Apply button in a configure dialog.
0167      */
0168     virtual void updateSettings();
0169 
0170     /**
0171      * Update the dialog based on the settings.
0172      * Virtual function for custom additions.
0173      *
0174      * Example use: Initialisation of dialog.
0175      * Example use: User clicks Reset button in a configure dialog.
0176      */
0177     virtual void updateWidgets();
0178 
0179     /**
0180      * Update the dialog based on the default settings.
0181      * Virtual function for custom additions.
0182      *
0183      * Example use: User clicks Defaults button in a configure dialog.
0184      */
0185     virtual void updateWidgetsDefault();
0186 
0187     /**
0188      * Updates the Apply and Default buttons.
0189      * Connect to this slot if you implement your own hasChanged()
0190      * or isDefault() methods for widgets not managed by KConfig.
0191      * @since 4.3
0192      */
0193     void updateButtons();
0194 
0195     /**
0196      * Some setting was changed. Emit the signal with the dialogs name.
0197      * Connect to this slot if there are widgets not managed by KConfig.
0198      * @since 4.3
0199      */
0200     void settingsChangedSlot();
0201 
0202     /**
0203      * Sets the help path and topic.
0204      *
0205      * The HTML file will be found using the X-DocPath entry in the application's desktop file.
0206      * It can be either a relative path, or a website URL.
0207      *
0208      * @param anchor      This has to be a defined anchor in your
0209      *                    docbook sources or website. If empty the main index
0210      *                    is loaded.
0211      * @param appname     This allows you to specify the .desktop file to get the help path from.
0212      *                    If empty the QCoreApplication::applicationName() is used.
0213      */
0214     void setHelp(const QString &anchor, const QString &appname = QString());
0215 
0216     /**
0217      * Displays help for this config dialog.
0218      * @since 5.0
0219      */
0220     virtual void showHelp();
0221 
0222 protected:
0223     /**
0224      * Returns whether the current state of the dialog is
0225      * different from the current configuration.
0226      * Virtual function for custom additions.
0227      */
0228     virtual bool hasChanged();
0229 
0230     /**
0231      * Returns whether the current state of the dialog is
0232      * the same as the default configuration.
0233      */
0234     virtual bool isDefault();
0235 
0236     /**
0237      * @internal
0238      */
0239     void showEvent(QShowEvent *e) override;
0240 
0241 private Q_SLOTS:
0242     /**
0243      * Slot which cleans up the KConfigDialogManager of the page.
0244      * */
0245     KCONFIGWIDGETS_NO_EXPORT void onPageRemoved(KPageWidgetItem *item);
0246 
0247 private:
0248     friend class KConfigDialogPrivate;
0249     std::unique_ptr<class KConfigDialogPrivate> const d;
0250 
0251     Q_DISABLE_COPY(KConfigDialog)
0252 };
0253 
0254 #endif // KCONFIGDIALOG_H