File indexing completed on 2025-01-05 04:47:11

 /*
     SPDX-FileCopyrightText: 2008 Volker Krause <vkrause@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #pragma once
 
 #include "akonadiwidgets_export.h"
 
 // AkonadiCore
 #include "akonadi/collection.h"
 #include "akonadi/item.h"
 
 #include <QObject>
 
 #include <memory>
 
 class QAction;
 class KActionCollection;
 class KLocalizedString;
 class QItemSelectionModel;
 class QWidget;
 class QMenu;
 
 namespace Akonadi
 {
 class FavoriteCollectionsModel;
 class StandardActionManagerPrivate;
 
 /**
  * @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();
  *   for ( 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 AKONADIWIDGETS_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
         SynchronizeCollectionTree, ///< Synchronize collection tree @since 4.15
         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 = nullptr);
 
     /**
      * Destroys the standard action manager.
      */
     ~StandardActionManager() override;
 
     /**
      * Sets the collection selection model based on which the collection
      * related actions should operate. If none is set, all collection actions
      * will be disabled.
      *
      * @param selectionModel model to be set for collection
      */
     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.
      *
      * @param selectionModel selection model for items
      */
     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.
      *
      * @param favoritesModel model for the user's favorite collections
      * @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.
      *
      * @param selectionModel selection model for favorite collections
      * @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.
      *
      * @param type action to be created
      */
     QAction *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).
      * @param type action type
      */
     QAction *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.
      * @param type the action to set a text for
      * @param text the text to display for the given action
      * 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 type action type
      * @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.
      *
      * @param type action type
      * @param context context for action
      * @param text content to set for the action
      * @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.
      *
      * @param type action type
      * @param context context for action
      * @param text content to set for the action
      * @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.
      *
      * @param mimeTypes filter for creating new resources
      * @since 4.6
      */
     void setMimeTypeFilter(const QStringList &mimeTypes);
 
     /**
      * Sets the capability filter that will be used when creating new resources.
      *
      * @param capabilities filter for 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.
      *
      * @param names list of names which will be used
      * @since 4.6
      */
     void setCollectionPropertiesPageNames(const QStringList &names);
 
     /**
      * Create a popup menu.
      *
      * @param menu parent menu for a popup
      * @param type action type
      * @since 4.8
      */
     void createActionFolderMenu(QMenu *menu, Type type);
 
     /**
      * Add a collection to the global recent collection list.
      *
      * @param id the collection ID
      * @since 5.18
      */
     void addRecentCollection(Akonadi::Collection::Id id) const;
 
 Q_SIGNALS:
 
     /**
      * 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);
 
     /**
      * 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
     friend class StandardActionManagerPrivate;
     std::unique_ptr<StandardActionManagerPrivate> const d;
 
     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))
     Q_PRIVATE_SLOT(d, void slotSynchronizeCollectionTree())
     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 &))
     /// @endcond
 };
 
 }