Writer/Core And Layout

Caution

This page is still under construction hence the content is still very tentative.

About Frames

The layout is the visual representation of a Writer document. Basically a frame is a rectangular area which is linked with other frames:

The base class of the frame hierachy is SwFrm, which is derived from SwClient for inheriting the ability of being notified by changes.

SwFrm : SwClient

pRegisteredIn : SwModify*

pUpper : SwFrm*

pNext : SwFrm*

pPrev : SwFrm*

aFrm : SwRect

aPrt : SwRect

bValidPos : bool

bValidSize : bool

bValidPrtArea : bool

A layout frame has an additional member pLower, i.e., a layout frame is a frame that contains other frames. Incarnations of a layout frame are pages, tables, ...

SwLayoutFrm : SwFrm

pLower : SwFrm*

Some frames are not only derived from SwFrm, but also from SwFlowFrm. These are the frames that are allowed at page breaks and shall continue on the next page, e.g., paragraphs, tables, ...

SwFlowFrm

rThis : SwFrm&

pFollow : SwFlowFrm*

The most important frame is the SwTxtFrm, which is the layout counterpart a SwTxtNode object. The nOfst member referes to the aText string member of the associated SwTxtNode object. A SwTxtFrm object is registered in a SwTxtNode object in order to be notified in case the SwTxtNode object is changed.

SwTxtFrm : SwFrm

nOfst : xub_StrLen

A page frame additionally has a couple of boolean members to indicate if any of the page contents is invalid. These flags are used during formatting of the document.

SwPageFrm

bInvalidLayout : bool

bInvalidContent : bool

bInvalidFly : bool

Some Notes about Nodes

A SwDoc object, which denotes the model of a Writer document, has as member of Type SwNodes, which stores the document content. The SwNodes object of an empty Writer document looks like this:

SwStartNode	(special start-end-section, not used)
SwEndNode
SwStartNode	(special start-end-section used for footnotes)
SwEndNode
SwStartNode	(special start-end-section used for frames, headers, footers)
SwEndNode
SwStartNode	(special start-end-section used for 'delete' redlines if they are not shown)
SwEndNode
SwStartNode (special start-end-section for 'regular' document content)
	SwTxtNode	(there always at least one empty paragraph in the document)
SwEndNode

SwTxtNode : SwCntntNode

aText : string

Relationship between nodes and frames

An important base class of the Writer model is SwNode, an important base class of the Writer view is SwFrm.

What's the relationship between the classes derived from these?

SwTxtNode <-> SwTxtFrm
Every SwTxtFrm belongs to a SwTxtNode, a SwTxtFrm is a SwClient and is registered in a SwModify (the SwTxtNode!).
Some SwTxtNodes do not have related SwTxtFrms, e.g. if they are in a hidden section or a header of an unused page style.
Some SwTxtNodes have more than one corresponding SwTxtFrm, e.g. if they are in a header of a used page style or if the content did not fit into one page.

SwTableNode <-> SwTabFrm
The relationship between SwTableNode and SwTabFrm is nearly like SwTxtNode/SwTxtFrm. One difference: the SwTabFrm is not registered in SwTableNode, it is registered in the table format (SwTableFmt).
A SwTableNode may have no SwTabFrm if it is hidden or part of an unused page style. A SwTableNode normally has one corresponding SwTabFrm, but could have more if it does not fit into one page or if it is part of a repeated page header/footer.

SwRowFrm
A SwRowFrm represents a row of a table. There is no corresponding SwNode object. A SwTabFrm contains at least one SwRowFrm (pLower). A SwRowFrm contains at least one SwCellFrm.

SwTableBoxStartNode <-> SwCellFrm
The cells of a table are represented in the nodes array by SwStartNode (type SwTableBoxStartNode), the content of the cell is represented by the nodes between this SwStartNode and its SwEndnode. The corresponding view object is the SwCellFrm. The relationship is again like the SwTxtNode/SwTxtFrm relationship.

SwRootFrm
If a Writer document has a view (layout) there is one SwRootFrm (member of SwDoc), which represent the complete document, i.e. the complete SwNodes array. This SwRootFrm contains a double linked list of SwPageFrm, the pages of the document.

SwPageFrm
A SwPageFrm is a view object without a corresponding model object (SwNode). The pLower of the SwRootFrm is a SwPageFrm, if the document contains more than one page, these are double linked (pNext, pPrev). The pUpper of a SwPageFrm is allways the SwRootFrm. A SwPageFrm contains a double linked list of SwLayoutFrms, at least a SwBodyFrm for the floating text content and an optional SwHeaderFrm and SwFooterFrm. The SwHeaderFrm is the first frame in the list, the SwFooterFrm the last one (if they exist).

SwColumnFrm
A SwColumnFrm is a view object without a corresponding model object. It divides its upper layout frame into several columns. This upper frame can be a SwBodyFrm, a SwFlyFrm or a SwSectionFrm. The pLower of a SwColumnFrm is a SwBodyFrm.

