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.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KEMAILCLIENTLAUNCHERJOB_H
9#define KEMAILCLIENTLAUNCHERJOB_H
10
11#include "kiogui_export.h"
12#include <KJob>
13#include <memory>
14
15class KEMailClientLauncherJobPrivate;
16
17/*!
18 * \class KEMailClientLauncherJob
19 * \inmodule KIOGui
20 *
21 * \brief KEMailClientLauncherJob starts a mail client in order to compose a new mail.
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.87
34 */
35class KIOGUI_EXPORT KEMailClientLauncherJob : public KJob
36{
37 Q_OBJECT
38public:
39 /*!
40 * Creates a KEMailClientLauncherJob.
41 *
42 * \a parent the parent QObject
43 */
44 explicit KEMailClientLauncherJob(QObject *parent = nullptr);
45
46 /*!
47 * Destructor
48 *
49 * Note that jobs auto-delete themselves after emitting result
50 */
51 ~KEMailClientLauncherJob() override;
52
53 /*!
54 * Sets the email address(es) that will be used in the To field for the email
55 *
56 * \a to recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
57 */
58 void setTo(const QStringList &to);
59 /*!
60 * Sets the email address(es) that will be used in the CC field for the email
61 *
62 * \a cc recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
63 */
64 void setCc(const QStringList &cc);
65 /*!
66 * Sets the email address(es) that will be used in the Bcc field for the email
67 *
68 * \a bcc recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
69 * \since 5.96
70 */
71 void setBcc(const QStringList &bcc);
72 /*!
73 * Sets the subject for the email
74 *
75 * \a subject the email subject
76 */
77 void setSubject(const QString &subject);
78 /*!
79 * Sets the body for the email
80 *
81 * \a body the email body
82 */
83 void setBody(const QString &body);
84 /*!
85 * Sets attachments for the email
86 *
87 * \a urls URLs of the attachments for the email
88 *
89 * Remember to use QUrl::fromLocalFile() to construct those URLs from local file paths.
90 */
91 void setAttachments(const QList<QUrl> &urls);
92
93 /*!
94 * Sets the platform-specific startup id of the mail client launch.
95 *
96 * \a startupId startup id, if any (otherwise "").
97 *
98 * For X11, this would be the id for the Startup Notification protocol.
99 *
100 * For Wayland, this would be the token for the XDG Activation protocol.
101 */
102 void setStartupId(const QByteArray &startupId);
103
104 /*!
105 * Starts the job.
106 *
107 * You must call this, after having called all the necessary setters.
108 */
109 void start() override;
110
111private:
112 friend class KEMailClientLauncherJobTest;
113 QUrl mailToUrl() const; // for the unittest
114 QStringList thunderbirdArguments() const; // for the unittest
115
116 KIOGUI_NO_EXPORT void emitDelayedResult();
117
118 friend class KEMailClientLauncherJobPrivate;
119 std::unique_ptr<KEMailClientLauncherJobPrivate> d;
120};
121
122#endif // KEMAILCLIENTLAUNCHERJOB_H
123

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