Canvas Organisation
Two parts:
DocView and how Canvas attaches/ relates to it.
- Canvas Classes Overview
Contents
DocView and Canvas
Standard DocView Setup
This figure you have seen in the DocviewModule description.
Still without anything looking like "canvas".
Canvas Relations
Now in focus are the a2dCanvas and related classes, DocView simplified.
The Document Manager is not used in this situation. There is only one a2dCanvas, which is derived from a2dDocumentViewWindow, and by itself is part of a wxFrame. It owns one a2dCanvasView and a2dCanvasDocument. This is already enough to display graphic data from the document. Changes made to the document will be updated automatically.
Next to this you may plug a a2dToolContr into the a2dCanvasView. The a2dToolContr allows to push and pop tools on a stack. The tools are interactive, and in general used to change the view's visible area (zoom), or they can add or manipulate a2dCanvasObjects in the document. a2dCanvasDocument contains two a2dCanvasObjects at the top, both contain two nested a2dCanvasObjects themselves.
Canvas Event Handling
Events coming in at the a2dCanvas window are redirected to the a2dCanvasView first. The a2dCanvasView redirects the events to the tool controller, when it is available.
The tool controller will redirect the events to the first tool on the tool stack. The tool that is active can handle the event, and do a hit test on any a2dCanvasObject itself. The object hit will now recieve events directly from the tool. In case of drawing a new object, the tool will handle all mouse events, and based on those events draw a new object. When the drawing is finished, the object will be added to the document via the a2dCanvasCommandProcessor. This directly ensures being able to undo redo.
If the event is not handled in the tool controller, it is futher processed in a2dCanvasView. a2dCanvasView does a hit test and redirects the events to the a2dCanvasObjects that are hit by the mouse pointer.
The Complete Thing
The next figure shows a more complex setup. Kind of combo of the two previous ones, DocView and Canvas together.
In a multiple document configuration there can be a tool controller inserted in each a2dCanvasView. A tool controller has a stack of tools. One tool is active in general. The active tool intercepts events coming from the a2dCanvas This can independently happen in several a2dCanvas windows at the same time. Even when it concerns the same document. All synchronization is taken care of.
Canvas Classes Overview
There is a a2dDocument called a2dCanvasDocument and a a2dView called a2dCanvasView. There can be several a2dCanvasDocuments open at the same time, and each can be displayed at several a2dCanvasViews too.
The a2dCanvasDocument always holds one a2dCanvasObject which is called the root object. All other a2dCanvasObjects in a document are nested children of this object. They form a tree like hierarchy of drawable objects.
Hierarchy is created by adding children to a a2dCanvasObject or by using special reference objects. In principle every type of hierarchy is using references to a2dCanvasObjects. All canvas objects are reference counted, and removing the last reference to a a2dCanvasObjects will also delete the object. Only the way the objects are placed in the hierarchy of objects (e.g children or subobjects of more advanced objects like end points of lines), defines how they will be rendered. A a2dCanvas uses a a2dCanvasView to display part of a a2dCanvasDocument. Its main purpose is to redirect events to and from a a2dCanvasView.
A a2dCanvasView is given a pointer to a a2dCanvasObject within a a2dCanvasDocument which needs to be displayed. This can be the a2dCanvasDocument's root object or any of its nested a2dCanvasObject children. At the same time the same or a different a2dCanvasObject within the same document can be displayed on a different a2dCanvasView.
The a2dCanvasView class holds a pointer to a a2dDrawer2D class. That class is used to draw basic primitives on a device, while the parent class a2dCanvasView is doing all the update work of modified objects and redraw areas.