File: panelpluginsmodel.h

package info (click to toggle)
lxqt-panel 2.1.4-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 15,748 kB
  • sloc: cpp: 27,548; xml: 798; makefile: 19
file content (339 lines) | stat: -rw-r--r-- 13,179 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
/* BEGIN_COMMON_COPYRIGHT_HEADER
 * (c)LGPL2+
 *
 * LXQt - a lightweight, Qt based, desktop toolset
 * https://lxqt.org
 *
 * Copyright: 2015 LXQt team
 *
 * This program or library is free software; you can redistribute it
 * and/or modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301 USA
 *
 * END_COMMON_COPYRIGHT_HEADER */

#ifndef PANELPLUGINSMODEL_H
#define PANELPLUGINSMODEL_H

#include <QAbstractListModel>
#include <memory>

namespace LXQt
{
    class PluginInfo;
    struct PluginData;
}

class LXQtPanel;
class Plugin;

/*!
 * \brief The PanelPluginsModel class implements the Model part of the
 * Qt Model/View architecture for the Plugins, i.e. it is the interface
 * to access the Plugin data associated with this Panel. The
 * PanelPluginsModel takes care for read-access as well as changes
 * like adding, removing or moving Plugins.
 */
class PanelPluginsModel : public QAbstractListModel
{
    Q_OBJECT
public:
    PanelPluginsModel(LXQtPanel * panel,
                      QString const & namesKey,
                      QStringList const & desktopDirs,
                      QObject * parent = nullptr);
    ~PanelPluginsModel();

    /*!
     * \brief rowCount returns the number of Plugins. It overrides/implements
     * QAbstractListModel::rowCount().
     * \param parent The parameter parent should be omitted to get the number of
     * Plugins. If it is given and a valid model index, the method returns 0
     * because PanelPluginsModel is not a hierarchical model.
     */
    virtual int rowCount(const QModelIndex & parent = QModelIndex()) const override;
    /*!
     * \brief data returns the Plugin data as defined by the Model/View
     * architecture. The Plugins itself can be accessed with the role
     * Qt::UserRole but they can also be accessed by the methods plugins(),
     * pluginByName() and pluginByID(). This method overrides/implements
     * QAbstractListModel::data().
     * \param index should be a valid model index to determine the Plugin
     * that should be read.
     * \param role The Qt::ItemDataRole to determine what kind of data should
     * be read, can be one of the following:
     * 1. Qt::DisplayRole to return a string that describes the Plugin.
     * 2. Qt::DecorationRole to return an icon for the Plugin.
     * 3. Qt::UserRole to return a Plugin*.
     * \return The data as determined by index and role.
     */
    virtual QVariant data(const QModelIndex & index, int role = Qt::DisplayRole) const override;
    /*!
     * \brief flags returns the item flags for the given model index. For
     * all Plugins, this is the same:
     * Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemNeverHasChildren.
     */
    virtual Qt::ItemFlags flags(const QModelIndex & index) const override;

    /*!
     * \brief pluginNames returns a list of names for all the Plugins in
     * this panel. The names are not the human-readable names but the names
     * that are used to identify the Plugins, e.g. in the config files. These
     * names can be used in the method pluginByName() to get a corresponding
     * Plugin.
     *
     * The plugin names are normally chosen to be equal to the
     * filename of the corresponding *.desktop-file. If multiple instances
     * of a single plugin-type are created, their names are created by
     * appending increasing numbers, e.g. 'mainmenu' and 'mainmenu2'.
     *
     * \sa findNewPluginSettingsGroup
     */
    QStringList pluginNames() const;
    /*!
     * \brief plugins returns a list of Plugins in this panel.
     */
    QList<Plugin *> plugins() const;
    /*!
     * \brief pluginByName gets a Plugin by its name.
     * \param name is the name of the plugin as it is used in the
     * config files. A list of names can be retrieved with the
     * method pluginNames().
     * \return the Plugin with the given name.
     *
     * \sa pluginNames
     */
    Plugin *pluginByName(QString name) const;
    /*!
     * \brief pluginByID gets a Plugin by its ID.
     * \param id is the *.desktop-file-ID of the plugin which in turn is the
     * QFileInfo::completeBaseName() of the desktop-file, e.g. "mainmenu".
     *
     * As these IDs are chosen according to the corresponding
     * desktop-file, these IDs are not unique. If multiple
     * instances of a single plugin-type are created, they share
     * the same ID in this sense. Then, this method will return
     * the first plugin of the given type.
     * \return the first Plugin found with the given ID.
     */
    Plugin const *pluginByID(QString id) const;