SwSectionNode <-> SwSectFrm
A section in Writer is represented in the model by a pair SwSectionNode/SwEndNode. The content of the section (paragraphs and tables) are enclosed by this pair. If a SwTxtFrm corresponds to a SwTxtNode which is part of a section then normally the SwTxtFrm is lower to the corresponding SwSectionFrm (see example later on). If such a paragraph is broken by the page border into two pieces, the corresponding SwTxtFrms are lower to two different SwSectionFrm.
The relationship between SwSectionNode and SwSectFrm becomes complicated for nested sections. Even the SwSectionNodes are neseted, the corresponding SwSectionFrm are not! They are not lower/upper of each other, they are in the same list as pPrev/pNext.

Time to have a look at some examples:
1. The simplest document: one paragraph
Model:

 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
   <SwTxtNode A>
 <SwEndNode>

View:

 <SwRootFrm>
   <SwPageFrm>
     <SwBodyFrm>
       <SwTxtFrm A/>
     </SwBodyFrm>
   </SwPageFrm>
 </SwRootFrm>

2. A document with a page header (containing two paragraphs) and four paragraphs in floating content. The third paragraph has been splitted at the page margin
Model:

 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
   <SwStartNode>
     <SwTxtNode X>
     <SwTxtNode Y>
   <SwEndNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
   <SwTxtNode A>
   <SwTxtNode B>
   <SwTxtNode C>
   <SwTxtNode D>
 <SwEndNode>

View:

 <SwRootFrm>
   <SwPageFrm>
     <SwHeaderFrm>
       <SwTxtFrm X/>
       <SwTxtFrm Y/>
     </SwHeaderFrm>
     <SwBodyFrm>
       <SwTxtFrm A/>
       <SwTxtFrm B/>
       <SwTxtFrm C (part 1)/>
     </SwBodyFrm>
   </SwPageFrm>
   <SwPageFrm>
     <SwHeaderFrm>
       <SwTxtFrm X/>
       <SwTxtFrm Y/>
     </SwHeaderFrm>
     <SwBodyFrm>
       <SwTxtFrm C (part 2)/>
       <SwTxtFrm D/>
     </SwBodyFrm>
   </SwPageFrm>
 </SwRootFrm>

3. A document with one 2x2 table, different amount of paragraphs in table boxes and one paragraph behind the table. Model:

 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
 <SwEndNode>
 <SwStartNode>
   <SwTableNode>
     <SwStartNode>
       <SwTxtNode X>
     <SwEndNode>
     <SwStartNode>
       <SwTxtNode Y>
       <SwTxtNode Z>
     <SwEndNode>
     <SwStartNode>
       <SwTxtNode A>
       <SwTxtNode B>
       <SwTxtNode C>
     <SwEndNode>
     <SwStartNode>
       <SwTxtNode D>
     <SwEndNode>
   <SwEndNode>
   <SwTxtNode Z>
 <SwEndNode>

View:

 <SwRootFrm>
   <SwPageFrm>
     <SwBodyFrm>
       <SwTableFrm>
         <SwRowFrm>
           <SwCellFrm>
             <SwTxtFrm X/>
           </SwCellFrm>
           <SwCellFrm>
             <SwTxtFrm Y/>
             <SwTxtFrm Z/>
           </SwCellFrm>
         </SwRowFrm>
         <SwRowFrm>
           <SwCellFrm>
             <SwTxtFrm A/>
             <SwTxtFrm B/>
             <SwTxtFrm C/>
           </SwCellFrm>
           <SwCellFrm>
             <SwTxtFrm D/>
           </SwCellFrm>
         </SwRowFrm>
       </SwTableFrm>
       <SwTxtFrm Z/>
     </SwBodyFrm>
   </SwPageFrm>
 </SwRootFrm>

Some UML Diagrams

Nodes

Attributes

Cursors

Formats / Styles

Tables

Basically, there is the model representation (class SwTable) and the view representation (SwTabFrm) of Writer tables.

The Table Model

The table model is defined in an SwTable object. The SwTable object consists of an array of SwTableLine objects, which in turn consist of arrays of SwTableBox objects. All these objects are registered in classes derived from SwFrmFmt (SwTableFmt, SwTableLineFmt, SwTableBoxFmt). The attributes of the table, the table lines and table boxes are set at these SwFrmFmt objects. This way, changes at the attributes are propagated via the Modify() function to the table model objects.

The Table Frames

The table layout objects are SwTabFrm, SwRowFrm, and SwCellFrm. Each of them is associated with a corresponding table model object: SwTable <-> SwTabFrm, SwTableLine <-> SwRowFrm, SwTableBox <-> SwCellFrm. Likr the table model objects, the table layout objects are also registered as clients of the respective SwFrmFmt objects.