Akonadi

standardactionmanager.h
1/*
2 SPDX-FileCopyrightText: 2008 Volker Krause <vkrause@kde.org>
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
19class QAction;
23class QWidget;
24class QMenu;
25
26namespace Akonadi
27{
28class FavoriteCollectionsModel;
29class 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 <vkrause@kde.org>
115 */
116class AKONADIWIDGETS_EXPORT StandardActionManager : public QObject
117{
118 Q_OBJECT
119public:
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 */
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 */
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
356Q_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 */
374
375private:
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}
Represents a collection of PIM items.
Definition collection.h:62
qint64 Id
Describes the unique id type.
Definition collection.h:79
A model that lists a set of favorite collections.
Represents a PIM item stored in Akonadi storage.
Definition item.h:101
Manages generic actions for collection and item views.
void actionStateUpdated()
This signal is emitted whenever the action state has been updated.
Type
Describes the supported actions.
@ CreateResource
Creates a new resource.
@ CreateCollection
Creates an collection.
@ MoveToTrashRestoreItem
Move Item to Trash or Restore it from Trash, needs EntityDeletedAttribute.
@ SynchronizeResources
Synchronizes the selected resources.
@ RemoveFromFavoriteCollections
Remove the collection from the favorite collections model.
@ DeleteItems
Deletes the selected items.
@ CopyCollectionToDialog
Copy a collection into another collection, select the target in a dialog.
@ SynchronizeCollections
Synchronizes collections.
@ MoveCollectionToDialog
Move a collection into another collection, select the target in a dialog.
@ CopyItemToMenu
Menu allowing to quickly copy an item into a collection.
@ RenameFavoriteCollection
Rename the collection of the favorite collections model.
@ SynchronizeFavoriteCollections
Synchronize favorite collections.
@ ResourceProperties
Provides the resource properties.
@ CutItems
Cuts the selected items.
@ DeleteCollections
Deletes the selected collections.
@ MoveToTrashRestoreCollection
Move Collection to Trash or Restore it from Trash, needs EntityDeletedAttribute.
@ ToggleWorkOffline
Toggles the work offline state of all resources.
@ ManageLocalSubscriptions
Manages local subscriptions.
@ CutCollections
Cuts the selected collections.
@ CopyCollectionToMenu
Menu allowing to quickly copy a collection into another collection.
@ MoveItemToMenu
Menu allowing to move item into a collection.
@ AddToFavoriteCollections
Add the collection to the favorite collections model.
@ SynchronizeCollectionsRecursive
Synchronizes collections in a recursive way.
@ SynchronizeCollectionTree
Synchronize collection tree.
@ MoveItemsToTrash
Moves the selected items to trash and marks them as deleted, needs EntityDeletedAttribute.
@ CopyCollections
Copies the selected collections.
@ Paste
Paste collections or items.
@ CollectionProperties
Provides collection properties.
@ DeleteResources
Deletes the selected resources.
@ RestoreItemsFromTrash
Restores the selected items from trash, needs EntityDeletedAttribute.
@ RestoreCollectionsFromTrash
Restores the selected collection from trash, needs EntityDeletedAttribute.
@ CopyItems
Copies the selected items.
@ MoveCollectionToMenu
Menu allowing to move a collection into another collection.
@ MoveItemToDialog
Move an item into a collection, select the target in a dialog.
@ CopyItemToDialog
Copy an item into a collection, select the target in a dialog.
@ MoveCollectionsToTrash
Moves the selected collection to trash and marks it as deleted, needs EntityDeletedAttribute.
~StandardActionManager() override
Destroys the standard action manager.
void selectionsChanged(const Collection::List &selectedCollectionsList, const Collection::List &selectedFavoriteCollectionsList, const Item::List &selectedItems)
This signal is emitted whenever one of the selections has changed (selected collections,...
TextContext
Describes the text context that can be customized.
@ MessageBoxText
The text of a message box.
@ MessageBoxTitle
The window title of a message box.
@ DialogTitle
The window title of a dialog.
@ ErrorMessageTitle
The window title of an error message.
@ MessageBoxAlternativeText
An alternative text of a message box.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:51:45 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.