File indexing completed on 2024-06-09 05:32:54

0001 /*
0002  *   SPDX-FileCopyrightText: 2009 Ben Cooksley <bcooksley@kde.org>
0003  *
0004  *   SPDX-License-Identifier: GPL-2.0-or-later
0005  */
0006 
0007 #ifndef BASEMODE_H
0008 #define BASEMODE_H
0009 
0010 #include <QObject>
0011 
0012 #include <KPluginMetaData>
0013 
0014 #include "systemsettingsview_export.h"
0015 
0016 class QAction;
0017 class MenuItem;
0018 class ModuleView;
0019 class KAboutData;
0020 class KConfigDialog;
0021 class KConfigGroup;
0022 class QAbstractItemView;
0023 template<typename T> class QList;
0024 
0025 /**
0026  * @brief Provides a interface for System Settings views
0027  *
0028  * BaseMode is a standard interface for all plugins to System Settings to allow them to provide
0029  * their own interface to KDE control modules.\n
0030  *
0031  * The developer need only ensure that they perform all initialization of their plugin in
0032  * initEvent() to ensure that the plugin is displayed, and initial actions are loaded.
0033  *
0034  * @author Ben Cooksley <bcooksley@kde.org>
0035  * @author Mathias Soeken <msoeken@informatik.uni-bremen.de>
0036  */
0037 class SYSTEMSETTINGSVIEW_EXPORT BaseMode : public QObject
0038 {
0039     Q_OBJECT
0040 
0041     Q_PROPERTY(ApplicationMode applicationMode READ applicationMode CONSTANT)
0042 
0043     /**
0044      * System Settings main application is allowed privileged access to handle tooltips
0045      */
0046     friend class SettingsBase;
0047 
0048 public:
0049     // Main mode of the app.
0050     // At the moment SystemSettings and InfoCenter are supported:
0051     // Changes mainly the set of module listed on the left menu
0052     enum ApplicationMode {
0053         SystemSettings = 0,
0054         InfoCenter,
0055     };
0056     Q_ENUM(ApplicationMode)
0057 
0058     virtual bool defaultsIndicatorsVisible() const;
0059     virtual void toggleDefaultsIndicatorsVisibility();
0060 
0061     void init();
0062 
0063     /**
0064      * Constructs a BaseMode for use in System Settings.\n
0065      * Plugin developers should perform all initialisation in initEvent() not here.
0066      *
0067      * @param parent The parent of this BaseMode.
0068      */
0069     explicit BaseMode(QObject *parent, const QVariantList &args);
0070     /**
0071      * Normal destructor. Plugin developers only need destroy what they created
0072      * not what is provided by BaseMode itself.
0073      */
0074     ~BaseMode() override;
0075 
0076     /**
0077      * These flags are used to control the presence of the Search and Configure actions on the toolbar
0078      */
0079     enum ToolBarItemsFlags {
0080         NoItems = 0x1, /**< The Toolbar will not have any items added by System Settings */
0081         Search = 0x2, /**< The Toolbar will have the search bar added by System Settings */
0082         Configure = 0x4, /**< The Toolbar will have configure added by System Settings */
0083         Quit = 0x8, /**< The toolbar will have exit added by System Settings */
0084     };
0085     Q_DECLARE_FLAGS(ToolBarItems, ToolBarItemsFlags)
0086 
0087     /**
0088      * Performs internal setup.\n
0089      * Plugin developers should perform initialisation in initEvent() not here.
0090      *
0091      * @param modeService Plugins service object, used for providing extra information to System Settings.
0092      */
0093     void init(const KPluginMetaData &metaData);
0094 
0095     /**
0096      * Prepares the BaseMode for use.\n
0097      * Plugin developers should perform initialisation here, creating the Models. They should perform widget
0098      * initialisation the first time mainWidget() is called, not here.
0099      */
0100     virtual void initEvent();
0101 
0102     /**
0103      * Returns the widget to be displayed in the center of System Settings.\n
0104      * The widget should be created the first time this function is called.
0105      *
0106      * @warning This function is called multiple times, ensure the widget is only created once.
0107      * @returns The main widget of the plugin.
0108      */
0109     virtual QWidget *mainWidget();
0110 
0111     /**
0112      * @returns the application mode of this systemsettings process: SystemSettings or InfoCenter
0113      */
0114     ApplicationMode applicationMode() const;
0115 
0116     /**
0117      * The state of the plugin ( position of the splitter for instance ) should be saved
0118      * to the configuration object when this is called.
0119      */
0120     virtual void saveState();
0121 
0122     /**
0123      * Used to give focus to the plugin. Plugin should call setFocus() on the appropriate widget
0124      *
0125      * @note Failure to reimplement will cause keyboard accessibility and widget focusing problems
0126      */
0127     virtual void giveFocus();
0128 
0129     /**
0130      * Provides access to the ModuleView the application uses to display control modules.\n
0131      *
0132      * @warning Failure to reimplement will cause modules not to be checked for configuration
0133      * changes, and for the module to not be displayed in the About dialog. It must be implemented.
0134      * @returns The ModuleView used by the plugin for handling modules.
0135      */
0136     virtual ModuleView *moduleView() const;
0137 
0138     /**
0139      * Provides the list of actions the plugin wants System Settings to display in the toolbar when
0140      * it is loaded. This function does not need to be implemented if adding actions to the toolbar
0141      * is not required.
0142      *
0143      * @returns The list of actions the plugin provides.
0144      */
0145     virtual QList<QAction *> &actionsList() const;
0146 
0147     const KPluginMetaData &metaData() const;
0148 
0149     void setStartupModule(const QString &startupModule);
0150     QString startupModule() const;
0151 
0152     void setStartupModuleArgs(const QStringList &startupModuleArgs);
0153     QStringList startupModuleArgs() const;
0154 
0155     virtual void reloadStartupModule() = 0;
0156 
0157 public Q_SLOTS:
0158     /**
0159      * Called when the text in the search box changes allowing the display to be filtered.
0160      *
0161      * @warning Search will not work in the view if this function is not implemented.
0162      */
0163     virtual void searchChanged(const QString &text);
0164 
0165     /**
0166      * Allows views to add custom configuration pages to the System Settings configure dialog
0167      *
0168      * @warning Deleting the config object will cause System Settings to crash
0169      */
0170     virtual void addConfiguration(KConfigDialog *config);
0171 
0172     /**
0173      * Allows views to load their configuration before the configuration dialog is shown
0174      * Views should revert any changes that have not been saved
0175      */
0176     virtual void loadConfiguration();
0177 
0178     /**
0179      * Should be implemented to ensure that views settings are saved when the user confirms their changes
0180      * Views should also apply the configuration at the same time
0181      */
0182     virtual void saveConfiguration();
0183 
0184 Q_SIGNALS:
0185     /**
0186      * Triggers a reload of the views actions by the host application.
0187      *
0188      * @warning Actions previously contained in the list must not be destroyed before this has been emitted.
0189      */
0190     void actionsChanged();
0191 
0192     /**
0193      * Should be emitted when the type ( list of modules / display of module )
0194      * of displayed view is changed.
0195      *
0196      * @param state Determines whether changes have been made in the view.
0197      * @warning Failure to Q_EMIT this will result in inconsistent application headers and change state.
0198      */
0199     void viewChanged(bool state);
0200 
0201     /**
0202      * Causes System Settings to hide / show the toolbar items specified.
0203      * This is used to control the display of the Configure and Search actions
0204      *
0205      * @param items The items that are wanted in the toolbar
0206      */
0207     void changeToolBarItems(BaseMode::ToolBarItems items);
0208 
0209 protected:
0210     /**
0211      * Returns the root item of the list of categorised modules.
0212      * This is usually passed to the constructor of MenuModel.
0213      *
0214      * @warning This is shared between all views, and should not be deleted manually.
0215      * @returns The root menu item as provided by System Settings.
0216      */
0217     MenuItem *rootItem() const;
0218 
0219     /**
0220      * Returns (if present) an item that corresponds to a KCM which should be used as startup page.
0221      *
0222      * @warning This is shared between all views, and should not be deleted manually.
0223      * @returns The item to load as startup page. It may be nullptr
0224      */
0225     MenuItem *homeItem() const;
0226 
0227     /**
0228      * Provides access to the configuration for the plugin.
0229      *
0230      * @returns The configuration group for the plugin.
0231      */
0232     KConfigGroup &config() const;
0233 
0234     /**
0235      * Provides access to item views used by the plugin.
0236      * This is currently used to show the enhanced tooltips.
0237      *
0238      * @returns A list of pointers to item views used by the mode.
0239      *          The list can be empty.
0240      */
0241     virtual QList<QAbstractItemView *> views() const;
0242 
0243 private:
0244     class Private;
0245     Private *const d;
0246 };
0247 
0248 Q_DECLARE_OPERATORS_FOR_FLAGS(BaseMode::ToolBarItems)
0249 
0250 #endif