Tools are used by the user to interact with the drawing. They are used to draw objects, and after that to edit those objects. Tools are organized around %DOX{a2dToolContr}%, which is a base class for tool controllers. The main implementation for the moment is %DOX{a2dStToolContr}%. The controller has a tool stack, and one can push and pop tools on/from it. The stack becomes important when wants to draw and zoom at the same time while drawing. In such cases first a drawing tool is pushed, and temporarily a zoom tool is pushed to zoom in on parts where accurate drawing is required, followed by a zoom out to continue drawing the rest of the object. Also drawing a new object can be followed by editing the same objects. Again the editing tools is pushed on the stack while the drawing tool is active. As soon as the editing is finished, the drawing tool becomes active again. This way one can draw and edit several object in a row. At last the tool stack becomes even more important when editing nested object within other objects. Here for every nested object anew edit tool is pushed. Finishing editing one nested object, automatically pops the tool, and brings you up one level in the nested objects. A simple use of this feature is used for editing text properties, which are children of drawn objects. A more complex use is when adding and editing curves, and even markers on those curves, on a curve group object. It makes it possible to edit level by level into a complex nested tree of objects.

How tools communicate

Often one wants to take over settings from the current tool to the new tool pushed, or to an existing tool when the current tool is popped. Same when a modeless style dialog does change the central stored style settings, the active tool might what to take over the new style. Like for a drawing tool it wants to use the new style. At the same time a zoom tool will always draw its zooming rectangle in the same style. To prevent having to derive each and every tool in order to adept to what is needed for an application, all tools share an extra event handler, next to being them selfs event handlers. The extra event handler is intercepting events when the tool itself doe not handle a tool event. It makes it possible to concentrate many customizations in to a central place.

The base class %DOX{a2dToolEvtHandler}% can be used as a sample event handler. And two functional implementations used by %DOX{a2dStToolContr}% and its %DOX{a2dStTool}% tools are:

Tool active in hierarchy of objects.

A tool can work on any level in a %DOX{a2dCanvasDocument}%. Often this is the ShowObject() of the %DOX{a2dCanvasView}% in which the tools is active, but it can also be a deeper nested child object of this ShowObject(). The parent object in the tools indicates the level, and children of this object are added or edited etc.. When editing an object, an edit copy of the object to edit is created, and added temporarily as a tool object to the parent object. So it really becomes part of the document, at that level in the document hierarchy. As an example editing a curve on a curve group inside a plot object. Here the edit copy is stored as part of the curve group as along as the curve is being edited. The tools its objects are rendered as part of the document, and therefore layers and hierarchy of objects is all handled properly. Next to the edit copy, the tools can add more object to decorate the editing features. But in case of editing the most important are %DOX{a2dHandle}%'s objects. The %DOX{a2dHandle}% object are added as children of the edit copy. The tools makes changes on the edit copy via the %DOX{a2dHandle}% objects, and the changes on the edit copy are transferred to the original object when appropriate. Like when dragging a handle to enlarge the edit copy, only at the end of a drag the change is transferred to the original. During the drag of the edit copy its handle the original is not changed. The changes are not made directly by calling members functions on the original, but via commands to the command processor of the document. This way all changes are recorded, and placed on the undo stack. Every change in state, can be undone by reversing the action of the command. The command records enough information to be able to undo its own actions. In other words, a command brings the state of the document from one state in to the next, and can also bring it back into the previous state.


Sub editing

Sub editing is a feature implemented via tools, which makes it possible to edit nested object in a recursive manner. The first click on the top object brings that object in edit mode, and makes it possible to edit nested objects and so one. The next topic CorridorPath, explains the mechanism to redirect events to the right object. A new edit tool for each nested object is pushed, when editing deeper nested objects. One edit tool is popped again when editing of a nested object finishes. Each edit tool has has its own %DOX{a2dCorridor}%, and when one is popped, the corridor of the next is restored. Editing works by making an edit copy of the original objects. Events modify the edit copy, and from there commands are sending the changes to the original. A hit on a sub object in the orginal, starts a subedit. The pushed edit tool for the subobject makes a new editcopy of the subobject, and the current tool is brought into halt state. Meaning that it still know it was in editing mode for an object, put the editcopy is removed. As soon as a sub edit tool finshes, the editcopy is regenerated for the halted tool. Normally tools itself decide when some action is finished, but in case of subediting the object itself needs to decide. Each object can have different ways of being editable or subeditable. A central edit tool can not know this. Subediting is for this reason always a oneshot actions, this means that when the object decides that editing on it is finished, this automatically result in popping the tool that did the editing. Resulting to make the halted last tool on the stack active. In case of several subediting actions in a row, the tool stack will contain several one shot object editing tools. Only the last one pushed, is not halted. The tools are popped one by one, to finally arrive at the ShowObject of the view, where one can start editing on other objects again. Only the first tool that started editing of a direct object of the ShowObject, is special, since it is able to jump from one object to another. Also here there is no parent object which started the editing. While all sub editing tools are one shot, the top one does not have to be.