1 | /* This file is part of the KDE project |
2 | Copyright (C) 1998-2009 David Faure <faure@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or modify |
5 | it under the terms of the GNU Library General Public License as published |
6 | by the Free Software Foundation; either version 2 of the License or |
7 | ( at your option ) version 3 or, at the discretion of KDE e.V. |
8 | ( which shall act as a proxy as in section 14 of the GPLv3 ), any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KFILEITEMACTIONS_H |
22 | #define KFILEITEMACTIONS_H |
23 | |
24 | #include <kservice.h> |
25 | #include <kfileitem.h> |
26 | #include <kio/kio_export.h> |
27 | |
28 | class KFileItemListProperties; |
29 | class KAction; |
30 | class ; |
31 | class KFileItemActionsPrivate; |
32 | |
33 | /** |
34 | * This class creates and handles the actions for a url (or urls) in a popupmenu. |
35 | * |
36 | * This includes: |
37 | * @li "open with <application>" actions, but also |
38 | * @li builtin services like mount/unmount for old-style device desktop files |
39 | * @li user-defined actions for a .desktop file, defined in the file itself (see the desktop entry standard) |
40 | * @li servicemenus actions, defined in .desktop files and selected based on the mimetype of the url |
41 | * |
42 | * @since 4.3 |
43 | */ |
44 | class KIO_EXPORT KFileItemActions : public QObject |
45 | { |
46 | Q_OBJECT |
47 | public: |
48 | /** |
49 | * Creates a KFileItemActions instance. |
50 | * Note that this instance must stay alive for at least as long as the popupmenu; |
51 | * it has the slots for the actions created by addOpenWithActionsTo/addServiceActionsTo. |
52 | */ |
53 | KFileItemActions(QObject* parent = 0); |
54 | |
55 | /** |
56 | * Destructor |
57 | */ |
58 | ~KFileItemActions(); |
59 | |
60 | /** |
61 | * Sets all the data for the next instance of the popupmenu. |
62 | * @see KFileItemListProperties |
63 | */ |
64 | void setItemListProperties(const KFileItemListProperties& itemList); |
65 | |
66 | /** |
67 | * Set the parent widget for any dialogs being shown. |
68 | * |
69 | * This should normally be your mainwindow, not a popup menu, |
70 | * so that it still exists even after the popup is closed |
71 | * (e.g. error message from KRun) and so that QAction::setStatusTip |
72 | * can find a statusbar, too. |
73 | */ |
74 | void setParentWidget(QWidget* widget); |
75 | |
76 | /** |
77 | * Generate the "Open With <Application>" actions, and adds them to the @p menu. |
78 | * All actions are created as children of the menu. |
79 | * @param menu the QMenu where to add actions |
80 | * @param traderConstraint this constraint allows to exclude the current application |
81 | * from the "open with" list. Example: "DesktopEntryName != 'kfmclient'". |
82 | * (Default value added in kdelibs-4.5, pass QString() explicitely for earlier versions). |
83 | */ |
84 | void (QMenu* , const QString& traderConstraint = QString()); |
85 | |
86 | /** |
87 | * Returns an action for the preferred application only. |
88 | * @param traderConstraint this constraint allows to exclude the current application |
89 | * from the "open with" list. Example: "DesktopEntryName != 'kfmclient'". |
90 | * @return the action - or 0 if no application was found. |
91 | */ |
92 | KAction* preferredOpenWithAction(const QString& traderConstraint); |
93 | |
94 | /** |
95 | * Helper method used internally, can also be used for similar GUIs that |
96 | * show the list of associated applications. |
97 | * Used in KParts::BrowserOpenOrSaveQuestion for example. |
98 | * |
99 | * This is basically a KMimeTypeTrader::query, but it supports multiple mimetypes, and |
100 | * also cleans up "apparent" duplicates, such as the kde3 and kde4 applications with the same name. |
101 | * |
102 | * The list is sorted according to the user preferences for the given mimetype(s). |
103 | * In case multiple mimetypes appear in the url list, the logic is: |
104 | * applications that on average appear earlier on the associated applications |
105 | * list for the given mimetypes also appear earlier on the final applications list. |
106 | * |
107 | * Note that for a single mimetype there is no need to use this, you should use |
108 | * KMimeTypeTrader instead, e.g. query() or preferredService(). |
109 | * |
110 | * Returns the applications associated with all the given mimetypes. |
111 | * @param mimeTypeList the mimetypes |
112 | * @param traderConstraint this optional constraint allows to exclude the current application |
113 | * from the "open with" list. Example: "DesktopEntryName != 'kfmclient'". |
114 | * @return the sorted list of services. |
115 | * @since 4.4 |
116 | */ |
117 | static KService::List associatedApplications(const QStringList& mimeTypeList, const QString& traderConstraint); |
118 | |
119 | /** |
120 | * Generate the user-defined actions and submenus, and adds them to the @p menu. |
121 | * User-defined actions include: |
122 | * - builtin services like mount/unmount for old-style device desktop files |
123 | * - user-defined actions for a .desktop file, defined in the file itself (see the desktop entry standard) |
124 | * - servicemenus actions, defined in .desktop files and selected based on the mimetype of the url |
125 | * |
126 | * When KFileItemListProperties::supportsWriting() is false, actions that modify the files are not shown. |
127 | * This is controlled by Require=Write in the servicemenu desktop files. |
128 | * |
129 | * All actions are created as children of the menu. |
130 | * @return the number of actions added |
131 | */ |
132 | int (QMenu* ); |
133 | |
134 | Q_SIGNALS: |
135 | /** |
136 | * Emitted before the "Open With" dialog is shown |
137 | * This is used e.g in folderview to close the folder peek popups on invoking the "Open With" menu action |
138 | * @since 4.8.2 |
139 | */ |
140 | void openWithDialogAboutToBeShown(); |
141 | |
142 | public Q_SLOTS: |
143 | /** |
144 | * Slot used to execute a list of files in their respective preferred application. |
145 | * @param fileOpenList the list of KFileItems to open. |
146 | * @param traderConstraint this optional constraint allows to exclude the current application |
147 | * @since 4.5 |
148 | */ |
149 | void runPreferredApplications(const KFileItemList& fileOpenList, const QString& traderConstraint); |
150 | |
151 | private: |
152 | KFileItemActionsPrivate* const d; |
153 | friend class KFileItemActionsPrivate; |
154 | }; |
155 | |
156 | #endif /* KFILEITEMACTIONS_H */ |
157 | |
158 | |