sw/README

   1 Writer application code.
   2
   3 Exact history was lost before Sept. 18th, 2000, but old source code
   4 comments show that Writer core dates back until at least November
   5 1990.
   6
   7 == Module contents ==
   8  * inc: headers available to all source files inside the module
   9  * qa: unit, slow and subsequent tests
  10  * sdi
  11  * source: see below
  12  * uiconfig: user interface configuration
  13  * util: UNO passive registration config
  14
  15 == Source contents ==
  16  * core: Writer core (document model, layout, UNO API implementation)
  17  * filter: Writer internal filters
  18    * ascii: plain text filter
  19    * basflt
  20    * docx: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes
  21    * html: HTML filter
  22    * inc: include files for filters
  23    * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter)
  24    * writer
  25    * ww8: DOC import, DOC/DOCX/RTF export
  26    * xml: ODF import/export, subclassed from xmloff (where most of the work is done)
  27  * uibase: user interface (those parts that are linked into sw & always loaded)
  28  * ui: user interface (optional parts that are loaded on demand (swui))
  29
  30 == Core ==
  31
  32 There is a good overview documentation of basic architecture of Writer core
  33 in the OOo wiki:
  34
  35 http://wiki.openoffice.org/wiki/Writer/Core_And_Layout
  36 http://wiki.openoffice.org/wiki/Writer/Text_Formatting
  37
  38 Writer specific WhichIds are defined in sw/inc/hintids.hxx.
  39
  40 The details below are mainly about details missing from the Wiki pages.
  41
  42 === SwDoc ===
  43
  44 The central class for a document is SwDoc, which represents a document.
  45
  46 A lot of the functionality is split out into separate Manager classes,
  47 each of which implements some IDocument* interface; there are
  48 SwDoc::getIDocument*() methods to retrieve the managers.
  49
  50 However there are still too many members and methods in this class,
  51 many of which could be moved to some Manager or other...
  52
  53 === SwNodes ===
  54
  55 Basically a (fancy) array of SwNode pointers.  There are special subclasses of
  56 SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree
  57 structure into the flat array; the range of nodes from SwStartNode to its
  58 corresponding SwEndNode is sometimes called a "section" (but is not necessarily
  59 what the high-level document model calls a "Section"; that is just one of the
  60 possibilities).
  61
  62 The SwNodes contains the following top-level sections:
  63
  64 1. Empty
  65 2. Footnote content
  66 3. Frame / Header / Footer content
  67 4. Deleted Change Tracking content
  68 5. Body content
  69
  70 === Undo ===
  71
  72 The Undo/Redo information is stored in a sw::UndoManager member of SwDoc,
  73 which implements the IDocumentUndoRedo interface.
  74 Its members include a SwNodes array containing the document content that
  75 is currently not in the actual document but required for Undo/Redo, and
  76 a stack of SwUndo actions, each of which represents one user-visible
  77 Undo/Redo step.
  78
  79 There are also ListActions which internally contain several individual SwUndo
  80 actions; these are created by the StartUndo/EndUndo wrapper methods.
  81
  82 === Text Attributes ===
  83
  84 The sub-structure of paragraphs is stored in the SwpHintsArray member
  85 SwTextNode::m_pSwpHints.  There is a base class SwTextAttr with numerous
  86 subclasses; the SwTextAttr has a start and end index and a SfxPoolItem
  87 to store the actual formatting attribute.
  88
  89 There are several sub-categories of SwTextAttr:
  90
  91 - formatting attributes: Character Styles (SwTextCharFormat, RES_TXTATR_CHARFMT)
  92   and Automatic Styles (no special class, RES_TXTATR_AUTOFMT):
  93   these are handled by SwpHintsArray::BuildPortions and MergePortions,
  94   which create non-overlapping portions of formatting attributes.
  95
  96 - nesting attributes: Hyperlinks (SwTextINetFormat, RES_TXTATR_INETFMT),
  97   Ruby (SwTextRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTextMeta,
  98   RES_TXTATR_META/RES_TXTATR_METAFIELD):
  99   these maintain a properly nested tree structure.
 100   The Meta/Metafield are "special" because they have both start/end
 101   and a dummy character at the start.
 102
 103 - misc. attributes: Reference Marks, ToX Marks
 104
 105 - attributes without end: Fields, Footnotes, Flys (AS_CHAR)
 106   These all have a corresponding dummy character in the paragraph text, which
 107   is a placeholder for the "expansion" of the attribute, e.g. field content.
 108
 109 === Fields ===
 110
 111 There are multiple model classes involved for fields:
 112
 113 - enum SwFieldIds enumerates the different types of fields.
 114 - SwFieldType contains some shared stuff for all fields of a type.
 115   There are many subclasses of SwFieldType, one for each different type
 116   of field.
 117   For most types of fields there is one shared instance of this per type,
 118   which is created in DocumentFieldsManager::InitFieldTypes()
 119   but for some there are more than one, and they are dynamically created, see
 120   DocumentFieldsManager::InsertFieldType().  An example for the latter are
 121   variable fields (SwFieldIds::GetExp/SwFieldIds::SetExp), with one SwFieldType per
 122   variable.
 123 - SwXFieldMaster is the UNO wrapper of a field type.
 124   It is a SwClient registered at the SwFieldType.
 125   Its life-cycle is determined by UNO clients outside of sw; it will get
 126   disposed when the SwFieldType dies.
 127 - SwFormatField is the SfxPoolItem of a field.
 128   The SwFormatField is a SwClient registered at its SwFieldType.
 129   The SwFormatField owns the SwField of the field.
 130 - SwField contains the core logic of a field.
 131   The SwField is owned by the SwFormatField of the field.
 132   There are many subclasses of SwField, one for each different type of field.
 133   Note that there are not many places that can Expand the field to its
 134   correct value, since for example page number fields require a View
 135   with an up to date layout; therefore the correct expansion is cached.
 136 - SwTextField is the text attribute of a field.
 137   It owns the SwFormatField of the field (like all text attributes).
 138 - SwXTextField is the UNO wrapper object of a field.
 139   It is a SwClient registered at the SwFormatField.
 140   Its life-cycle is determined by UNO clients outside of sw; it will get
 141   disposed when the SwFormatField dies.
 142