*** How to understand the writer core ***


* What does a document look like ?

	"Hello <b>World</b>\nParagraph 2\n"

-------------------------- basics --------------------------

* here goes:

sw/inc/doc.hxx (class SwDoc):

	SwNodes		aNodes;    - the contents of the document
	SwAttrPool	aAttrPool; - default document properties; from SfxPoolItem
	SwUndoNodes     aUndoNodes; - undo nodes.

SwNodes -> BigPtrArray (inc/ndarr.hxx)

sw/inc/node.hxx (SwNode):

	+ then 'SwCntntNode' (content node)

sw/inc/ndtxt.hxx (class SwTxtNode)
	XubString	aText;   => "Hello World"
	SwpHints	*pSwpHints;   (inc/ndhints.hxx)
		+ "not a hint" - it's the real document attribute data.
		+ means 'Attributes'
		+ eg. (6,10, "bold")

	friend of SwpHints::BuildPortions
		+ a portion - something the layout does;
			+ builds a portion; 

Key concept:
	+ Portion + - a uniform run of text with the same attributes
		+ ie. 2 runs for "Hello", <b>"World"</b>

	Another interesting impl.
		+ SwpHints::Insert (SwTxtAttr *, SwTxtNode &, USHORT);
		+ inserts tripples : this automatically merges sub-'Hints'


-------------------------- more detail --------------------------

* 65k - for para length.
	+ problems with line breaks. <shift>Enter
		+ from HTML <br> instead of <p> - a nightmare.
	+ extra logic for:
		+ cursor extends before the 'H' of hello world; hit enter.
		+ paragraph - split it to two;
			+ SplitCntntNode ...
			+ all kinds of magic - splitting the attributes too.
				+ now consistent (?)

* Undo:
	+ as you change a node, copied to the aUndoNodes
		+ implemented with copy/paste - same code.
		+ select entire para, copy into undo, then split the para,
		+ then keep a stack, of what need to do to undo.

	+ There is a single huge "un-do document" lurking in the background.

	* Try - turn on red-lining; want to track changes,
		+ also want to see original document.
		+ As you type: Writer copies in all the redlining; makes the
		  modification; updates it; copies the differences back.
			+ magic alert box - do something different...

* Sections:
	+ (inc/node.hxx) SwSectionNode derived from 'SwStartNode'
		+ implemented when everyone wanted to be an HTML editor
		+ web editor & web viewer - Brauer implementation +
			+ like a <div> tag.
	+ mutual pointers to each other.

* Tables:
	+ (inc/node.hxx) SwTableNode (an SwStartNode)
		+ completed by the 'SwEndNode'
		+ 'Frame' is a layout object ...
			+ 'SwFrm' - everything based on this
				+ ptr to child / parent / rectangle
		+ design nightmare:
			+ layout in model is necessary to do some
			  internal navigation
		+ the real table content appears just like a flat
		  document between; *but*:

	+ SwTable (inc/swtable.hxx):
		+ this stores pointers to the underlying paragraphs
		  for rows / columns.

	+ cell merging, vert / horiz now possible;
		+ previously - you could split cells
			+ but couldn't display every table from merge model.
			+ "Table too complex" / export same problem.
			+ need to know widths of rows to do this export.
	+ the merge thing is now implemented;
		+ only impl. for ODF; not yet in the doc import/export.
		+ CWS not yet complete.
			+ all the old documents still have this model.
			+ can mix models.

	+ no real red-lining support for tables:
		+ was there a row deleted / cell inserted ?
		+ serious problem +


* SwPaM (point and mark) (inc/pam.hxx)
	+ can be a selection, or a cursor position.
	+ most famous: "insert-unicode character"
		+ used in import filters:
			+ as if you type it in.



Q. why can't we skip nodes in layout ?
	+ how hard-coded is all that ? - just a flat piece-table like
	  representation etc. ?


-------------------------- layout --------------------------

* Everything in layout is measured in TWIPS
	+ 1440 twip/inch. or 567 / cm.  [ cumul error ? ]
		+ so ~250k page limit.
	+ DPI neceessary to do layout; used to use printer
	  resolution; re-layout with a different printer.
	+ nowadays - layout is done at:
		+ 8640 DPI (usually) used for fonts.
		+ then convert to TWIPS & loose resolution.
	+ using device-independaent layout;
		+ metrics & char widths used from high res,
		+ looses lots of fidelity / wastes the work
		  of the artists, doing lower-res tweaking.

