File indexing completed on 2024-12-08 11:01:32

0001 /*
0002  *   SPDX-FileCopyrightText: 2009 Ben Cooksley <bcooksley@kde.org>
0003  *   SPDX-FileCopyrightText: 2009 Mathias Soeken <msoeken@informatik.uni-bremen.de>
0004  *
0005  *   SPDX-License-Identifier: GPL-2.0-or-later
0006  */
0007 
0008 #ifndef MODULE_VIEW_H
0009 #define MODULE_VIEW_H
0010 
0011 #include <KPageView>
0012 #include <QModelIndex>
0013 #include <QWidget>
0014 
0015 #include "systemsettingsview_export.h"
0016 
0017 class KCModuleInfo;
0018 class KCModuleProxy;
0019 class KPageWidgetItem;
0020 class KPluginMetaData;
0021 class MenuItem;
0022 
0023 /**
0024  * @brief Provides a convenient way to display modules
0025  *
0026  * Provides a standardised interface for displaying multiple modules simultaneously
0027  * and provides facilities to access the current module, and to load its help, restore
0028  * default settings, save new settings and revert changes to settings
0029  *
0030  * It also provides checking for when a module has changed its configuration, and will prompt
0031  * if the user tries to change module or view if BaseMode is reimplemented correctly
0032  *
0033  * It also provides signals for active module changes, configuration changes and for when it has
0034  * been requested to close by button press
0035  *
0036  * @author Mathias Soeken <msoeken@informatik.uni-bremen.de>
0037  * @author Ben Cooksley <bcooksley@kde.org>
0038  */
0039 class SYSTEMSETTINGSVIEW_EXPORT ModuleView : public QWidget
0040 {
0041     Q_OBJECT
0042 
0043 public:
0044     /**
0045      * Constructs a ModuleView, with the parent specified.
0046      */
0047     explicit ModuleView(QWidget *parent = nullptr);
0048 
0049     /**
0050      * Destroys the module view, along with all modules loaded, and any changes present in them.
0051      *
0052      * @warning The user will not be prompted to save changes if any exist.
0053      */
0054     ~ModuleView() override;
0055 
0056     /**
0057      * Provides the module information, which is used to set the caption of the window when either the
0058      * active module or configuration changes.
0059      */
0060     QString activeModuleName() const;
0061 
0062     /**
0063      * Resolves any changes in the currently active module by prompting the user if they exist.
0064      *
0065      * @returns true if the user saved or discarded changes, or there were no changes at all.
0066      * @returns false if the user canceled the module change.
0067      */
0068     bool resolveChanges();
0069 
0070     /**
0071      * Closes all active modules, after checking there are no active changes.
0072      *
0073      * @warning This forces all modules to be destroyed regardless of if changes exist or not
0074      * If possible, always check with resolveChanges() first.
0075      */
0076     void closeModules();
0077 
0078     void setFaceType(KPageView::FaceType type);
0079 
0080     KPageView::FaceType faceType() const;
0081 
0082     /**
0083      * Sets whether Systemsettings should save statisctics about
0084      * most used modules using KActivities::Stats
0085      */
0086     void setSaveStatistics(bool save);
0087 
0088     /**
0089      * @returns whether Systemsettings should save statisctics about
0090      * most used module
0091      */
0092     bool saveStatistics() const;
0093 
0094     /**
0095      * Shows or hides the Apply button.
0096      */
0097     void setApplyVisible(bool visible);
0098 
0099     /**
0100      * @returns True if the Apply button is visible.
0101      */
0102     bool isApplyVisible() const;
0103 
0104     /**
0105      * Shows or hides the Defaults button.
0106      */
0107     void setDefaultsVisible(bool visible);
0108 
0109     /**
0110      * @returns True if the Defaults button is visible.
0111      */
0112     bool isDefaultsVisible() const;
0113 
0114     /**
0115      * @returns True if the Reset button is visible.
0116      */
0117     bool isResetVisible() const;
0118 
0119     /**
0120      * Show or hide defaults indicators (field level)
0121      */
0122     void moduleShowDefaultsIndicators(bool show);
0123 
0124     qreal headerHeight() const;
0125     void setHeaderHeight(qreal height);
0126 
0127     void setActiveModule(const QString &moduleName);
0128 
0129     /**
0130      * The active module's KPluginMetaData.
0131      */
0132     KPluginMetaData activeModuleMetadata() const;
0133 
0134 public Q_SLOTS:
0135     /**
0136      * Loads the module specified by menuItem.\n
0137      * If the module has children, they will all be loaded instead of the module.
0138      *
0139      * @param menuItem the QModelIndex that you want to load. Must be sourced from either MenuModel or MenuProxyModel
0140      */
0141     void loadModule(const QModelIndex &menuItem, const QStringList &args);
0142 
0143     /**
0144      * Will open KHelpCenter, and load the help for the active module.
0145      */
0146     void moduleHelp();
0147 
0148     /**
0149      * Causes the active module to reload its configuration, reverting all changes.
0150      */
0151     void moduleLoad();
0152 
0153     /**
0154      * Causes the active module to save its configuration, applying all changes.
0155      */
0156     bool moduleSave();
0157 
0158     /**
0159      * Causes the active module to revert all changes to the configuration, and return to defaults.
0160      */
0161     void moduleDefaults();
0162 
0163     /**
0164      * Reimplemented for internal reasons.\n
0165      */
0166     void keyPressEvent(QKeyEvent *event) override;
0167 
0168 private:
0169     bool resolveChanges(KCModuleProxy *currentProxy);
0170     void addModule(MenuItem *item, const QStringList &args);
0171     bool moduleSave(KCModuleProxy *module);
0172     void updatePageIconHeader(KPageWidgetItem *page);
0173     void updateButtons();
0174 
0175 private Q_SLOTS:
0176     void activeModuleChanged(KPageWidgetItem *current, KPageWidgetItem *previous);
0177     void stateChanged();
0178 
0179 Q_SIGNALS:
0180     /**
0181      * Emitted when the currently active module is changed. This occurs whenever the active module or
0182      * its configuration changes. This causes the window caption to update.
0183      */
0184     void moduleChanged(bool state);
0185 
0186     /**
0187      * Emitted after the currently active module was saved.
0188      */
0189     void moduleSaved();
0190 
0191     /**
0192      * Emitted when the ModuleView is asked to close.\n
0193      */
0194     void closeRequest();
0195 
0196     /**
0197      * Emitted when showDefaultsIndicators state changed
0198      */
0199     void showDefaultsIndicatorsChanged(bool show);
0200 
0201 private:
0202     class Private;
0203     Private *const d;
0204 };
0205 
0206 #endif