sw/README.md

   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 - <https://wiki.openoffice.org/wiki/Writer/Core_And_Layout>
  36 - <https://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
 143 ### Lists
 144
 145 - `SwNumFormat` (subclass of `SvxNumFormat`) determines the formatting of a single
 146   numbering level.
 147
 148 - `SwNumRule` (NOT a subclass of `SvxNumRule`) is a *list style*, containing one
 149   `SwNumFormat` per list level.
 150   `SwNumRule::maTextNodeList` is the list of `SwTextNode` that have this list style
 151   applied.
 152
 153 - `SwNumberTreeNode` is a base class that represents an abstract node in a
 154   hierarchical tree of numbered nodes.
 155
 156 - `SwNodeNum` is the subclass of `SwNumberTreeNode` that connects it with an
 157   actual `SwTextNode` and also with a `SwNumRule`;
 158   `SwTextNode::mpNodeNum` points back in the other direction
 159
 160 - `SwList` represents a list, which is (mostly) a vector of `SwNodeNum` trees,
 161   one per `SwNodes` top-level section (why that?).
 162
 163 - `IDocumentListsAccess`, `sw::DocumentListsManager` owns all `SwList` instances,
 164   and maintains mappings:
 165   + from list-id to `SwList`
 166   + from list style name to `SwList` (the "default" `SwList` for that list style)
 167
 168 - `IDocumentListItems`, `sw::DocumentListItemsManager` contains a set of all
 169   `SwNodeNum` instances, ordered by `SwNode` index
 170
 171 - the special Outline numbering rule: `SwDoc::mpOutlineRule`
 172
 173 - `IDocumentOutlineNodes`, `sw::DocumentOutlineNodesManager` maintain
 174   a list (which is actually stored in `SwNodes::m_pOutlineNodes`) of `SwTextNodes`
 175   that either have the Outline numrule applied,
 176   or have the `RES_PARATR_OUTLINELEVEL` item set (note that in the latter case,
 177   the `SwTextNode` does not have a `SwNodeNum` and is not associated with the
 178   `SwDoc::mpOutlineRule`).
 179
 180 - `SwTextNodes` and paragraph styles have items/properties:
 181   + `RES_PARATR_OUTLINELEVEL/"OutlineLevel"` to specify an outline level without
 182     necessarily having the outline `SwNumRule` assigned
 183   + `RES_PARATR_NUMRULE/"NumberingStyleName"` the list style to apply; may be
 184     empty `""` which means no list style (to override inherited value)
 185   Only `SwTextNode` has these items:
 186   + `RES_PARATR_LIST_ID/"ListId"`
 187     determines the `SwList` to which the node is added
 188   + `RES_PARATR_LIST_LEVEL/"NumberingLevel"`
 189     the level at which the `SwTextNode` will appear in the list
 190   + `RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart"`
 191     restart numbering sequence at this `SwTextNode`
 192   + `RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue"`
 193     restart numbering sequence at this `SwTextNode` with this value
 194   + `RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber"`
 195     determines if the node is actually counted in the numbering sequence;
 196     these are different from `"phantoms"` because there's still a `SwTextNode`.
 197
 198 Note that there is no UNO service to represent a list.
 199
 200 ### Layout
 201
 202 The layout is a tree of `SwFrame` subclasses, the following relationships are
 203 possible between frames:
 204
 205 - You can visit the tree by following the upper, lower, next and previous pointers.
 206 - The functionality of flowing of a frame across multiple parents (e.g. pages)
 207   is implemented in `SwFlowFrame`, which is not an `SwFrame` subclass. The logical
 208   chain of such frames can be visited using the follow and precede pointers.
 209   ("Leaf" is a term that refers to such a relationship.)
 210 - In case a frame is split into multiple parts, then the first one is called
 211   master, while the others are called follows.