vasilito
cf12defd28
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
255 lines
9.0 KiB
C++
255 lines
9.0 KiB
C++
/*
|
|
This file is part of the KDE libraries
|
|
SPDX-FileCopyrightText: 2003 Benjamin C Meyer <ben+kdelibs at meyerhome dot net>
|
|
SPDX-FileCopyrightText: 2003 Waldo Bastian <bastian@kde.org>
|
|
|
|
SPDX-License-Identifier: LGPL-2.0-or-later
|
|
*/
|
|
|
|
#ifndef KCONFIGDIALOG_H
|
|
#define KCONFIGDIALOG_H
|
|
|
|
#include <KPageDialog>
|
|
#include <memory>
|
|
|
|
#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 <bastian@kde.org>
|
|
*/
|
|
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<class KConfigDialogPrivate> const d;
|
|
|
|
Q_DISABLE_COPY(KConfigDialog)
|
|
};
|
|
|
|
#endif // KCONFIGDIALOG_H
|