1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2021 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 KTERMINALLAUNCHERJOB_H
9#define KTERMINALLAUNCHERJOB_H
10
11#include <KIO/CommandLauncherJob>
12#include <memory>
13
14class KTerminalLauncherJobPrivate;
15
16/*!
17 * \class KTerminalLauncherJob
18 * \inmodule KIOGui
19 *
20 * \brief KTerminalLauncherJob starts a terminal application,
21 * either for the user to use interactively, or to execute a command.
22 *
23 * It creates a startup notification and finishes it on success or on error (for the taskbar).
24 * It also emits an error message if necessary (e.g. "program not found").
25 *
26 * The job finishes when the application is successfully started.
27 * For error handling, either connect to the result() signal, or for a simple messagebox on error,
28 * you can do
29 * \code
30 * job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
31 * \endcode
32 *
33 * \since 5.83
34 */
35class KIOGUI_EXPORT KTerminalLauncherJob : public KJob
36{
37 Q_OBJECT
38public:
39 /*!
40 * Creates a KTerminalLauncherJob.
41 *
42 * \a command the command to execute in a terminal, can be empty.
43 *
44 * \a parent the parent QObject
45 */
46 explicit KTerminalLauncherJob(const QString &command, QObject *parent = nullptr);
47
48 /*!
49 * Destructor
50 *
51 * Note that jobs auto-delete themselves after emitting result
52 */
53 ~KTerminalLauncherJob() override;
54
55 /*!
56 * Sets the working directory from which to run the command.
57 *
58 * \a workingDirectory path of a local directory
59 */
60 void setWorkingDirectory(const QString &workingDirectory);
61
62 /*!
63 * Sets the platform-specific startup id of the command launch.
64 *
65 * \a startupId startup id, if any (otherwise "").
66 *
67 * For X11, this would be the id for the Startup Notification protocol.
68 *
69 * For Wayland, this would be the token for the XDG Activation protocol.
70 */
71 void setStartupId(const QByteArray &startupId);
72
73 /*!
74 * Can be used to pass environment variables to the child process.
75 *
76 * \a environment set of environment variables to pass to the child process
77 *
78 * \sa QProcessEnvironment
79 */
80 void setProcessEnvironment(const QProcessEnvironment &environment);
81
82 /*!
83 * Checks whether the command to launch a terminal can be constructed and sets it.
84 *
85 * The start() function calls this internally, so you only need to call prepare()
86 * directly if you want to validate the command separately from actually starting
87 * the terminal.
88 *
89 * This is useful if you want to avoid calling start() just to catch an error,
90 * for example to conditionally show or hide a GUI element depending on whether
91 * launching a terminal is likely to succeed.
92 *
93 * \return true if a launch command could be constructed, false otherwise.
94 * \sa start()
95 *
96 * \since 6.17
97 */
98 bool prepare();
99
100 /*!
101 * Starts the job.
102 * You must call this, after having called all the necessary setters.
103 */
104 void start() override;
105
106private:
107 friend class KTerminalLauncherJobTest;
108 void determineFullCommand(bool fallbackToKonsoleService = true); // for the unittest
109 QString fullCommand() const; // for the unittest
110
111 KIOGUI_NO_EXPORT void emitDelayedResult();
112
113 friend class KTerminalLauncherJobPrivate;
114 std::unique_ptr<KTerminalLauncherJobPrivate> d;
115};
116
117#endif // KTERMINALLAUNCHERJOB_H
118

source code of kio/src/gui/kterminallauncherjob.h