1 /* 2 * SPDX-FileCopyrightText: 2009 Ben Cooksley <bcooksley@kde.org> 3 * 4 * SPDX-License-Identifier: GPL-2.0-or-later 5 */ 6 7 #ifndef BASEMODE_H 8 #define BASEMODE_H 9 10 #include <QObject> 11 12 #include <KPluginMetaData> 13 14 #include "systemsettingsview_export.h" 15 16 class QAction; 17 class MenuItem; 18 class ModuleView; 19 class KAboutData; 20 class KConfigDialog; 21 class KConfigGroup; 22 class QAbstractItemView; 23 template<typename T> class QList; 24 25 /** 26 * @brief Provides a interface for System Settings views 27 * 28 * BaseMode is a standard interface for all plugins to System Settings to allow them to provide 29 * their own interface to KDE control modules.\n 30 * 31 * The developer need only ensure that they perform all initialization of their plugin in 32 * initEvent() to ensure that the plugin is displayed, and initial actions are loaded. 33 * 34 * @author Ben Cooksley <bcooksley@kde.org> 35 * @author Mathias Soeken <msoeken@informatik.uni-bremen.de> 36 */ 37 class SYSTEMSETTINGSVIEW_EXPORT BaseMode : public QObject 38 { 39 Q_OBJECT 40 41 Q_PROPERTY(ApplicationMode applicationMode READ applicationMode CONSTANT) 42 43 /** 44 * System Settings main application is allowed priviledged access to handle tooltips 45 */ 46 friend class SettingsBase; 47 48 public: 49 // Main mode of the app. 50 // At the moment SystemSettings and InfoCenter are supported: 51 // Changes mainly the set of module listed on the left menu 52 enum ApplicationMode { 53 SystemSettings = 0, 54 InfoCenter, 55 }; 56 Q_ENUM(ApplicationMode); 57 58 /** 59 * Constructs a BaseMode for use in System Settings.\n 60 * Plugin developers should perform all initialisation in initEvent() not here. 61 * 62 * @param parent The parent of this BaseMode. 63 */ 64 explicit BaseMode(QObject *parent, const QVariantList &args); 65 /** 66 * Normal destructor. Plugin developers only need destroy what they created 67 * not what is provided by BaseMode itself. 68 */ 69 ~BaseMode() override; 70 71 /** 72 * These flags are used to control the presence of the Search and Configure actions on the toolbar 73 */ 74 enum ToolBarItemsFlags { 75 NoItems = 0x1, /**< The Toolbar will not have any items added by System Settings */ 76 Search = 0x2, /**< The Toolbar will have the search bar added by System Settings */ 77 Configure = 0x4, /**< The Toolbar will have configure added by System Settings */ 78 Quit = 0x8, /**< The toolbar will have exit added by System Settings */ 79 }; 80 Q_DECLARE_FLAGS(ToolBarItems, ToolBarItemsFlags) 81 82 /** 83 * Performs internal setup.\n 84 * Plugin developers should perform initialisation in initEvent() not here. 85 * 86 * @param modeService Plugins service object, used for providing extra information to System Settings. 87 */ 88 void init(const KPluginMetaData metaData); 89 90 /** 91 * Prepares the BaseMode for use.\n 92 * Plugin developers should perform initialisation here, creating the Models. They should perform widget 93 * initialisation the first time mainWidget() is called, not here. 94 */ 95 virtual void initEvent(); 96 97 /** 98 * Returns the widget to be displayed in the center of System Settings.\n 99 * The widget should be created the first time this function is called. 100 * 101 * @warning This function is called multiple times, ensure the widget is only created once. 102 * @returns The main widget of the plugin. 103 */ 104 virtual QWidget *mainWidget(); 105 106 /** 107 * Provides information about the plugin, which is used in the About dialog of System Settings.\n 108 * This does not need to be implemented, and need only be implemented if the author 109 * wants information about the view displayed in the About dialog. 110 * 111 * @returns The about data of the plugin. 112 */ 113 virtual KAboutData *aboutData(); 114 115 /** 116 * @returns the application mode of this systemsettings process: SystemSettings or InfoCenter 117 */ 118 ApplicationMode applicationMode() const; 119 120 /** 121 * The state of the plugin ( position of the splitter for instance ) should be saved 122 * to the configuration object when this is called. 123 */ 124 virtual void saveState(); 125 126 /** 127 * Causes the view to unload all modules in the module view, and return to their module selection state 128 * 129 * @warning Failure to reimplement will cause modules to not be unloaded when changing views. 130 * This must be implemented. 131 */ 132 virtual void leaveModuleView(); 133 134 /** 135 * Used to give focus to the plugin. Plugin should call setFocus() on the appropriate widget 136 * 137 * @note Failure to reimplement will cause keyboard accessibility and widget focusing problems 138 */ 139 virtual void giveFocus(); 140 141 /** 142 * Provides access to the ModuleView the application uses to display control modules.\n 143 * 144 * @warning Failure to reimplement will cause modules not to be checked for configuration 145 * changes, and for the module to not be displayed in the About dialog. It must be implemented. 146 * @returns The ModuleView used by the plugin for handling modules. 147 */ 148 virtual ModuleView *moduleView() const; 149 150 /** 151 * Provides the list of actions the plugin wants System Settings to display in the toolbar when 152 * it is loaded. This function does not need to be implemented if adding actions to the toolbar 153 * is not required. 154 * 155 * @returns The list of actions the plugin provides. 156 */ 157 virtual QList<QAction *> &actionsList() const; 158 159 const KPluginMetaData &metaData() const; 160 161 /** 162 * tells the config view whether to make use of tooltips or not 163 */ 164 void setShowToolTips(bool show); 165 166 /** 167 * @returns true if the view should use tooltips 168 */ 169 bool showToolTips() const; 170 171 void setStartupModule(const QString &startupModule); 172 QString startupModule() const; 173 174 void setStartupModuleArgs(const QStringList &startupModuleArgs); 175 QStringList startupModuleArgs() const; 176 177 virtual void reloadStartupModule() = 0; 178 179 public Q_SLOTS: 180 /** 181 * Called when the text in the search box changes allowing the display to be filtered. 182 * 183 * @warning Search will not work in the view if this function is not implemented. 184 */ 185 virtual void searchChanged(const QString &text); 186 187 /** 188 * Allows views to add custom configuration pages to the System Settings configure dialog 189 * 190 * @warning Deleting the config object will cause System Settings to crash 191 */ 192 virtual void addConfiguration(KConfigDialog *config); 193 194 /** 195 * Allows views to load their configuration before the configuration dialog is shown 196 * Views should revert any changes that have not been saved 197 */ 198 virtual void loadConfiguration(); 199 200 /** 201 * Should be implemented to ensure that views settings are saved when the user confirms their changes 202 * Views should also apply the configuration at the same time 203 */ 204 virtual void saveConfiguration(); 205 206 Q_SIGNALS: 207 /** 208 * Triggers a reload of the views actions by the host application. 209 * 210 * @warning Actions previously contained in the list must not be destroyed before this has been emitted. 211 */ 212 void actionsChanged(); 213 214 /** 215 * Should be emitted when the type ( list of modules / display of module ) 216 * of displayed view is changed. 217 * 218 * @param state Determines whether changes have been made in the view. 219 * @warning Failure to Q_EMIT this will result in inconsistent application headers and change state. 220 */ 221 void viewChanged(bool state); 222 223 /** 224 * Causes System Settings to hide / show the toolbar items specified. 225 * This is used to control the display of the Configure and Search actions 226 * 227 * @param items The items that are wanted in the toolbar 228 */ 229 void changeToolBarItems(BaseMode::ToolBarItems items); 230 231 protected: 232 /** 233 * Returns the root item of the list of categorised modules. 234 * This is usually passed to the constructor of MenuModel. 235 * 236 * @warning This is shared between all views, and should not be deleted manually. 237 * @returns The root menu item as provided by System Settings. 238 */ 239 MenuItem *rootItem() const; 240 241 /** 242 * Returns (if present) an item that corresponds to a KCM which should be used as startup page. 243 * 244 * @warning This is shared between all views, and should not be deleted manually. 245 * @returns The item to load as startup page. It may be nullptr 246 */ 247 MenuItem *homeItem() const; 248 249 /** 250 * Provides access to the configuration for the plugin. 251 * 252 * @returns The configuration group for the plugin. 253 */ 254 KConfigGroup &config() const; 255 256 /** 257 * Provides access to item views used by the plugin. 258 * This is currently used to show the enhanced tooltips. 259 * 260 * @returns A list of pointers to item views used by the mode. 261 * The list can be empty. 262 */ 263 virtual QList<QAbstractItemView *> views() const; 264 265 private: 266 class Private; 267 Private *const d; 268 }; 269 270 Q_DECLARE_OPERATORS_FOR_FLAGS(BaseMode::ToolBarItems) 271 272 #endif 273