KIO

commandlauncherjob.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_COMMANDLAUNCHERJOB_H
9 #define KIO_COMMANDLAUNCHERJOB_H
10 
11 #include "kiogui_export.h"
12 #include <KJob>
13 
14 class KRunPrivate; // KF6 REMOVE
15 class CommandLauncherJobTest; // KF6 REMOVE
16 
18 namespace KIO
19 {
20 class CommandLauncherJobPrivate;
21 
22 /**
23  * @class CommandLauncherJob commandlauncherjob.h <KIO/CommandLauncherJob>
24  *
25  * @brief CommandLauncherJob runs a command and watches it while running.
26  *
27  * It creates a startup notification and finishes it on success or on error (for the taskbar).
28  * It also emits an error message if necessary (e.g. "program not found").
29  *
30  * The job finishes when the application is successfully started. At that point you can
31  * query the PID.
32  *
33  * For error handling, either connect to the result() signal, or for a simple messagebox on error,
34  * you can do
35  * @code
36  * job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
37  * @endcode
38  *
39  * @since 5.69
40  */
41 class KIOGUI_EXPORT CommandLauncherJob : public KJob
42 {
43 public:
44  /**
45  * Creates a CommandLauncherJob.
46  * @param command the shell command to run
47  * The command is given "as is" to the shell, it must already be quoted if necessary.
48  * If @p command is instead a filename, consider using the other constructor, even if no args are present.
49  * @param parent the parent QObject
50  *
51  * Please consider also calling setDesktopName(), or setExecutable() and setIcon()
52  * for better startup notification.
53  */
54  explicit CommandLauncherJob(const QString &command, QObject *parent = nullptr);
55 
56  /**
57  * Creates a CommandLauncherJob.
58  * @param executable the name of the executable
59  * @param args the commandline arguments to pass to the executable
60  * @param parent the parent QObject
61  *
62  * Please consider also calling setDesktopName(), or setExecutable() and setIcon()
63  * for better startup notification.
64  */
65  explicit CommandLauncherJob(const QString &executable, const QStringList &args, QObject *parent = nullptr);
66 
67  /**
68  * Destructor
69  *
70  * Note that jobs auto-delete themselves after emitting result
71  */
72  ~CommandLauncherJob() override;
73 
74  /**
75  * Sets the name of the executable, used in the startup notification
76  * (see KStartupInfoData::setBin()).
77  * @param executable executable name, with or without a path
78  *
79  * Alternatively, use setDesktopName().
80  */
81  void setExecutable(const QString &executable);
82 
83  /**
84  * Sets the icon for the startup notification.
85  * @param iconName name of the icon, to be loaded from the current icon theme
86  *
87  * Alternatively, use setDesktopName().
88  */
89  void setIcon(const QString &iconName);
90 
91  /**
92  * Set the name of the desktop file (e.g.\ "org.kde.dolphin", the extension is optional).
93  *
94  * This is an alternative solution for setIcon() and setExecutable(), i.e. the icon
95  * will be taken from the desktop file, and the executable inferred from the "Exec" line.
96  */
97  void setDesktopName(const QString &desktopName);
98 
99  /**
100  * Sets the startup notification id of the command launch.
101  * @param startupId startup notification id, if any (otherwise "").
102  */
103  void setStartupId(const QByteArray &startupId);
104 
105  /**
106  * Sets the working directory from which to run the command.
107  * @param workingDirectory path of a local directory
108  */
109  void setWorkingDirectory(const QString &workingDirectory);
110 
111  /**
112  * Sets the environment that will be passed to the child process.
113  * Can be used to pass environment variables to the child process.
114  * @param environment set of environment variables to pass to the child process
115  * @see QProcessEnvironment
116  * @since 5.82
117  */
118  void setProcessEnvironment(const QProcessEnvironment &environment);
119 
120  /**
121  * Starts the job.
122  * You must call this, after having done all the setters.
123  */
124  void start() override;
125 
126  /**
127  * @return the PID of the application that was started
128  *
129  * Available after the job emits result().
130  */
131  qint64 pid() const;
132 
133 private:
134  friend class ::KRunPrivate; // KF6 REMOVE
135  friend class ::CommandLauncherJobTest; // KF6 REMOVE
136  /**
137  * Blocks until the process has started. Only exists for KRun, will disappear in KF6.
138  */
139  bool waitForStarted();
140 
141  friend class CommandLauncherJobPrivate;
143 };
144 
145 } // namespace KIO
146 
147 #endif
A namespace for KIO globals.
CommandLauncherJob runs a command and watches it while running.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri May 14 2021 23:00:08 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.