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: plan text filter
  19    * basflt
  20    * html: HTML filter
  21    * inc: include files for filters
  22    * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter)
  23    * writer
  24    * ww1
  25    * ww8: DOC import, DOC/DOCX/RTF export
  26    * xml: ODF import/export, subclassed from xmloff (where most of the work is done)
  27  * ui: user interface
  28
  29 == Core ==
  30
  31 There is a good overview documentation of basic architecture of Writer core
  32 in the OOo wiki:
  33
  34 http://wiki.openoffice.org/wiki/Writer/Core_And_Layout
  35 http://wiki.openoffice.org/wiki/Writer/Text_Formatting
  36
  37 Writer specific WhichIds are defined in sw/inc/hintids.hxx.
  38
  39 The details below are mainly about details missing from the Wiki pages.
  40
  41 === SwDoc ===
  42
  43 The central class for a document is SwDoc, which represents a document.
  44
  45 This is a huge class with hundreds of methods; there are some efforts
  46 to split up the class into many smaller classes that implement more
  47 specific interfaces but this is not fully implemented yet; see the various
  48 IDocument* classes.
  49
  50 === SwNodes ===
  51
  52 Basically a (fancy) array of SwNode pointers.  There are special subclasses of
  53 SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree
  54 structure into the flat array; the range of nodes from SwStartNode to its
  55 corresponding SwEndNode is sometimes called a "section" (but is not necessarily
  56 what the high-level document model calls a "Section"; that is just one of the
  57 possibilities).
  58
  59 The SwNodes contains the following top-level sections:
  60
  61 1. Empty
  62 2. Footnote content
  63 3. Frame / Header / Footer content
  64 4. Deleted Change Tracking content
  65 5. Body content
  66
  67 === Undo ===
  68
  69 The Undo/Redo information is stored in a sw::UndoManager member of SwDoc,
  70 which implements the IDocumentUndoRedo interface.
  71 Its members include a SwNodes array containing the document content that
  72 is currently not in the actual document but required for Undo/Redo, and
  73 a stack of SwUndo actions, each of which represents one user-visible
  74 Undo/Redo step.
  75
  76 There are also ListActions which internally contain several individual SwUndo
  77 actions; these are created by the StartUndo/EndUndo wrapper methods.
  78
  79 === Text Attributes ===
  80
  81 The sub-structure of paragraphs is stored in the SwpHintsArray member
  82 SwTxtNode::m_pSwpHints.  There is a base class SwTxtAttr with numerous
  83 subclasses; the SwTxtAttr has a start and end index and a SfxPoolItem
  84 to store the actual formatting attribute.
  85
  86 There are several sub-categories of SwTxtAttr:
  87
  88 - formatting attributes: Character Styles (SwTxtCharFmt, RES_TXTATR_CHARFMT)
  89   and Automatic Styles (no special class, RES_TXTATR_AUTOFMT):
  90   these are handled by SwpHintsArray::BuildPortions and MergePortions,
  91   which create non-overlapping portions of formatting attributes.
  92
  93 - nesting attributes: Hyperlinks (SwTxtINetFmt, RES_TXTATR_INETFMT),
  94   Ruby (SwTxtRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTxtMeta,
  95   RES_TXTATR_META/RES_TXTATR_METAFIELD):
  96   these maintain a properly nested tree structure.
  97   The Meta/Metafield are "special" because they have both start/end
  98   and a dummy character at the start.
  99
 100 - misc. attributes: Reference Marks, ToX Marks
 101
 102 - attributes without end: Fields, Footnotes, Flys (AS_CHAR)
 103   These all have a corresponding dummy character in the paragraph text, which
 104   is a placeholder for the "expansion" of the attribute, e.g. field content.
 105
 106