Messagelib

viewer.h
1 /*
2  This file is part of KMail, the KDE mail client.
3  SPDX-FileCopyrightText: 1997 Markus Wuebben <[email protected]>
4  SPDX-FileCopyrightText: 2009 Klarälvdalens Datakonsult AB, a KDAB Group company, [email protected]
5  SPDX-FileCopyrightText: 2009 Andras Mantia <[email protected]>
6 
7  SPDX-License-Identifier: GPL-2.0-or-later
8 */
9 
10 #pragma once
11 
12 #include "config-messageviewer.h"
13 #include "messageviewer/viewerplugininterface.h"
14 #include "messageviewer_export.h"
15 #include <MimeTreeParser/Enums>
16 
17 #include <KMime/Message>
18 
19 #include <QWidget>
20 #include <memory>
21 
22 namespace Akonadi
23 {
24 class Item;
25 class ItemFetchJob;
26 }
27 
28 namespace KIdentityManagement
29 {
30 class IdentityManager;
31 }
32 
33 class KActionCollection;
34 class QAction;
35 class KToggleAction;
36 class KActionMenu;
37 
38 class QAbstractItemModel;
39 class QCloseEvent;
40 class QEvent;
41 class QResizeEvent;
42 
43 namespace WebEngineViewer
44 {
45 class WebHitTestResult;
46 }
47 
48 namespace MessageViewer
49 {
50 class WebHitTestResult;
51 class DKIMWidgetInfo;
52 class DKIMViewerMenu;
53 class AttachmentStrategy;
54 class HeaderStylePlugin;
55 class CSSHelper;
56 class ViewerPrivate;
57 class Viewer;
58 class RemoteContentMenu;
59 class MDNWarningWidget;
60 
61 /**
62  * An interface to plug in a handler that is called when
63  * an message item has been loaded into the view.
64  */
65 class MESSAGEVIEWER_EXPORT AbstractMessageLoadedHandler
66 {
67 public:
70 
71  /**
72  * This method is called whenever a message item has been loaded
73  * into the view.
74  *
75  * @param item The message item that has been loaded.
76  */
77  virtual void setItem(const Akonadi::Item &item) = 0;
78 
79 protected:
80  Akonadi::Session *session() const;
81 
82 private:
83  void setSession(Akonadi::Session *session);
84 
85  friend class Viewer;
86  class AbstractMessageLoadedHandlerPrivate;
87  std::unique_ptr<AbstractMessageLoadedHandlerPrivate> const d;
88 };
89 
90 /**
91  * This is the main widget for the viewer.
92  * See the documentation of ViewerPrivate for implementation details.
93  * See Mainpage.dox for an overview of the classes in the messageviewer library.
94  */
95 class MESSAGEVIEWER_EXPORT Viewer : public QWidget
96 {
97  Q_OBJECT
98 
99  Q_DECLARE_PRIVATE(Viewer)
100 
101 public:
102  /**
103  * Create a mail viewer widget
104  * @param parent parent widget
105  * @param widget the application's main widget
106  * @param actionCollection the action collection where the widget's actions will belong to
107  */
108  explicit Viewer(QWidget *parent, QWidget *widget = nullptr, KActionCollection *actionCollection = nullptr);
109  ~Viewer() override;
110 
111  /**
112  * Returns the current message displayed in the viewer.
113  */
114  Q_REQUIRED_RESULT KMime::Message::Ptr message() const;
115 
116  /**
117  * Returns the current message item displayed in the viewer.
118  */
119  Q_REQUIRED_RESULT Akonadi::Item messageItem() const;
120 
121  enum DisplayFormatMessage { UseGlobalSetting = 0, Text = 1, Html = 2, Unknown = 3, ICal = 4 };
122 
123  enum AttachmentAction { Open = 1, OpenWith, View, Save, Properties, Delete, Copy, ScrollTo, ReplyMessageToAuthor, ReplyMessageToAll };
124 
125  enum ResourceOnlineMode { AllResources = 0, SelectedResource = 1 };
126 
127  /**
128  * Set the message that shall be shown.
129  * @param message - the message to be shown. If 0, an empty page is displayed.
130  * @param updateMode - update the display immediately or not. See UpdateMode.
131  */
132  void setMessage(const KMime::Message::Ptr &message, MimeTreeParser::UpdateMode updateMode = MimeTreeParser::Delayed);
133 
134  /**
135  * Set the Akonadi item that will be displayed.
136  * @param item - the Akonadi item to be displayed. If it doesn't hold a mail (KMime::Message::Ptr as payload data),
137  * an empty page is shown.
138  * @param updateMode - update the display immediately or not. See UpdateMode.
139  */
140  void setMessageItem(const Akonadi::Item &item, MimeTreeParser::UpdateMode updateMode = MimeTreeParser::Delayed);
141 
142  /**
143  * The path to the message in terms of Akonadi collection hierarchy.
144  */
145  Q_REQUIRED_RESULT QString messagePath() const;
146 
147  /**
148  * Set the path to the message in terms of Akonadi collection hierarchy.
149  */
150  void setMessagePath(const QString &path);
151 
152  /**
153  * Instead of settings a message to be shown sets a message part
154  * to be shown
155  */
156  void setMessagePart(KMime::Content *aMsgPart);
157 
158  /**
159  * Convenience method to clear the reader and discard the current message. Sets the internal message pointer
160  * returned by message() to 0.
161  * @param updateMode - update the display immediately or not. See UpdateMode.
162  */
163  void clear(MimeTreeParser::UpdateMode updateMode = MimeTreeParser::Delayed);
164 
165  void update(MimeTreeParser::UpdateMode updateMode = MimeTreeParser::Delayed);
166 
167  /**
168  * Sets a message as the current one and print it immediately.
169  * @param msg the message to display and print
170  */
171  void printMessage(const Akonadi::Item &msg);
172 
173  void printPreviewMessage(const Akonadi::Item &message);
174 
175  /** Print the currently displayed message */
176  void print();
177  void printPreview();
178 
179  /** Get the html override setting */
180  Q_REQUIRED_RESULT Viewer::DisplayFormatMessage displayFormatMessageOverwrite() const;
181 
182  /** Override default html mail setting */
183  void setDisplayFormatMessageOverwrite(Viewer::DisplayFormatMessage format);
184 
185  /** Get the load external references override setting */
186  bool htmlLoadExtOverride() const;
187 
188  /** Default behavior for loading external references.
189  * Use this for specifying the external reference loading behavior as
190  * specified in the user settings.
191  * @see setHtmlLoadExtOverride
192  */
193  void setHtmlLoadExtDefault(bool loadExtDefault);
194 
195  /** Override default load external references setting
196  * @warning This must only be called when the user has explicitly
197  * been asked to retrieve external references!
198  * @see setHtmlLoadExtDefault
199  */
200  void setHtmlLoadExtOverride(bool loadExtOverride);
201 
202  /** Is html mail to be supported? Takes into account override */
203  Q_REQUIRED_RESULT bool htmlMail() const;
204 
205  /** Is loading ext. references to be supported? Takes into account override */
206  Q_REQUIRED_RESULT bool htmlLoadExternal() const;
207 
208  /**
209  * Display a generic HTML splash page instead of a message.
210  * @param templateName - the template to be loaded
211  * @param data - data for the template
212  * @param domain the domain.
213  */
214  void displaySplashPage(const QString &templateName, const QVariantHash &data, const QByteArray &domain = QByteArray());
215 
216  /** Enable the displaying of messages again after an splash (or other) page was displayed */
217  void enableMessageDisplay();
218 
219  /** Returns true if the message view is scrolled to the bottom. */
220  void atBottom();
221 
222  Q_REQUIRED_RESULT bool isFixedFont() const;
223  void setUseFixedFont(bool useFixedFont);
224 
225  Q_REQUIRED_RESULT QWidget *mainWindow();
226 
227  /** Enforce message decryption. */
228  void setDecryptMessageOverwrite(bool overwrite = true);
229 
230  /**
231  * Initiates a delete, by sending a signal to delete the message item */
232  void deleteMessage();
233 
234  Q_REQUIRED_RESULT const AttachmentStrategy *attachmentStrategy() const;
235  void setAttachmentStrategy(const AttachmentStrategy *strategy);
236 
237  Q_REQUIRED_RESULT QString overrideEncoding() const;
238  void setOverrideEncoding(const QString &encoding);
239  Q_REQUIRED_RESULT CSSHelper *cssHelper() const;
240  void setPrinting(bool enable);
241 
242  void selectAll();
243  void copySelectionToClipboard();
244 
245  void setZoomFactor(qreal zoomFactor);
246 
247  Q_REQUIRED_RESULT KToggleAction *toggleFixFontAction() const;
248 
249  Q_REQUIRED_RESULT KToggleAction *toggleMimePartTreeAction() const;
250 
251  Q_REQUIRED_RESULT QAction *selectAllAction() const;
252  Q_REQUIRED_RESULT QAction *copyURLAction() const;
253  Q_REQUIRED_RESULT QAction *copyAction() const;
254  Q_REQUIRED_RESULT QAction *urlOpenAction() const;
255  Q_REQUIRED_RESULT QAction *speakTextAction() const;
256  Q_REQUIRED_RESULT QAction *copyImageLocation() const;
257  Q_REQUIRED_RESULT QAction *viewSourceAction() const;
258  Q_REQUIRED_RESULT QAction *findInMessageAction() const;
259  Q_REQUIRED_RESULT QAction *saveAsAction() const;
260  Q_REQUIRED_RESULT QAction *saveMessageDisplayFormatAction() const;
261  Q_REQUIRED_RESULT QAction *resetMessageDisplayFormatAction() const;
262  Q_REQUIRED_RESULT QAction *shareTextAction() const;
263 
264  Q_REQUIRED_RESULT QAction *developmentToolsAction() const;
265  Q_REQUIRED_RESULT KToggleAction *disableEmoticonAction() const;
266  Q_REQUIRED_RESULT KActionMenu *shareServiceUrlMenu() const;
267  Q_REQUIRED_RESULT HeaderStylePlugin *headerStylePlugin() const;
268  Q_REQUIRED_RESULT MessageViewer::DKIMViewerMenu *dkimViewerMenu();
269 
270  Q_REQUIRED_RESULT MessageViewer::RemoteContentMenu *remoteContentMenu() const;
271 
272  void setPluginName(const QString &pluginName);
273 
274  void writeConfig(bool withSync = true);
275 
276  Q_REQUIRED_RESULT QUrl urlClicked() const;
277  Q_REQUIRED_RESULT QUrl imageUrlClicked() const;
278 
279  void readConfig();
280 
281  /** A QAIM tree model of the message structure. */
282  QAbstractItemModel *messageTreeModel() const;
283 
284  /**
285  * Create an item fetch job that is suitable for using to fetch the message item that will
286  * be displayed on this viewer.
287  * It will set the correct fetch scope.
288  * You still need to connect to the job's result signal.
289  */
290  Akonadi::ItemFetchJob *createFetchJob(const Akonadi::Item &item);
291 
292  /**
293  * Adds a @p handler for actions that will be executed when the message
294  * has been loaded into the view.
295  */
296  void addMessageLoadedHandler(AbstractMessageLoadedHandler *handler);
297 
298  /**
299  * Removes the @p handler for actions that will be executed when the message
300  * has been loaded into the view.
301  */
302  void removeMessageLoadedHandler(AbstractMessageLoadedHandler *handler);
303 
304  Q_REQUIRED_RESULT QString selectedText() const;
305 
306  void saveMainFrameScreenshotInFile(const QString &filename);
307  bool mimePartTreeIsEmpty() const;
308 
309  void showOpenAttachmentFolderWidget(const QList<QUrl> &urls);
310  Q_REQUIRED_RESULT QList<QAction *> viewerPluginActionList(MessageViewer::ViewerPluginInterface::SpecificFeatureTypes features);
311  Q_REQUIRED_RESULT QList<QAction *> interceptorUrlActions(const WebEngineViewer::WebHitTestResult &result) const;
312 
313  void runJavaScript(const QString &code);
314  void setPrintElementBackground(bool printElementBackground);
315 
316  Q_REQUIRED_RESULT bool printingMode() const;
317 
318  Q_REQUIRED_RESULT bool showSignatureDetails() const;
319  void setShowSignatureDetails(bool showDetails);
320 
321  Q_REQUIRED_RESULT qreal webViewZoomFactor() const;
322  void setWebViewZoomFactor(qreal factor);
323 
324  Q_REQUIRED_RESULT bool showEncryptionDetails() const;
325  void setShowEncryptionDetails(bool showDetails);
326 
327  void hasMultiMessages(bool messages);
328  void updateShowMultiMessagesButton(bool enablePreviousButton, bool enableNextButton);
329  Q_REQUIRED_RESULT MessageViewer::DKIMWidgetInfo *dkimWidgetInfo();
330 
331  void exportToPdf(const QString &fileName);
332 
333  void showDevelopmentTools();
334 
335  void setIdentityManager(KIdentityManagement::IdentityManager *ident);
336  void setFolderIdentity(uint folderIdentity);
337  Q_REQUIRED_RESULT MessageViewer::MDNWarningWidget *mdnWarning() const;
338 Q_SIGNALS:
339  void moveMessageToTrash();
340  void pageIsScrolledToBottom(bool);
341 
342  /**
343  * Emitted when a status bar message is shown. Note that the status bar message is also set to
344  * KPIM::BroadcastStatus in addition.
345  */
346  void showStatusBarMessage(const QString &message);
347 
348  /** The user presses the right mouse button. 'url' may be 0. */
349  void popupMenu(const Akonadi::Item &msg, const QUrl &url, const QUrl &imageUrl, const QPoint &mousePos);
350  void displayPopupMenu(const Akonadi::Item &msg, const WebEngineViewer::WebHitTestResult &result, const QPoint &mousePos);
351  /**
352  * The message viewer handles some types of urls itself, most notably http(s)
353  * and ftp(s). When it can't handle the url it will Q_EMIT this signal.
354  */
355  void urlClicked(const Akonadi::Item &, const QUrl &);
356 
357  void requestConfigSync();
358 
359  /// Emitted when the content should be shown in a separate window
360  void showReader(KMime::Content *aMsgPart, bool aHTML, const QString &encoding);
361 
362  /// Emitted when the message should be shown in a separate window
363  void showMessage(const KMime::Message::Ptr &message, const QString &encoding);
364 
365  void replyMessageTo(const KMime::Message::Ptr &message, bool replyToAll);
366 
367  void deleteMessage(const Akonadi::Item &);
368 
369  /// Emitted when the item, previously set with setMessageItem, has been removed.
370  void itemRemoved();
371 
372  void makeResourceOnline(MessageViewer::Viewer::ResourceOnlineMode mode);
373 
374  void printingFinished();
375  void zoomChanged(qreal zoomFactor);
376  void showNextMessage();
377  void showPreviousMessage();
378 
379 private:
380  void initialize();
381  void slotGeneralPaletteChanged();
382 
383 public Q_SLOTS:
384 
385  /**
386  * HTML Widget scrollbar and layout handling.
387  *
388  * Scrolling always happens in the direction of the slot that is called. I.e.
389  * the methods take the absolute value of
390  */
391  void slotScrollUp();
392  void slotScrollDown();
393  void slotScrollPrior();
394  void slotScrollNext();
395  void slotJumpDown();
396  void slotFind();
397  void slotSaveMessage();
398  void slotAttachmentSaveAs();
399  void slotAttachmentSaveAll();
400  void slotShowMessageSource();
401  void slotZoomIn();
402  void slotZoomOut();
403  void slotZoomReset();
404  void slotChangeDisplayMail(Viewer::DisplayFormatMessage, bool);
405 
406 protected:
407  /** Some necessary event handling. */
408  void closeEvent(QCloseEvent *) override;
409  void resizeEvent(QResizeEvent *) override;
410  /** Watch for palette changes */
411  Q_REQUIRED_RESULT bool event(QEvent *e) override;
412  void changeEvent(QEvent *event) override;
413 
414  ViewerPrivate *const d_ptr;
415 };
416 }
The DKIMWidgetInfo class.
The CSSHelper class.
Definition: csshelper.h:21
This is the main widget for the viewer.
Definition: viewer.h:95
The DKIMViewerMenu class.
The RemoteContentMenu class.
The WebHitTestResult class.
An interface to plug in a handler that is called when an message item has been loaded into the view.
Definition: viewer.h:65
The HeaderStylePlugin class.
The AttachmentStrategy class.
The MDNWarningWidget class.
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Wed Aug 17 2022 04:07:57 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.