moved kdeaccessibility kdeaddons kdeadmin kdeartwork kdebindings kdeedu kdegames...

[kdeedu.git] / kig / DESIGN

EXPLANATION OF THE KIG DESIGN
=============================

1. Object system
----------------

The Kig Object System is a design I'm particularly proud of.  It
started out pretty basic, but has undergone some major revisions, that
have proven very succesful.  Currently, I have just made one more
major change, and I think this will be the last majore change to it
for quite some time to come.  That's also why I'm writing this
explanation for other developers.



1.1 ObjectImp's:  Basic objects.

An ObjectImp represents the current state of an object in Kig.  It
keeps information about what type of object it is ( e.g. a line, a
point, a circle etc. ), and its exact data ( e.g. the center and
radius of the circle ).  It is *not* in any way aware of how the
object was calculated from its parents (e.g. is this a line that is
constructed as the parallel of another line, or as the line going
through two given points ? ) or how it is drawn on the window (
e.g. the thickness of the line, its color etc. ).

There is also the notion of BogusImp's in Kig.  These are special
kinds of ObjectImp's that *only* hold data.  They do not represent any
real object that can be drawn on a window.  Their use is *only* in
holding data for other objects to use.  Examples are StringImp,
IntImp, ConicImp etc.

There are a lot of ObjectImp's in Kig, most of them are in files
called *_imp.h and *_imp.cc or *_imp.cpp in the objects subdirectory.
Examples are PointImp, LineImp, ConicImp, CircleImp, CubicImp,
AngleImp etc.

There is also the concept of ObjectImpType's.  These identify a kind
of ObjectImp.  They carry information about the inheritance among the
different ObjectImp types, and some strings identifying them.  You can
get hold of the ObjectImpType of a certain ObjectImp by using its
type() method, you can also get hold of them by name using
ObjectImpFactory.


1.2 ObjectCalcer's: calculating ObjectImp's from other ObjectImp's

An ObjectCalcer is an object that represents an algorithm for
calculating an ObjectImp from other ObjectImp's.  It is also a node in
the dependency graph of a certain document. E.g. a LineImp can be
calculated from the two PointImp's it has to go through; every time
either of them moves, this calculation is redone.  In this case, there
would be an ObjectCalcer that keeps a reference to its two parents (
the ObjectCalcer's representing the points ), and that will calculate
its ObjectImp value every time it is asked to do so ( i.e. every time
one of its parents moves.. ).

Because of the complex relations that ObjectCalcer's hold to other
ObjectCalcer's and to other classes, they have been made
reference-counted.  This means that they keep a count internally of
how much times a pointer to them is held.  If this count reaches 0,
this means that nobody needs them anymore, and they delete themselves.
E.g. an ObjectCalcer always keeps a reference to its parents, to
ensure that those aren't deleted before it is deleted.  

In the inheritance graph of a document, the lowermost objects keep
references to their parents and those keep reference to their parents,
so that all of the top of the graph is kept alive.  Of course, someone
needs to keep a reference to the bottommost objects in the graph,
because otherwise, the entire graph would be deleted.  As we will see
later, an external class ( ObjectHolder ) keeps a reference to the
ObjectCalcer's that the user is aware of.  Thus, the reference
counting system makes sure that all the objects that the user knows
about, and all of their ancestors are kept alive, and the others die.
At the end of the program, this reference is released, and all the
objects are deleted.

A special case of an ObjectCalcer is the ObjectConstCalcer.  This is
an ObjectCalcer that has no parents, and only holds some data.  The
data is held as an ObjectImp of some type, and it will remain
constant, and no calculation needs to be done to get it, it is just
returned every time it is needed.

Other ObjectCalcer's are ObjectPropertyCalcer and ObjectTypeCalcer.
ObjectTypeCalcer is a ObjectCalcer that calculates an object according
to what a ObjectType object specifies.  It basically forwards all
calculations to that object ( check below ).  An ObjectPropertyCalcer
gets data from a property of a certain object.  In fact, ObjectImp's
can specify property's ( e.g. properties of a circle are its radius,
its circumference, its center etc. An angle has its bisector as a
LineImp property ), and they are returned as ObjectImp's of an
appropriate type.  The ObjectPropertyCalcer just gets one of the
properties of a certain ObjectImp and stores it.


1.3 ObjectType's: a specification of how to calculate an object.

An ObjectType represents a certain algorithm to calculate an ObjectImp
from other ObjectImp's.  Unlike an ObjectCalcer, it does not
participate in the inheritance graph, and there is only one
instantiation of each type of ObjectType.  An ObjectTypeCalcer is an
ObjectCalcer that keeps a pointer to a certain ObjectType, and
forwards all requests it gets to its ObjectType.  It's very normal
that multiple ObjectTypeCalcer's share the same ObjectType.

There are very much ObjectType's in Kig, check out all of the files
that end in *_type.* or *_types.* in the objects subdirectory of the
Kig source code.


1.4 ObjectHolder's: a link from the document to the hierarchy

An ObjectHolder represents an object as it is known to the document.
It keeps a pointer to an ObjectCalcer, where it gets its data ( the
ObjectImp that the ObjectCalcer holds ) from.  It also holds
information about how to draw this ObjectImp on the window, by keeping
a pointer to an ObjectDrawer ( see below ).  In its draw method, it
gets the ObjectImp from the ObjectCalcer, and passes it to the
ObjectDrawer, asking it to draw the ObjectImp on the window.

The document ( check the KigDocument class ) holds a list of these
ObjectHolder's.  This is its only link with the ObjectCalcer
dependency graph.  An ObjectHolder keeps a reference to its ObjectCalcer.


