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
28class KFileItemListProperties;
29class KAction;
30class QMenu;
31class 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 */
44class KIO_EXPORT KFileItemActions : public QObject
45{
46 Q_OBJECT
47public:
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 addOpenWithActionsTo(QMenu* menu, 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 addServiceActionsTo(QMenu* menu);
133
134Q_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
142public 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
151private:
152 KFileItemActionsPrivate* const d;
153 friend class KFileItemActionsPrivate;
154};
155
156#endif /* KFILEITEMACTIONS_H */
157
158