File indexing completed on 2024-06-09 07:40:59

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 1998-2009 David Faure <faure@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0006 */
0007 
0008 #ifndef KFILEITEMACTIONS_H
0009 #define KFILEITEMACTIONS_H
0010 
0011 #include "kiowidgets_export.h"
0012 #include <KService>
0013 #include <kfileitem.h>
0014 
0015 #include <memory>
0016 
0017 class KFileItemListProperties;
0018 class QAction;
0019 class QMenu;
0020 class KFileItemActionsPrivate;
0021 
0022 /**
0023  * @class KFileItemActions kfileitemactions.h <KFileItemActions>
0024  *
0025  * This class creates and handles the actions for a url (or urls) in a popupmenu.
0026  *
0027  * This includes:
0028  * @li "open with <application>" actions, but also
0029  * @li user-defined actions for a .desktop file, defined in the file itself (see the desktop entry standard)
0030  * @li servicemenus actions, defined in .desktop files and selected based on the MIME type of the url
0031  *
0032  * KFileItemActions respects Kiosk-based restrictions (see the KAuthorized
0033  * namespace in the KConfig framework). In particular, the "action/openwith"
0034  * action is checked when determining actions for opening files (see
0035  * addOpenWithActionsTo()) and service-specific actions are checked before
0036  * adding service actions to a menu (see addServiceActionsTo()).
0037  *
0038  * For user-defined actions in a .desktop file, the "X-KDE-AuthorizeAction" key
0039  * can be used to determine which actions are checked before the user-defined
0040  * action is allowed.  The action is ignored if any of the listed actions are
0041  * not authorized.
0042  *
0043  * @note: The builtin services like mount/unmount for old-style device desktop
0044  * files (which mainly concerns CDROM and Floppy drives) have been deprecated
0045  * since 5.82; those menu entries were hidden long before that, since the FSDevice
0046  * .desktop template file hadn't been installed for quite a while.
0047  *
0048  */
0049 class KIOWIDGETS_EXPORT KFileItemActions : public QObject
0050 {
0051     Q_OBJECT
0052 public:
0053     /**
0054      * Creates a KFileItemActions instance.
0055      * Note that this instance must stay alive for at least as long as the popupmenu;
0056      * it has the slots for the actions created by addOpenWithActionsTo/addServiceActionsTo.
0057      */
0058     KFileItemActions(QObject *parent = nullptr);
0059 
0060     /**
0061      * Destructor
0062      */
0063     ~KFileItemActions() override;
0064 
0065     /**
0066      * Sets all the data for the next instance of the popupmenu.
0067      * @see KFileItemListProperties
0068      */
0069     void setItemListProperties(const KFileItemListProperties &itemList);
0070 
0071     /**
0072      * Set the parent widget for any dialogs being shown.
0073      *
0074      * This should normally be your mainwindow, not a popup menu,
0075      * so that it still exists even after the popup is closed
0076      * (e.g. error message from KRun) and so that QAction::setStatusTip
0077      * can find a statusbar, too.
0078      */
0079     void setParentWidget(QWidget *widget);
0080 
0081     /**
0082      * Generates the "Open With <Application>" actions, and inserts them in @p menu,
0083      * before action @p before. If @p before is nullptr or doesn't exist in the menu
0084      * the actions will be appended to the menu.
0085      *
0086      * All actions are created as children of the menu.
0087      *
0088      * No actions will be added if the "openwith" Kiosk action is not authorized
0089      * (see KAuthorized::authorize()).
0090      *
0091      * @param before the "open with" actions will be inserted before this action; if this action
0092      * is nullptr or isn't available in @p topMenu, the "open with" actions will be appended
0093      * @param menu the QMenu where the actions will be added
0094      * @param excludedDesktopEntryNames list of desktop entry names that will not be shown
0095      *
0096      * @since 5.82
0097      */
0098     void insertOpenWithActionsTo(QAction *before, QMenu *topMenu, const QStringList &excludedDesktopEntryNames);
0099 
0100     /**
0101      * Returns the applications associated with all the given MIME types.
0102      *
0103      * This is basically a KApplicationTrader::query, but it supports multiple MIME types, and
0104      * also cleans up "apparent" duplicates, such as different versions of the same
0105      * application installed in parallel.
0106      *
0107      * The list is sorted according to the user preferences for the given MIME type(s).
0108      * In case multiple MIME types appear in the URL list, the logic is:
0109      * applications that on average appear earlier on the associated applications
0110      * list for the given MIME types also appear earlier on the final applications list.
0111      *
0112      * Note that for a single MIME type there is no need to use this, you should use
0113      * KApplicationTrader instead, e.g. query() or preferredService().
0114      *
0115      * This will return an empty list if the "openwith" Kiosk action is not
0116      * authorized (see @c KAuthorized::authorize()).
0117      *
0118      * @param mimeTypeList the MIME types
0119      * @return the sorted list of services.
0120      * @since 5.83
0121      */
0122     static KService::List associatedApplications(const QStringList &mimeTypeList);
0123 
0124     enum class MenuActionSource {
0125         Services = 0x1, ///< Add user defined actions and servicemenu actions (this used to include builtin
0126                         ///< actions, which have been deprecated since 5.82 see class API documentation)
0127         Plugins = 0x2, ///< Add actions implemented by plugins. See KAbstractFileItemActionPlugin base class.
0128         All = Services | Plugins,
0129     };
0130     Q_DECLARE_FLAGS(MenuActionSources, MenuActionSource)
0131 
0132     /**
0133      * This methods adds additional actions to the menu.
0134      * @param menu Menu to which the actions/submenus will be added.
0135      * @param sources sources from which the actions should be fetched. By default all sources are used.
0136      * @param additionalActions additional actions that should be added to the "Actions" submenu or
0137      * top level menu if there are less than three entries in total.
0138      * @param excludeList list of action names or plugin ids that should be excluded
0139      * @since 5.77
0140      */
0141     void addActionsTo(QMenu *menu,
0142                       MenuActionSources sources = MenuActionSource::All,
0143                       const QList<QAction *> &additionalActions = {},
0144                       const QStringList &excludeList = {});
0145 
0146 Q_SIGNALS:
0147     /**
0148      * Emitted before the "Open With" dialog is shown
0149      * This is used e.g in folderview to close the folder peek popups on invoking the "Open With" menu action
0150      * @since 4.8.2
0151      */
0152     void openWithDialogAboutToBeShown();
0153 
0154     /**
0155      * Forwards the errors from the KAbstractFileItemActionPlugin instances
0156      * @since 5.82
0157      */
0158     void error(const QString &errorMessage);
0159 
0160 public Q_SLOTS:
0161     /**
0162      * Slot used to execute a list of files in their respective preferred application.
0163      * @param fileOpenList the list of KFileItems to open.
0164      * @since 5.83
0165      */
0166     void runPreferredApplications(const KFileItemList &fileOpenList);
0167 
0168 private:
0169     std::unique_ptr<KFileItemActionsPrivate> const d;
0170     friend class KFileItemActionsPrivate;
0171 };
0172 Q_DECLARE_OPERATORS_FOR_FLAGS(KFileItemActions::MenuActionSources)
0173 
0174 #endif /* KFILEITEMACTIONS_H */