File indexing completed on 2024-05-12 03:54:10

 /*
     SPDX-FileCopyrightText: 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
     SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnau@gmx.de>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KCMODULE_H
 #define KCMODULE_H
 
 #include "kcmutils_export.h"
 #include <KAbstractConfigModule>
 #include <KPluginMetaData>
 
 #include <QVariant>
 #include <QWidget>
 #include <memory>
 
 class KConfigDialogManager;
 class KCoreConfigSkeleton;
 class KConfigSkeleton;
 class KCModulePrivate;
 
 /**
  * @class KCModule kcmodule.h KCModule
  *
  * The base class for QWidgets configuration modules.
  * Configuration modules are loaded as plugins.
  *
  * The module in principle is a simple widget displaying the
  * item to be changed. The module has a very small interface.
  *
  * To write a config module, you have to create a library
  * that contains a factory class like the following:
  *
  * \code
  * #include <KPluginFactory>
  *
  * K_PLUGIN_CLASS_WITH_JSON(MyKCModule, "mykcmodule.json")
  * \endcode
  *
  * The constructor of the KCModule then looks like this:
  * \code
  * YourKCModule::YourKCModule(QWidget *parent, const KPluginMetaData &data)
  *   : KCModule(parent, data)
  * {
  * // KCModule does not directly extend QWidget due to ambiguity with KAbstractConfigModule
  * // Because of this, you need to call widget() to get the parent widget
  * auto label = new QLabel(widget());
  * label->setText(QStringLiteral("Demo Text"));
  * }
  * \endcode
  *
  * This KCM can be loaded in a KCMultiDialog of kcmshell6
  *
  * @since 6.0
  */
 class KCMUTILS_EXPORT KCModule : public KAbstractConfigModule
 {
     Q_OBJECT
 
 public:
     /**
      * Base class for all QWidgets configuration modules.
      *
      * @note do not emit changed signals here, since they are not yet connected
      *       to any slot.
      */
     explicit KCModule(QWidget *parent, const KPluginMetaData &data);
 
     /**
      * Destroys the module.
      */
     ~KCModule() override;
 
     /**
      * @return a list of @ref KConfigDialogManager's in use, if any.
      */
     QList<KConfigDialogManager *> configs() const;
 
     void load() override;
     void save() override;
     void defaults() override;
 
     /**
      * Utility function that marks the KCM as changed
      */
     void markAsChanged()
     {
         setNeedsSave(true);
     }
 
     /**
      * Get the associated widget that can be embedded
      * The returned widget should be used as a parent for widgets you create
      *
      * @note Overwriting this function should not be necessary for consumers!
      */
     virtual QWidget *widget();
 
 protected:
     /**
      * Adds a KCoreConfigskeleton @p config to watch the widget @p widget
      *
      * This function is useful if you need to handle multiple configuration files.
      *
      * @return a pointer to the KCoreConfigDialogManager in use
      * @param config the KCoreConfigSkeleton to use
      * @param widget the widget to watch
      */
     KConfigDialogManager *addConfig(KCoreConfigSkeleton *config, QWidget *widget);
 
 protected Q_SLOTS:
     /**
      * A managed widget was changed, the widget settings and the current
      * settings are compared and a corresponding needsSaveChanged() signal is emitted
      */
     void widgetChanged();
 
 protected:
     /**
      * Returns the changed state of automatically managed widgets in this dialog
      */
     bool managedWidgetChangeState() const;
 
     /**
      * Returns the defaulted state of automatically managed widgets in this dialog
      */
     bool managedWidgetDefaultState() const;
 
     /**
      * Call this method when your manually managed widgets change state between
      * changed and not changed
      */
     void unmanagedWidgetChangeState(bool);
 
     /**
      * Call this method when your manually managed widgets change state between
      * defaulted and not defaulted
      */
     void unmanagedWidgetDefaultState(bool);
 
     /**
      * Utility overload to avoid having to take both parent and parentWidget
      * KCModuleLoader::loadModule enforces the parent to be a QWidget anyway
      */
     explicit KCModule(QObject *parent, const KPluginMetaData &data)
         : KCModule(qobject_cast<QWidget *>(parent), data)
     {
     }
 
     /**
      * Utility constructor for creating a KCModule that is embedded, for example in a KPluginWidget
      * This constructor should not be used for KCMs that are part launched in systemsettings!
      *
      * @note do not emit changed signals here, since they are not yet connected
      *       to any slot.
      */
     explicit KCModule(QObject *parent)
         : KCModule(qobject_cast<QWidget *>(parent), KPluginMetaData{})
     {
     }
 
 private:
     std::unique_ptr<KCModulePrivate> const d;
 };
 
 #endif // KCMODULE_H