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 kemailclientlauncherjob.h <KEMailClientLauncherJob>
19 *
20 * @brief KEMailClientLauncherJob starts a mail client in order to compose a new mail.
21 *
22 * It creates a startup notification and finishes it on success or on error (for the taskbar).
23 * It also emits an error message if necessary (e.g. "program not found").
24 *
25 * The job finishes when the application is successfully started.
26 * For error handling, either connect to the result() signal, or for a simple messagebox on error,
27 * you can do
28 * @code
29 * job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
30 * @endcode
31 *
32 * @since 5.87
33 */
34class KIOGUI_EXPORT KEMailClientLauncherJob : public KJob
35{
36 Q_OBJECT
37public:
38 /**
39 * Creates a KEMailClientLauncherJob.
40 * @param parent the parent QObject
41 */
42 explicit KEMailClientLauncherJob(QObject *parent = nullptr);
43
44 /**
45 * Destructor
46 *
47 * Note that jobs auto-delete themselves after emitting result
48 */
49 ~KEMailClientLauncherJob() override;
50
51 /**
52 * Sets the email address(es) that will be used in the To field for the email
53 * @param to recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
54 */
55 void setTo(const QStringList &to);
56 /**
57 * Sets the email address(es) that will be used in the CC field for the email
58 * @param cc recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
59 */
60 void setCc(const QStringList &cc);
61 /**
62 * Sets the email address(es) that will be used in the Bcc field for the email
63 * @param bcc recipients; each entry can use the format "someone@example.com" or "John Doe <someone@example.com>"
64 * @since 5.96
65 */
66 void setBcc(const QStringList &bcc);
67 /**
68 * Sets the subject for the email
69 * @param subject the email subject
70 */
71 void setSubject(const QString &subject);
72 /**
73 * Sets the body for the email
74 * @param body the email body
75 */
76 void setBody(const QString &body);
77 /**
78 * Sets attachments for the email
79 * @param urls URLs of the attachments for the email
80 * Remember to use QUrl::fromLocalFile() to construct those URLs from local file paths.
81 */
82 void setAttachments(const QList<QUrl> &urls);
83
84 /**
85 * Sets the platform-specific startup id of the mail client launch.
86 * @param startupId startup id, if any (otherwise "").
87 * For X11, this would be the id for the Startup Notification protocol.
88 * For Wayland, this would be the token for the XDG Activation protocol.
89 */
90 void setStartupId(const QByteArray &startupId);
91
92 /**
93 * Starts the job.
94 * You must call this, after having called all the necessary setters.
95 */
96 void start() override;
97
98private:
99 friend class KEMailClientLauncherJobTest;
100 QUrl mailToUrl() const; // for the unittest
101 QStringList thunderbirdArguments() const; // for the unittest
102
103 KIOGUI_NO_EXPORT void emitDelayedResult();
104
105 friend class KEMailClientLauncherJobPrivate;
106 std::unique_ptr<KEMailClientLauncherJobPrivate> d;
107};
108
109#endif // KEMAILCLIENTLAUNCHERJOB_H
110

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