== Most Important Classes in CanvasModule == Here an overview of the most important classes. <> == a2dCanvasObject == Every part of a drawing contained within a <> is derived from the <> base class. Every <> can have nested <>'s , called children. The base class has a list <>, adding to this list is the way to add children to the <>. WxCanvasDocument itself contains one root <> , and its children and nested children form the contents of the document. They are displayed when a <> is rendered to a <>. Children are added to the <> to fill the document. But since the children itself can have children also etc., in the end this results in a tree like structure. All other nested <>'s can be reached by recursive iterating over the child list of the root object of the <> and the deeper nested child objects. A child of one <> can at the same time be a child of other <>'s, this is a key feature of the wxArt2D library. In derived <> classes, one can add extra <> pointers as members. This is called adding a reference to a <>. Adding end and begin objects to polylines and lines is a good example of one case where extra references will be needed. In principle any new type of <> can decide to use other <>'s references inside itself. Another use of references is on the undo stack. Objects can easily be switched from the document to the undo stack and back. The references only need to respect the reference counting mechanism which is used within a <>. Reference Counting is used to keep track of all references to one instance of a <>. The "parent pointing object" tells that the object pointed to is Owned, resulting in incrementing its internal reference count. When the parent object no longer needs the object pointed to, it Releases it. If all pointers pointing to a <> are released and the reference count reaches zero, the object will automatically be deleted for real. As consequence a <> has not just one parent, and the document structure is not a strict tree, its branches can touch eachother making it more a graph structure. Pins are used to connect <>'s. Several <> objects can be added as childs to its parent <>. A pin has ( as all other child objects) a relative position towards its parent <>. Therefore pins can be added at any position within a <>. One <> can be connected to another wxCanvasPins in a different <>, and that is how a2dCanvasObjects are connected. The pin always have a pointer back to its parent, which makes it possible to walk through connected objects via its pins. In general the same a2dCanvasObjects can be added to several parent objects, but for a pin this is not allowed. A pin can only have one parent and it also saves that parent internal. When connected a pin is only connected to one pin on Another <>. Deleting the Parent Object should also really delete those Children Objects which are <>'s, even if they are connected to other pins. When a pin is deleted it will automatically disconnect itself. A global <> instance called wxNullCanvasObject is often used to switch a reference from nothing to something. For instance when a Line should have no begin and end points, the members of the class holding this information will point to wxNullCanvasObject. All functions are aware of the fact that wxNullCanvasObject means it should not be used and ignored. Because wxNullCanvasObject is reference counted as any other <>, this makes it much easier to switch reference counted pointers. By default an object renders itself and its children, for derived object this can be extended to also render references to other objects which were stored as members of the object and are not part of the default child list. A Line with endpoints being references to other canvas objects is a good example of that. The difference is that children are always placed relative to (0,0) of the <> with its matrix already applied, while in case of endpoint's on a line, the end objects are placed relative to both endpoints of the line. Each <> derived class always has a matrix to position itself relative to its parent objects. Where the parents can be one of the following: a <> to which it was added as a child a a2dCanvasObjectReference any other object containing pointers/references to the object. The position of a <> is defined by a 3*2 matrix. The matrix defines the rotation, scaling, skew, mirror and at last a translation which defines the actual position. The matrix is the same and relative to all parent objects of the <>. It is not very usefull to place an object two times as a child within the same parent object. This will simply render the object twice at the same position. And changing the position of the child , meaning changing its matrix, will effect both in the same manner. If one still wants to do something like this, one should add an extra level using a <> or a plain <> with the above child as its child, which can be placed twice at a different position. See <> storage. The child objects placed in the <> of a <>, are placed relative to that parent <>. In different words, the child object its matrix is relative to the parent object. But a child is nothing more then a reference to another <>, and other <> may exist that also use the same object as there child. So a <> can have many parent objects. Things go wrong when parent objects are inserted as children in their own nested children, this will result in a circular calls to rendering routines. <> is derived from wxCanvasEvtHandler, therefore you can have event tables for canvas objects. Events are redirected from a <> to the <>. The lowest nested <> which is hit by the mouse and is displayed on top of others, will get events first. If the event is not handled, it will travel up the hierarchy of a2dCanvasObjects. The <> receives events from <> ( derived from wxWindow ) on its turn. See Events and Hittests WxCanvasObjects has also a list to add properties. wxCanvasPropertyBase Properties are invisible, but using a special <> called <>(), which has a reference to a wxCanvasPropertyBase, they can be displayed as text. All <> have a boundingbox defined in worldcoordinates, and this eqaul for all <>'s displaying the object. To cope with world as well as pixel like objects, there is a pixel and world extend that is added to the boundingbox of the object when needed. See BoundingBoxes. During rendering of each a2dCanvasObjectits boundingbox is checked. If it is within in the Update area it will be rendered, else not. Therefore the boundingboxes must always be up to date. Rendering takes time, so all objects that are outside the Update area will be skipped, which is very good for speed. The boundingbox of an object is always relative to its parent objects, because it already includes the matrix of the object itself. Still an untransformed boundingbox can be retreived also, but that one is not stored, and calculated each time. == a2dCanvasDocument == <> holds a2dCanvasObjects organized in a tree like structure. Each <> can have a list of child a2dCanvasObjects. Every <> is placed on a layer. A layer is a 3D z level, and is used when rendering the objects. Objects with the same layer id are rendered at the same level, while objects on another layer are rendered on top or in the back of that first layer. WxCanvasDocument has a root <>, and its children is the first level in the document. If those child a2dCanvasObjects also have children themself, we have a second level of hierarchy. This is the standard manner of building groups of a2dCanvasObjects. Specific classes derived from <>, can have more ways to store pointers to a2dCanvasObjects. And that way adds hierarchy in a different way. A good example is adding endpoints to a line segment. The endpoints are two pointers to a2dCanvasObjects. The position of Children is relative to the position of the parent object holding the children. For the end objects of a line this would be hard to use. Here the begin/end objects should be relative to the position of the begin and endpoint of the line. Yet Another way of nesting is by using wxCanvasRefObject's, which must be seen as a specialized <> with just one child object. WxCanvasObjects are reference counted, every pointer to the same <> brings more hierarchy to the <>. Children of a <>, are in fact references to other a2dCanvasObjects. And the same a2dCanvasObjectcan be a child of two different parent object. The layers settings are part of a <> too. The layers setting define the default Strokes and Fills for a2dCanvasObjects on a certain layer. <> are placed on layers by setting a layer id for it. The layers are drawn in a certain order, which is part of the layer settings. In practice it just means that the <> is rendering layer after layer. While rendering one layer, only <>'s with that layer id are rendered. All a2dCanvasObjects contained within a <> know the <> to which they belong, a pointer to the <> is a member of every <>. The <> pointer is the only connection a <> has to the outside world. For drawing the iretation context <>, is given as a parameter to the drawing functions. Via the drawing context the <> can be reached from within a <>. On its turn <> has a <> which is used to draw/render the <> in some way. See <> and <>. Rendering start at the ShowObject set within the <>. Therefore <> does not always start rendering at the <> its rootobject, it can be any <> that is nested within the <>. See <> organization for a simple case. Here the a2dCanvasObjects are on three layers. One first level <> has five objects, four on layer1 and one on layer2. One of its objects is a <> to an image on layer3. This same image is also placed directly in the top of <>. See in this figure <> as seen from the top how the above will look like when rendered from the <>. {{attachment:rootdraw2.gif}} {{attachment:rootdraw.gif}} ZChanges in a <> are announced to the <> views which display the document via a <> of type wxEVT_UPDATE_VIEWS. First the changed object sets itself and the document as having pending objects. In idle time this is checked, resulting in the update event sent to the a2dDocviewGlobals EventDistributer. This will distribute the event to all <> views, and the right ones will start updating themselfs. After that all boundingboxes are recalculated for the changed objects, and another Update event is sent. This cycle makes sure all changed areas on all view are redrawn. If a certain <> is not shown/visible at the moment its internal buffer will still be updated. As soon as the <> is shown it will re-use what is in the backup buffer when possible. The result is that minimizing a whole application and maximizing it again does not result in a total redraw. For the moment this seems best. Currently in a single view/document setup the <> window intercept idle events and redirects them to <>. In a multiple document setup, the idle events come from the frames attached to the <>'s. It would be easier to have <> recieve Onidle events directly, but this is not possible for a non wxWindow class. Therefore it is required to intercept Onidle events somewhere in a wxWindow and redirect them to the <> class. The docview frame classes like <> and <> do this by default. As an example, assume one <> that is part of a certain <> is moved in position, as result of a mouse move event. This means that all <> views for this <> need two updates. One for the old position of the object and one for the new. To achieve this, the Translate member of <> translates the object, and sets it as Pending. {{{ void <>::Translate( double x, double y ) { m_lworld.Translate(x,y); SetPending(TRUE); } }}} The SetPending call, sets a pending flag in the object and flags the <> that there are pending objects. In the first OnIdle call to a <>/<>, the programs discovers that there are pending objects, and this triggers the updating of the pending objects on all a2dCanvasViews that use the <>. See a2dCanvasView == a2dCanvasView and a2dDrawer2D == See [[DrawingAndUpdating|drawing and updating]] == a2dRenderImage == <> is a special kind of <>, placed within a <> structure, it act's like an Image with a width and height. The contents of the image is the result of rendering another <> structure to the image. <> is using a <> internal to render the document part. The drawer its buffer is copied to a wxImage, this image is scalled and cashed and after that displayed when the <> object is rendered from the document where it is placed into. == a2dCanvas == <> is a wxWindow used for displaying a buffer rendered by a <> its <>. It takes care of redefining mapping of the <>, based on the scrollbar positions and size of the window. Restricting the amount of scrolling is possible. WxCanvas displays the <> buffer which contains a part rendered from a <>. WxCanvas its scrolling is in world coordinates. WxCanvas also intercepts OnIdle and Onpaint events. During those events, updating/redrawing of pending areas or objects takes place. The OnIdle event calls <> to update things for all a2dCanvasViews sharing the same <>. The contents displayed on the <> can be written to a SVG file. It takes into account the current visible part on the <> window. == a2dCanvasObjectReference == A <> is a <> that displays another <> at a different position, without duplicating the data of the object to display. In principle this is the same for every child added to a <>, which are references also. But this type does have some specific features. References to a <> in other <>'s, than the one where the reference is placed in, is no problem. You can make libraries containing many used objects this way. The object that is referenced within a <> will be deleted if its refcount is 0. If the object referenced is not inside the same <> (same m_root), it will not be deleted. When deleting a wxCanvasDocuent, a <> is either really deleted through a <> or a reference depending on which one makes the refcount reach zero. If a reference to an extranal object exists (different m_root), that object will be deleted when the <> containing that object is deleted. References to external objects, will result in rendering that particular object using layersettings that are defined for the <> that contains the external object. So colours, strokes (width) and fills used in an external reference, will use the layersettings of the external <>. But for calculating pixel based object values, the Active Drawer is still used. A <> to a canvasobject placed inside the same parent <> will have has its own boundingbox. But the <> uses the position/matrix of the canvasobject. The canvasobject matrix is multiplied with the matrix of the <>. So a circle at (8,10) , referenced by <> somewhere else at (2,3), will be drawn at (10,13). == a2dNamedProperty == The <> is the base class for adding properties to any <>. These properties can be added to the propertylist of a <> from which <> is derived. Properties are stored in the <> property list. Properties can be added and removed while the program is running, and memory is freed when removing a property. Because of this it is ideal to use them for storing temporary information in a <>, for which you prefer not to use memory all the time, but only when needed. The basic <> editing features are setup like that. All property classes are derived from <>. Each property has an id which makes it unique. The use of the property classes is not only within the <> itself, a <> uses them to set the current style for drawing and the layer settings of a document also uses properties for setting the style of a layer. <> does have a specific id as defined by its <> and via that id it has a name too. The properties containing basic types ( bool int double void*), can hold as a value the types in question. A property can be made visible on the canvas using a special <> called <>. This <> is added to the parent <> rendering the property as a normal canvas child object. It takes care of displaying the property in text form, using the stringpresentation of the property. Some properties have a special meaning for the parent <>. <> and <> influence the rendering of its parent <>. <> has a reference to a <> containing a polygon, which will be used to clip the drawing of this property its parent <> object. It is possible to display the clipping object itself too. <> can have style references <>, <> and <>, which are stored as a <>. These properties are treated in a special manner, in this case to set the color, outline etc. of the <> containing the properties. The <> is used to store extra style properties, to be used for other purposes within the <>. For instance <> is derived from <>, and the color etc. of the shadow can be set independent of the <> its own style. If style properties are not available, layers settings will be used for the default style to render the object. The basic rendering routines in <> always set the style to be used for the <>, either based on the style properties if available, or else based on the layer setting of the document. This all does not mean that the object can and should only use this style, in fact it may set any style it wants to draw itself. The above mechanism is just the default way to set style for a <>, and works well for simple primitives. In case of complex objects, like curve containers etc, clearly more is needed. And therefore in such an object more style is stored, either via properties or directly as members of the class. When useful more then one of the same property can be added to an object. The following picture visible properties objects demonstrates the combination of properties using <> to show those properties as normal child objects within the parent <>. {{attachment:asso.gif|width='553' height='446'}} Hit tests, rendering and bounding box calculation is always inclusive the properties that are made visible using <> Objects. <> is just acting the same as any other normal child of a <>. <> has a reference to a <> containing a polygon, if this polygon itself is added as a child to the parent <>, it will be displayed as any other child. You can even edit the polygon interactif, in order to change the clipping property. The idea behind displaying properties indirectly via an <>, is to be able to edit them in the same manner that one can do with all <>'s. See PropertySystem more on properties. == a2dIterC == <> is used while traversing a document to render its contents to the screen or when processing mouse events. It is called the iterative context. When rendering, via this class one will have access to the <> and <>. When doing a hittest, the hit margin is available via this class. A reference to a <> class is passed as an argument to the rendering, hit test and event processing functions. In general all functions doing matrix calculations, in order to find the absolute position of the object, will use a <> as parameter. In combination with <>, the matrix calculation for each new child level in <> is calculated. While traversing the document <> object are pushed on and popped from the stack. This is automatically done, since the <> are just local variables. The constructor of <> take care of multiplying the matrix of the new child object with the foregoing parent matrixes. The resulting matrix is set to the <>. And in the destructor of <> the old matrix without the child included is set again to the <>. This is a very convenient way to make sure matrix calculations are done right. Together with the matrix to convert from relative coordinates to absolute coordinates, also the inverse matrix is calculated. This is often used in hit testing. ---- CategoryModules