1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1998-2009 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KFILEITEMACTIONS_H
9#define KFILEITEMACTIONS_H
10
11#include "kiowidgets_export.h"
12#include <KService>
13#include <kfileitem.h>
14
15#include <memory>
16
17class KFileItemListProperties;
18class QAction;
19class QMenu;
20class KFileItemActionsPrivate;
21
22/**
23 * @class KFileItemActions kfileitemactions.h <KFileItemActions>
24 *
25 * This class creates and handles the actions for a url (or urls) in a popupmenu.
26 *
27 * This includes:
28 * @li "open with <application>" actions, but also
29 * @li user-defined actions for a .desktop file, defined in the file itself (see the desktop entry standard)
30 * @li servicemenus actions, defined in .desktop files and selected based on the MIME type of the url
31 *
32 * KFileItemActions respects Kiosk-based restrictions (see the KAuthorized
33 * namespace in the KConfig framework). In particular, the "action/openwith"
34 * action is checked when determining actions for opening files (see
35 * addOpenWithActionsTo()) and service-specific actions are checked before
36 * adding service actions to a menu (see addServiceActionsTo()).
37 *
38 * For user-defined actions in a .desktop file, the "X-KDE-AuthorizeAction" key
39 * can be used to determine which actions are checked before the user-defined
40 * action is allowed. The action is ignored if any of the listed actions are
41 * not authorized.
42 *
43 * @note: The builtin services like mount/unmount for old-style device desktop
44 * files (which mainly concerns CDROM and Floppy drives) have been deprecated
45 * since 5.82; those menu entries were hidden long before that, since the FSDevice
46 * .desktop template file hadn't been installed for quite a while.
47 *
48 */
49class KIOWIDGETS_EXPORT KFileItemActions : public QObject
50{
51 Q_OBJECT
52public:
53 /**
54 * Creates a KFileItemActions instance.
55 * Note that this instance must stay alive for at least as long as the popupmenu;
56 * it has the slots for the actions created by addOpenWithActionsTo/addServiceActionsTo.
57 */
58 KFileItemActions(QObject *parent = nullptr);
59
60 /**
61 * Destructor
62 */
63 ~KFileItemActions() override;
64
65 /**
66 * Sets all the data for the next instance of the popupmenu.
67 * @see KFileItemListProperties
68 */
69 void setItemListProperties(const KFileItemListProperties &itemList);
70
71 /**
72 * Set the parent widget for any dialogs being shown.
73 *
74 * This should normally be your mainwindow, not a popup menu,
75 * so that it still exists even after the popup is closed
76 * (e.g. error message from KRun) and so that QAction::setStatusTip
77 * can find a statusbar, too.
78 */
79 void setParentWidget(QWidget *widget);
80
81 /**
82 * Generates the "Open With <Application>" actions, and inserts them in @p menu,
83 * before action @p before. If @p before is nullptr or doesn't exist in the menu
84 * the actions will be appended to the menu.
85 *
86 * All actions are created as children of the menu.
87 *
88 * No actions will be added if the "openwith" Kiosk action is not authorized
89 * (see KAuthorized::authorize()).
90 *
91 * @param before the "open with" actions will be inserted before this action; if this action
92 * is nullptr or isn't available in @p topMenu, the "open with" actions will be appended
93 * @param menu the QMenu where the actions will be added
94 * @param excludedDesktopEntryNames list of desktop entry names that will not be shown
95 *
96 * @since 5.82
97 */
98 void insertOpenWithActionsTo(QAction *before, QMenu *topMenu, const QStringList &excludedDesktopEntryNames);
99
100 /**
101 * Returns the applications associated with all the given MIME types.
102 *
103 * This is basically a KApplicationTrader::query, but it supports multiple MIME types, and
104 * also cleans up "apparent" duplicates, such as different versions of the same
105 * application installed in parallel.
106 *
107 * The list is sorted according to the user preferences for the given MIME type(s).
108 * In case multiple MIME types appear in the URL list, the logic is:
109 * applications that on average appear earlier on the associated applications
110 * list for the given MIME types also appear earlier on the final applications list.
111 *
112 * Note that for a single MIME type there is no need to use this, you should use
113 * KApplicationTrader instead, e.g. query() or preferredService().
114 *
115 * This will return an empty list if the "openwith" Kiosk action is not
116 * authorized (see @c KAuthorized::authorize()).
117 *
118 * @param mimeTypeList the MIME types
119 * @return the sorted list of services.
120 * @since 5.83
121 */
122 static KService::List associatedApplications(const QStringList &mimeTypeList);
123
124 enum class MenuActionSource {
125 Services = 0x1, ///< Add user defined actions and servicemenu actions (this used to include builtin
126 ///< actions, which have been deprecated since 5.82 see class API documentation)
127 Plugins = 0x2, ///< Add actions implemented by plugins. See KAbstractFileItemActionPlugin base class.
128 All = Services | Plugins,
129 };
130 Q_DECLARE_FLAGS(MenuActionSources, MenuActionSource)
131
132 /**
133 * This methods adds additional actions to the menu.
134 * @param menu Menu to which the actions/submenus will be added.
135 * @param sources sources from which the actions should be fetched. By default all sources are used.
136 * @param additionalActions additional actions that should be added to the "Actions" submenu or
137 * top level menu if there are less than three entries in total.
138 * @param excludeList list of action names or plugin ids that should be excluded
139 * @since 5.77
140 */
141 void addActionsTo(QMenu *menu,
142 MenuActionSources sources = MenuActionSource::All,
143 const QList<QAction *> &additionalActions = {},
144 const QStringList &excludeList = {});
145
146Q_SIGNALS:
147 /**
148 * Emitted before the "Open With" dialog is shown
149 * This is used e.g in folderview to close the folder peek popups on invoking the "Open With" menu action
150 * @since 4.8.2
151 */
152 void openWithDialogAboutToBeShown();
153
154 /**
155 * Forwards the errors from the KAbstractFileItemActionPlugin instances
156 * @since 5.82
157 */
158 void error(const QString &errorMessage);
159
160public Q_SLOTS:
161 /**
162 * Slot used to execute a list of files in their respective preferred application.
163 * @param fileOpenList the list of KFileItems to open.
164 * @since 5.83
165 */
166 void runPreferredApplications(const KFileItemList &fileOpenList);
167
168private:
169 std::unique_ptr<KFileItemActionsPrivate> const d;
170 friend class KFileItemActionsPrivate;
171};
172Q_DECLARE_OPERATORS_FOR_FLAGS(KFileItemActions::MenuActionSources)
173
174#endif /* KFILEITEMACTIONS_H */
175

source code of kio/src/widgets/kfileitemactions.h