messageviewer/Mainpage.dox

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