* Everything derived from SwFrm
	+ source/core/inc/frame.hxx
		+ (SwRectFnCollection)
	+ class SwFrm:
		SwRect aFrm; - absolute document position
		SwRect aPrt; - same rectangle relative to parent
	+ SwRect (long X,Y,Width,Height)
	+ 'SwRootFrame' (source/core/inc/rootfrm.hxx)
		+ children of that - are pages.
		+ 5000 pages; 

	+ Root frame
		+ Page Frame
			+ Header
			+ Body
				+ Paragraph |
				+ Table frame |
				+ Column frame
			+ Footer 

	* first time you want to do layout:
		+ create a root frame, call "make all"
			+ called recusively in a timer loop,
			  every <N> milliseconds.
			+ creates all the children ?
		+ walk tree / is there a difference ?
			+ insert a new para or not.
			+ lots of difference detection.

	* every few ms - layout calls 'make all'

	* create an SwDoc, insert a new character; trigger make all
		+ run through whole tree
			- try to skip as much as possible
		+ modify the current layout.
		+ OLPC - has issues; open a writer document
			+ don't do anything - watch battery go down
			+ idle loop, kicks in regularly.

	* Beware while debugging:
		+ if you 'continue' - can come back into breakpoints
		  via the timer ... / makes life hard.

	* layout loops / debugging:
		+ nightmares with absolute positioned objects
			+ Paragraph lays itself out; places an object
			  somewhere, starts to re-layout.
			+ no single control loop,
				+ any object can ping - (ie. force relayout)
				  of any other object.

	* frame.hxx (ShrinkFrm, GrowFrm) - called lots
		+ eg. footnote example, push footnote off - ShrinkFrm
		  pushes para to next page, 
		+ previous page - GrowFrm - to fit next next para.

	* Layout loops - 10 man year a hole, trying to understand the issues

	* Loop free layout:
		* an example:
			+ source/core/layout/calcmove.cxx (SwCntntFrm::MakeAll)
			+ #define STOP_FLY_FORMAT 10
			+ eg.:
// --> OD 2006-09-25 #b6448963# - loop prevention
const int cnStopFormat = 15;
// <--
            // --> OD 2006-01-23 #i59341#
            // Workaround for inadequate layout algorithm:
            // suppress invalidation and calculation of position, if paragraph
            // has formatted itself at least STOP_FLY_FORMAT times and
            // has anchored objects.
            // Thus, the anchored objects get the possibility to format itself
            // and this probably solve the layout loop.

		* 'StackHack' - is a framek already invalidated [etc.]
			+ try not to re-invalidate it.
			+ does loop detection

		* improvement - hit pause in the debugger, add a loop
		  catch repeat.

	* Macros to detect it:

    // NEW: Looping Louie (Light). Should not be applied in balanced sections.
    // Should only be applied if there is no better solution!
    LOOPING_LOUIE_LIGHT( bMovedFwd && bMovedBwd && !IsInBalancedSection() &&

	* The MS layout algorithm is -much- simpler.
		+ lots of features, this layout supports, we don't need to
		  be interoperable.
		+ the answer - throw away stuff.



-------------------------- misc --------------------------

* most functions - designed to respond to user input.

* the legacy Word import filter:
	+ fills out internal structures, etc.

* Import issues:
	+ Doc import currently:
		+ type text in, go back, create selection,
		  apply attributes etc.
		+ as if you would type it.
	+ UNO API: wrapper around SwDoc, again as if you were typing.
		+ can't front-load attributes as we push them.
		+ InsertAttr -> import filters; append attributes.
		+ extra space & empty para at the end.
			+ clean new style info.
			+ new 'Filter' API ...
	+ lots of additional tricks to overcome these problems.
		+ consider the issues +
		+ "<b>Hello</b>\nWorld"
			+ as you type 'World' it becomes bold, so you
			  have to overcome this by misc. evil. tricks.
	+ as you debug import:
		+ see lots of additional spaces / paras being inserted
		  and subsequently removed ...
			+ someone forgot to cleanup artificial paragraph.

* MS do things differently
	+ piece-table, formatting codes etc.
	+ OTOH - word can't do nested sections (yet)
		+ entirely different concepts +
		+ word section - more like a "Master Page" / "Page style"
			+ except for 1 thing:
			+ Word sections, can be balanced.





