1// Put this in the MessageViewer namespace so that autolinks to classes work without needing a 2// MessageViewer:: prefix. 3 4namespace MessageViewer { 5 6/** \mainpage The MessageViewer library 7\section Overview 8 9The messageviewer is a library that provides a widget that can show a KMime::Message in a nice 10way. 11 12The message is displayed by first converting it to HTML and then displaying the HTML in a widget 13based on WebKit. 14 15\section ObjectTreeParser 16 17The class ObjectTreeParser is used to parse the KMime::Message and create a HTML representation out 18of it. An implementation of the ObjectTreeSource interface is passed to the ObjectTreeParser, 19which provides an interface for the ObjectTreeParser to interact with the viewer widget. The most 20import part of this interface is that it provides a HtmlWriter, which the ObjectTreeParser uses to 21write the HTML it generates to. 22 23The HtmlWriter passed to the ObjectTreeParser can be a dummy implementation, like in EmptySource. 24This is used when one is not interested in the interaction between the ObjectTreeParser and the 25viewer. The most common use case is that one is not interested in the generated HTML, but only in 26the textual content that the ObjectTreeParser extracted, which can be retrieved with 27ObjectTreeParser::textualContent(). This is used for example when KMail creates an inline forward 28message. 29 30The Viewer of course uses a non-dummy implementation of the ObjectTreeSource, the MailViewerSource. 31The HtmlWriter provided by the MailViewerSource is a WebKitPartHtmlWriter, which writes the HTML 32directly to the MailWebView widget, which is a KWebView. 33 34The header of the message or the headers of any embedded messages are formatted in a special way. 35The user can chose between many styles of header formatting, like 'fancy' or 'brief'. The creation 36of the HTML code for these headers is handled by HeaderStyle. The ObjectTreeParser does not use 37the HeaderStyle classes directly; instead, it is delegated to ViewerPrivate::writeMsgHeader() via 38ObjectTreeSource::createMessageHeader(). 39 40The 'fancy' header style can display the spam status of the message in a nice way. To extract the 41spam information, SpamHeaderAnalyzer, AntiSpamConfig and SpamAgent are used. 42 43The HeaderStrategy controls which parts of the header should be shown. Based on this strategy, the 44HeaderStyle implementations decide which header fields to include in the HTML code they generate. 45 46Some parts of the appearance of the message can be customized by changing the CSS. For this, the 47CSSHelper class is used, which is passed to the ObjectTreeParser with ObjectTreeSource::cssHelper(). 48 49The ObjectTreeParser can have plugins that create the HTML for special MIME parts themselves. Those 50plugins are found in kdepim/plugins/messageviewer. Examples are plugins that render the vCard in a 51nice way when a vCard MIME type is encountered, or which do the same when a diff attachment is found. 52The classes used for this are the interfaces BodyPartFormatter and BodyPartFormatterPlugin and their 53helper interfaces in the interfaces/ subdirectory. The plugins only depend on these interfaces and 54are independent from the rest of the viewer. 55 56Most MIME parts are handled internally, like all multipart types or text/plain and text/html. For 57text/html, a HTMLQuoteColorer is used to change the HTML of the message to include coloring of the 58quotes. 59 60The AttachmentStrategy which is passed to the constructor or ObjectTreeParser controls how some of 61the MIME parts are handled: For example, an image MIME part might be displayed as an icon, or it 62might display the full image inline in the body. 63 64For details on the internals of the ObjectTreeParser, especially the way it parses and changes a 65message, see the documentation of ObjectTreeParser. 66 67\section Widgets 68 69The Viewer consists of several widgets. 70The main widget is the MailWebView, which displays the HTML code that the ObjectTreeParser generated 71from the message. 72On the left side of that, a HtmlStatusBar displays the type of the displayed message. 73Below the MailWebView, a QTreeView shows the message structure by using a MimeTreeModel. 74The viewer can open an additional window to show the raw message source with the MailSourceViewer. 75The viewer also can show the properties of a MIME part of the message, which uses the 76AttachmentDialog class. 77When opening MIME parts that are vCards, they are displayed in a VCardViewer. 78When searching through the message, a FindBar is displayed at the bottom. 79 80\section urlhandling URL handling 81 82The generated HTML has many different URLs in it. Those can be the normal URLs which are contained 83in the message text, the mailto URLs that are in the header, or special KMail URLs. These KMail URLs 84for example include the "Load external references" link for HTML mails with external images, the 85"Show details" link for signed messages, the URL to expand or collapse quoted text and many more. 86 87Throughout the displayed message, there are links to attachments, either in the header when using 88some header styles, or at the place where the actual attachment is, in the body. These URLs all 89start with 'attachment:', followed by a number that describes the KMime::ContentIndex of the 90attachment. The attachment links also contain a parameter that describes whether the link is in the 91header of the message or in the body. This is needed because clicking on the links in the header 92should scroll to the attachment in the body. 93 94These URLs are all written to the HTML code by ObjectTreeParser, but it is up to the Viewer to 95handle interaction with these URLs, such as clicking on them or hovering over them. 96 97For this, the Viewer has a URLHandlerManager, which manages a list of URLHandler. An URLHandler is 98responsible for the interaction with exactly one type or URL. Interaction means executing an action 99when clicking the URL or showing a status bar message when hovering over it. Examples of these 100URLHandler are AttachmentURLHandler or ExpandCollapseQuoteURLManager. The special 101KMailProtocolURLHandler deals with multiple types of URLs that all start with 'kmail:'. 102 103Note that the 'kmail:' URLs are only named like this for historic reasons, nowadays the viewer is 104independent of KMail. 105 106\section Misc 107 108There are various smaller and unimportant classes in this library. 109 110PartNodeBodyPart is an implementation of the BodyPart interface. It is used by plugins to gain 111access to various properties of the MIME part the plugins are supposed to handle. 112 113NodeHelper currently is a big mess that consists of mainly two things: First, it provides 114convenience methods for operations related to the MIME part class KMime::Content, such as 115nextSibling() or charset(). All these methods should eventually be moved away from here, either to 116kdepim/messagecore or to kdpimlibs/kmime. 117Secondly, it provides lists and maps which are used by the ObjectTreeParser and the Viewer during 118processing. Such can include a list of all KMime::Content that are currently being processed, a map 119of KMime::Content to their signature or encryption state, a map of KMime::Content to PartMetaData, 120and so on. 121 122The class Global is used so that applications that use this library can set the correct config 123object. Those applications also can use the ConfigureWidget in their application to display some 124settings. Most of the settings use KConfigXT, and the file for the settings definitions is 125messageviewer.kcfg. The GlobalSettings class is a thin wrapper around the GlobalSettingsBase class, 126which is generated from the KCFG. 127 128StringUtil is a namespace that groups various functions that mainly do string operations, for 129example on mail addresses. 130 131Then there is the Util namespace, which again has some convenience functions that neither fit into 132StringUtil or into NodeHelper. 133 134The last utilitly thing are the functions in stl_util.h, which are supposed to be used in 135combination with STL algorithms. 136 137There are a bunch of smaller classes like AutoQPointer, EditorWatcher, IconNameCache, KCursorSaver, 138KleoJobExecutor, KabcBridge and many more. See the full class list if you're curious. 139 140You should also read the documentation of the following classes, which are extensively documented: 141\sa MessageViewer::ViewerPrivate 142\sa MessageViewer::ObjectTreeParser 143 144*/ 145 146} 147// DOXYGEN_NAME=messageviewer 148// DOXYGEN_ENABLE=YES 149// DOXYGEN_REFERENCES=kmime 150