Akonadi

standardactionmanager.h
1 /*
2  SPDX-FileCopyrightText: 2008 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadiwidgets_export.h"
10 
11 // AkonadiCore
12 #include <akonadi/collection.h>
13 #include <akonadi/item.h>
14 
15 #include <QObject>
16 
17 #include <memory>
18 
19 class QAction;
20 class KActionCollection;
21 class KLocalizedString;
23 class QWidget;
24 class QMenu;
25 
26 namespace Akonadi
27 {
28 class FavoriteCollectionsModel;
29 class StandardActionManagerPrivate;
30 
31 /**
32  * @short Manages generic actions for collection and item views.
33  *
34  * Manages generic Akonadi actions common for all types. This covers
35  * creating of the actions with appropriate labels, icons, shortcuts
36  * etc., updating the action state depending on the current selection
37  * as well as default implementations for the actual operations.
38  *
39  * If the default implementation is not appropriate for your application
40  * you can still use the state tracking by disconnecting the triggered()
41  * signal and re-connecting it to your implementation. The actual KAction
42  * objects can be retrieved by calling createAction() or action() for that.
43  *
44  * If the default look and feel (labels, icons, shortcuts) of the actions
45  * is not appropriate for your application, you can access them as noted
46  * above and customize them to your needs. Additionally, you can set a
47  * KLocalizedString which should be used as a action label with correct
48  * plural handling for actions operating on multiple objects with
49  * setActionText().
50  *
51  * Finally, if you have special needs for the action states, connect to
52  * the actionStateUpdated() signal and adjust the state accordingly.
53  *
54  * The following actions are provided (KAction name in parenthesis):
55  * - Creation of a new collection (@c akonadi_collection_create)
56  * - Copying of selected collections (@c akonadi_collection_copy)
57  * - Deletion of selected collections (@c akonadi_collection_delete)
58  * - Synchronization of selected collections (@c akonadi_collection_sync)
59  * - Showing the collection properties dialog for the current collection (@c akonadi_collection_properties)
60  * - Copying of selected items (@c akonadi_itemcopy)
61  * - Pasting collections, items or raw data (@c akonadi_paste)
62  * - Deleting of selected items (@c akonadi_item_delete)
63  * - Managing local subscriptions (@c akonadi_manage_local_subscriptions)
64  *
65  * The following example shows how to use standard actions in your application:
66  *
67  * @code
68  *
69  * Akonadi::StandardActionManager *actMgr = new Akonadi::StandardActionManager( actionCollection(), this );
70  * actMgr->setCollectionSelectionModel( collectionView->collectionSelectionModel() );
71  * actMgr->createAllActions();
72  *
73  * @endcode
74  *
75  * Additionally you have to add the actions to the KXMLGUI file of your application,
76  * using the names listed above.
77  *
78  * If you only need a subset of the actions provided, you can call createAction()
79  * instead of createAllActions() for the action types you want.
80  *
81  * If you want to use your own implementation of the actual action operation and
82  * not the default implementation, you can call interceptAction() on the action type
83  * you want to handle yourself and connect the slot with your own implementation
84  * to the triggered() signal of the action:
85  *
86  * @code
87  *
88  * using namespace Akonadi;
89  *
90  * StandardActionManager *manager = new StandardActionManager( actionCollection(), this );
91  * manager->setCollectionSelectionModel( collectionView->collectionSelectionModel() );
92  * manager->createAllActions();
93  *
94  * // disable default implementation
95  * manager->interceptAction( StandardActionManager::CopyCollections );
96  *
97  * // connect your own implementation
98  * connect( manager->action( StandardActionManager::CopyCollections ), SIGNAL(triggered(bool)),
99  * this, SLOT(myCopyImplementation()) );
100  * ...
101  *
102  * void MyClass::myCopyImplementation()
103  * {
104  * const Collection::List collections = manager->selectedCollections();
105  * for ( const Collection &collection : collections ) {
106  * // copy the collection manually...
107  * }
108  * }
109  *
110  * @endcode
111  *
112  * @todo collection deleting and sync do not support multi-selection yet
113  *
114  * @author Volker Krause <[email protected]>
115  */
116 class AKONADIWIDGETS_EXPORT StandardActionManager : public QObject
117 {
118  Q_OBJECT
119 public:
120  /**
121  * Describes the supported actions.
122  */
123  enum Type {
124  CreateCollection, ///< Creates an collection
125  CopyCollections, ///< Copies the selected collections
126  DeleteCollections, ///< Deletes the selected collections
127  SynchronizeCollections, ///< Synchronizes collections
128  CollectionProperties, ///< Provides collection properties
129  CopyItems, ///< Copies the selected items
130  Paste, ///< Paste collections or items
131  DeleteItems, ///< Deletes the selected items
132  ManageLocalSubscriptions, ///< Manages local subscriptions
133  AddToFavoriteCollections, ///< Add the collection to the favorite collections model @since 4.4
134  RemoveFromFavoriteCollections, ///< Remove the collection from the favorite collections model @since 4.4
135  RenameFavoriteCollection, ///< Rename the collection of the favorite collections model @since 4.4
136  CopyCollectionToMenu, ///< Menu allowing to quickly copy a collection into another collection @since 4.4
137  CopyItemToMenu, ///< Menu allowing to quickly copy an item into a collection @since 4.4
138  MoveItemToMenu, ///< Menu allowing to move item into a collection @since 4.4
139  MoveCollectionToMenu, ///< Menu allowing to move a collection into another collection @since 4.4
140  CutItems, ///< Cuts the selected items @since 4.4
141  CutCollections, ///< Cuts the selected collections @since 4.4
142  CreateResource, ///< Creates a new resource @since 4.6
143  DeleteResources, ///< Deletes the selected resources @since 4.6
144  ResourceProperties, ///< Provides the resource properties @since 4.6
145  SynchronizeResources, ///< Synchronizes the selected resources @since 4.6
146  ToggleWorkOffline, ///< Toggles the work offline state of all resources @since 4.6
147  CopyCollectionToDialog, ///< Copy a collection into another collection, select the target in a dialog @since 4.6
148  MoveCollectionToDialog, ///< Move a collection into another collection, select the target in a dialog @since 4.6
149  CopyItemToDialog, ///< Copy an item into a collection, select the target in a dialog @since 4.6
150  MoveItemToDialog, ///< Move an item into a collection, select the target in a dialog @since 4.6
151  SynchronizeCollectionsRecursive, ///< Synchronizes collections in a recursive way @since 4.6
152  MoveCollectionsToTrash, ///< Moves the selected collection to trash and marks it as deleted, needs EntityDeletedAttribute @since 4.8
153  MoveItemsToTrash, ///< Moves the selected items to trash and marks them as deleted, needs EntityDeletedAttribute @since 4.8
154  RestoreCollectionsFromTrash, ///< Restores the selected collection from trash, needs EntityDeletedAttribute @since 4.8
155  RestoreItemsFromTrash, ///< Restores the selected items from trash, needs EntityDeletedAttribute @since 4.8
156  MoveToTrashRestoreCollection, ///< Move Collection to Trash or Restore it from Trash, needs EntityDeletedAttribute @since 4.8
157  MoveToTrashRestoreCollectionAlternative, ///< Helper type for MoveToTrashRestoreCollection, do not create directly. Use this to override texts of the
158  ///< restore action. @since 4.8
159  MoveToTrashRestoreItem, ///< Move Item to Trash or Restore it from Trash, needs EntityDeletedAttribute @since 4.8
160  MoveToTrashRestoreItemAlternative, ///< Helper type for MoveToTrashRestoreItem, do not create directly. Use this to override texts of the restore
161  ///< action. @since 4.8
162  SynchronizeFavoriteCollections, ///< Synchronize favorite collections @since 4.8
163  SynchronizeCollectionTree, ///< Synchronize collection tree @since 4.15
164  LastType ///< Marks last action
165  };
166 
167  /**
168  * Describes the text context that can be customized.
169  */
170  enum TextContext {
171  DialogTitle, ///< The window title of a dialog
172  DialogText, ///< The text of a dialog
173  MessageBoxTitle, ///< The window title of a message box
174  MessageBoxText, ///< The text of a message box
175  MessageBoxAlternativeText, ///< An alternative text of a message box
176  ErrorMessageTitle, ///< The window title of an error message
177  ErrorMessageText ///< The text of an error message
178  };
179 
180  /**
181  * Creates a new standard action manager.
182  *
183  * @param actionCollection The action collection to operate on.
184  * @param parent The parent widget.
185  */
186  explicit StandardActionManager(KActionCollection *actionCollection, QWidget *parent = nullptr);
187 
188  /**
189  * Destroys the standard action manager.
190  */
191  ~StandardActionManager() override;
192 
193  /**
194  * Sets the collection selection model based on which the collection
195  * related actions should operate. If none is set, all collection actions
196  * will be disabled.
197  *
198  * @param selectionModel model to be set for collection
199  */
200  void setCollectionSelectionModel(QItemSelectionModel *selectionModel);
201 
202  /**
203  * Sets the item selection model based on which the item related actions
204  * should operate. If none is set, all item actions will be disabled.
205  *
206  * @param selectionModel selection model for items
207  */
208  void setItemSelectionModel(QItemSelectionModel *selectionModel);
209 
210  /**
211  * Sets the favorite collections model based on which the collection
212  * relatedactions should operate. If none is set, the "Add to Favorite Folders" action
213  * will be disabled.
214  *
215  * @param favoritesModel model for the user's favorite collections
216  * @since 4.4
217  */
218  void setFavoriteCollectionsModel(FavoriteCollectionsModel *favoritesModel);
219 
220  /**
221  * Sets the favorite collection selection model based on which the favorite
222  * collection related actions should operate. If none is set, all favorite modifications
223  * actions will be disabled.
224  *
225  * @param selectionModel selection model for favorite collections
226  * @since 4.4
227  */
228  void setFavoriteSelectionModel(QItemSelectionModel *selectionModel);
229 
230  /**
231  * Creates the action of the given type and adds it to the action collection
232  * specified in the constructor if it does not exist yet. The action is
233  * connected to its default implementation provided by this class.
234  *
235  * @param type action to be created
236  */
237  QAction *createAction(Type type);
238 
239  /**
240  * Convenience method to create all standard actions.
241  * @see createAction()
242  */
243  void createAllActions();
244 
245  /**
246  * Returns the action of the given type, 0 if it has not been created (yet).
247  * @param type action type
248  */
249  QAction *action(Type type) const;
250 
251  /**
252  * Sets the label of the action @p type to @p text, which is used during
253  * updating the action state and substituted according to the number of
254  * selected objects. This is mainly useful to customize the label of actions
255  * that can operate on multiple objects.
256  * @param type the action to set a text for
257  * @param text the text to display for the given action
258  * Example:
259  * @code
260  * acctMgr->setActionText( Akonadi::StandardActionManager::CopyItems,
261  * ki18np( "Copy Mail", "Copy %1 Mails" ) );
262  * @endcode
263  */
264  void setActionText(Type type, const KLocalizedString &text);
265 
266  /**
267  * Sets whether the default implementation for the given action @p type
268  * shall be executed when the action is triggered.
269  *
270  * @param type action type
271  * @param intercept If @c false, the default implementation will be executed,
272  * if @c true no action is taken.
273  *
274  * @since 4.6
275  */
276  void interceptAction(Type type, bool intercept = true);
277 
278  /**
279  * Returns the list of collections that are currently selected.
280  * The list is empty if no collection is currently selected.
281  *
282  * @since 4.6
283  */
284  Akonadi::Collection::List selectedCollections() const;
285 
286  /**
287  * Returns the list of items that are currently selected.
288  * The list is empty if no item is currently selected.
289  *
290  * @since 4.6
291  */
292  Akonadi::Item::List selectedItems() const;
293 
294  /**
295  * Sets the @p text of the action @p type for the given @p context.
296  *
297  * @param type action type
298  * @param context context for action
299  * @param text content to set for the action
300  * @since 4.6
301  */
302  void setContextText(Type type, TextContext context, const QString &text);
303 
304  /**
305  * Sets the @p text of the action @p type for the given @p context.
306  *
307  * @param type action type
308  * @param context context for action
309  * @param text content to set for the action
310  * @since 4.6
311  */
312  void setContextText(Type type, TextContext context, const KLocalizedString &text);
313 
314  /**
315  * Sets the mime type filter that will be used when creating new resources.
316  *
317  * @param mimeTypes filter for creating new resources
318  * @since 4.6
319  */
320  void setMimeTypeFilter(const QStringList &mimeTypes);
321 
322  /**
323  * Sets the capability filter that will be used when creating new resources.
324  *
325  * @param capabilities filter for creating new resources
326  * @since 4.6
327  */
328  void setCapabilityFilter(const QStringList &capabilities);
329 
330  /**
331  * Sets the page @p names of the config pages that will be used by the
332  * built-in collection properties dialog.
333  *
334  * @param names list of names which will be used
335  * @since 4.6
336  */
337  void setCollectionPropertiesPageNames(const QStringList &names);
338 
339  /**
340  * Create a popup menu.
341  *
342  * @param menu parent menu for a popup
343  * @param type action type
344  * @since 4.8
345  */
346  void createActionFolderMenu(QMenu *menu, Type type);
347 
348  /**
349  * Add a collection to the global recent collection list.
350  *
351  * @param id the collection ID
352  * @since 5.18
353  */
354  void addRecentCollection(Akonadi::Collection::Id id) const;
355 
356 Q_SIGNALS:
357 
358  /**
359  * This signal is emitted whenever one of the selections has changed
360  * (selected collections, selected favorites collections, selected items)
361  * This allows other action managers to update their actions accordingly
362  * (see e.g. StandardMailActionManager)
363  */
364  void selectionsChanged(const Collection::List &selectedCollectionsList,
365  const Collection::List &selectedFavoriteCollectionsList,
366  const Item::List &selectedItems);
367 
368  /**
369  * This signal is emitted whenever the action state has been updated.
370  * In case you have special needs for changing the state of some actions,
371  * connect to this signal and adjust the action state.
372  */
373  void actionStateUpdated();
374 
375 private:
376  /// @cond PRIVATE
377  friend class StandardActionManagerPrivate;
378  std::unique_ptr<StandardActionManagerPrivate> const d;
379 
380  Q_PRIVATE_SLOT(d, void updateActions())
381 
382  Q_PRIVATE_SLOT(d, void slotCreateCollection())
383  Q_PRIVATE_SLOT(d, void slotCopyCollections())
384  Q_PRIVATE_SLOT(d, void slotCutCollections())
385  Q_PRIVATE_SLOT(d, void slotDeleteCollection())
386  Q_PRIVATE_SLOT(d, void slotMoveCollectionToTrash())
387  Q_PRIVATE_SLOT(d, void slotMoveItemToTrash())
388  Q_PRIVATE_SLOT(d, void slotRestoreCollectionFromTrash())
389  Q_PRIVATE_SLOT(d, void slotRestoreItemFromTrash())
390  Q_PRIVATE_SLOT(d, void slotTrashRestoreCollection())
391  Q_PRIVATE_SLOT(d, void slotTrashRestoreItem())
392  Q_PRIVATE_SLOT(d, void slotSynchronizeCollection())
393  Q_PRIVATE_SLOT(d, void slotSynchronizeCollectionRecursive())
394  Q_PRIVATE_SLOT(d, void slotSynchronizeFavoriteCollections())
395  Q_PRIVATE_SLOT(d, void slotCollectionProperties())
396  Q_PRIVATE_SLOT(d, void slotCopyItems())
397  Q_PRIVATE_SLOT(d, void slotCutItems())
398  Q_PRIVATE_SLOT(d, void slotPaste())
399  Q_PRIVATE_SLOT(d, void slotDeleteItems())
400  Q_PRIVATE_SLOT(d, void slotDeleteItemsDeferred(const Akonadi::Item::List &))
401  Q_PRIVATE_SLOT(d, void slotLocalSubscription())
402  Q_PRIVATE_SLOT(d, void slotAddToFavorites())
403  Q_PRIVATE_SLOT(d, void slotRemoveFromFavorites())
404  Q_PRIVATE_SLOT(d, void slotRenameFavorite())
405  Q_PRIVATE_SLOT(d, void slotCopyCollectionTo())
406  Q_PRIVATE_SLOT(d, void slotMoveCollectionTo())
407  Q_PRIVATE_SLOT(d, void slotCopyItemTo())
408  Q_PRIVATE_SLOT(d, void slotMoveItemTo())
409  Q_PRIVATE_SLOT(d, void slotCopyCollectionTo(QAction *))
410  Q_PRIVATE_SLOT(d, void slotMoveCollectionTo(QAction *))
411  Q_PRIVATE_SLOT(d, void slotCopyItemTo(QAction *))
412  Q_PRIVATE_SLOT(d, void slotMoveItemTo(QAction *))
413  Q_PRIVATE_SLOT(d, void slotCreateResource())
414  Q_PRIVATE_SLOT(d, void slotDeleteResource())
415  Q_PRIVATE_SLOT(d, void slotResourceProperties())
416  Q_PRIVATE_SLOT(d, void slotSynchronizeResource())
417  Q_PRIVATE_SLOT(d, void slotToggleWorkOffline(bool))
418  Q_PRIVATE_SLOT(d, void slotSynchronizeCollectionTree())
419  Q_PRIVATE_SLOT(d, void collectionCreationResult(KJob *))
420  Q_PRIVATE_SLOT(d, void moveItemToTrashResult(KJob *))
421  Q_PRIVATE_SLOT(d, void resourceCreationResult(KJob *))
422  Q_PRIVATE_SLOT(d, void pasteResult(KJob *))
423 
424  Q_PRIVATE_SLOT(d, void enableAction(int, bool))
425  Q_PRIVATE_SLOT(d, void updatePluralLabel(int, int))
426  Q_PRIVATE_SLOT(d, void updateAlternatingAction(int))
427  Q_PRIVATE_SLOT(d, bool isFavoriteCollection(const Akonadi::Collection &))
428  /// @endcond
429 };
430 
431 }
432 
@ CopyItems
Copies the selected items.
@ CutItems
Cuts the selected items.
@ SynchronizeFavoriteCollections
Synchronize favorite collections.
Manages generic actions for collection and item views.
@ ErrorMessageTitle
The window title of an error message.
Represents a collection of PIM items.
Definition: collection.h:61
@ Paste
Paste collections or items.
@ ToggleWorkOffline
Toggles the work offline state of all resources.
@ CopyCollectionToDialog
Copy a collection into another collection, select the target in a dialog.
@ CollectionProperties
Provides collection properties.
@ RemoveFromFavoriteCollections
Remove the collection from the favorite collections model.
@ ResourceProperties
Provides the resource properties.
@ RestoreCollectionsFromTrash
Restores the selected collection from trash, needs EntityDeletedAttribute.
@ SynchronizeCollectionsRecursive
Synchronizes collections in a recursive way.
@ RestoreItemsFromTrash
Restores the selected items from trash, needs EntityDeletedAttribute.
@ AddToFavoriteCollections
Add the collection to the favorite collections model.
@ CopyItemToDialog
Copy an item into a collection, select the target in a dialog.
@ SynchronizeResources
Synchronizes the selected resources.
@ CopyCollections
Copies the selected collections.
@ DeleteResources
Deletes the selected resources.
@ MessageBoxTitle
The window title of a message box.
@ CopyCollectionToMenu
Menu allowing to quickly copy a collection into another collection.
@ MessageBoxText
The text of a message box.
@ DialogTitle
The window title of a dialog.
A model that lists a set of favorite collections.
@ CutCollections
Cuts the selected collections.
@ CreateResource
Creates a new resource.
@ ManageLocalSubscriptions
Manages local subscriptions.
@ MoveItemToDialog
Move an item into a collection, select the target in a dialog.
TextContext
Describes the text context that can be customized.
@ SynchronizeCollectionTree
Synchronize collection tree.
Type
Describes the supported actions.
@ DeleteCollections
Deletes the selected collections.
@ MoveToTrashRestoreCollection
Move Collection to Trash or Restore it from Trash, needs EntityDeletedAttribute.
@ CopyItemToMenu
Menu allowing to quickly copy an item into a collection.
@ MoveCollectionToMenu
Menu allowing to move a collection into another collection.
@ DeleteItems
Deletes the selected items.
@ MoveToTrashRestoreItem
Move Item to Trash or Restore it from Trash, needs EntityDeletedAttribute.
@ CreateCollection
Creates an collection.
@ RenameFavoriteCollection
Rename the collection of the favorite collections model.
@ MessageBoxAlternativeText
An alternative text of a message box.
qint64 Id
Describes the unique id type.
Definition: collection.h:79
@ MoveCollectionsToTrash
Moves the selected collection to trash and marks it as deleted, needs EntityDeletedAttribute.
@ MoveItemsToTrash
Moves the selected items to trash and marks them as deleted, needs EntityDeletedAttribute.
@ MoveCollectionToDialog
Move a collection into another collection, select the target in a dialog.
@ SynchronizeCollections
Synchronizes collections.
Represents a PIM item stored in Akonadi storage.
Definition: item.h:104
@ MoveItemToMenu
Menu allowing to move item into a collection.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:00:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.