Warning, file /plasma/systemsettings/core/BaseMode.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

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     /**
0062      * Constructs a BaseMode for use in System Settings.\n
0063      * Plugin developers should perform all initialisation in initEvent() not here.
0064      *
0065      * @param parent The parent of this BaseMode.
0066      */
0067     explicit BaseMode(QObject *parent, const QVariantList &args);
0068     /**
0069      * Normal destructor. Plugin developers only need destroy what they created
0070      * not what is provided by BaseMode itself.
0071      */
0072     ~BaseMode() override;
0073 
0074     /**
0075      * These flags are used to control the presence of the Search and Configure actions on the toolbar
0076      */
0077     enum ToolBarItemsFlags {
0078         NoItems = 0x1, /**< The Toolbar will not have any items added by System Settings */
0079         Search = 0x2, /**< The Toolbar will have the search bar added by System Settings */
0080         Configure = 0x4, /**< The Toolbar will have configure added by System Settings */
0081         Quit = 0x8, /**< The toolbar will have exit added by System Settings */
0082     };
0083     Q_DECLARE_FLAGS(ToolBarItems, ToolBarItemsFlags)
0084 
0085     /**
0086      * Performs internal setup.\n
0087      * Plugin developers should perform initialisation in initEvent() not here.
0088      *
0089      * @param modeService Plugins service object, used for providing extra information to System Settings.
0090      */
0091     void init(const KPluginMetaData &metaData);
0092 
0093     /**
0094      * Prepares the BaseMode for use.\n
0095      * Plugin developers should perform initialisation here, creating the Models. They should perform widget
0096      * initialisation the first time mainWidget() is called, not here.
0097      */
0098     virtual void initEvent();
0099 
0100     /**
0101      * Returns the widget to be displayed in the center of System Settings.\n
0102      * The widget should be created the first time this function is called.
0103      *
0104      * @warning This function is called multiple times, ensure the widget is only created once.
0105      * @returns The main widget of the plugin.
0106      */
0107     virtual QWidget *mainWidget();
0108 
0109     /**
0110      * Provides information about the plugin, which is used in the About dialog of System Settings.\n
0111      * This does not need to be implemented, and need only be implemented if the author
0112      * wants information about the view displayed in the About dialog.
0113      *
0114      * @returns The about data of the plugin.
0115      */
0116     virtual KAboutData *aboutData();
0117 
0118     /**
0119      * @returns the application mode of this systemsettings process: SystemSettings or InfoCenter
0120      */
0121     ApplicationMode applicationMode() const;
0122 
0123     /**
0124      * The state of the plugin ( position of the splitter for instance ) should be saved
0125      * to the configuration object when this is called.
0126      */
0127     virtual void saveState();
0128 
0129     /**
0130      * Causes the view to unload all modules in the module view, and return to their module selection state
0131      *
0132      * @warning Failure to reimplement will cause modules to not be unloaded when changing views.
0133      * This must be implemented.
0134      */
0135     virtual void leaveModuleView();
0136 
0137     /**
0138      * Used to give focus to the plugin. Plugin should call setFocus() on the appropriate widget
0139      *
0140      * @note Failure to reimplement will cause keyboard accessibility and widget focusing problems
0141      */
0142     virtual void giveFocus();
0143 
0144     /**
0145      * Provides access to the ModuleView the application uses to display control modules.\n
0146      *
0147      * @warning Failure to reimplement will cause modules not to be checked for configuration
0148      * changes, and for the module to not be displayed in the About dialog. It must be implemented.
0149      * @returns The ModuleView used by the plugin for handling modules.
0150      */
0151     virtual ModuleView *moduleView() const;
0152 
0153     /**
0154      * Provides the list of actions the plugin wants System Settings to display in the toolbar when
0155      * it is loaded. This function does not need to be implemented if adding actions to the toolbar
0156      * is not required.
0157      *
0158      * @returns The list of actions the plugin provides.
0159      */
0160     virtual QList<QAction *> &actionsList() const;
0161 
0162     const KPluginMetaData &metaData() const;
0163 
0164     void setStartupModule(const QString &startupModule);
0165     QString startupModule() const;
0166 
0167     void setStartupModuleArgs(const QStringList &startupModuleArgs);
0168     QStringList startupModuleArgs() const;
0169 
0170     virtual void reloadStartupModule() = 0;
0171 
0172 public Q_SLOTS:
0173     /**
0174      * Called when the text in the search box changes allowing the display to be filtered.
0175      *
0176      * @warning Search will not work in the view if this function is not implemented.
0177      */
0178     virtual void searchChanged(const QString &text);
0179 
0180     /**
0181      * Allows views to add custom configuration pages to the System Settings configure dialog
0182      *
0183      * @warning Deleting the config object will cause System Settings to crash
0184      */
0185     virtual void addConfiguration(KConfigDialog *config);
0186 
0187     /**
0188      * Allows views to load their configuration before the configuration dialog is shown
0189      * Views should revert any changes that have not been saved
0190      */
0191     virtual void loadConfiguration();
0192 
0193     /**
0194      * Should be implemented to ensure that views settings are saved when the user confirms their changes
0195      * Views should also apply the configuration at the same time
0196      */
0197     virtual void saveConfiguration();
0198 
0199 Q_SIGNALS:
0200     /**
0201      * Triggers a reload of the views actions by the host application.
0202      *
0203      * @warning Actions previously contained in the list must not be destroyed before this has been emitted.
0204      */
0205     void actionsChanged();
0206 
0207     /**
0208      * Should be emitted when the type ( list of modules / display of module )
0209      * of displayed view is changed.
0210      *
0211      * @param state Determines whether changes have been made in the view.
0212      * @warning Failure to Q_EMIT this will result in inconsistent application headers and change state.
0213      */
0214     void viewChanged(bool state);
0215 
0216     /**
0217      * Causes System Settings to hide / show the toolbar items specified.
0218      * This is used to control the display of the Configure and Search actions
0219      *
0220      * @param items The items that are wanted in the toolbar
0221      */
0222     void changeToolBarItems(BaseMode::ToolBarItems items);
0223 
0224 protected:
0225     /**
0226      * Returns the root item of the list of categorised modules.
0227      * This is usually passed to the constructor of MenuModel.
0228      *
0229      * @warning This is shared between all views, and should not be deleted manually.
0230      * @returns The root menu item as provided by System Settings.
0231      */
0232     MenuItem *rootItem() const;
0233 
0234     /**
0235      * Returns (if present) an item that corresponds to a KCM which should be used as startup page.
0236      *
0237      * @warning This is shared between all views, and should not be deleted manually.
0238      * @returns The item to load as startup page. It may be nullptr
0239      */
0240     MenuItem *homeItem() const;
0241 
0242     /**
0243      * Provides access to the configuration for the plugin.
0244      *
0245      * @returns The configuration group for the plugin.
0246      */
0247     KConfigGroup &config() const;
0248 
0249     /**
0250      * Provides access to item views used by the plugin.
0251      * This is currently used to show the enhanced tooltips.
0252      *
0253      * @returns A list of pointers to item views used by the mode.
0254      *          The list can be empty.
0255      */
0256     virtual QList<QAbstractItemView *> views() const;
0257 
0258 private:
0259     class Private;
0260     Private *const d;
0261 };
0262 
0263 Q_DECLARE_OPERATORS_FOR_FLAGS(BaseMode::ToolBarItems)
0264 
0265 #endif