koffice/kformula/DESIGN

                        The design of kformula
                          (as we imagine it)

The core of kformula is a tree of element objects that make up the
formula which is beeing edited.

The element tree itself
#######################

BasicElement
------------

All element classes are derived from this one.
So it provides the interface that is common to all elements.
BasicElement itself is an abstract class. You never want to create
objects from it.

Responsebilities
(This goes for every derived element and therefore for each one.)

- knows its children. Actually BasicElement doesn't have any. But it
  already defines that children must be known by their parent.
- knows its bounding rectangle (its size.) The children are included
  in this rect. (Only width and height are needed. Positions are
  handled by the parent)
//- knows its middle line. (for alignment)
- knows it's zero point for midline (vertical alignment) and 
  keep open the possibility of negative positions (out of bounding rect)
- draws itself (given a painter); children are drawn, too
- knows all positions where the cursor is allowed to be. (see below)
- knows its parent; The topmost element has no parent; there is a
  implicit garantie that the topmost element is always a
  SequenceElement.
- can save and load itself. different formates. (see below)
- all children must be a SequenceElement. Except for SequenceElement's
  children that might be of any type.
- might have its own color.
- might have its own font size (see below).


SequenceElement from BasicElement
---------------

Manages a list of children. The children are aligned horizontally at
one middle line. No gaps, no overlaps.

Has no own look. It just draws all its children and is done. Except if
its empty. It looks like an empty space then (i.e. a little square)

Has n+1 valid cursor positions where n is the number of
children. These are before, between and after the children.

May contain any (type of) element as child 

except SequenceElements if they contains a SequenceElement they merge 
it in the list

They can handle splitting of the sequence to allow "select an put selected item
between parenthesis" i.e. as content child of a delimiterelement) 


FormulaElement from SequenceElement
--------------

The only element those parent is null. The root of the element object
tree.

This is the element that is created by the KFormulaDoc and that knows
about it. As every other element knows its parent and therefore the
FormulaElement we get a chance to pass messages to the outside world.


RootElement from BasicElement
-----------

contains two children. content and index. index is optional.


IndexElement from BasicElement
------------

contains five children. content and four indexes. all indexes are
optional. If there is no index the element might be replaced by its content.


TextElement from BasicElement
-----------

contains one char and no children at all.


Might have its own font and size. But preferes to use a reasonalbe
font and size that are calculated from its parents font and a given
scheme (see below).


DelimiterElement from BasicElement
----------------

contains one child and draws delimiters around it. You are free to
choose with.


FractionElement from BasicElement
---------------

2 children: numerator, denominator


DecorationElement from BasicElement
-----------------

A piece of art. It has one child and decorates it above (or below or
both) with some nice decor. Some decor might be required to be as
width as the content. There is a way to guarantee this.

We could even add yet another child that can optionally be shown at
the other side of the decoration.


SumIntegralElement from BasicElement  //PrefixedElement
------------------

draws all sorts of mathematical symbols with three children. Above,
below (or whereever the indices and limits go)and to the right.


GeometryElement from BasicElement
---------------

One child.
Draw it at a fixed position relative to parent or absolute.
This is to do dirty things.

This element must not be used, kformula will provide you everything
without the use of this kind of element, any way for strange reasons
you want to do things that are not usually allowed and that are not
typical of a math formula.
[We will decide if implement this element or not]


MatrixElement from BasicElement
-------------

A matrix of children.
With all align stuff, internal borders etc, matrix dots handling (i.e.
those dots or lines that complete the matrix, not well handled in TeX),
etc..

SpaceElement from BasicElement
------------

No children at all. Provides the facility to insert horizontal spaces
in the formula. (therefore it is similar to TextElement.)


OperatorElement from TextElement
---------------

The element to be used for all kinds of operators. It needed because
operators require some space before and after and are therefore no
simple text.

They can you pixamps inestead of fonts, the use of pixmaps is needed only 
to give the user the possibilty of introduce its strange operator that we 
do not provide as a font. There problems with the scalability but we will
include as fonts (or vectorial images) in kformula all TeX operators so we
hope there is no need to use pixamps for a standard use of KFormula

Navigation
##########

There is a class Cursor that implements a pointer to a valid cursor
position inside the formula structure. Each kformula view needs to
have its own object of this class.

The Cursor class uses the elements facility to travel throught the
structure. (It gives the key to the current element and asks for the
new position.)

If the cursor points into an element this element is said to own the
cursor. There are a few rules that describe how new cursor positions
are calculated given the current key:

- An elements cursor positions are its children. The element might not
own the cursor except when it is owned by one of its children. The
only exception is SequenceElement which has valid cursor positions
before, between and after its children, too.

(Therefore the cursor is always owned by a SequenceElement.)

- Each element's children are ordered. If the cursor leaves one child
the next child it. The direction depends on the key that moved the
cursor. If there is child left the cursor is passed to the parent.

- If the cursor comes from our parent the first or the last child gets
it. Depending on the direction in which the cursor moved.

Please note that because each element knows its own cursor positions
and how to behave, it is possible for each combination of elements to
work together correctly.



Save and Load (Import/Export)
#############################

there are quite a few formats we want to read and write:

Built in:
- native koffice xml

Import/Export filters
- MathML 
- C like math strings 
- LaTeX



Element templates
#################

example: you can create a template to write limits:
it is a "lim ( )" string over 2 empty elements with an arrows that separe
them



"Look" templates
################

There need to be templates that tell which font to use, how the sizes
differ among different elements and what spaces are to be
included. (And much more.)

Your only need to choose one of them to get a reasonable good look.



Interface templates 
###################

Decide what KAction have to be toolbars,
what element templates must be loaded, what toolbar display....
There will be predefined (sorry for the spelling error) templates for 
-General...
-Physics (Vectors , integral, partial derivative etc are preferred..)
-Analysis (Integral and diff equation stuff)
-Geometry (Tensor product etc)
-Chemistry (Arrows, Periodic table external toolbar)
-Computer science (...)
-????



Context sensibility
###################

We want a formula to look different according to its
surroundings. (Most obviosly according to the available height and/or width.)

It would be great to get something like automatic operator
alignment. So if you type some formulas each on its own line the
assigment operators should be automatically in a column. (If the user
turns this on.)



Fonts and font size (2 ideas)
###################

1)
Each element know its font family (also if it is not a text element) so that it 
can give this font to its children.

The font size is calculated starting from a global scale factor and appling to it
a local size modifier (like HTML -2, -1,+3,etc..), this also calculate the 
QPen width for vector drawn stuff (like root symbol etc) and it gives a scale
factor for pixmap.

2)
When it comes to drawing we pass a StyleContext to the
FormulaElement. The StyleContext contains the font family to use, the
normal font size, the spaces to include between certain elements and
all sorts of context information that is needed to draw the
formula. As it is passed down the tree it also counts the current level
so it can tell each element the font size it is supposed to use.

The elements use this information to calculate their sizes and to draw
themselves. Each element is allowed to choose different settings for
whatever reason. But if the formula looks ugly then its the elements
blame.


Andrea Rizzi <rizzi@kde.org>
Ulrich Kuettler <ulrich.kuettler@mailbox.tu-dresden.de>