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 | |
14 | class 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 | */ |
35 | class KIOGUI_EXPORT KTerminalLauncherJob : public KJob |
36 | { |
37 | Q_OBJECT |
38 | public: |
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 | |
106 | private: |
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 | |