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 | |
15 | class 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 | */ |
35 | class KIOGUI_EXPORT KEMailClientLauncherJob : public KJob |
36 | { |
37 | Q_OBJECT |
38 | public: |
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 | |
111 | private: |
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 | |