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

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