1.5 ObjectDrawer: An intelligent struct keeping some data about how to
    draw an ObjectImp on screen.

An ObjectDrawer is used by an ObjectHolder to keep information about
how to draw an ObjectImp on the window.  It is really nothing more
than a struct with some convenience methods.  It does not have any
virtual methods, or have any complex semantics.  It keeps information
like the thickness of an object, its color, and whether or not it is
hidden.


2. Interesting Issues
---------------------

Here, I explain some parts of the design that may at first look
difficult to understand.  This part assumes you have read the above.


2.1 Text labels 

Text labels in Kig are designed in a pretty flexible
way.  I will explain all the classes involved.

2.1.1 TextImp

First of all, there is the TextImp class.  It is an ObjectImp (
cf. supra ), and thus represents a piece of text that can be drawn on
the document.  It contains a QString ( the text to be shown ), a
coordinate ( the location to draw it ), and a boolean saying whether a
frame should be drawn around it.  As with all ObjectImp's, it does not
contain any code for calculating it, or how it behaves on user input.
Most of this is handled by the TextType class.

2.1.2 TextType

The TextType class is an implementation of an ObjectType.  It contains
code specifying how to calculate a TextImp from its parents, and for
how it behaves on user input.  A text object has at least three
parents, and can handle any number of optional arguments.  The three
mandatory arguments are an int, which is set to 1 or 0 depending on
whether the label needs a surrounding box, a PointImp, containing the
location of the text label, and a string containing the text of the
label.  The text can contain tokens like '%1', '%2' etc.  Every
additional argument is used to replace the lowest-numbered of those
tokens, with its string representation.  The function
ObjectImp::fillInNextEscape is used for this.

For example, if a TextType has the following parents:
a IntImp with value 0
a PointImp with value (0,0)
a String with value "This segment is %1 units long."
a DoubleImp with value 3.9

This would result in a string being drawn at the coordinate (0,0),
with no surrounding box, and showing the text "This segment is 3.9
units long.".

All this gives labels in Kig a lot of flexibility.

2.2 Locuses

Locuses are a mathematical concept that has been modelled in Kig.
Loosely defined, a locus is the mathematical shape defined by the set
of points that a certain point moves through while another point is
moved over its constraints.  This can be used to define mathematical
objects like conics, and various other things.  It has been modelled
in Kig in the most flexible way I can imagine, and I must say that I'm
proud of this design.

2.2.1 Constrained points

In the implementation of this, we use the concept of constrained
points.  This is a point that is attached to a certain curve.  It is
implemented in Kig by the ConstrainedPointType, which takes a CurveImp
and a DoubleImp as parents and calculates a Point from these by using
the CurveImp::getPoint function.

2.2.2 The Implementation

When a Locus is constructed by the user, Kig receives two points, at
least one of which is a Constrained point, and the other one somehow
depends on the first.  This is checked before trying to construct a
Locus, and the user is not allowed to try to construct locuses from
other sorts of points.

Next, Kig takes a look at the ObjectCalcer hierarchy.  We look at the
smallest part of the hierarchy that contains all paths from the first
point to the second point.  We then determine all objects that are not
*on* one of those paths ( meaning that they are not calculated from
the first point, or another object that is on one of those paths ),
but that are parents of one or more objects that are on those paths.
I call this set of objects the "side of the path" sometimes in the
code.  The function that finds them is called sideOfTreePath.

Next, an ObjectHierarchy object is constructed, which stores the way
to calculate the second point from the first point and the objects
from the previous paragraph.

An object is then constructed that has as parent the curve parent that
the first point is constrained to, the HierarchyImp containing the
ObjectHierarchy from the previous paragraph, and all the objects from
the "side of the tree".  This new object is an ObjectTypeCalcer with
the LocusType as its type.  In its calc() function, it calculates a
LocusImp by taking the objecthierarchy and substituting all the
current values of the objects from the "side of the path", resulting
in an ObjectHierarchy that takes one PointImp and calculates another
PointImp from that.  The LocusImp then contains the new
ObjectHierarchy and the current value of the curve that the first
point is constrained to.  In the drawing function of this LocusImp,
points on the curve are calculated, and then the hierarchy is used to
calculated from those points the location of the second point.  A
dynamic feedback algorithm, which has been written with a lot of help
from the mathematician "Franco Pasquarelli" is used to determine which
of the points on the curve should be used.

2.2.3 The Rationale

The above explanation may seem very complicated, but I am very much
convinced that this *is* the proper way to handle locuses.  I will
here try explain why I think it is superior to the much simpler
implementation that is used by much other programs.

The basic alternative implementation involves just keeping a pointer
to the first and second point in the locus object, and when the locus
is drawn, the first point is moved over all its possible locations,
the second point is calculated, and a point is drawn at its new
location.

The reason I think that this is a bad implementation is that it is not
possible to model the real dependency relations properly in this
scheme.  For example, the locus object would then be made dependent on
the constrained point.  This is wrong because when the constrained
point moves within the limits of the curve constraining it, the locus
does by definition not change.  Also, if the constrained point is
redefined so that it is no longer constrained to any curve, this is a
major problem, because it would invalidate the locus.  Another point
is that in practice, the locus depends on more objects than its
parents alone.  This is not a good thing, because it makes it
impossible to optimise drawing of the objects, using the information
about which objects depend on which others, because this information
is invalid.

The reason we need to calculate the "side of the path" above is that,
together with the curve that the first point is constrained to, these
are the objects that the locus is really dependent on.

The current Kig system correctly models all dependency relations to
the extent possible, while keeping a correct implementation.