diff options
Diffstat (limited to 'sw')
| -rw-r--r-- | sw/README.md | 216 |
1 files changed, 108 insertions, 108 deletions
diff --git a/sw/README.md b/sw/README.md index f4c6e44e1c28..58a6cc9e1bdb 100644 --- a/sw/README.md +++ b/sw/README.md @@ -5,61 +5,61 @@ comments show that Writer core dates back until at least November 1990. ## Module Contents - * inc: headers available to all source files inside the module - * qa: unit, slow and subsequent tests - * sdi - * source: see below - * uiconfig: user interface configuration - * util: UNO passive registration config + * `inc`: headers available to all source files inside the module + * `qa`: unit, slow and subsequent tests + * `sdi` + * `source`: see below + * `uiconfig`: user interface configuration + * `util`: UNO passive registration config ## Source Contents - * core: Writer core (document model, layout, UNO API implementation) - * filter: Writer internal filters - * ascii: plain text filter - * basflt - * docx: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes - * html: HTML filter - * inc: include files for filters - * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter) - * writer - * ww8: DOC import, DOC/DOCX/RTF export - * xml: ODF import/export, subclassed from xmloff (where most of the work is done) - * uibase: user interface (those parts that are linked into sw & always loaded) - * ui: user interface (optional parts that are loaded on demand (swui)) + * `core`: Writer core (document model, layout, UNO API implementation) + * `filter`: Writer internal filters + * `ascii`: plain text filter + * `basflt` + * `docx`: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes + * `html`: HTML filter + * `inc`: include files for filters + * `rtf`: thin copy&paste helper around the UNO RTF import filter (in writerfilter) + * `writer` + * `ww8`: DOC import, DOC/DOCX/RTF export + * `xml`: ODF import/export, subclassed from xmloff (where most of the work is done) + * `uibase`: user interface (those parts that are linked into `sw` & always loaded) + * `ui`: user interface (optional parts that are loaded on demand (`swui`)) ## Core There is a good overview documentation of basic architecture of Writer core in the OOo wiki: -- http://wiki.openoffice.org/wiki/Writer/Core_And_Layout -- http://wiki.openoffice.org/wiki/Writer/Text_Formatting +- <https://wiki.openoffice.org/wiki/Writer/Core_And_Layout> +- <https://wiki.openoffice.org/wiki/Writer/Text_Formatting> -Writer specific WhichIds are defined in sw/inc/hintids.hxx. +Writer specific WhichIds are defined in `sw/inc/hintids.hxx`. -The details below are mainly about details missing from the Wiki pages. +The details below are mainly about details missing from the wiki pages. ### SwDoc -The central class for a document is SwDoc, which represents a document. +The central class for a document is `SwDoc`, which represents a document. A lot of the functionality is split out into separate Manager classes, -each of which implements some IDocument* interface; there are -SwDoc::getIDocument*() methods to retrieve the managers. +each of which implements some `IDocument*` interface; there are +`SwDoc::getIDocument*()` methods to retrieve the managers. However there are still too many members and methods in this class, many of which could be moved to some Manager or other... ### SwNodes -Basically a (fancy) array of SwNode pointers. There are special subclasses of -SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree -structure into the flat array; the range of nodes from SwStartNode to its -corresponding SwEndNode is sometimes called a "section" (but is not necessarily +Basically a (fancy) array of `SwNode` pointers. There are special subclasses of +`SwNode` (`SwStartNode` and `SwEndNode`) which are used to encode a nested tree +structure into the flat array; the range of nodes from `SwStartNode` to its +corresponding `SwEndNode` is sometimes called a "section" (but is not necessarily what the high-level document model calls a "Section"; that is just one of the possibilities). -The SwNodes contains the following top-level sections: +The `SwNodes` contains the following top-level sections: 1. Empty 2. Footnote content @@ -69,40 +69,40 @@ The SwNodes contains the following top-level sections: ### Undo -The Undo/Redo information is stored in a sw::UndoManager member of SwDoc, -which implements the IDocumentUndoRedo interface. -Its members include a SwNodes array containing the document content that +The Undo/Redo information is stored in a `sw::UndoManager` member of `SwDoc`, +which implements the `IDocumentUndoRedo` interface. +Its members include a `SwNodes` array containing the document content that is currently not in the actual document but required for Undo/Redo, and -a stack of SwUndo actions, each of which represents one user-visible +a stack of `SwUndo` actions, each of which represents one user-visible Undo/Redo step. -There are also ListActions which internally contain several individual SwUndo +There are also `ListActions` which internally contain several individual `SwUndo` actions; these are created by the StartUndo/EndUndo wrapper methods. ### Text Attributes -The sub-structure of paragraphs is stored in the SwpHintsArray member -SwTextNode::m_pSwpHints. There is a base class SwTextAttr with numerous -subclasses; the SwTextAttr has a start and end index and a SfxPoolItem +The sub-structure of paragraphs is stored in the `SwpHintsArray` member +`SwTextNode::m_pSwpHints`. There is a base class `SwTextAttr` with numerous +subclasses; the `SwTextAttr` has a start and end index and a `SfxPoolItem` to store the actual formatting attribute. -There are several sub-categories of SwTextAttr: +There are several sub-categories of `SwTextAttr`: -- formatting attributes: Character Styles (SwTextCharFormat, RES_TXTATR_CHARFMT) - and Automatic Styles (no special class, RES_TXTATR_AUTOFMT): - these are handled by SwpHintsArray::BuildPortions and MergePortions, +- formatting attributes: Character Styles (`SwTextCharFormat`, `RES_TXTATR_CHARFMT`) + and Automatic Styles (no special class, `RES_TXTATR_AUTOFMT`): + these are handled by `SwpHintsArray::BuildPortions` and MergePortions, which create non-overlapping portions of formatting attributes. -- nesting attributes: Hyperlinks (SwTextINetFormat, RES_TXTATR_INETFMT), - Ruby (SwTextRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTextMeta, - RES_TXTATR_META/RES_TXTATR_METAFIELD): +- nesting attributes: Hyperlinks (`SwTextINetFormat`, `RES_TXTATR_INETFMT`), + Ruby (`SwTextRuby`, `RES_TXTATR_CJK_RUBY`) and Meta/MetaField (`SwTextMeta`, + `RES_TXTATR_META/RES_TXTATR_METAFIELD`): these maintain a properly nested tree structure. The Meta/Metafield are "special" because they have both start/end and a dummy character at the start. - misc. attributes: Reference Marks, ToX Marks -- attributes without end: Fields, Footnotes, Flys (AS_CHAR) +- attributes without end: Fields, Footnotes, Flys (`AS_CHAR`) These all have a corresponding dummy character in the paragraph text, which is a placeholder for the "expansion" of the attribute, e.g. field content. @@ -110,90 +110,90 @@ There are several sub-categories of SwTextAttr: There are multiple model classes involved for fields: -- enum SwFieldIds enumerates the different types of fields. -- SwFieldType contains some shared stuff for all fields of a type. - There are many subclasses of SwFieldType, one for each different type +- `enum SwFieldIds` enumerates the different types of fields. +- `SwFieldType` contains some shared stuff for all fields of a type. + There are many subclasses of `SwFieldType`, one for each different type of field. For most types of fields there is one shared instance of this per type, - which is created in DocumentFieldsManager::InitFieldTypes() + which is created in `DocumentFieldsManager::InitFieldTypes()` but for some there are more than one, and they are dynamically created, see - DocumentFieldsManager::InsertFieldType(). An example for the latter are - variable fields (SwFieldIds::GetExp/SwFieldIds::SetExp), with one SwFieldType per + `DocumentFieldsManager::InsertFieldType()`. An example for the latter are + variable fields (`SwFieldIds::GetExp/SwFieldIds::SetExp`), with one `SwFieldType` per variable. -- SwXFieldMaster is the UNO wrapper of a field type. - It is a SwClient registered at the SwFieldType. - Its life-cycle is determined by UNO clients outside of sw; it will get - disposed when the SwFieldType dies. -- SwFormatField is the SfxPoolItem of a field. - The SwFormatField is a SwClient registered at its SwFieldType. - The SwFormatField owns the SwField of the field. -- SwField contains the core logic of a field. - The SwField is owned by the SwFormatField of the field. - There are many subclasses of SwField, one for each different type of field. +- `SwXFieldMaster` is the UNO wrapper of a field type. + It is a `SwClient` registered at the `SwFieldType`. + Its life-cycle is determined by UNO clients outside of `sw`; it will get + disposed when the `SwFieldType` dies. +- `SwFormatField` is the `SfxPoolItem` of a field. + The `SwFormatField` is a `SwClient` registered at its `SwFieldType`. + The `SwFormatField` owns the `SwField` of the field. +- `SwField` contains the core logic of a field. + The `SwField` is owned by the `SwFormatField` of the field. + There are many subclasses of `SwField`, one for each different type of field. Note that there are not many places that can Expand the field to its correct value, since for example page number fields require a View with an up to date layout; therefore the correct expansion is cached. -- SwTextField is the text attribute of a field. - It owns the SwFormatField of the field (like all text attributes). -- SwXTextField is the UNO wrapper object of a field. - It is a SwClient registered at the SwFormatField. - Its life-cycle is determined by UNO clients outside of sw; it will get - disposed when the SwFormatField dies. +- `SwTextField` is the text attribute of a field. + It owns the `SwFormatField` of the field (like all text attributes). +- `SwXTextField` is the UNO wrapper object of a field. + It is a `SwClient` registered at the `SwFormatField`. + Its life-cycle is determined by UNO clients outside of `sw`; it will get + disposed when the `SwFormatField` dies. ### Lists -- SwNumFormat (subclass of SvxNumFormat) determines the formatting of a single +- `SwNumFormat` (subclass of `SvxNumFormat`) determines the formatting of a single numbering level. -- SwNumRule (NOT a subclass of SvxNumRule) is a *list style*, containing one - SwNumFormat per list level. - SwNumRule::maTextNodeList is the list of SwTextNode that have this list style +- `SwNumRule` (NOT a subclass of `SvxNumRule`) is a *list style*, containing one + `SwNumFormat` per list level. + `SwNumRule::maTextNodeList` is the list of `SwTextNode` that have this list style applied. -- SwNumberTreeNode is a base class that represents an abstract node in a +- `SwNumberTreeNode` is a base class that represents an abstract node in a hierarchical tree of numbered nodes. -- SwNodeNum is the subclass of SwNumberTreeNode that connects it with an - actual SwTextNode and also with a SwNumRule; - SwTextNode::mpNodeNum points back in the other direction +- `SwNodeNum` is the subclass of `SwNumberTreeNode` that connects it with an + actual `SwTextNode` and also with a `SwNumRule`; + `SwTextNode::mpNodeNum` points back in the other direction -- SwList represents a list, which is (mostly) a vector of SwNodeNum trees, - one per SwNodes top-level section (why that?). +- `SwList` represents a list, which is (mostly) a vector of `SwNodeNum` trees, + one per `SwNodes` top-level section (why that?). -- IDocumentListsAccess, sw::DocumentListsManager owns all SwList instances, +- `IDocumentListsAccess`, `sw::DocumentListsManager` owns all `SwList` instances, and maintains mappings: - + from list-id to SwList - + from list style name to SwList (the "default" SwList for that list style) + + from list-id to `SwList` + + from list style name to `SwList` (the "default" `SwList` for that list style) -- IDocumentListItems, sw::DocumentListItemsManager contains a set of all - SwNodeNum instances, ordered by SwNode index +- `IDocumentListItems`, `sw::DocumentListItemsManager` contains a set of all + `SwNodeNum` instances, ordered by `SwNode` index -- the special Outline numbering rule: SwDoc::mpOutlineRule +- the special Outline numbering rule: `SwDoc::mpOutlineRule` -- IDocumentOutlineNodes, sw::DocumentOutlineNodesManager maintain - a list (which is actually stored in SwNodes::m_pOutlineNodes) of SwTextNodes +- `IDocumentOutlineNodes`, `sw::DocumentOutlineNodesManager` maintain + a list (which is actually stored in `SwNodes::m_pOutlineNodes`) of `SwTextNodes` that either have the Outline numrule applied, - or have the RES_PARATR_OUTLINELEVEL item set (note that in the latter case, - the SwTextNode does not have a SwNodeNum and is not associated with the - SwDoc::mpOutlineRule). - -- SwTextNodes and paragraph styles have items/properties: - + RES_PARATR_OUTLINELEVEL/"OutlineLevel" to specify an outline level without - necessarily having the outline SwNumRule assigned - + RES_PARATR_NUMRULE/"NumberingStyleName" the list style to apply; may be - empty "" which means no list style (to override inherited value) - Only SwTextNode has these items: - + RES_PARATR_LIST_ID/"ListId" - determines the SwList to which the node is added - + RES_PARATR_LIST_LEVEL/"NumberingLevel" - the level at which the SwTextNode will appear in the list - + RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart" - restart numbering sequence at this SwTextNode - + RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue" - restart numbering sequence at this SwTextNode with this value - + RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber" + or have the `RES_PARATR_OUTLINELEVEL` item set (note that in the latter case, + the `SwTextNode` does not have a `SwNodeNum` and is not associated with the + `SwDoc::mpOutlineRule`). + +- `SwTextNodes` and paragraph styles have items/properties: + + `RES_PARATR_OUTLINELEVEL/"OutlineLevel"` to specify an outline level without + necessarily having the outline `SwNumRule` assigned + + `RES_PARATR_NUMRULE/"NumberingStyleName"` the list style to apply; may be + empty `""` which means no list style (to override inherited value) + Only `SwTextNode` has these items: + + `RES_PARATR_LIST_ID/"ListId"` + determines the `SwList` to which the node is added + + `RES_PARATR_LIST_LEVEL/"NumberingLevel"` + the level at which the `SwTextNode` will appear in the list + + `RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart"` + restart numbering sequence at this `SwTextNode` + + `RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue"` + restart numbering sequence at this `SwTextNode` with this value + + `RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber"` determines if the node is actually counted in the numbering sequence; - these are different from "phantoms" because there's still a SwTextNode. + these are different from `"phantoms"` because there's still a `SwTextNode`. Note that there is no UNO service to represent a list. @@ -204,7 +204,7 @@ possible between frames: - You can visit the tree by following the upper, lower, next and previous pointers. - The functionality of flowing of a frame across multiple parents (e.g. pages) - is implemented in SwFlowFrame, which is not an SwFrame subclass. The logical + is implemented in `SwFlowFrame`, which is not an `SwFrame` subclass. The logical chain of such frames can be visited using the follow and precede pointers. ("Leaf" is a term that refers to such a relationship.) - In case a frame is split into multiple parts, then the first one is called |