standardactionmanager.h 17.8 KB
Newer Older
1
/*
2
    SPDX-FileCopyrightText: 2008 Volker Krause <vkrause@kde.org>
3

4
    SPDX-License-Identifier: LGPL-2.0-or-later
5
6
7
8
9
*/

#ifndef AKONADI_STANDARDACTIONMANAGER_H
#define AKONADI_STANDARDACTIONMANAGER_H

10
#include "akonadiwidgets_export.h"
11

Daniel Vrátil's avatar
Daniel Vrátil committed
12
#include <QObject>
13

14
15
#include "collection.h"
#include "item.h"
16

Laurent Montel's avatar
Laurent Montel committed
17
class QAction;
18
class KActionCollection;
19
class KLocalizedString;
20
21
class QItemSelectionModel;
class QWidget;
22
class QMenu;
23

Laurent Montel's avatar
Laurent Montel committed
24
25
namespace Akonadi
{
26

27
28
class FavoriteCollectionsModel;

29
/**
Tobias Koenig's avatar
Tobias Koenig committed
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
 * @short Manages generic actions for collection and item views.
 *
 * Manages generic Akonadi actions common for all types. This covers
 * creating of the actions with appropriate labels, icons, shortcuts
 * etc., updating the action state depending on the current selection
 * as well as default implementations for the actual operations.
 *
 * If the default implementation is not appropriate for your application
 * you can still use the state tracking by disconnecting the triggered()
 * signal and re-connecting it to your implementation. The actual KAction
 * objects can be retrieved by calling createAction() or action() for that.
 *
 * If the default look and feel (labels, icons, shortcuts) of the actions
 * is not appropriate for your application, you can access them as noted
 * above and customize them to your needs. Additionally, you can set a
 * KLocalizedString which should be used as a action label with correct
 * plural handling for actions operating on multiple objects with
 * setActionText().
 *
 * Finally, if you have special needs for the action states, connect to
 * the actionStateUpdated() signal and adjust the state accordingly.
 *
 * The following actions are provided (KAction name in parenthesis):
 * - Creation of a new collection (@c akonadi_collection_create)
 * - Copying of selected collections (@c akonadi_collection_copy)
 * - Deletion of selected collections (@c akonadi_collection_delete)
 * - Synchronization of selected collections (@c akonadi_collection_sync)
 * - Showing the collection properties dialog for the current collection (@c akonadi_collection_properties)
 * - Copying of selected items (@c akonadi_itemcopy)
 * - Pasting collections, items or raw data (@c akonadi_paste)
 * - Deleting of selected items (@c akonadi_item_delete)
 * - Managing local subscriptions (@c akonadi_manage_local_subscriptions)
 *
 * The following example shows how to use standard actions in your application:
 *
 * @code
 *
 * Akonadi::StandardActionManager *actMgr = new Akonadi::StandardActionManager( actionCollection(), this );
 * actMgr->setCollectionSelectionModel( collectionView->collectionSelectionModel() );
 * actMgr->createAllActions();
 *
 * @endcode
 *
 * Additionally you have to add the actions to the KXMLGUI file of your application,
 * using the names listed above.
 *
 * If you only need a subset of the actions provided, you can call createAction()
 * instead of createAllActions() for the action types you want.
 *
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 * If you want to use your own implementation of the actual action operation and
 * not the default implementation, you can call interceptAction() on the action type
 * you want to handle yourself and connect the slot with your own implementation
 * to the triggered() signal of the action:
 *
 * @code
 *
 * using namespace Akonadi;
 *
 * StandardActionManager *manager = new StandardActionManager( actionCollection(), this );
 * manager->setCollectionSelectionModel( collectionView->collectionSelectionModel() );
 * manager->createAllActions();
 *
 * // disable default implementation
 * manager->interceptAction( StandardActionManager::CopyCollections );
 *
 * // connect your own implementation
Guy Maurel's avatar
Guy Maurel committed
96
97
 * connect( manager->action( StandardActionManager::CopyCollections ), SIGNAL(triggered(bool)),
 *          this, SLOT(myCopyImplementation()) );
98
99
100
101
102
 * ...
 *
 * void MyClass::myCopyImplementation()
 * {
 *   const Collection::List collections = manager->selectedCollections();
Daniel Vrátil's avatar
Daniel Vrátil committed
103
 *   for ( const Collection &collection : collections ) {
104
105
106
107
108
109
 *     // copy the collection manually...
 *   }
 * }
 *
 * @endcode
 *
Tobias Koenig's avatar
Tobias Koenig committed
110
111
112
113
 * @todo collection deleting and sync do not support multi-selection yet
 *
 * @author Volker Krause <vkrause@kde.org>
 */
114
class AKONADIWIDGETS_EXPORT StandardActionManager : public QObject
115
{
Guy Maurel's avatar
Guy Maurel committed
116
117
    Q_OBJECT
public:
Tobias Koenig's avatar
Tobias Koenig committed
118
119
120
    /**
     * Describes the supported actions.
     */
121
    enum Type {
Guy Maurel's avatar
Guy Maurel committed
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
        CreateCollection,                        ///< Creates an collection
        CopyCollections,                         ///< Copies the selected collections
        DeleteCollections,                       ///< Deletes the selected collections
        SynchronizeCollections,                  ///< Synchronizes collections
        CollectionProperties,                    ///< Provides collection properties
        CopyItems,                               ///< Copies the selected items
        Paste,                                   ///< Paste collections or items
        DeleteItems,                             ///< Deletes the selected items
        ManageLocalSubscriptions,                ///< Manages local subscriptions
        AddToFavoriteCollections,                ///< Add the collection to the favorite collections model @since 4.4
        RemoveFromFavoriteCollections,           ///< Remove the collection from the favorite collections model @since 4.4
        RenameFavoriteCollection,                ///< Rename the collection of the favorite collections model @since 4.4
        CopyCollectionToMenu,                    ///< Menu allowing to quickly copy a collection into another collection @since 4.4
        CopyItemToMenu,                          ///< Menu allowing to quickly copy an item into a collection @since 4.4
        MoveItemToMenu,                          ///< Menu allowing to move item into a collection @since 4.4
        MoveCollectionToMenu,                    ///< Menu allowing to move a collection into another collection @since 4.4
        CutItems,                                ///< Cuts the selected items @since 4.4
        CutCollections,                          ///< Cuts the selected collections @since 4.4
        CreateResource,                          ///< Creates a new resource @since 4.6
        DeleteResources,                         ///< Deletes the selected resources @since 4.6
        ResourceProperties,                      ///< Provides the resource properties @since 4.6
        SynchronizeResources,                    ///< Synchronizes the selected resources @since 4.6
        ToggleWorkOffline,                       ///< Toggles the work offline state of all resources @since 4.6
        CopyCollectionToDialog,                  ///< Copy a collection into another collection, select the target in a dialog @since 4.6
        MoveCollectionToDialog,                  ///< Move a collection into another collection, select the target in a dialog @since 4.6
        CopyItemToDialog,                        ///< Copy an item into a collection, select the target in a dialog @since 4.6
        MoveItemToDialog,                        ///< Move an item into a collection, select the target in a dialog @since 4.6
        SynchronizeCollectionsRecursive,         ///< Synchronizes collections in a recursive way @since 4.6
        MoveCollectionsToTrash,                  ///< Moves the selected collection to trash and marks it as deleted, needs EntityDeletedAttribute @since 4.8
        MoveItemsToTrash,                        ///< Moves the selected items to trash and marks them as deleted, needs EntityDeletedAttribute @since 4.8
        RestoreCollectionsFromTrash,             ///< Restores the selected collection from trash, needs EntityDeletedAttribute @since 4.8
        RestoreItemsFromTrash,                   ///< Restores the selected items from trash, needs EntityDeletedAttribute @since 4.8
        MoveToTrashRestoreCollection,            ///< Move Collection to Trash or Restore it from Trash, needs EntityDeletedAttribute @since 4.8
        MoveToTrashRestoreCollectionAlternative, ///< Helper type for MoveToTrashRestoreCollection, do not create directly. Use this to override texts of the restore action. @since 4.8
        MoveToTrashRestoreItem,                  ///< Move Item to Trash or Restore it from Trash, needs EntityDeletedAttribute @since 4.8
        MoveToTrashRestoreItemAlternative,       ///< Helper type for MoveToTrashRestoreItem, do not create directly. Use this to override texts of the restore action. @since 4.8
        SynchronizeFavoriteCollections,          ///< Synchronize favorite collections @since 4.8
159
        SynchronizeCollectionTree,               ///< Synchronize collection tree @since 4.15
Guy Maurel's avatar
Guy Maurel committed
160
        LastType                                 ///< Marks last action
161
162
    };

163
164
165
166
    /**
     * Describes the text context that can be customized.
     */
    enum TextContext {
Guy Maurel's avatar
Guy Maurel committed
167
168
169
170
171
172
173
        DialogTitle,                ///< The window title of a dialog
        DialogText,                 ///< The text of a dialog
        MessageBoxTitle,            ///< The window title of a message box
        MessageBoxText,             ///< The text of a message box
        MessageBoxAlternativeText,  ///< An alternative text of a message box
        ErrorMessageTitle,          ///< The window title of an error message
        ErrorMessageText            ///< The text of an error message
174
175
    };

176
    /**
Tobias Koenig's avatar
Tobias Koenig committed
177
178
179
180
181
     * Creates a new standard action manager.
     *
     * @param actionCollection The action collection to operate on.
     * @param parent The parent widget.
     */
Laurent Montel's avatar
Laurent Montel committed
182
    explicit StandardActionManager(KActionCollection *actionCollection, QWidget *parent = nullptr);
183
184

    /**
Tobias Koenig's avatar
Tobias Koenig committed
185
186
     * Destroys the standard action manager.
     */
187
188
189
    ~StandardActionManager();

    /**
Tobias Koenig's avatar
Tobias Koenig committed
190
191
192
     * Sets the collection selection model based on which the collection
     * related actions should operate. If none is set, all collection actions
     * will be disabled.
193
194
     *
     * @param selectionModel model to be set for collection
Tobias Koenig's avatar
Tobias Koenig committed
195
     */
Guy Maurel's avatar
Guy Maurel committed
196
    void setCollectionSelectionModel(QItemSelectionModel *selectionModel);
197

198
    /**
Tobias Koenig's avatar
Tobias Koenig committed
199
200
     * Sets the item selection model based on which the item related actions
     * should operate. If none is set, all item actions will be disabled.
201
202
     *
     * @param selectionModel selection model for items
Tobias Koenig's avatar
Tobias Koenig committed
203
     */
Guy Maurel's avatar
Guy Maurel committed
204
    void setItemSelectionModel(QItemSelectionModel *selectionModel);
205

206
207
208
209
    /**
     * Sets the favorite collections model based on which the collection
     * relatedactions should operate. If none is set, the "Add to Favorite Folders" action
     * will be disabled.
Tobias Koenig's avatar
Tobias Koenig committed
210
     *
211
     * @param favoritesModel model for the user's favorite collections
Tobias Koenig's avatar
Tobias Koenig committed
212
     * @since 4.4
213
     */
Guy Maurel's avatar
Guy Maurel committed
214
    void setFavoriteCollectionsModel(FavoriteCollectionsModel *favoritesModel);
215

216
217
218
219
    /**
     * Sets the favorite collection selection model based on which the favorite
     * collection related actions should operate. If none is set, all favorite modifications
     * actions will be disabled.
Tobias Koenig's avatar
Tobias Koenig committed
220
     *
221
     * @param selectionModel selection model for favorite collections
Tobias Koenig's avatar
Tobias Koenig committed
222
     * @since 4.4
223
     */
Guy Maurel's avatar
Guy Maurel committed
224
    void setFavoriteSelectionModel(QItemSelectionModel *selectionModel);
225

226
    /**
Tobias Koenig's avatar
Tobias Koenig committed
227
228
229
     * Creates the action of the given type and adds it to the action collection
     * specified in the constructor if it does not exist yet. The action is
     * connected to its default implementation provided by this class.
230
231
     *
     * @param type action to be created
Tobias Koenig's avatar
Tobias Koenig committed
232
     */
Laurent Montel's avatar
Laurent Montel committed
233
    QAction *createAction(Type type);
234
235

    /**
Tobias Koenig's avatar
Tobias Koenig committed
236
237
238
     * Convenience method to create all standard actions.
     * @see createAction()
     */
239
240
241
    void createAllActions();

    /**
Tobias Koenig's avatar
Tobias Koenig committed
242
     * Returns the action of the given type, 0 if it has not been created (yet).
243
     * @param type action type
Tobias Koenig's avatar
Tobias Koenig committed
244
     */
Laurent Montel's avatar
Laurent Montel committed
245
    QAction *action(Type type) const;
246

247
    /**
Tobias Koenig's avatar
Tobias Koenig committed
248
249
250
251
     * Sets the label of the action @p type to @p text, which is used during
     * updating the action state and substituted according to the number of
     * selected objects. This is mainly useful to customize the label of actions
     * that can operate on multiple objects.
Kevin Krammer's avatar
Kevin Krammer committed
252
253
     * @param type the action to set a text for
     * @param text the text to display for the given action
Tobias Koenig's avatar
Tobias Koenig committed
254
255
256
257
258
259
     * Example:
     * @code
     * acctMgr->setActionText( Akonadi::StandardActionManager::CopyItems,
     *                         ki18np( "Copy Mail", "Copy %1 Mails" ) );
     * @endcode
     */
Guy Maurel's avatar
Guy Maurel committed
260
    void setActionText(Type type, const KLocalizedString &text);
261

262
263
264
265
    /**
     * Sets whether the default implementation for the given action @p type
     * shall be executed when the action is triggered.
     *
266
     * @param type action type
267
268
269
270
271
     * @param intercept If @c false, the default implementation will be executed,
     *                  if @c true no action is taken.
     *
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
272
    void interceptAction(Type type, bool intercept = true);
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289

    /**
     * Returns the list of collections that are currently selected.
     * The list is empty if no collection is currently selected.
     *
     * @since 4.6
     */
    Akonadi::Collection::List selectedCollections() const;

    /**
     * Returns the list of items that are currently selected.
     * The list is empty if no item is currently selected.
     *
     * @since 4.6
     */
    Akonadi::Item::List selectedItems() const;

290
291
292
    /**
     * Sets the @p text of the action @p type for the given @p context.
     *
293
294
295
     * @param type action type
     * @param context context for action
     * @param text content to set for the action
296
297
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
298
    void setContextText(Type type, TextContext context, const QString &text);
299

300
301
302
    /**
     * Sets the @p text of the action @p type for the given @p context.
     *
303
304
305
     * @param type action type
     * @param context context for action
     * @param text content to set for the action
306
307
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
308
    void setContextText(Type type, TextContext context, const KLocalizedString &text);
309

310
311
312
    /**
     * Sets the mime type filter that will be used when creating new resources.
     *
313
     * @param mimeTypes filter for creating new resources
314
315
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
316
    void setMimeTypeFilter(const QStringList &mimeTypes);
317
318
319
320

    /**
     * Sets the capability filter that will be used when creating new resources.
     *
321
     * @param capabilities filter for creating new resources
322
323
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
324
    void setCapabilityFilter(const QStringList &capabilities);
325

326
327
328
329
    /**
     * Sets the page @p names of the config pages that will be used by the
     * built-in collection properties dialog.
     *
330
     * @param names list of names which will be used
331
332
     * @since 4.6
     */
Guy Maurel's avatar
Guy Maurel committed
333
    void setCollectionPropertiesPageNames(const QStringList &names);
334

335
336
    /**
     * Create a popup menu.
337
338
339
     *
     * @param menu parent menu for a popup
     * @param type action type
340
341
342
     * @since 4.8
     */
    void createActionFolderMenu(QMenu *menu, Type type);
343

Guy Maurel's avatar
Guy Maurel committed
344
Q_SIGNALS:
345
346
347
348
349
350
351
352
353
354
355

    /**
     * This signal is emitted whenever one of the selections has changed
     * (selected collections, selected favorites collections, selected items)
     * This allows other action managers to update their actions accordingly
     * (see e.g. StandardMailActionManager)
     */
    void selectionsChanged(const Collection::List &selectedCollectionsList,
                           const Collection::List &selectedFavoriteCollectionsList,
                           const Item::List &selectedItems);

356
    /**
Tobias Koenig's avatar
Tobias Koenig committed
357
358
359
360
     * This signal is emitted whenever the action state has been updated.
     * In case you have special needs for changing the state of some actions,
     * connect to this signal and adjust the action state.
     */
361
362
    void actionStateUpdated();

Guy Maurel's avatar
Guy Maurel committed
363
private:
Tobias Koenig's avatar
Tobias Koenig committed
364
    //@cond PRIVATE
365
    class Private;
Guy Maurel's avatar
Guy Maurel committed
366
    Private *const d;
367

Guy Maurel's avatar
Guy Maurel committed
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
    Q_PRIVATE_SLOT(d, void updateActions())

    Q_PRIVATE_SLOT(d, void slotCreateCollection())
    Q_PRIVATE_SLOT(d, void slotCopyCollections())
    Q_PRIVATE_SLOT(d, void slotCutCollections())
    Q_PRIVATE_SLOT(d, void slotDeleteCollection())
    Q_PRIVATE_SLOT(d, void slotMoveCollectionToTrash())
    Q_PRIVATE_SLOT(d, void slotMoveItemToTrash())
    Q_PRIVATE_SLOT(d, void slotRestoreCollectionFromTrash())
    Q_PRIVATE_SLOT(d, void slotRestoreItemFromTrash())
    Q_PRIVATE_SLOT(d, void slotTrashRestoreCollection())
    Q_PRIVATE_SLOT(d, void slotTrashRestoreItem())
    Q_PRIVATE_SLOT(d, void slotSynchronizeCollection())
    Q_PRIVATE_SLOT(d, void slotSynchronizeCollectionRecursive())
    Q_PRIVATE_SLOT(d, void slotSynchronizeFavoriteCollections())
    Q_PRIVATE_SLOT(d, void slotCollectionProperties())
    Q_PRIVATE_SLOT(d, void slotCopyItems())
    Q_PRIVATE_SLOT(d, void slotCutItems())
    Q_PRIVATE_SLOT(d, void slotPaste())
    Q_PRIVATE_SLOT(d, void slotDeleteItems())
    Q_PRIVATE_SLOT(d, void slotDeleteItemsDeferred(const Akonadi::Item::List &))
    Q_PRIVATE_SLOT(d, void slotLocalSubscription())
    Q_PRIVATE_SLOT(d, void slotAddToFavorites())
    Q_PRIVATE_SLOT(d, void slotRemoveFromFavorites())
    Q_PRIVATE_SLOT(d, void slotRenameFavorite())
    Q_PRIVATE_SLOT(d, void slotCopyCollectionTo())
    Q_PRIVATE_SLOT(d, void slotMoveCollectionTo())
    Q_PRIVATE_SLOT(d, void slotCopyItemTo())
    Q_PRIVATE_SLOT(d, void slotMoveItemTo())
    Q_PRIVATE_SLOT(d, void slotCopyCollectionTo(QAction *))
    Q_PRIVATE_SLOT(d, void slotMoveCollectionTo(QAction *))
    Q_PRIVATE_SLOT(d, void slotCopyItemTo(QAction *))
    Q_PRIVATE_SLOT(d, void slotMoveItemTo(QAction *))
    Q_PRIVATE_SLOT(d, void slotCreateResource())
    Q_PRIVATE_SLOT(d, void slotDeleteResource())
    Q_PRIVATE_SLOT(d, void slotResourceProperties())
    Q_PRIVATE_SLOT(d, void slotSynchronizeResource())
    Q_PRIVATE_SLOT(d, void slotToggleWorkOffline(bool))
Laurent Montel's avatar
Laurent Montel committed
406
    Q_PRIVATE_SLOT(d, void slotSynchronizeCollectionTree())
Guy Maurel's avatar
Guy Maurel committed
407
408
409
410
411
412
413
414
415
    Q_PRIVATE_SLOT(d, void collectionCreationResult(KJob *))
    Q_PRIVATE_SLOT(d, void moveItemToTrashResult(KJob *))
    Q_PRIVATE_SLOT(d, void resourceCreationResult(KJob *))
    Q_PRIVATE_SLOT(d, void pasteResult(KJob *))

    Q_PRIVATE_SLOT(d, void enableAction(int, bool))
    Q_PRIVATE_SLOT(d, void updatePluralLabel(int, int))
    Q_PRIVATE_SLOT(d, void updateAlternatingAction(int))
    Q_PRIVATE_SLOT(d, bool isFavoriteCollection(const Akonadi::Collection &))
Tobias Koenig's avatar
Tobias Koenig committed
416
    //@endcond
417
418
419
420
421
};

}

#endif