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 | |
17 | class KFileItemListProperties; |
18 | class QAction; |
19 | class ; |
20 | class 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 | */ |
51 | class KIOWIDGETS_EXPORT KFileItemActions : public QObject |
52 | { |
53 | Q_OBJECT |
54 | public: |
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 (QAction *before, QMenu *, 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 { |
135 | = 0x1, |
136 | = 0x2, |
137 | = Services | Plugins, |
138 | }; |
139 | Q_DECLARE_FLAGS(, 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 (QMenu *, |
156 | MenuActionSources sources = MenuActionSource::All, |
157 | const QList<QAction *> &additionalActions = {}, |
158 | const QStringList &excludeList = {}); |
159 | |
160 | Q_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 | |
174 | public 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 | |
184 | private: |
185 | std::unique_ptr<KFileItemActionsPrivate> const d; |
186 | friend class KFileItemActionsPrivate; |
187 | }; |
188 | Q_DECLARE_OPERATORS_FOR_FLAGS(KFileItemActions::MenuActionSources) |
189 | |
190 | #endif /* KFILEITEMACTIONS_H */ |
191 | |