1 files changed, 129 insertions, 0 deletions
diff --git a/kword/DESIGN b/kword/DESIGN
new file mode 100644
index 00000000..6a01ae28
--- /dev/null
+++ b/kword/DESIGN
@@ -0,0 +1,129 @@
+Overall design
+==============
+
+* The document (KWDocument) has a list of framesets (KWFrameSet)
+
+* Framesets include: text frameset, picture/clipart frameset, table frameset etc.
+
+* A frameset has a list of frames, KWFrame. A KWFrame is basically a rectangle
+(KoRect) with a bunch of attributes. 
+The frameset contains the contents, like the text or a picture.
+The frames visualize the contents of the frameset. 
+Imagine a 10 pages document, with 1 text-frameset and 10 frames, because our
+example author wants to have one frame per page.  This means that there is one 
+text, and the frames define where on the pages this text is displayed.
+
+* About text framesets: they hold a text document (KWTextDocument, which is
+a QTextDocument from the KoText classes - more on KoText later).
+
+* About Tables; one table is a KWTableFrameset. This tableframeset contains
+all the cells as its frames. But because the cells have a different text per
+cell, we contain the cells in their own KWTextFrameset.
+
+   KWTableFrameSet
+    |           |
+    |        TextFrames
+  Cells               +--------+
+      |                        |
+      + ---> KWTextFrameSet    |
+      |          +-> KWFrame <-+
+      |                        |
+      + ---> KWTextFrameSet    |
+      |          +-> KWFrame <-+
+      |                        |
+      + ---> KWTextFrameSet    |
+                 +-> KWFrame <-+
+
+* The z-order of the frames (i.e. which one is on top of which)
+is defined by m_zOrder in KWFrame. This number is relative to the other
+frames *on the same page*.
+
+Frame layout and pages
+======================
+Generally, the user is free to position frames where he/she wants to.
+
+KWTextFrameSet::slotAfterFormatting() takes care of triggering frame
+resizing (AutoExtend frames), creating a new page (AutoCreateNewFrame), etc.
+
+However, in Word Processing mode, some frames are special: main text frameset
+(which might include columns), headers, footers, and footnotes. All of those
+are laid out by the KWFrameLayout class, which is triggered by
+KWDocument::recalcFrames.
+
+When creating a new page, KWDocument::insertPage takes care of creating the
+followup frames for all frames with newFrameBehavior=Reconnect.
+
+The newFrameBehavior called "Copy" means "exact copy of the contents of
+the frame". This is used for headers/footers (but the user can also use
+it for logos and stuff). In such a case we don't copy anything, we simply
+paint the same contents in many pages.
+
+In WP mode, removing pages is automatically done by KWDocument::tryRemovingPages().
+
+In DTP mode pages are user-controlled (insert and delete page actions),
+but overflowing text can still create a new page as well.
+
+The difficulty with frame layout is that in most cases the frame size and
+number depends on the text inside, and the text layout depends on the frames
+(frame width, frames on top, etc.). This is why text layout (formatMore())
+and frame layout (e.g. KWFrameLayout) often call each other, resulting in
+infinite loops when some code goes wrong.
+
+Editing
+=======
+To edit the contents of a text frameset (including table cells), the user clicks on it.
+This creates an edit object for the frameset, which will be destroyed as soon as we go
+edit another frameset. This means, in a given view (canvas), there is only one edit
+object at a given moment (for text objects, it's the one with the cursor).
+There is one type of edit object per type of frameset. For instance: KWTextFrameSetEdit.
+
+The kotext library provides a base class for the 'text editing' object, it's KoTextView.
+
+Custom items
+============
+A custom item is anything (like an inline frame, a variable etc.) that
+is treated as a special character. QTextCustomItem is the base class for
+it, we have KoTextCustomItem in kotext.
+
+Inline frames are one kind of custom item. The frame (and its englobing
+frameset) exist as usual, but a KWAnchor instance is created, inserted
+into the text, and linked to the frame. The anchor always has the same size
+as the frame. When the text is flowed, the anchor is positioned, it tells
+the frame to move to the new position.
+
+Painting
+========
+Here's how the painting (drawing the stuff on screen, and on printer) works:
+Each frameset is responsible for drawing itself. The base class, KWFrameSet,
+handles the generic code for iterating through the frames, applying the
+"frame is a copy" stuff, drawing the borders, etc. So each specific frameset
+class only has to implement drawFrame (exception for KWTableFrameset though).
+
+Painting of text: KWTextFrameset paints the text for each frame, calling
+KoTextDocument::drawWYSIWYG (with flags for "only the changed paragraphs" etc).
+When printing this method delegates to drawWithoutDoubleBuffer.
+Both methods iterate through the paragraphs, and call drawParagWYSIWYG for each
+one to be redrawn. This method implements the double-buffering, paints the
+background color and the space on the right of the paragraph, and calls
+QTextParag::paint(). Its role is to draw series of characters with the same
+formatting at once (in one go). For each set of chars to be painted,
+KoTextParag::drawParagString is called.
+
+In short:
+KWFrame::drawContents -> KWTextFrameSet::drawFrame
+ -> KoTextDocument::drawWYSIWYG -> KoTextDocument::drawParagWYSIWYG
+ -> KoTextParag::paint -> KoTextParag::drawParagString -> KoTextParag::drawParagStringInternal
+
+The cursor is also drawn by KoTextParag::paint, which calls KoTextParag::drawCursor.
+The blinking cursor is implemented in KoTextView, which calls a virtual
+drawCursor() method, implemented in KWTextFrameSetEdit.
+
+More low-level things
+=====================
+.. such as coordinate systems, font sizes, justified spaces etc.
+See lib/kotext/DESIGN.
+
+
+Wow, you managed to read this until the end ? Good. "GOTO 10" now ;)
+
+David Faure <faure@kde.org>