    /*!
     * \brief movePlugin moves a Plugin in the underlying data.
     *
     * This method is useful whenever a Plugin should be moved several
     * positions at once. If a Plugin should only be moved one position
     * up or down, consider using onMovePluginUp or onMovePluginDown.
     *
     * \param plugin Plugin that has been moved
     * \param nameAfter name of the Plugin that should be located after
     * the moved Plugin after the move operation, so this parameter
     * determines the new position of plugin. If an empty string is
     * given, plugin will be moved to the end of the list.
     *
     * \note This method is especially useful for drag and drop reordering.
     * Therefore, it will be called whenever the user moves a Plugin in
     * the panel ("Move Plugin" in the context menu of the panel).
     *
     * \sa onMovePluginUp, onMovePluginDown
     */
    void movePlugin(Plugin * plugin, QString const & nameAfter);

signals:
    /*!
     * \brief pluginAdded gets emitted whenever a new Plugin is added
     * to the panel.
     */
    void pluginAdded(Plugin * plugin);
    /*!
     * \brief pluginRemoved gets emitted whenever a Plugin is removed.
     * \param plugin The Plugin that was removed. This could be a nullptr.
     */
    void pluginRemoved(Plugin * plugin);
    /*!
     * \brief pluginMoved gets emitted whenever a Plugin is moved.
     *
     * This signal gets emitted in movePlugin, onMovePluginUp and
     * onMovePluginDown.
     *
     * \param plugin The Plugin that was moved. This could be a nullptr.
     *
     * \sa pluginMovedUp
     */
    void pluginMoved(Plugin * plugin); //plugin can be nullptr in case of move of not loaded plugin
    /*!
     * \brief pluginMovedUp gets emitted whenever a Plugin is moved a single
     * slot upwards.
     *
     * When a Plugin is moved a single slot upwards, this signal will be
     * emitted additionally to the pluginMoved signal so that two signals
     * get emitted.
     *
     * If a Plugin is moved downwards, that Plugin will swap places with
     * the following Plugin so that the result equals moving the following
     * Plugin a single slot upwards. So, whenever two adjacent Plugins
     * swap their places, this signal gets emitted with the Plugin that
     * moves upwards as parameter.
     *
     * For simplified use, only this signal is implemented. There is no
     * similar pluginMovedDown-signal.
     *
     * This signal gets emitted from onMovePluginUp and onMovePluginDown.
     *
     * \param plugin The Plugin that moved a slot upwards.
     *
     * \sa pluginMoved
     */
    void pluginMovedUp(Plugin * plugin);

public slots:
    /*!
     * \brief addPlugin Adds a new Plugin to the model.
     *
     * \param desktopFile The PluginInfo (which inherits XdgDesktopFile)
     * for the Plugin that should be added.
     *
     * \note AddPluginDialog::pluginSelected is connected to this slot.
     */
    void addPlugin(const LXQt::PluginInfo &desktopFile);
    /*!
     * \brief removePlugin Removes a Plugin from the model.
     *
     * The Plugin to remove is identified by the QObject::sender() method
     * when the slot is called. Therefore, this method should only be called
     * by connecting a signal that a Plugin will emit to this slot.
     * Otherwise, nothing will happen.
     *
     * \note Plugin::remove is connected to this slot as soon as the
     * Plugin is loaded in the PanelPluginsModel.
     */
    void removePlugin();

