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
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
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
406
407
408
|
/*
Copyright (c) 2008 Volker Krause <vkrause@kde.org>
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published by
the Free Software Foundation; either version 2 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 Library General Public
License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
*/
#ifndef AKONADI_STANDARDACTIONMANAGER_H
#define AKONADI_STANDARDACTIONMANAGER_H
#include "akonadi_export.h"
#include <QtCore/QObject>
#include <akonadi/collection.h>
#include <akonadi/item.h>
class KAction;
class KActionCollection;
class KLocalizedString;
class QItemSelectionModel;
class QWidget;
class QMenu;
namespace Akonadi {
class FavoriteCollectionsModel;
/**
* @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.
*
* 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
* connect( manager->action( StandardActionManager::CopyCollections ), SIGNAL( triggered( bool ) ),
* this, SLOT( myCopyImplementation() ) );
* ...
*
* void MyClass::myCopyImplementation()
* {
* const Collection::List collections = manager->selectedCollections();
* foreach ( const Collection &collection, collections ) {
* // copy the collection manually...
* }
* }
*
* @endcode
*
* @todo collection deleting and sync do not support multi-selection yet
*
* @author Volker Krause <vkrause@kde.org>
*/
class AKONADI_EXPORT StandardActionManager : public QObject
{
Q_OBJECT
public:
/**
* Describes the supported actions.
*/
enum Type {
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
LastType ///< Marks last action
};
/**
* Describes the text context that can be customized.
*/
enum TextContext {
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
};
/**
* Creates a new standard action manager.
*
* @param actionCollection The action collection to operate on.
* @param parent The parent widget.
*/
explicit StandardActionManager( KActionCollection *actionCollection, QWidget *parent = 0 );
/**
* Destroys the standard action manager.
*/
~StandardActionManager();
/**
* Sets the collection selection model based on which the collection
* related actions should operate. If none is set, all collection actions
* will be disabled.
*/
void setCollectionSelectionModel( QItemSelectionModel *selectionModel );
/**
* Sets the item selection model based on which the item related actions
* should operate. If none is set, all item actions will be disabled.
*/
void setItemSelectionModel( QItemSelectionModel* selectionModel );
/**
* 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.
*
* @since 4.4
*/
void setFavoriteCollectionsModel( FavoriteCollectionsModel *favoritesModel );
/**
* 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.
*
* @since 4.4
*/
void setFavoriteSelectionModel( QItemSelectionModel *selectionModel );
/**
* 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.
*/
KAction* createAction( Type type );
/**
* Convenience method to create all standard actions.
* @see createAction()
*/
void createAllActions();
/**
* Returns the action of the given type, 0 if it has not been created (yet).
*/
KAction* action( Type type ) const;
/**
* 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.
*
* Example:
* @code
* acctMgr->setActionText( Akonadi::StandardActionManager::CopyItems,
* ki18np( "Copy Mail", "Copy %1 Mails" ) );
* @endcode
*/
void setActionText( Type type, const KLocalizedString &text );
/**
* Sets whether the default implementation for the given action @p type
* shall be executed when the action is triggered.
*
* @param intercept If @c false, the default implementation will be executed,
* if @c true no action is taken.
*
* @since 4.6
*/
void interceptAction( Type type, bool intercept = true );
/**
* 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;
/**
* Sets the @p text of the action @p type for the given @p context.
*
* @since 4.6
*/
void setContextText( Type type, TextContext context, const QString &text );
/**
* Sets the @p text of the action @p type for the given @p context.
*
* @since 4.6
*/
void setContextText( Type type, TextContext context, const KLocalizedString &text );
/**
* Sets the mime type filter that will be used when creating new resources.
*
* @since 4.6
*/
void setMimeTypeFilter( const QStringList &mimeTypes );
/**
* Sets the capability filter that will be used when creating new resources.
*
* @since 4.6
*/
void setCapabilityFilter( const QStringList &capabilities );
/**
* Sets the page @p names of the config pages that will be used by the
* built-in collection properties dialog.
*
* @since 4.6
*/
void setCollectionPropertiesPageNames( const QStringList &names );
/**
* Create a popup menu.
* @since 4.8
*/
void createActionFolderMenu(QMenu *menu, Type type);
Q_SIGNALS:
/**
* 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.
*/
void actionStateUpdated();
private:
//@cond PRIVATE
class Private;
Private* const d;
Q_PRIVATE_SLOT( d, void updateActions() )
#ifndef QT_NO_CLIPBOARD
Q_PRIVATE_SLOT( d, void clipboardChanged(QClipboard::Mode) )
#endif
Q_PRIVATE_SLOT( d, void collectionSelectionChanged() )
Q_PRIVATE_SLOT( d, void favoriteSelectionChanged() )
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) )
Q_PRIVATE_SLOT( d, void collectionCreationResult(KJob*) )
Q_PRIVATE_SLOT( d, void collectionDeletionResult(KJob*) )
Q_PRIVATE_SLOT( d, void moveCollectionToTrashResult(KJob*) )
Q_PRIVATE_SLOT( d, void moveItemToTrashResult(KJob*) )
Q_PRIVATE_SLOT( d, void itemDeletionResult(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&) )
Q_PRIVATE_SLOT( d, void aboutToShowMenu() )
//@endcond
};
}
#endif
|