Warning, /education/kig/DESIGN is written in an unsupported language. File is not indexed.

 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.