diff options
Diffstat (limited to 'kig/DESIGN')
| -rw-r--r-- | kig/DESIGN | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/kig/DESIGN b/kig/DESIGN new file mode 100644 index 00000000..fd887779 --- /dev/null +++ b/kig/DESIGN @@ -0,0 +1,275 @@ +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. + + |