KIO

applicationlauncherjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2020 David Faure <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6 */
7 
8 #ifndef KIO_APPLICATIONLAUNCHERJOB_H
9 #define KIO_APPLICATIONLAUNCHERJOB_H
10 
11 #include "kiogui_export.h"
12 #include <KJob>
13 #include <KService>
14 #include <QUrl>
15 
16 class KRun; // KF6 REMOVE
17 class ApplicationLauncherJobTest; // KF6 REMOVE
18 
19 namespace KIO
20 {
21 class ApplicationLauncherJobPrivate;
22 
23 /**
24  * @class ApplicationLauncherJob applicationlauncherjob.h <KIO/ApplicationLauncherJob>
25  *
26  * @brief ApplicationLauncherJob runs an application and watches it while running.
27  *
28  * It creates a startup notification and finishes it on success or on error (for the taskbar).
29  * It also emits an error message if necessary (e.g. "program not found").
30  *
31  * When passing multiple URLs to an application that doesn't support opening
32  * multiple files, the application will be launched once for each URL.
33  *
34  * The job finishes when the application is successfully started. At that point you can
35  * query the PID(s).
36  *
37  * For error handling, either connect to the result() signal, or for a simple messagebox on error,
38  * you can use:
39  * @code
40  * job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
41  * @endcode
42  * Using JobUiDelegate (which is widgets based) also enables the feature of asking the user
43  * in case the executable or desktop file isn't marked as executable. Otherwise the job will
44  * just refuse executing such files.
45  *
46  * To invoke the open-with dialog (from KIOWidgets), construct an ApplicationLauncherJob without
47  * any arguments or with a null KService.
48  *
49  * @since 5.69
50  */
51 class KIOGUI_EXPORT ApplicationLauncherJob : public KJob
52 {
53 public:
54  /**
55  * Creates an ApplicationLauncherJob.
56  * @param service the service (application desktop file) to run
57  * @param parent the parent QObject
58  */
59  explicit ApplicationLauncherJob(const KService::Ptr &service, QObject *parent = nullptr);
60 
61  /**
62  * Creates an ApplicationLauncherJob.
63  * @param serviceAction the service action to run
64  * @param parent the parent QObject
65  */
66  explicit ApplicationLauncherJob(const KServiceAction &serviceAction, QObject *parent = nullptr);
67 
68  /**
69  * Creates an ApplicationLauncherJob which will prompt the user for which application to use
70  * (via the open-with dialog from KIOWidgets).
71  * @param parent the parent QObject
72  * @since 5.71
73  */
74  explicit ApplicationLauncherJob(QObject *parent = nullptr);
75 
76  /**
77  * Destructor
78  *
79  * Note that jobs auto-delete themselves after emitting result.
80  * Deleting/killing the job will not stop the started application.
81  */
82  ~ApplicationLauncherJob() override;
83 
84  /**
85  * Specifies the URLs to be passed to the application.
86  * @param urls list of files (local or remote) to open
87  *
88  * Note that when passing multiple URLs to an application that doesn't support opening
89  * multiple files, the application will be launched once for each URL.
90  */
91  void setUrls(const QList<QUrl> &urls);
92 
93  /**
94  * @see RunFlag
95  */
96  enum RunFlag {
97  DeleteTemporaryFiles = 0x1, ///< the URLs passed to the service will be deleted when it exits (if the URLs are local files)
98  };
99  /**
100  * Stores a combination of #RunFlag values.
101  */
102  Q_DECLARE_FLAGS(RunFlags, RunFlag)
103 
104  /**
105  * Specifies various flags.
106  * @param runFlags the flags to be set. For instance, whether the URLs are temporary files that should be deleted after execution.
107  */
108  void setRunFlags(RunFlags runFlags);
109 
110  /**
111  * Sets the file name to use in the case of downloading the file to a tempfile
112  * in order to give to a non-URL-aware application.
113  * Some apps rely on the extension to determine the MIME type of the file.
114  * Usually the file name comes from the URL, but in the case of the
115  * HTTP Content-Disposition header, we need to override the file name.
116  * @param suggestedFileName the file name
117  */
118  void setSuggestedFileName(const QString &suggestedFileName);
119 
120  /**
121  * Sets the startup notification id of the application launch.
122  * @param startupId startup notification id, if any (otherwise "").
123  */
124  void setStartupId(const QByteArray &startupId);
125 
126  /**
127  * Starts the job.
128  * You must call this, after having done all the setters.
129  * This is (potentially) a GUI job, never use exec(), it would block user interaction.
130  */
131  void start() override;
132 
133  /**
134  * @return the PID of the application that was started
135  *
136  * Convenience method for pids().at(0). You should only use this when specifying zero or one URL,
137  * or when you are sure that the application supports opening multiple files. Otherwise use pids().
138  * Available after the job emits result().
139  */
140  qint64 pid() const;
141 
142  /**
143  * @return the PIDs of the applications that were started
144  *
145  * Available after the job emits result().
146  */
147  QVector<qint64> pids() const;
148 
149 private:
150  friend class ::KRun; // KF6 REMOVE
151  friend class ::ApplicationLauncherJobTest; // KF6 REMOVE
152  /**
153  * Blocks until the process has started. Only exists for KRun, will disappear in KF6.
154  */
155  bool waitForStarted();
156  void emitUnauthorizedError();
157  void proceedAfterSecurityChecks();
158 
159  friend class ApplicationLauncherJobPrivate;
160  QScopedPointer<ApplicationLauncherJobPrivate> d;
161 };
162 
163 } // namespace KIO
164 
165 #endif
A namespace for KIO globals.
To open files with their associated applications in KDE, use KRun.
Definition: krun.h:52
ApplicationLauncherJob runs an application and watches it while running.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu May 6 2021 23:00:20 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.