    // slots for configuration dialog
    /*!
     * \brief onMovePluginUp Moves the Plugin corresponding to the given
     * model index a slot upwards.
     *
     * \note The 'Up' button in the configuration widget is connected to this
     * slot.
     */
    void onMovePluginUp(QModelIndex const & index);
    /*!
     * \brief onMovePluginDown Moves the Plugin corresponding to the given
     * model index a slot downwards.
     *
     * \note The 'Down' button in the configuration widget is connected to this
     * slot.
     */
    void onMovePluginDown(QModelIndex const & index);
    /*!
     * \brief onConfigurePlugin If the Plugin corresponding to the given
     * model index has a config dialog (checked via the flag
     * ILXQtPanelPlugin::HaveConfigDialog), this method shows
     * it by calling plugin->showConfigureDialog().
     *
     * \note The 'Configure' button in the configuration widget is connected to
     * this slot.
     */
    void onConfigurePlugin(QModelIndex const & index);
    /*!
     * \brief onRemovePlugin Removes the Plugin corresponding to the given
     * model index from the Model.
     *
     * \note The 'Remove' button in the configuration widget is connected to
     * this slot.
     */
    void onRemovePlugin(QModelIndex const & index);

private:
    /*!
     * \brief pluginslist_t is the data type used for mPlugins which stores
     * all the Plugins.
     *
     * \sa mPlugins
     */
    typedef QList<std::pair <QString/*name*/, QPointer<Plugin> > > pluginslist_t;

private:
    /*!
     * \brief loadPlugins Loads all the Plugins.
     * \param desktopDirs These directories are scanned for corresponding
     * .desktop-files which are necessary to load the plugins.
     */
    void loadPlugins(QStringList const & desktopDirs);
    /*!
     * \brief loadPlugin Loads a Plugin and connects signals and slots.
     * \param desktopFile The desktop file that specifies how to load the
     * Plugin.
     * \param settingsGroup QString which specifies the settings group. This
     * will only be redirected to the Plugin so that it knows how to read
     * its settings.
     * \return A QPointer to the Plugin that was loaded.
     */
    QPointer<Plugin> loadPlugin(LXQt::PluginInfo const & desktopFile, QString const & settingsGroup);
    /*!
     * \brief findNewPluginSettingsGroup Creates a name for a new Plugin
     * that is not yet present in the settings file. Whenever multiple
     * instances of a single Plugin type are created, they have to be
     * distinguished by this name.
     *
     * The first Plugin of a given type will be named like the type, e.g.
     * "mainmenu". If a name is already present, this method tries to
     * find a free name by appending increasing integers (starting with 2),
     * e.g. "mainmenu2". If, for example, only "mainmenu2" exists because
     * "mainmenu" was deleted, "mainmenu" would be returned. So, the method
     * always finds the first suitable name that is not yet present in the
     * settings file.
     * \param pluginType Type of the Plugin.
     * \return The created name for the Plugin.
     */
    QString findNewPluginSettingsGroup(const QString &pluginType) const;
    /*!
     * \brief isIndexValid Checks if a given model index is valid for the
     * underlying data (column 0, row lower than number of Plugins and
     * so on).
     */
    bool isIndexValid(QModelIndex const & index) const;
    /*!
     * \brief removePlugin Removes a given Plugin from the model.
     */
    void removePlugin(pluginslist_t::iterator plugin);

    /*!
     * \brief mNamesKey The key to the settings-entry that stores the
     * names of the Plugins in a panel. Set upon creation, passed as
     * a parameter by the panel.
     */
    const QString mNamesKey;
    /*!
     * \brief mPlugins Stores all the Plugins.
     *
     * mPlugins is a QList of elements while each element corresponds to a
     * single Plugin. Each element is a std::pair of a QString and a QPointer
     * while the QPointer points to a Plugin.
     *
     * To access the elements, you can use indexing or an iterator on the
     * list. For each element p, p.first is the name of the Plugin as it
     * is used in the configuration files, p.second.data() is the Plugin.
     *
     * \sa pluginslist_t
     */
    pluginslist_t mPlugins;
    /*!
     * \brief mPanel Stores a reference to the LXQtPanel.
     */
    LXQtPanel * mPanel;
};

#endif // PANELPLUGINSMODEL_H