canobj.h

Go to the documentation of this file.

/*! \file wx/canvas/canobj.h
    \brief The base class for all drawable objects in a a2dCanvasDocument.
    
    Next to a2dCanvasObject, there are classes for filtering object ( a2dCanvasObjectFilter )
    when iterating recursively through a document hierarchy. 
    The class a2dIterC is used for holding the iteration context, 
    which on its turn holds the drawing context when needed.

    \author Klaas Holwerda &  Robert Roebling 

    Copyright: 2000-2004 (c) Robert Roebling

    Licence: wxWidgets Licence

    RCS-ID: $Id: canobj.h,v 1.85 2009/07/10 19:23:13 titato Exp $
*/

#ifndef __WXCANOBJ_H__
#define __WXCANOBJ_H__

#ifndef WX_PRECOMP
    #include "wx/wx.h"
#endif

#include "wx/image.h"
#include "wx/txtstrm.h"

#include "wx/general/genmod.h"

#include "wx/geometry.h"
#include "wx/artbase/afmatrix.h"
#include "wx/artbase/bbox.h"
#include "wx/canvas/candefs.h"
#include "wx/canvas/styleprop.h"
#include "wx/canvas/xmlpars.h"
#include "wx/canvas/restrict.h"
#include "wx/canvas/hittest.h"

class a2dWalkerIOHandlerWithContext;

//----------------------------------------------------------------------------
// decls
//----------------------------------------------------------------------------

#if defined(WXART2D_USINGDLL)
template class A2DCANVASDLLEXP a2dSmrtPtr<a2dCanvasObject>;
template class A2DCANVASDLLEXP a2dSmrtPtr<a2dCanvasView>;
#endif
typedef a2dSmrtPtr<a2dCanvasObject> a2dCanvasObjectPtr;
#if defined(WXART2D_USINGDLL)
template class A2DCANVASDLLEXP a2dPropertyIdTyped<a2dCanvasObjectPtr, a2dCanvasObjectPtrProperty>;
template class A2DCANVASDLLEXP a2dPropertyIdProp<a2dStyleProperty>;
template class A2DCANVASDLLEXP a2dPropertyIdProp<a2dShadowStyleProperty>;
template class A2DCANVASDLLEXP a2dPropertyIdTyped<a2dBoundingBox, a2dBoudingBoxProperty>;
#endif
typedef a2dPropertyIdTyped<a2dCanvasObjectPtr, class a2dCanvasObjectPtrProperty> a2dPropertyIdCanvasObject;
typedef a2dPropertyIdProp<class a2dStyleProperty> a2dPropertyIdCanvasStyle;
typedef a2dPropertyIdProp<class a2dShadowStyleProperty> a2dPropertyIdCanvasShadowStyle;
typedef a2dPropertyIdTyped<a2dBoundingBox, a2dBoudingBoxProperty> a2dPropertyIdBoundingBox;

class A2DCANVASDLLEXP a2dPinClass;
class A2DCANVASDLLEXP a2dHandle;

//! mask flags for a2dCanvasObject
/*!
 \ingroup canvasobject
*/
typedef wxUint64 a2dCanvasObjectFlagsMask;


//! Enum for hit test options

enum a2dHitOption {
    //! no special options
    a2dCANOBJHITOPTION_NONE = 0x0000,

    //! if set, respect layer order, hit testing is done per layer from the top.
    a2dCANOBJHITOPTION_LAYERS = 0x0001,
    //! if set, don't hit test the root object or object for which IsHitWorld is called
    /*!
        This option hit tests the child objects as seen from the parent object.
    */
    a2dCANOBJHITOPTION_NOROOT = 0x0002,

    //! object hit should not have select flag set
    a2dCANOBJHITOPTION_NOTSELECTED = 0x0004,

    //! if set, don't stop at the first hit, but test child/sibling objects anyway
    a2dCANOBJHITOPTION_ALL    = 0x0008,
};

//! OR-ing a2dHitOption is allowed

inline a2dHitOption operator | ( a2dHitOption a, a2dHitOption b )
{
    return (a2dHitOption) ( (int) a | (int) b );
}



enum wxEditStyle 
{ 
    //! no special flags set
    wxEDITSTYLE_NONE     = 0x0000,

    //! edit a copy of the original object
    /*! There are two reasons, why you might want to edit a copy:

        - In layered drawings, one might want to see the effect of the layering
          during editing (e.g. that the edited object ist partially obscured),
          while at the same time the outline of the object and the editing handles
          should be rendered on top. This behaviour is best implemented by having
          two objects, an editing object with handles on top and the usual object.
        
        - in wxEDIT_COPY mode the editing information is transfered from the editing
          object to the original object using the command processor. This way the command
          processor is not only used for undo and redo but for all editing. This results
          in a more robust architecture (especially concerning undo/redo).
        
        If this style is not set, the original object is edited directly. Commands
        are still generated for undo/redo but the original object is not changed
        by these commands, so undo/redo is less robust.
    */
    wxEDITSTYLE_COPY      = 0x0001,

    //! editing is completely controlled by tools. No handles are added
    /*! If a master tool is used, handle editing is not realy appropriate, because
        the editing tool is not active and handles are not visible before the user
        clicks somewhere. Also master tools  need fine control over editing and use
        tools that perform a very specific task. This can be done without handles.
    */
    wxEDITSTYLE_NOHANDLES = 0x0002,

    //! Clone the edit object using clone_reconnectable
    wxEDITSTYLE_CONNECTED = 0x0004
};

inline wxEditStyle operator | (wxEditStyle a, wxEditStyle b) {
    return (wxEditStyle) ( (int) a | (int) b );
}

//----------------------------------------------------------------------------
// a2dCanvasObject
//----------------------------------------------------------------------------


//! a2dCanvasObject flags as a structure \ingroup canvasobject
/*!
 \ingroup canvasobject
*/
class A2DCANVASDLLEXP a2dCanvasOFlags
{

public:

    //! Flags for a2dCanvasObject
    /*!
    Those flags or used in mask for set flag inside a a2dCanvasObject or
    to get the value of a flag.

    \sa  a2dCanvasObject_FlagsS
    \sa  a2dCanvasObjectFlagsMask

       \ingroup canvasobject
    */
    static const a2dCanvasObjectFlagsMask NON                ;  /*!< No flags */
    static const a2dCanvasObjectFlagsMask SELECTED           ; /*!< object is selected */
    static const a2dCanvasObjectFlagsMask SELECTABLE         ; /*!< can select object */
    static const a2dCanvasObjectFlagsMask HasSelectedObjectsBelow ; /*!< selected objects detected below */
    static const a2dCanvasObjectFlagsMask SubEdit            ; /*!< allow subedit of children within this object */
    static const a2dCanvasObjectFlagsMask SubEditAsChild     ; /*!< allow subedit on this object when child of other object */
    static const a2dCanvasObjectFlagsMask VISIBLE            ; /*!< is the object visible (overruled by parent object in some cases during rendering */
    static const a2dCanvasObjectFlagsMask DRAGGABLE          ; /*!< can be dragged */
    static const a2dCanvasObjectFlagsMask SHOWSHADOW         ; /*!< show shadow object if true and shadow property is available */
    static const a2dCanvasObjectFlagsMask FILLED             ; /*!< use fill to fill if set */
    static const a2dCanvasObjectFlagsMask A                  ; /*!< group A flag (e.g boolean operations) */
    static const a2dCanvasObjectFlagsMask B                  ; /*!< group B flag (e.g boolean operations) */
    static const a2dCanvasObjectFlagsMask BIN                ; /*!< general flag  ( used for temporarely marking object ) */
    static const a2dCanvasObjectFlagsMask BIN2               ; /*!< general flag  ( used for temporarely marking object ) */
    static const a2dCanvasObjectFlagsMask PENDING            ; /*!< set when a2dCanvasObject needs an update (redraw) */
    static const a2dCanvasObjectFlagsMask SNAP               ; /*!< snapping of editable object or when moving */
    static const a2dCanvasObjectFlagsMask SNAP_TO            ; /*!< snapping of other object to this when in place*/
    static const a2dCanvasObjectFlagsMask PUSHIN             ; /*!< push into allowed */
    static const a2dCanvasObjectFlagsMask PRERENDERASCHILD   ; /*!< as child this object will be rendered before the parent object itself when true (default) */
    static const a2dCanvasObjectFlagsMask VISIBLECHILDS      ; /*!< child objects are visible or not */
    static const a2dCanvasObjectFlagsMask EDITABLE           ; /*!< object can be edited */
    static const a2dCanvasObjectFlagsMask ChildrenOnSameLayer; /*!< child objects are rendered when the object is rendered itself.
                                                   The effect is that the children will appear on the same layer as the object. */
    static const a2dCanvasObjectFlagsMask DoConnect          ; /*!< in case of pins on the object is it currely allowed for other object to connect to it? */
    static const a2dCanvasObjectFlagsMask IsOnCorridorPath   ; /*!< this object is on the corridor path to a captured object */
    static const a2dCanvasObjectFlagsMask HasPins            ; /*!< true if this object does have a2dPin's as children */
    static const a2dCanvasObjectFlagsMask Editing            ; /*!< true if the object is currently being edited */
    static const a2dCanvasObjectFlagsMask EditingCopy        ; /*!< true if the object needs is the editcopy of an object that is edited. */
    static const a2dCanvasObjectFlagsMask IsProperty         ; /*!< True if object is a property show object */
    static const a2dCanvasObjectFlagsMask MouseInObject      ; /*!< true is mouse is currently within object */
    static const a2dCanvasObjectFlagsMask HighLight          ; /*!< true is object is highlighted */
    static const a2dCanvasObjectFlagsMask Notused            ; /*!< not used for the moment */
    static const a2dCanvasObjectFlagsMask ignoreSetpending   ; /*!< ignore Setpending calls on a2dCanvasObject */ 
    static const a2dCanvasObjectFlagsMask HasToolObjectsBelow  ; /*!< special tool object detected below */
    static const a2dCanvasObjectFlagsMask ChildOnlyTranslate   ; /*!< do not tranfrom only translate. */
    static const a2dCanvasObjectFlagsMask ignoreLayer          ; /*!< ignore Layer id, just render always*/
    static const a2dCanvasObjectFlagsMask generatePins         ; /*!< generate Pins when asked for  */ 
    static const a2dCanvasObjectFlagsMask normalized           ; /*!< normalized coordinates */  
    static const a2dCanvasObjectFlagsMask NoRenderCanvasObject ; /*!< do not render if no children */
    static const a2dCanvasObjectFlagsMask ALL                  ;  /*!< To set all flags at once */

    a2dCanvasOFlags( a2dCanvasObjectFlagsMask newmask = NON );

    void SetSpecificFlags( bool setOrClear, a2dCanvasObjectFlagsMask which );

    a2dCanvasObjectFlagsMask GetFlags() const;

    void SetFlags( a2dCanvasObjectFlagsMask which );

    bool GetFlag( a2dCanvasObjectFlagsMask which ) const;

    bool CheckMask( a2dCanvasObjectFlagsMask mask) const;

    //!object is selected
    bool m_selected:1;

    //!can select object
    bool m_selectable:1;

    //!allow subedit of children within this object
    bool m_subEdit:1;

    //!allow subedit on this object when child of other object
    bool m_subEditAsChild:1;

    //!is the object visible (overruled by paranet object in some cases during rendering
    bool m_visible:1;

    //!can be dragged
    bool m_draggable:1;

    //!show shadow object if true and shadow property is available
    bool m_showshadow:1;

    //!use fill to fill if set
    bool m_filled:1;

    //!group A flag (e.g boolean operations)
    bool m_a:1;

    //!group B flag (e.g boolean operations)
    bool m_b:1;

    //! generate pins if true
    bool m_generatePins:1;

    //!general flag ( used for temporarely marking object )
    bool m_bin:1;

    //!general flag  ( used for temporarely marking object )
    bool m_bin2:1;

    //! set when a2dCanvasObject needs an update (redraw).
    bool m_pending:1;

    //!snapping of editable object or when moving
    bool m_snap:1;

    //!snapping of other objects to this when in place
    bool m_snap_to:1;

    //! is push into allowed
    bool m_pushin;

    //!as child this object will be rendered before the parent object itself when true (default)
    bool m_prerenderaschild:1;

    //! child objects are visible or not
    bool m_visiblechilds:1;

    //! object can be edited
    bool m_editable:1;

    //! true if the object is currently being edited
    bool m_editing:1;

    //! true if the object needs to be rendered in edit mode.
    bool m_editingCopy:1;

    //! ignore this object in a2dCanvasObject::SetPending()
    bool m_ignoreSetpending:1;

    //! child objects are rendered when the object is rendered itself.
    //! The effect is that the children will appear on the same layer as the object.
    bool m_childrenOnSameLayer:1;

    //! in case of pins on the object is it currely allowed for other object to connect to it?
    bool m_doConnect:1;

    //! This object is on the corridor path to a captured object or to a corridored object.
    /*!
        When an object is captured, it and its parent, grandparent etc. objects get this flag set.
    */
    bool m_isOnCorridorPath:1;

    //! true if this object does have a2dPin's as children
    bool m_hasPins:1;

    bool m_IsProperty:1;

    bool m_MouseInObject:1;

    bool m_HighLight:1;

    bool m_ChildOnlyTranslate:1;

    //! when this is set DoRender() is called even if layer of the object is not the layer to be rendered.
    bool m_ignoreLayer:1;

    //! GDSII format flag
    bool m_template:1 ;

    //! GDSII format flag
    bool m_external :1 ;

    //! GDSII format flag
    bool m_used :1 ;

    //! special tool object detected below
    bool m_HasToolObjectsBelow :1 ;

    //! true is the object is a a2dCanvasObject (or derived ) without rendering something if there or now children.
    bool m_NoRenderCanvasObject :1 ;

    //! selected objects detected below
    bool m_HasSelectedObjectsBelow :1 ;

    //! when true, the wxEVT_CANVASOBJECT_RESIZE_EVENT is sent to this object, if the child box did change.
    bool m_resizeToChilds :1 ;

    //! true if the object is defined in normalized coordinates
    bool m_normalized:1;

};

//! event mask flags for a2dCanvasObject hit 
/*! a2dCanvasObjectHitFlags used in a mask for defining how an object should be hit

 \ingroup canvasobject

*/
enum a2dCanvasObjectHitFlags
{
    a2dCANOBJ_EVENT_NON=0x0001, //!< no hit will be reported 
    a2dCANOBJ_EVENT_FILL=0x0002,  //!< hit if filled 
    a2dCANOBJ_EVENT_STROKE=0x0004, //!< hit if stroked
    a2dCANOBJ_EVENT_FILL_NON_TRANSPARENT=0x0008,  //!< hit if filling is not transparent
    a2dCANOBJ_EVENT_STROKE_NON_TRANSPARENT=0x0010, //!< hit if stroke is not transparent
    a2dCANOBJ_EVENT_VISIBLE=0x0020, //!< hit if visible
    a2dCANOBJ_EVENT_ALL=0x0040 //!< always hit
};

//! flags for searching a connecting a2dpinClass, for the connecting task at hand.
/*!
    The format is:

    a2d_PinClassWanted_ForPinClassGiven_DirectionFlags

    ObjectPinClass is the object to which we want to connect
    ToConnectPinClass is pinclass from where we want to connect to an object

*/
enum a2dConnectTask
{
    a2d_ToConnectPinClassWire_ObjectPinClass_In,      //!< find wire/connect pinclass, given Normal Object In pinclass
    a2d_ToConnectPinClassWire_ObjectPinClass_Out,     //!< find wire/connect pinclass, given Normal Object Out pinclass
    a2d_ToConnectPinClassWire_ObjectPinClass_InOut,   //!< find wire/connect pinclass, given Normal Object In pinclass

    a2d_ObjectPinClass_ToConnectPinClassWire_In,     //!< find normal object pinclass, given Connect/wire pinclass In
    a2d_ObjectPinClass_ToConnectPinClassWire_Out,    //!< find normal object pinclass, given Connect/wire pinclass Out
    a2d_ObjectPinClass_ToConnectPinClassWire_InOut,  //!< find normal object pinclass, given Connect/wire pinclass In/Out

    a2d_ToConnectPinClassObject_ObjectPinClass_In,      //!< find pinclass, given Normal Object In pinclass
    a2d_ToConnectPinClassObject_ObjectPinClass_Out,     //!< find pinclass, given Normal Object Out pinclass
    a2d_ToConnectPinClassObject_ObjectPinClass_InOut,   //!< find pinclass, given Normal Object In/Out pinclass

    a2d_ObjectPinClass_ToConnectPinClassObject_In,      //!< find normal object pinclass, given Normal Object In pinclass
    a2d_ObjectPinClass_ToConnectPinClassObject_Out,     //!< find normal object pinclass, given Normal Object Out pinclass
    a2d_ObjectPinClass_ToConnectPinClassObject_InOut,   //!< find normal object pinclass, given Normal Object In/Out pinclass
};

//! a2dCanvasObject hit flags as a structure \ingroup canvasobject
/*! a2dCanvasOHitFlags is used as mask for defining how an object should be hit
*/
struct a2dCanvasOHitFlags
{
    //!no events
    bool m_non:1;
    //! only when over filled area of object
    bool m_fill:1;
    //! only when over stroked area of object
    bool m_stroke:1;
    //! only when non transparent fill
    bool m_fill_non_transparent:1;
    //! only when non transparent stroke
    bool m_stroke_non_transparent:1;
    //! only when visible
    bool m_visible:1;
    //!all events
    bool m_all:1;

};

//! This is one hit result from a2dExtendedResult
class A2DCANVASDLLEXP a2dExtendedResultItem
{
public:
    //! Default Constructor
    a2dExtendedResultItem() {}
    //! Standard Constructor
    a2dExtendedResultItem( a2dCanvasObject *object, a2dCanvasObject *parent, a2dHit type, int level, int typeex )
    {
        m_object = object;
        m_parent = parent;
        m_type = type;
        m_level = level;
        m_typeex = typeex;
    }
    //! the hit object
    class a2dCanvasObject *GetObject() { return m_object; };
    //! the parent object of the hit object
    class a2dCanvasObject *GetParent() { return m_parent; };
    //! type of the hit
    const a2dHit &GetHitType() { return m_type; }
    //! level of the hit object below the start (root) object
    int GetLevel() { return m_level; }

protected:
    friend class a2dExtendedResult;
    //! the hit object
    a2dCanvasObject *m_object;
    //! the parent object of the hit object
    a2dCanvasObject *m_parent;
    //! type of the hit
    a2dHit m_type;
    //! level of the hit object below the start (root) object
    /*! note: the extended result can contain multiple hits on the same level */
    int m_level;
    //! Extended hit type
    /*! This is generally class specific.
        Derived classes must include the IDs for the base class.
        a2dCanvasObject does not define extended hit IDs.
    */
    int m_typeex;
};

//! An object of this class represents the context of a query like a hit test
/*! This is similar to a2dIterC, but it is not used for iteration, but for
    return values.
*/
class A2DCANVASDLLEXP a2dExtendedResult: public std::vector<a2dExtendedResultItem>
{
public:
    //! Default constructor
    a2dExtendedResult();
    //! Destructor
    ~a2dExtendedResult();
};

//! structure to give as parameter to member functions of wxCanvasObject
/*!
    During event processing and hittesting in a a2dCanvasView and a2dCanvasDocument, this
    structure is used to give and assemble information while traversing the document.
*/
class a2dHitEvent
{

public:

    a2dHitEvent( double absx = 0, double absy = 0, bool continues = true, 
        a2dHitOption option = a2dCANOBJHITOPTION_NONE, bool wantExtended = false )
    {
        m_option = option;
        m_maxlevel = INT_MAX;
        m_relx = 0;
        m_rely = 0;
        m_x = absx;
        m_y = absy;
        m_processed = false;
        m_continue = continues;
        m_isHit = false;
        m_how = a2dHit::stock_nohit;
        m_id = 0;
        m_extendedWanted = wantExtended;
        m_xyRelToChildren = false;
        m_event = NULL;
    }

    void SetProcessed( bool val )
    {
#ifdef _DEBUG
        if ( val )
            m_processed = true;
        else
            m_processed = false;
#else
        m_processed = val;
#endif
    }

    //! (world coordinates) hit point x relative to the canvas object its parent object(s) 
    double m_relx;
    //! (world coordinates) hit point y relative to the canvas object its parent object(s) 
    double m_rely;
    //! (world coordinates) hit point x as in a2dCanvasView or any other top level
    double m_x;
    //! (world coordinates) hit point y as in a2dCanvasView or any other top level
    double m_y;
    //! is set, m_x and m_y are supplied relative to the child objects ( object matrix m_world already applied )
    bool m_xyRelToChildren;
    //! the way to hit/traverse the document.
    wxUint32 m_option;
    //! return in which way the object was hit (stroke, fill, ...)
    a2dHit m_how;
    //! extended result information with e.g path to lead to the nested object hit
    a2dExtendedResult m_extended;
    //! fill m_extended or not
    bool m_extendedWanted;
    //! maximum level of hit object below this (this = level 0)
    int m_maxlevel;
    //! event to process in case of event processing call
    wxEvent* m_event;
    //! set if event was processed sofar
    bool m_processed;
    //! set if the event processing or hittest needs to continue after first hit
    bool m_continue;
    //! in the end if there was a hit (even if not processed event)
    bool m_isHit;
    //! application specific use
    int m_id;
};


//! when a new wire or other connection object needs to be created,
/*! this class or a derived one, will deliver the right connection object.
    In other situations it will tell which objects are connectable on two pins, and the wire needed for that. 

    The idea is that objects do not only decide themselfs if they can connect to other objects and which.
    Instead this job is centralized to this class. Because of that an object does not need to know himself 
    to which objects it can connect, and what wire to use for that. The a2dConnectionGenerator knows which objects 
    can connect to others. Actualy in the default situation it is not the object which decides, 
    but the pinclass of a pin is the input for the a2dConnectionGenerator. So one asks the a2dConnectionGenerator 
    if a pinclass of a pin on a certain object, can connect to something else. 
    
    This class here can restrict what is the default way of allowing connections, or implement its own rules.
    When you want to limit the possible connection you can switch to a derived a2dConnectionGenerator.
    An a2dConnectionGenerator is shared by a set of a2dPinClass Objects, and this is how one finds the
    a2dConnectionGenerator for a connection task at hand.

    As an example of a derived a2dConnectionGenerator: 
    if you want to limit a wire tool to only draw lines from objects which have pins
    of a specific pin class, overriding GeneratePossibleConnections() can do the job.

    a2dPinClass itself has information on hich other a2dPinClass it may connect to, and two 
    pin classes can only connect if they both agree.
    a2dPinClass even knows which type of wire/connect object is required hen this pinclass is meant for 
    being on a wire its pin.
    So when starting a new wire, at a certain pin, the object and wire its a2dPinClass must be able
    to connect to one another. A wiretool is only able to connect two pins of objects if 
    the pinclasses in its connect lists are compatible, meaning the one pin contains the other as connectable.
    If the pin is oke, the found PinClassMap defines what type of wire needs to be created now. 
    This information is stored in the a2dPinClass, as a template wire/connect object.
    The tool therefore is able to generate a2dCanvasObject connections ( e.g. a2dWirePolylineL wires )
    of different types, and which type is created depends on the pin that is hit when starting a wire.
    
    In the above one object was normal and the connecting object was a wire. Another situation is when two normal objects
    are dragged appart and a wire needs to be created in between. Again pinclasses of the two a2dPin's that will be 
    disconnected will be searched in its connect lists, for a wire pincclass, which can connect to both pins.
    When a wire pinclass is found which can connect to both pins, the type of wire will be created via that same 
    pinclass its template object for a wire.  This is achieved CreateConnectObject().
    
    To understand the principle, imagine 3 a2dCanvasObject's with pins which have Pin classes.
        - one with a2dPinClass A
        - the second with a2dPinClass B 
        - the third with a2dPinClass C
    Now when A connects to B we want a wire of type X, if A connects to C, we want wire Y,
    at last when C connects to B we want wire Z.
    On top of this the direction of the connection can be defined, A to C can be different from C to A.
    The information on which pin can connect to which other pin, is stored in the a2dPinClass of the a2dPin.
    Here one can find which other a2dPinClass object can connect to this one, and if it is for a wire, a template object
    to create that wire.

    If more B objects are connected to an A object, via multiple wires, the connection of wires to wires must be defined too
    To conclude we are not only defining the relations between A-B-C, but also the wire begin and end relations towards eachother.
    In our case here, we create wires which are extensions of the pin where they are connected to, meaning the end pin of the wire
    is the same as the pinclass to which the begin pin is connected. 
    All this to connect one object pin with pinclass to other objects at a pin with a certain pin class.
    If we define 3 pinclasses for pins on the object A,B,C and three extra pinclasses WA WB WC for wire between those objects,
    we get the following connection tables.

    For the pinclasses which can be connected to each other:

    - (A-PinClass) -> (B-PinClass) (C-PinClass) (WB-PinClass) (WC-PinClass) 
    - (B-PinClass) -> (A-PinClass) (C-PinClass) (WA-PinClass) (WC-PinClass) 
    - (C-PinClass) -> (A-PinClass) (B-PinClass) (WA-PinClass) (WB-PinClass) 

    We get for wires which start at A or C:

    - (A-PinClass) -> (WB-PinClass) Wire X (WA-PinClass) -> (B-PinClass)
    - (A-PinClass) -> (WC-PinClass) Wire Y (WA-PinClass) -> (C-PinClass)
    - (C-PinClass) -> (WB-PinClass) Wire Z (WC-PinClass) -> (B-PinClass)

    And if bidirectional wires which start at B or C:

    - (B-PinClass) -> (WA-PinClass) Wire X (WB-PinClass) -> (A-PinClass)
    - (C-PinClass) -> (WA-PinClass) Wire Y (WC-PinClass) -> (A-PinClass)
    - (B-PinClass) -> (WC-PinClass) Wire Z (WB-PinClass) -> (C-PinClass)

    Interesting in this table is that one can not start a wire on an object, whithout knowing its type, since always two are possible.
    So a wire tool needs to define for which pinclass a wire is needed, before asking this a2dConnectionGenerator to tell if 
    the object is oke with that. Another option is to start a wire on a starting pin, and only when finishing the wire decide what  
    type of wire is really needed for the begin and end pin of the wire.
    It is best to give wire ohter pinclasses then normal objects, since that makes it easier to know if one can start a wire 
    on a certain pin, and what type of wire it needs to be.

    As an example, drawing a wire using a tool.
    If the user clicks on an object type pin, the corresponding pin
    in the newly created wire will be a Non object type pin. 

    At last in the above, there were three objects, but in fact they are of no interest, since the pins its pinclasses define all.
    This way it is possible to define several "flows" in a group of objects. E.g. You can define in and output pinclasses for each 
    flow you require. Multiple flow pins can be added to the same object, connecting a set of flow pins by one type of wire.
    You end up with several flows within a group of objects ( control flow - data flow ).

*/
class A2DCANVASDLLEXP a2dConnectionGenerator : public a2dObject
{


public:

    //! constructor
    a2dConnectionGenerator();
    //! destructor
    ~a2dConnectionGenerator();

    //! create connection object based on two pins which need to be connected. 
    /*!
        Called from the default a2dCanvasObject::CreateConnectObject(), in order to easily change the behaviour
        of standard objects concerning possible connections.
        The returned object is a (connection) object (e.g. a2dWirePolylineL ), with correct pins at the 
        position of pinThis and pinOther. The pins are connected already.
        When undo is true, the right commands are sent to the document its command processor.
        In general this means those commands are part of a group of commands in a a2dCommandGroup,
        which internal resulted in a connection being created. For example as a result of dragging an object. 
    */
    virtual a2dCanvasObject* CreateConnectObject( a2dCanvasObject* parent, a2dPin* pinThis, a2dPin* pinOther, bool undo = false ) const;

    //! create connection object based on two pin classes, which (may) need to be connected. 
    virtual a2dCanvasObject* GetConnectTemplate( const a2dCanvasObject* object, a2dPinClass* mapObject, const a2dCanvasObject* other, a2dPinClass* mapOther ) const;

    //! generate temporary pins to which objects can connect
    /*!
        When drawing wires object, other object are asked to display pin possition,
        to which the wire may connect.  See a2dCanvasObject::GeneratePinsPossibleConnections(). This process is called by the tools,
        and is called editing Feedback.  The pins created are only temporary, and will be removed at the end of a tool its busy cycle.

        The default implementation uses pinClass->GetConnectionGenerator()
        to ask this object to generate a pin in a2dCanvasObject::GeneratePins(). The reason for this, is that there may be more involved
        to allow a pin to connect. Like the pin class.

        \param object The object on which to create temporary pins
        \param pinClass The pinclass to which the generated pins must be able to connect, if NULL any pinclass 
        \param task for what purpose is the connection needed
        \param x only connect at this position
        \param y only connect at this position

    */
    virtual bool GeneratePossibleConnections( a2dCanvasObject* object, a2dPinClass* pinClass, a2dConnectTask task, double x, double y ) const;

    //! return a a2dPinClass which should be used to connect to the input a2dPinClass.
    /*!
        The connection generator searches for a possible connection to the input a2dPinClass in combination
        with the canvasobject obj if needed.

        \param pinClass pin class for which to search a connecting PinClass
        \param task for what purpose is the connection needed
        \param obj object for which pins are checked / needed.

        \return If a a2dPinClass is not found NULL is returned.
    */
    virtual a2dPinClass* GetPinClassForTask( a2dPinClass* pinClass, a2dConnectTask task, a2dCanvasObject* obj ) const;

    //! return the pin class for GetPinClassForTask( a2dPinClass::Any  )
    /*!
        Basic object can generate pins by a2dPinclass, but i8n case of a2dPinClass::Any 
        it will generate pins of this pinclass. 
    */
    a2dPinClass *GetAnyPinClass() const { return m_anypinclass; }

    //! see GetAnyPinClass()
    void SetAnyPinClass( a2dPinClass* pinClass ) { m_anypinclass = pinClass; }

    //! when a wire was created, this return the direction is was created ( first to last pin or visa versa ).
    bool GetLastConnectCreationDirection() const { return m_reverseCreate; }

protected:

    //! template pinclass
    a2dPinClass* m_anypinclass;

    //! how to create a connection
    mutable bool m_reverseCreate;

    //! Some stuff needed by the ref counting base class
    virtual a2dObject* Clone( CloneOptions WXUNUSED(options) ) const { wxASSERT(0); return 0; }

private:

#if wxART2D_USE_CVGIO
    virtual void DoSave( wxObject* WXUNUSED(parent), a2dIOHandlerXmlSerOut &WXUNUSED(out), a2dXmlSer_flag WXUNUSED(xmlparts), a2dObjectList* WXUNUSED(towrite) ) { wxASSERT(0); }
    virtual void DoLoad( wxObject* WXUNUSED(parent), a2dIOHandlerXmlSerIn& WXUNUSED(parser), a2dXmlSer_flag WXUNUSED(xmlparts) ) { wxASSERT(0); }
#endif //wxART2D_USE_CVGIO

};

//! Smart pointer type for a2dConnectionGenerator
template class A2DCANVASDLLEXP a2dSmrtPtr<a2dConnectionGenerator>;
typedef a2dSmrtPtr<a2dConnectionGenerator> a2dConnectionGeneratorPtr;

//!a2dCanvasObject is the base class for Canvas Objects. 
/*!
    All objects for drawing on the a2dCanvas are derived from this class.
    A a2dCanvasDocument is filled with instances of this object.
    a2dCanvasObject can have children, which are also a2dCanvasObjects.
    A a2dCanvasObject itself can be a child of more than one parent a2dCanvasObject.
    The reference counter takes care of deleting the object when all references are released.

    Child objects are stored in a2dCanvasObjectList m_childobjects, which is only created
    when the first child is added to the a2dCanvasObject. Else it points to wxNullCanvasObjectList.

    Each a2dCanvasObject can also have a list of a2dObject objects.   
    They are stored in the a2dObjectList m_properties.

    Asking for the GetCount() of the above two lists, is save, since wxNullCanvasObjectList
    will return 0.

    Traversing a a2dCanvasDocument is mainly by traversing of the child list of each a2dCanvasObject in the
    document in a recursive manner.
    Many functions in a2dCanvasObject need to traverse the document, therefore there is often a DoSomething
    function called from the base a2dCanvasObject, in order to do the object specific job while
    traversing the document.

    Rendering of a2dCanvasObject's is via the base Render function, which takes care 
    of rendering child objects. It also does the clipping of objects to the area to be drawn.
    First it searches for style properties in the property list, if found they will be used
    to set the drawing style of the active a2dCanvasView which is used to draw on a device.
    If no style properties are available, the layer settings are used to set the style of the a2dCanvasView.
    Next to style properties, there can be other properties which influence the rendering of the object
    in general; e.g. the  a2dClipPathProperty, is pushed into the a2dCanvasView to clip the child objects.    
    After setting the style the rendering can start. First the children which have the flag 
    m_prerenderaschild set are rendered. Next the a2dCanvasObject derived object itself is rendered
    via the virtual DoRender() method. After that the rest of the child objects are rendered.
    In the end visible properties are rendered, via their a2dCanvasObject, which they may use for displaying
    themselfs. 
     
    It is possible to intercept mouse event on a a2dCanvasObject.
    a2dCanvasObject's receive there events after a hit of the mouse pointer was detected
    from within a a2dCanvasView or a2dCanvas object. 
    The lowest object seen from the a2dCanvasView::ShowObject() receives the events first, and if skipped there
    and no othere child proesses the event, its parent will get the event etc.

    \remark When a style (fill or stroke) is set it will be used instead of the layer fill and stroke
    \remark fill style is inherited by children

    \ingroup canvasobject
*/
class A2DCANVASDLLEXP a2dCanvasObject: public a2dEvtHandler
{

public:

    friend class a2dCanvasObjectFilter;
    friend class a2dCanvasObjectFilterLayerMask;
    friend class a2dCanvasObjectFilterLayerMaskNoToolNoEdit;

    //! used to tell which child object to render and to detect the need for it.
    struct RenderChild
    {
        bool m_prerender:1;  /*!< object marked for pre rendering ( before the parent ) */
        bool m_postrender:1; /*!< object marked for post rendering ( after the parent ) */
        bool m_property:1; /*!< object marked for property rendering */
    };


    A2D_DECLARE_EVENT_TABLE()

    //****************** CONSTRUCTION AND REF COUNTING ******************/
    /*! \name Construction and reference counting
    */
    //\{

    DECLARE_DYNAMIC_CLASS(a2dCanvasObject)

    //!constructor called by derived objects
    a2dCanvasObject( double x = 0 , double y = 0);

    //!constructor using reference to existing canvas object
    a2dCanvasObject( const a2dCanvasObject &other, CloneOptions options );

    //!Clone this object and return a pointer to the new object
    virtual a2dObject* Clone( CloneOptions options ) const;

    inline a2dCanvasObject* TClone( CloneOptions options ) { return (a2dCanvasObject*) Clone( options ); }

    //!destructor called by derived objects
    virtual ~a2dCanvasObject();

    //! returns if this object does have nested objects
    /*!
        If the object has children it is nested, but if not it can still have nested objects. This is when 
        a derived a2dCanvasObject does have a2dCanvasObject's members itself.
        This function should return true if an object does have nested children or members.
    */
    virtual bool IsRecursive();

    //! All direct a2dCanvasObject which are part of this one are made unique
    /*!
        The base implementation check all child objects in m_childobjects for being more then single referenced.
        If not a clone is created in put in place of the one there, leving the origenal to the other objects
        which owned that child too.
        Derived a2dCanvasObject must implement this, if it has members which can be multiple referenced.
    */
    virtual void MakeReferencesUnique();


    //\}
    //**************** END CONSTRUCTION AND REF COUNTING ****************/

    //****************** AFFINE TRANSFORMATION ******************/
    /*! \name Affine Transformation
        Each a2dCanvasObject has an affine Transformation to translate, rotate, scale, 
        and skew it. The Transformations are mutiplied with the transformations of
        all parent objects up the show object of teh current view.
    */
    //\{
public:

    //!Rotates this object clockwise
    /*!
        Rotates this object clockwise: If you call <code>Rotate(20); Rotate(10);</code> the 
        absolute rotation will be 30 degrees (if initially rotation was 0 degrees)
        \see a2dAffineMatrix::Rotate
        \see SetRotation
    
        \param rotation rotate by this angle in degrees
    */
    void Rotate(double rotation);

    //!Sets a rotation of this object
    /*!
        Sets in opposite to Rotate the absolute rotation of this object.
        \see a2dAffineMatrix::SetRotation
        \see Rotate

        \param rotation set rotation angle in degrees
    */
    void SetRotation(double rotation);

    //! Scale in x and y ( > zero)
    /*!
        \param scalex scalling in X
        \param scaley scalling in Y
    */
    void Scale( double scalex, double scaley );

    //!Mirrors this object in x or y orientation
    /*!
    \param x mirror at X-axis (horizontally orientation)
    \param y mirror at Y-axis (vertically orientation)
    */
    void Mirror(bool x=true, bool y=false);

    //! Skew in X
    /*!
        \param angle angle to skew in X
    */
    void SkewX( double angle );

    //! Skew in Y
    /*!
        \param angle angle to skew in Y
    */
    void SkewY( double angle );

    //!get the matrix used to position the object
    const a2dAffineMatrix& GetTransformMatrix() const { return m_lworld; }

    a2dAffineMatrix GetTransform() const { return m_lworld; }
    void SetTransform( a2dAffineMatrix mat = a2dIDENTITY_MATRIX ){ m_lworld = mat; SetPending(true); }

    //! Returns the matrix used to position the object
    /*!
        \param mat matrix set for transforming the object
    */
    void SetTransformMatrix(const a2dAffineMatrix& mat = a2dIDENTITY_MATRIX ){ m_lworld = mat; SetPending(true); }

    //!Sets the matrix used to position the object
    /*!
        A new matrix will be constructed for transforming this object.

        \see SetTransformMatrix
        \see a2dAffineMatrix::a2dAffineMatrix

        \param xt      x translation
        \param yt      y translation
        \param scalex  x scale factor
        \param scaley  y scale factor
        \param degrees rotation in degrees
     */    
    void SetTransformMatrix( double xt, double yt, double scalex = 1, double scaley = 1, double degrees = 0 );

    //!get x position from affine matrix
    double GetPosX() const { return m_lworld.GetValue(2,0); }

    //!get y position from affine matrix
    double GetPosY() const { return m_lworld.GetValue(2,1); }

    //!get position of object
    a2dPoint2D GetPosXY() const { return a2dPoint2D( m_lworld.GetValue(2,0), m_lworld.GetValue(2,1) ); }

    //!set position to x,y
    /*! translation is set to x,y, rest of the affine matrix is preserved.
        \param x x position
        \param y y position
        \param restrict use a2dCanvasGlobals->GetRestrictionEngine() to snap position
    */
    void SetPosXY( double x, double y, bool restrict = false ); 

    //!set position to x,y
    /*! translation is set to x,y, rest of the affine matrix is preserved.
        \param pos position
    */
    void SetPosXyPoint( const a2dPoint2D &pos ) 
    { 
        SetPosXY( pos.m_x, pos.m_y, false ); 
    }

    //!set position to x,y but restricted, returns new values
    /*! translation is set to x,y, rest of the affine matrix is preserved.
        
        Same as SetPoXY(), but returneing restricted values
        
        \param x x position
        \param y y position       
        \return true of point was restricted/changed
    */
    bool SetPosXYRestrict( double& x, double& y ); 

    //!relative translate the object to position x,y in world coordinates
    /*! this function may be defined for each derived object, to move other object with this object.
        it is used internally for dragging and moving objects.
        \param x delta x for translation
        \param y delta y for translation
    */
    void Translate( double x, double y ) { m_lworld.Translate(x,y); SetPending(true); }

    //!transform the object using the given matrix
    /*!If the object can not rotate or scale those will be ignored
    and only translation will take place.
    If totally transformed it will return true else false.
    \param tworld matrix for transform
    */
    void Transform( const a2dAffineMatrix& tworld ) { m_lworld = tworld*m_lworld; SetPending(true); }

    //! called from an a2dRestrictionEngine, to restrict vertexes, lines, object to this object.
    /*!
        When other object, vertexes or lines are moved (e.g. by a tool), the restriction engine can be set to snap/restrict
        to neighbouring objects. Here you can define to which parts of those neighbour objects something can be snapped.
        For a simple polygon this will be its vertexes, for an ellipse its extremes. For complex objects, it can be anything. 
        For objects with pins, it will be the pins if that is asked for.
        For the various types of snap, you only implement what is useful for the object.

        The default can snap to:
            - pins snapToWhat == snapToWhat & a2dRestrictionEngine::snapToPins or a2dRestrictionEngine::snapToPinsUnconnected  
            - the object its position snapToWhat == a2dRestrictionEngine::snapToObjectPos
            - the vector path conversion with GetAsCanvasVpaths() snapToWhat == a2dRestrictionEngine::snapToObjectVertexes
    */
    virtual bool RestrictToObject( a2dRestrictionEngine* engine, a2dSnapToWhatMask snapToWhat );

    //! return a vectorpath indicating on which point/segments the object likes to be snap.
    /*! 
        If a drag of this object is on going, one may want to snap itself to other objects, while dragging.
        This member functions will tell the a2dRestrictionEngine on which points this object likes to snap to others.

        The default implementation for a2dRestrictionEngine::snapToObjectVertexes tries to convert to a Vpath, 
        and if so, uses that as return, if not, it takes the boundingbox its points.
        For a2dRestrictionEngine::snapToObjectPos its is the position of the object that is added.
        For a2dRestrictionEngine::snapToBoundingBox its is the BoundingBox points of the object that are added.
    */
    virtual a2dCanvasObjectList* GetSnapVpath( a2dSnapToWhatMask snapToWhat );

    //! reduce matrix to identity 
    /*! Override if possible to eliminate matrix of the object
        For a non Derived a2dCanvasObject this function multiplies its children
        with this object matrix, and reduces its own matrix to identity.
    */
    virtual bool EliminateMatrix();

    //\}
    //****************** END AFFINE TRANSFORMATION ******************/

    //****************** BOUNDING BOX ******************/
    /*! \name Bounding box
        Each a2dCanvasObject has a Bounding box for efficient drawing and hit testing.
        The bounding box is always the bounding box of the vertices. It is extended 
        in pixels or would units to cope for stroke width and decorations like handles.
    */
    //\{
public:

    //! flags for calculating boundingbox of derived object 
    /*! 
        Those flags are used in a a2dBboxFlags to indicate different ways of bounding boxes to be calculated.

        \sa DoGetUnTransformedBbox()
        \sa GetUnTransformedBbox()
        
        \ingroup canvasobject

    */
    enum a2dBboxFlag
    {
        a2dCANOBJ_BBOX_NON  =0x0000,     //!< return full boundingbox of derived object
        a2dCANOBJ_BBOX_EDIT =0x0001,      //!< return to contain edit bbox, suitable for editing matrix of object
        a2dCANOBJ_BBOX_CHILDREN =0x0002  //!< return to contain children bbox
    };
    
    typedef unsigned int a2dBboxFlags;

    //!get minimum X of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxMinX()     { return GetBbox().GetMinX(); }

    //!get minimum Y of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxMinY()     { return GetBbox().GetMinY(); }

    //!get maximum X of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxMaxX()     { return GetBbox().GetMaxX(); }

    //!get maximum Y of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxMaxY()     { return GetBbox().GetMaxY(); }

    //!get width  of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxWidth()     { return GetBbox().GetWidth(); }

    //!get height of the boundingbox in world coordinates relative to its parents
    /*!
        \remark stroke width is not included.
    */
    double  GetBboxHeight()     { return GetBbox().GetHeight(); }

    //!get boundingbox in world coordinates exclusive stroke width relative to its parent
    /*!
        \remark stroke width is not included.

        \remark if the boundingbox is not valid, it will be calculated right now,
        and to make sure parent object will have the right boundingbox, the object is
        set pending. That will in the update of a2dCanvasDocument, lead to redrawing and
        recalculation of this object and parent boundingbox will be recalculated.
    */
    a2dBoundingBox& GetBbox();

    //!Get boundingbox without the affine matrix transform included.
    /*!
        Extends as a result of stroke etc. is not included.

        \param flags default a2dCANOBJ_BBOX_CHILDREN to include child objects in the boundingbox
    */
    virtual a2dBoundingBox GetUnTransformedBbox( a2dBboxFlags flags = a2dCANOBJ_BBOX_CHILDREN ) const;

    //!Like GetBbox, but it always calculcates the bounding box from scratch
    /*!
       This is usefull, when you need the bounding box, but the stored bounding box
       is not up to date. The rendering system relies on doing this update on its own,
       because it needs the old bounding box for update area calculation.

        \param nChildLevels number of child levels to include (0=no childs, 1=direct childs, ...)
    */
    a2dBoundingBox GetCalculatedBoundingBox( int nChildLevels );

    //!first translate boundingbox with cworld and recalculate at new position
    /*!
        \remark a2dCanvasView for the a2dCanvasDocument must be set.
        \param ic iterative context contains matrix which is applied first to get to absolute position
        \param withExtend if true boundingbox includes extend in world and pixels ( a2dCanvasView must be set for m_root )
    */
    a2dBoundingBox GetMappedBbox( a2dIterC& ic, bool withExtend  = true );

    //!first translate boundingbox with cworld and recalculate at new position
    /*!
        \param cworld matrix applied first to get to absolute position
    */
    a2dBoundingBox GetMappedBbox( const a2dAffineMatrix& cworld );


    //!Get absolute occupied area in the device coordinates.
    /*!
        The object its boundingbox in world coordinates is first translated using the matrix cworld.
        Cworld will normally contain the accumulated matrix to the object with in the
        object Tree structure.

        \remark pixel and world extend are included.

        \param ic iterative context to get matrix which is applied first to get to absolute position
        \param inflate extra pxiels added on each size, to get rid of double to int rounding problems.
    */
    wxRect GetAbsoluteArea( a2dIterC& ic, int inflate = 2 );

    //!get world extend
    /*!
         world extend is the amount that the boundingbox is enlarged because
         of the stroke its size in case of a stroke with width defined in world coordinates.
         Other things may be included to get the total extend to the boundingbox of the object.
         
         The complete area occupied by a a2dCanvasObject in general is the boundingbox enlarged with
         the worldExtend + the pixelExtend ( expressed in worldcoordinates ).
         But if needed one can add to the both extends whatever is needed.
          
         \remark  worldExtend is calculated while Updating document/object
    */
    float GetWorldExtend() const { return m_worldExtend; }

    //!get pixel extend
    /*!
         pixel extend is the amount that the boundingbox is enlarged because
         of the stroke its size in case of a storke with width defined in pixel coordinates.
         Other things may be included to get the total extend to the boundingbox of the object.
         
         The complete area occupied by a a2dCanvasObject in general is the boundingbox enlarged with
         the worldExtend + the pixelExtend ( expressed in worldcoordinates ).
         But if needed one can add to the both extends whatever is needed.
          
         \remark  pixelExtend is calculated while Updating document/object

         \remark a trick to be able to use objects complete in pixel coordinates, 
         the boundingbox can be made zero while the pixel extend account for the rest.
         a2dHandle uses this approach. It will result in a total area that is square. 
    */
    int GetPixelExtend() const { return m_pixelExtend; }

    //! used for deciding if the object needs to be rendered against the current clipping area of the active drawer.
    /*!
        \param ic iterative context contains matrix which is applied first to get to absolute position
        \param clipparent clipping status of parent object ( to optimize )
    */
    OVERLAP GetClipStatus( a2dIterC& ic, OVERLAP clipparent );

    //! returns boundingbox clipping object if clipping property is set
    /*! \sa a2dClipPathProperty
        \param ic iterative context contains matrix which is applied first to get to absolute position
    */
    a2dBoundingBox GetClipBox( a2dIterC& ic );

    //\}
    //****************** END BOUNDING BOX ******************/
    
    //****************** EVENT PROCESSING AND HIT TESTING ******************/
    /*! \name Event processing
        Windows events are routed to the canvas objects under the mouse
    */
    //\{
public:

    //! Do hittest on children
    /*!
        Ignores this object its m_layer and drawing for the object and properties.
        Only does a hit test on the children. 
        When hitEvent.m_option & a2dCANOBJHITOPTION_LAYERS is true, iteration on layers is performed,
        by setting ic.SetPerLayerMode( true ).
        When hitEvent.m_xyRelToChildren is true, hit test is done relative to child objects, realized by
        adding inverse matrix of object to the a2dIterC first.
        The a2dIterC can contain a a2dIterC::SetObjectFilter() but this is only used when not iterating layers.
        When iterating layers, first normal objects are tested for a hit in reverse order of drawing the layers.
        So last drawn layer displayed on top, is tested first. At last the edit and tool object are tested.

        \param ic iterative context, relative to this testing is performed.
        \param hitEvent contains x,y to test, and other hit info is assembled here
        \param filterSelectableLayers if true layers should not only be visible but also selectable
    */
    a2dCanvasObject* ChildIsHitWorld( a2dIterC& ic, a2dHitEvent& hitEvent, bool filterSelectableLayers = false ); 

    //!If the position (x,y) is within the object return this
    /*! 
        First a simple bounding box test is done, if that hit is positive, a recursive call on child objects
        and properties which are normarmally rendered id done.
        The hit test is in reverse order of the rendering order of the object and its nested child
        objects.

        For an accurate hittest one needs to implement DoIsHitWorld() for the derived a2dCanvasObject,
        in that function one should test the object accurate, and also additional object which are 
        not in the childslist but real members of the derived object.
        DoIsHitWorld() should return the way the object is hit by filling a2dHitEvent::m_how with the correct info. 
        
        \param ic contains iteration context
        \param hitEvent stores hit information

        \return this pointer if there is a hit on this object or its children or its properties.
    */
    a2dCanvasObject* IsHitWorld( a2dIterC& ic, a2dHitEvent& hitEvent );

    //!set hit flags
    /*!
        Based on these flags the object will generate a hit true.
        \param mask set hit flags in object according to given mask.
    */
    void SetHitFlags( a2dCanvasObjectFlagsMask mask );

    //! Hit objects will receive the event
    /*! 
        The event is first sent to the child objects, and if not processes there,
        testing for a hit on the object itself is done, and if true a2dEvtHandler::ProcessEvent is called. 
        The function goes through the whole hierarchy, even if event is already processed. 
        It maybe be that other events are generated while iterating over the document.

        \param ic iteration context
        \param hitEvent stores hit information

        \return true if Object (or a child ) did process the event and did not call event.Skip()
    */
    virtual bool ProcessCanvasObjectEvent( a2dIterC& ic, a2dHitEvent& hitEvent );

    //! default handler for mouse events, sent to the object from the a2dCanvasView.
    /*!
        Mouse events are sent to the object when the mouse pointer is hiting the object.
        The default is used when the object is in edit mode. Else it will detect
        if the special object tip property named __OBJECTTIP__ is available, and switch 
        it on or off when the mouse eneter or leaves the object.
    */
    void OnCanvasObjectMouseEvent( a2dCanvasObjectMouseEvent& event );

    //! default handler for character events
    void OnChar(wxKeyEvent& event);

    //! called on Right Down by default.
    void OnPopUpEvent(a2dCanvasObjectMouseEvent &event);

    //! called when the mouse enters the object
    void OnEnterObject(a2dCanvasObjectMouseEvent &event);

    //! called when the mouse leaves the object
    void OnLeaveObject(a2dCanvasObjectMouseEvent &event);

    //! object with mouse in flag set, will sent a leave event, and set flag off.
    //! recursive for children.
    void LeaveInObjects( a2dIterC& ic, a2dHitEvent& hitEvent );

    //! called if a mouse event occured on a child object, that is a handle
    void OnHandleEvent(a2dHandleMouseEvent &event);

protected:

    //!This is an internal function used by IsHitWorld(). Don't use it directly.
    a2dCanvasObject* IsHitWorldChildObjects( a2dIterC& ic, RenderChild& whichchilds, a2dHitEvent& hitEvent ); 

    //!Does hit test on the object (exclusif child objects)
    /*!
        DoIsHitWorld() should return the way the object is hit by filling a2dHitEvent::m_how with the correct info. 

        \param ic iterative context ( e.g. current transform WITH the local transform applied )
        \param hitEvent stores hit information
        \return true if hit
    */
    virtual bool DoIsHitWorld( a2dIterC& ic, a2dHitEvent& hitEvent );

    //!This is an internal function used by IsHitWorldChildObjects(). Don't use it directly.
    a2dCanvasObject* HitChildObjectsOneLayer( a2dIterC& ic, RenderChild& whichchilds, a2dHitEvent& hitEvent );

    //\}
    //****************** END EVENT PROECSSING AND HIT TESTING ******************/

    //****************** CHILD TREE AND DOCUMENT STRUCTURE ******************/
    /*! \name Child tree and document structure
        Every a2dCanvasObject has a list of child objects. One a2dCanvasObject can
        be element of multiple child lists and can thus have multiple parents.
        Reference counting is used to control the life time of a a2dCanvasObject.
        Because a a2dCanvasObject can have multiple parents, it has no parent pointer.
        A a2dCanvasObject has a pointer to the a2dCanvasDocument it belongs to.
    */
    //\{
public:

    //!get a2dCanvasDocument of the object.
    /*!
        Root (a2dCanvasDocument) needs to be known to each object for the following reasons:
         - It is used to inform the document that there are pending objects in the document.
         - To reach the layer setup of the document.
         - To reach the command processor of the document, which is used to submit commands to,
           that can be undone if needed.

    */
    inline a2dCanvasDocument *GetCanvasDocument() const { return m_root; }

    //! Sets this object to a a2dCanvasDocument.
    /*!   
         \param root set the a2dCanvasDocument for this object to this (if appropriate recursive)
         \param recurse default true, which uses a2dWalker_SetCanvasDocument for doing the
                same recursive for nested object and nested object in derived classes.
    */
    void SetCanvasDocument( a2dCanvasDocument *root, bool recurse = true );

    //!prepend a a2dCanvasObject to the childobjects
    void Prepend( a2dCanvasObject* obj );

    //!append a a2dCanvasObject to the childobjects
    void Append( a2dCanvasObject* obj );

    //!insert a a2dCanvasObject to the childobjects
    void Insert( size_t before, a2dCanvasObject* obj, bool ignoreReleased = true );

    //!get the list where the child objects are stored in.
    /*!
         \return A pointer to the childlist. If there is no child list yet, it returns wxNullCanvasObjectList.

         \remark  wxNullCanvasObjectList has no children and therefore one can use 
         GetChildObjectList()->GetCount() to test for children.
    */
    a2dCanvasObjectList* GetChildObjectList();
    const a2dCanvasObjectList* GetChildObjectList() const;

    //!create and get the list where the child objects are stored in.
    /*!
        If there is no childlist yet (wxNullCanvasObjectList), a new childlist will be created.
        Else the existing one will be returned.

         \return A pointer to the childlist. 
    */
    a2dCanvasObjectList* CreateChildObjectList();

    //! get number of child objects
    /*!
        \return number of child objects
    */
    unsigned int GetChildObjectsCount() const;

    //!object with the same given mask are made into a group.
    /*!
        \param mask: mask for objects to assemble for creating a group of child objects
        \param createref: next to a new a2dCanvasObject, create a reference to the new object.
        \return return newly created object only if objects where found else NULL
    */
    a2dCanvasObject* CreateHierarchy( a2dCanvasObjectFlagsMask mask, bool createref = true );

    //! move childs of childs and members which have hierarchy one level up to this object its child list.
    /*!
        The base implementation takes child object in m_childobjects to the parent object.
        The child object are transformed by the parent its transform.
    */
    virtual void RemoveHierarchy();

    //!remove the given object from the childobjects
    /*! The object will be Realeased.
        if its refcount is 0 it will be deleted else its refcount decremented.
        
        \param obj object to release
        \param backwards start at the end 
        \param all if true remove all references to object
        \param now if true remove all references to object now!, else only delete flag is set, 
        and Update() takes care of it.

        \return number of released objects
    */
    int ReleaseChild( a2dCanvasObject* obj, bool backwards = false, bool all = false, bool now = false );


    //!removes and release only from the childobjects the objects with the given mask
    /*!
        \return true if some object were released
    */
    bool ReleaseChildObjects( a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL );

    //!returns index of the given a2dCanvasObject in this childobjects
    int IndexOf( a2dCanvasObject* obj ) const;

    //!return the object which fits the filter.
    /*!
        \param objectname object with this name to search for
        \param classname If classname is empty it collects all objects else only object with this class name.
        \param mask object must have this mask.
        \param propid if a property id is given, the object must have a property with this id
        \param valueAsString StringValueRepresentation of the property that is required (if not empty).
        \param id GetUniqueSerializationId() should be this unless 0
    */
    a2dCanvasObject* Find( const wxString& objectname, const wxString& classname = wxT(""), 
         a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL , const a2dPropertyId *propid = NULL, const wxString& valueAsString = wxT(""),
         wxUint32 id = 0 ) const;

    //!return the child object if it is part of this object
    /*! 
        \param obj object to search for
    */
    a2dCanvasObject* Find( a2dCanvasObject* obj ) const;

    //! the object with the given name is released and switched in place to newobject
    /*!
        \return true if object was found else false
    */
    bool SwitchChildNamed( const wxString& objectname, a2dCanvasObject* newobject );

    //!Copy objects with the right conditions to the total list.
    /*!
        \param total list of object found (may already contain elements found in earlier call)
        \param classname If classname is empty it collects all objects else only object with this class name.
        \param mask object must have this mask.
        \param id  If property id is set the object needs to have this property.
        \param bbox only find objects within this box.

        \remark only searches this object and its children, not deeper.

        \return number of objects found
    */
    int CollectObjects( a2dCanvasObjectList* total,
                        const wxString& classname = wxT(""),
                        a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL,
                        const a2dPropertyId *id = 0,
                        const a2dBoundingBox& bbox = wxNonValidBbox
                      ) const;

    //\}
    //****************** END CHILD TREE AND DOCUMENT STRUCTURE ******************/
    
    //****************** UPDATE AND PENDING ******************/
    /*! \name Update and Pending
    */
    //\{
public:
    //! Various mode flags for Update
    /*! It doesn't make sense to bit-or these, but these are bitflags anyway
        for quick multi-testing (e.g. ( mode & (mode1|mode2|mode3) ) */
    enum UpdateMode
    {
        /*! saves old valid boundingbox as boundingbox property */ 
        update_save = 0x0001,

        /*! includes boundingbox properties in object its boundingbox */
        update_includebboxprop = 0x0002,

        /*!  update_save and update_includebboxprop combined */
        updatemask_save_includebboxprop = 
            update_includebboxprop |
            update_save,

        //! All updates of these modes force an update (e.g. update non-pending valid bounding boxes)
        updatemask_force = 
            update_includebboxprop |
            update_save,

        //! object with invalid boundingbox or pending objects their boundingbix is recalculated.
        //! When boundingbox properties are found, theye will be include in the box.
        updatemask_normal = 
            update_includebboxprop
    };

    //! Update the state of the object according to its current position etc.
    /*!
        This usually does the following:
          - calculates the new bounding box in world coordinates relative to parents.
          - Release childs that have m_release set

        This function is usually called in a2dCanvasDocument::AddPendingUpdatesOldNew between adding
        the old and the new bounding box to the pending area.
        You should NOT do any change here that issues commands to the command processor,
        because such commands wouldn't have a proper context. Such things should be
        done in UpdateImmediate.
        Other things like updating the cache data need to be done here.

        Takes into account associated child, properties and derived objects.
        If a2dCanvasObject::UpdateMode = updatemask_force all boundingboxes are invalidated and recalculated,
        else it only recalculates if invalid or one of the children is invalid.

        This function calls DoUpdate(), when needed. The idea is to minimize the number of recalculated boudingboxes.
        So if an object is setpending or a child became pending, the boudingbox needs to be recalculated, 
        but since this is a combination of property, child and derived object boundingboxes, this is optimized. 

        \return true if the bounding box did change and the parent has to recalculate


        \remark The object its layers is set in the layersetup as being available in the document.
        \remark if overridden in derived class, also call baseclass Update
        \remark in derived classes DoUpdate() should be implemented to at least calculate the boundingbox of the object
        without children in m_childobjects, but including any referenced objects in the derived objects. Like arrow point
        objects on a line or polyline.
    */
    virtual bool Update( UpdateMode mode );

    //! A data structure for DoUpdateImmediate
    /*! All this could be given as parameters as well, but for a recursive function
        with always identical parameters, using a struct is more efficient and easier to extend

        This is derived from a2dPropObject, so that it can also be used as a means for 
        communication between different objects (usually of the same class) during update.

        \remark a2dDoUpdateImmediateData is derived from a2dPropObject so that it can have properties
        but a2dDoUpdateImmediateData is/should be never ref counted!

    */
    class A2DCANVASDLLEXP a2dDoUpdateImmediateData : public a2dPropObject
    {
    public:
        //! Current phase of the update process
        /*! This always starts with 0 and goes up if requested in phase 0 */
        int m_phase;
        //! Set a bit in here to request execution of an update phase
        int m_phaserequest;
        //! This has a bit set for every phase, that was already done
        int m_phasedone;
        //! If true, the current phase is executed for the first time
        bool m_phase_first;
        //! If true this is a final update of the original data, not an intermediate update of the editcopy
        bool m_final;
        //! If true, DoImmediateUpdate was called on an original object
        /*! Usually DoUpdateImmediate is called on an editcopy */
        bool m_original;
        //! If true, allow reconnecting the begin pin
        bool m_allowreconnectbegin;
        //! If true, allow reconnecting the end pin
        bool m_allowreconnectend;
        //! If true, before the next phase change the update object list is sorted by PROPID_UpdateImmediatePriority
        bool m_sortbeforenextphase;
        //! The tool, that issued this update, may be NULL, if not m_parent is set from it.
        class a2dBaseTool *m_tool;
        //! parent of the set of child objects to update.
        /*!
            Like the wires connecting normal objects, these are all children of the same parent.
        */
        a2dCanvasObjectPtr m_parent;

        //! constructor
        /*!
            \param final true when last stage needs to be executed in an reroute cycle,
            resulting in commands being issued.
            \param tool tool from which update is called, may be NULL
            \param parent parent of which the object need to be updated, if NULL,
                   m_tool->GetCanvasView()->GetShowObject() is taken as m_parent 
        */
        a2dDoUpdateImmediateData( bool final, a2dBaseTool *tool, a2dCanvasObject* parent );

        //! Set a bit in m_phaserequest
        void RequestPhase( int i )
        {
            wxASSERT( i>=0 && i<32 );
            m_phaserequest |= (1<<i);
        }

        //! Request that on the next phase change, the objects in the update list are sorted by PROPID_UpdateImmediatePriority
        void RequestSortPriorityBeforeNextPhase()
        {
            m_sortbeforenextphase = true;
        }

        DECLARE_CLASS( a2dDoUpdateImmediateData )

        //! Holds temporary routing data
        static a2dPropertyIdRefObject* PROPID_RouteData;

        DECLARE_PROPERTIES()
    };

    //! Like Update, but this is called not on OnIdle, but at well defined points
    /*! Use this function to adjust objects to a changing environment (e.g. wires
        to moving objects) when the changes are done by commands and need a proper
        command context. This function calls DoUpdateImmediate.

        The DoUpdateImmediateData structure, contains data which controls the recursive/repeating
        calls to this function. The idea is that objects which change can request more phases.
        Which eventually leads to extra calls until no more is requested.

        \param final signals last update that will be called in a row.
        \param tool tool from which update is called, may be NULL
        \param parent parent of which the object need to be updated, if NULL,
               m_tool->GetCanvasView()->GetShowObject() is taken as m_parent 
        \param data a structure with data controlling the update process
    */
    virtual void UpdateImmediate( bool final, a2dBaseTool *tool, a2dCanvasObject* parent = 0, a2dDoUpdateImmediateData *data = 0 );

    //! See UpdateImediate()
    virtual void DoUpdateImmediate( a2dDoUpdateImmediateData *data );

    //!is this object pending for update?
    /*!(overruled by parent object in some cases during rendering)
     \remark set the object its pending flag and inform root about this
    */
    bool GetPending() const { return m_flags.m_pending; }

    //!set this object pending for update
    /*!
     This flag is set when an object has changed, which means that it needs to be redrawn.
     Since an object can be Referenced also, it can be drawn at several positions.
     Therefore the redrawing needs to be done indirectly from the top, and for each a2dCanvasView
     displaying the object. In general old and new boundingbox areas are updated on the display.
     \li Step 1 add pending objects occupied areas to drawer.
     \li Step 2 The new boundingbox is calculated.
     \li Step 3 add pending objects occupied areas to draweronce more.
     \li Step 4 reset all pending flags for objects.

     \remark Does also inform the a2dCanvasDocument that there are pending objects.
     \remark If because of this object becoming pending other objects should become pending also,
     one should override this function to set those other objects pending.
     \remark If redefined in derived object always call base also.

     \sa DependencyPending()

     \param pending if true set object pending

    */
    virtual void SetPending( bool pending );

    //!search objects ( if nested recursive ) that have the pending flag Set
    /*!
        And add the current absolute boudingbox of the object to the pendingareas in the active
        a2dCanvasView for update/redrawing that area later. After a this normally the boundingbox of 
        this object will be recalculated in a2dCanvasObject::Update(), followed by one more call to this function 
        here, in order to also redraw the new boundingbox its area.
        When all pending areas are combined to a minimum in a2dCanvasView, the areas will be redrawn.

        The area currently occupied by the object in the active a2dCanvasView is added for update in case
        the object was pending. Next to that the  a2dCanvasView is informed that the object its layer 
        is available in the document and should be rendered. 
        In case the object will be released ( m_Release is set ), the a2dCanvasView::SetLayerCheck( objectlayer )
        is called, in order to recheck if there or still object on that layer as seen from that view.

        \remark this method is fast if many objects need an update.
        \remark You are responsible for setting and resetting the pending flag.
        \remark Not valid boundingbox in the object, means the object and its children will be ignored.

        \param ic iterative context, contains cumulative matrix for transforming object to absolute position
    */
    void AddPending( a2dIterC& ic );

    
    //!called by  to check if this object becomes pending as a result of other objects
    /*! 
        You can Override DependencyPending() to set your object pending, when another object was
        set pending. 
    */
    virtual void DependencyPending( a2dWalkerIOHandler* WXUNUSED(handler) );


    //****************** END UPDATE AND PENDING ******************/

    //****************** RENDERING AND STYLE ******************/
    /*! \name Rendering and style
    */
    //\{
public:

    //!Render this object to the active a2dCanvasView 
    /*!
    
    This function is called via the a2dCanvasDocument class or its nested children.
    The active a2dCanvasView which is set for the document is used to draw 
    to (either on its buffer or directly on the device)
    All rendering goes through this function to be able to render specific things
    in the base class first (like a2dCanvasObject its properties.)
    Somewhere internal DoRender will be called to really render the derived object itself.
    Next to that nested a2dCanvasObject's will be rendered too.

    If wanted only the canvas objects with a certain mask set, will be rendered.
    Mask example: Checking visible and selected

    use: mask=(a2dCANOBJ_VISIBLE | a2dCANOBJ_SELECTED)

    \remark 
    Do not use directly from outside the containing document of this object.
    Normally only used directly in derived classes \sa a2dCanvasDocument

    \remark The active clipping rectangle is set within the active drawer. 
    It can be used to decide which parts of the object need to be re-drawn or not. 
    This may speed up drawing in sepcial cases, but in general the active a2dCanvasView, simply
    clips all that is drawn on it to active clipping rectangle.
    The fact that the object is called to redrawn itself, is not decided here, instead it is part
    of the pending object mechanism. Which uses the object its boundingbox to request redrawing.

    \remark Normally an object will be rendered if the given layer is equal to the object its layer.

    \remark wxLAYER_ALL has a special meaning.
    If the given input layer is wxLAYER_ALL, then the m_layer of objects is not tested. 
    So the child objects their own layer settings are ignored/not checked in that case.
    All child objects are drawn at once, still the style of the layers settings is used when needed.

    If the flag "m_flags.m_childrenOnSameLayer" is set, a new iteration over layers will take place.
    The effect is that all children will be drawn at once ( not only objects on the given layer ),
    but the order of the layers will be taken into account to draw the children. 
    If the flag "m_flags.m_childrenOnSameLayer" is NOT set, a new iteration on layers is NOT done,
    and only the objects on the given layer will be drawn.

    \remark  ic.GetPerLayerMode() is true, then only ic.GetLayer() is rendered, which  can not be wxLAYER_ALL.

    \param ic iteration context (has a2dCanvasView accumulative matrix to calculate absolute position of the object)
    \param clipparent this must be the clip status of parent object, it is used to optimize drawing speed.
           e.g If parent is completely within the current clipping rectangle of the a2dCanvasView,
           there is no need to check child objects.
    */
    virtual void Render( a2dIterC& ic, OVERLAP clipparent );

    //! update the transform matrix for objects with property 'PROPID_viewDependent' 
    /*!
        will recursive call the UpdateViewDependentObjects routines of all the child objects (TODO for optimize: with flag 'm_childpixelsize=true').
        \param ic iteration context (has a2dCanvasView accumulative matrix to calculate absolute position of the object)

        \remark Check all child objects with (TODO for optimize: flag 'm_childpixelsize=true').
    */
    void UpdateViewDependentObjects( a2dIterC& ic );

    //! called by Render() if m_flags.m_HighLight is set
    /*!
        \param ic iteration context (has a2dCanvasView accumulative matrix to calculate absolute position of the object)
    */
    virtual void DrawHighLighted( a2dIterC& ic );

    //!set if this object will visible (be rendered or not)
    /*!(overruled by parent object in some cases during rendering)
        \remark set the object its pending flag and inform root about this
        \param visible if true set object visible
    */
    void SetVisible(bool visible) 
    { 
        if(m_flags.m_visible != visible) { m_flags.m_visible = visible; SetPending(true); } 
    }

    //!get visibility (rendering depends on layer settings also)
    bool GetVisible() const { return m_flags.m_visible; }

    //!get visibility (rendering depends on layer settings also)
    /*!
        Alias for GetVisible
         \see GetVisible
    */
    inline bool IsVisible() const { return GetVisible(); }    
    
    //!Set a fill for the object which will be used instead of the layer fill
    /*!
    The fill is for filling the object.
    Use a2dCanvasNullFill or 0 to remove the fill from a object.
    Use a2dTRANSPARENT_FILL to not fill the object.
    \remark m_flags.m_filled flag overrules the fill to fill TRANSPARENT
    \remark inheritance to children of object
    \remark object is free to use style or not
    \remark a style resulting in wxLAYER_FILL means property will be removed
    \sa a2dStyleProperty
    */
    void SetFill( const a2dFill& fill );

    a2dFill GetFill() const;

    //!Set a fill color for the object which will be used instead of the layer fill
    /*!
    \param fillcolor color to fill object with
    \param style style for one colour fill
    \remark creates a a2dOneColourFill internal
    \remark inheritance to children of object
    \remark object is free to use style or not
    \sa a2dStyleProperty
    \sa a2dOneColourFill
    */
    void SetFill( const wxColour& fillcolor, a2dFillStyle style = a2dFILL_SOLID );

    //!Set a fill color for the object which will be used instead of the layer fill
    /*!
    \param fillcolor color to fill object with
    \param fillcolor2 color to fill object with
    \param style style for one colour fill
    \remark inheritance to children of object
    \remark object is free to use style or not
    \sa a2dStyleProperty
    \sa a2dTwoColourFill
    */
    void SetFill(  const wxColour& fillcolor, const wxColour& fillcolor2, a2dFillStyle style = a2dFILL_SOLID );

    //! set first colour of fill
    void SetFillColour( const wxColour& colour );

    //! get first colour of fill 
    wxColour GetFillColour() const;

    //!Set a stroke  for the object which will be used instead of the layer stroke
    /*!
    \param strokecolor color to stroke object with
    \param width width of stroke in world coordinates
    \param style style for one colour stroke
    \remark a style resulting in wxLAYER_STROKE means property will be removed
    \remark inheritance to children of object
    \remark object is free to use style or not
    \sa a2dStyleProperty
    */
    void SetStroke(  const wxColour& strokecolor, double width = 0,  a2dStrokeStyle style = a2dSTROKE_SOLID );

    //!Set a stroke  for the object which will be used instead of the layer stroke
    /*!
    \param strokecolor color to stroke object with
    \param width width of stroke in device coordinates
    \param style style for one colour stroke
    \remark creates a a2dOneColourStroke property internal
    \remark inheritance to children of object
    \remark object is free to use style or not
    \sa a2dStyleProperty
    */
    void SetStroke(  const wxColour& strokecolor, int width ,  a2dStrokeStyle style = a2dSTROKE_SOLID );

    //! Set stroke using pointer to a stroke
    /*!
    The stroke is for drawing outlines of the object.
    Use a2dNullStroke to remove the stroke  from a object.
    Use a2dTRANSPARENT_STROKE to not fill the object.
    \remark a style resulting in wxLAYER_STROKE means property will be removed
    */
    void SetStroke( const a2dStroke& stroke);

    a2dStroke GetStroke() const;

    //! set first colour of stroke
    void SetStrokeColour( const wxColour& colour );

    //! get first colour of stroke
    wxColour GetStrokeColour() const;

    //!set the Contour width of the shape
    /*!
        Next to the stroke width one can sometimes set a contour width e.g. a circular donut.
    */
    virtual void SetContourWidth(double WXUNUSED(width)) {}

    //!get the Contour width of the shape
    virtual double GetContourWidth() const { return 0; }

    //!sets fill and stroke of object to a2dCanvasView
    /*!
        sets local fill and pen into a2dCanvasView if available, else
        they will be set on basis of the layer index.
        \sa a2dCanvasView
    */
    void SetDrawerStyle( a2dIterC& ic, a2dStyleProperty* style );

    //!if set children are rendered on the same layer as this object.
    /*!
        Children will be rendered at the same moment as the object itself, the effect
        is that they appear at the same layer.
        The rendering style of the children will be based on their own layer id's or style properties.

        \param samelayer if true render children on same layer
    */
    inline void SetChildrenOnSameLayer(bool samelayer) { SetPending(true); m_flags.m_childrenOnSameLayer = samelayer; }

    //!are children rendered on the same layer as this object?
    inline bool GetChildrenOnSameLayer() const { return m_flags.m_childrenOnSameLayer; }

    //!set the object view dependent and maybe process all children to set these flags 
    /*!
        \param aView view for adding next properties on this object and maybe its children.
        \param viewdependent if true, then add property 'PROPID_viewDependent' to objects 
                             that are depending on 'aView' view when it comes to size. 
                             Else to remove this property. 
        \param viewspecific  if true then add property 'PROPID_viewSpecific' to objects 
                             that are only visible on 'aView' view.
                             Else to remove this property to make visible on all views. 
        \param onlyinternalarea removing scale for children
        \param deep if true then set flags for all nested children objects
    */
    void SetViewDependent(a2dCanvasView* aView, bool viewdependent, bool viewspecific = false, bool onlyinternalarea = false, bool deep = false );

    //! How a child is placed towards its parent object.
    /*!
        If set true this object as a child object is placed only relative to the position of the
        parent object. Rotation and scaling of parent object are ignored.
    */
    inline void SetChildOnlyTranslate(bool onlytranslate) { SetPending(true); m_flags.m_ChildOnlyTranslate = onlytranslate; }

    //!are children rendered using just the translation of the parent or also rotation and scale.
    inline bool GetChildOnlyTranslate() const { return m_flags.m_ChildOnlyTranslate; }

    //! If set, this object has a higher priority in rendering than other children objects.
    /*!
        This method sets a priority in rendering: All children which have set
        the property m_prerenderaschild will be rendered before other children objects.

        As default the a2dCanvasObject has no priority in rendering, you have to
        set this property to true, if you want prerendering.

        \param prerender <code>true</code> to prerender this object, else <code>false</code>

    */    
    inline void SetPreRenderAsChild(bool prerender) { SetPending(true); m_flags.m_prerenderaschild = prerender; }

    //! Returns if this object should be rendered before other children objects.
    inline bool GetPreRenderAsChild() const { return m_flags.m_prerenderaschild; }

    //!is the object filled flag set
    //!Rendering is only outline when set.
    bool GetFilled() const { return m_flags.m_filled; }

    //!set the filled flag to render only outlines
    /*!Rendering is only outline when set.
     \remark set the object its pending flag and inform root about this
     \param filled if true set object filled
    */
    void  SetFilled(bool filled) { if (m_flags.m_filled != filled) SetPending(true); m_flags.m_filled = filled; }

    //! If True shadow object is visible (if property is there)
    bool GetShowShadow() const { return m_flags.m_showshadow; }

    //! If True shadow object is visible (if property is there)
    void SetShowShadow(bool showshadow) { m_flags.m_showshadow = showshadow; }

    //! see SetResizeOnChildBox()
    bool GetResizeOnChildBox() const { return m_flags.m_resizeToChilds; }

    //! If True resize to child boundingbox
    /*!
        In a2dCanvasObject::Update() a wxEVT_CANVASOBJECT_RESIZE_EVENT will be sent to this object.
        Default there is no handler for the event.
    */
    void SetResizeOnChildBox(bool resizeToChilds ) { m_flags.m_resizeToChilds = resizeToChilds; }

    //!quick way to get the style property containing Shadow property
    /*! style is maintained within an object as a a2dStyleProperty called __SHADOW__
    \remark object is free to use style or not
    \sa a2dShadowStyleProperty
    */
    const a2dShadowStyleProperty* GetShadowStyle() const ;

    void CallDoRender( a2dIterC& ic, OVERLAP clipparent )
    {
        DoRender( ic, clipparent );
    }

protected:

    const a2dFill& MX_GetFill() const; 
    void MX_SetFill( const a2dFill& value ); 
    const a2dStroke& MX_GetStroke() const; 
    void MX_SetStroke( const a2dStroke& value ); 

        
    //!render derived object
    /*!if the object has sub objects (apart from the childobject which are handled here),
    those subobject most rendered by iterating on layer when needed/wanted, simular to child objects.
    We do not iterate here, since that is only needed if indeed there or subobjects.
    This will be know in a "wxDerivedCanvasObject DoRender".

    SO parent objects that call this function, must:

        \li 1-  clip object against area to redraw.
        \li 2-  iterate on layers when needed.

    A a2dCanvasObject is rendered as a + (plus sign) when there or no children. 

    */
    virtual void DoRender( a2dIterC& WXUNUSED(ic), OVERLAP WXUNUSED(clipparent) );

    //! update transform matrix   klion: I'm not sure that this function necessary as virtual
    virtual void DoUpdateViewDependentTransform( a2dIterC& ic );
    
    //! update derived objects
    virtual void DoUpdateViewDependentObjects( a2dIterC& WXUNUSED(ic) );

    //! render only the child objects
    /*!
    \param ic iteration context (has a2dCanvasView accumulative matrix to calculate absolute position of the object)
    \param whichchilds defined which childs will be rendered now, and detects while rendering other types.
    \param clipparent this must be the clip status of parent object.
    */
    virtual void RenderChildObjects( a2dIterC& ic, RenderChild& whichchilds, OVERLAP clipparent );

    //!to render the child objects
    /*!
    \param ic iteration context (has a2dCanvasView accumulative matrix to calculate absolute position of the object)
    \param whichchilds defined which childs will be rendered now, and detects while rendering other types.
    \param clipparent this must be the clip status of parent object.
    */
    virtual void RenderChildObjectsOneLayer( a2dIterC& ic, RenderChild& whichchilds, OVERLAP clipparent );

    //\}
    //****************** END RENDERING AND STYLE ******************/

    //****************** EDITING AND HIGHLIGHTING ******************/
    /*! \name Editing and Highlighting
    */
    //\{
public:

    //!Sets if this object may be edited
    /*!
        If editable is set to <code>true</code> the object may be edited by an user.
        The default behaviour of this object is to allow modifications (editable).
        
        \param editable <code>true</code> to allow modifications, else <code>false</code>
    */    
    inline void SetEditable(bool editable) { m_flags.m_editable = editable; }

    //!get if the object may be edited
    inline bool GetEditable() const { return m_flags.m_editable; }

    //!get if the object may be edited
    /*!
        Alias for GetEditable
         \see GetEditable
    */
    inline bool IsEditable()  const { return GetEditable(); }

    //!is the object selected flag set
    /*!
        Rendering is different when set, it will use a special layer in this case.
    */
    bool GetSelected() const { return m_flags.m_selected;}
    
    //!Is the object selected flag set
    /*!
        Alias for GetSelected
         \see GetSelected
    */
    bool IsSelected() const { return GetSelected();}    

    //!Set the object selected flag if allowed
    /*!
        When set the second rendering cycle from the document a2dCanvasDocument::Render() etc.
        will draw this object selected.

         \remark sets the object its pending flag and inform root about this
         \param selected if true set object selected
    */
    void  SetSelected(bool selected) {
        if (m_flags.m_selectable) { if(m_flags.m_selected != selected) SetPending(true); m_flags.m_selected = selected;} }

    //!is the object selectable flag set
    /*!
         \return <code>true</code> if object is selectable, else <code>false</code>
    */
    bool GetSelectable() const { return m_flags.m_selectable; }

    //! Is the object selectable flag set
    /*!
        Alias for GetSelectable
         \see GetSelectable
    */
    bool IsSelectable() const { return GetSelectable(); }

    //!Allows to select this object.
    /*!
        If selectable is set to <code>true</code> the object may be selected by an user.
        The default behaviour of this object is to allow selection.
        
        \param selectable <code>true</code> to allow selection, else <code>false</code>
    */
    void  SetSelectable( bool selectable ) { m_flags.m_selectable = selectable; }

    //!Sets if this object may be dragged
    /*!
        If draggable is set to <code>true</code> the object may be dragged by an user.
        The default behaviour of this object is to allow dragg-operations.
        
        \param draggable <code>true</code> to allow selection, else <code>false</code>
    */    
    inline void SetDraggable(bool draggable) { m_flags.m_draggable = draggable; }

    //!get if the object can be dragged
    inline bool GetDraggable() const { return m_flags.m_draggable; }

    //!get if the object can be dragged
    /*!
        Alias for GetDraggable
         \see GetDraggable
    */
    inline bool IsDraggable() const  { return GetDraggable(); }

    //!is snap flag set?
    bool GetSnap() const { return m_flags.m_snap; }

    //!Sets snap flag
    /*!
        If snap is set to <code>true</code> this object is snapped by
        the restriction engine of a2dCanvasGlobal, when it is edited/moved etc.

        \see Restrict
    */
    void SetSnap( bool snap ) { m_flags.m_snap = snap; }

    //!Sets snap_to flag
    /*!
        If snap is set to <code>true</code> others objects may snap to this object by 
        the restriction engine of a2dCanvasGlobal.

        \see Restrict
    */
    void SetSnapTo( bool snap ) { m_flags.m_snap_to = snap; }

    //!is snap_to flag set?
    bool GetSnapTo() const { return m_flags.m_snap_to; }

    //! you may use it to modify rendering of the object depending on setting
    /*!
        Override this function to define a way to modify rendering for a derived object.

        e.g. When hiting an object you could modify the rendering to notify it to the user.
    */
    virtual void SetMode( int WXUNUSED(mode) ) {}

    //! get the rendering mode of the object.
    virtual int GetMode() const { return 0; }

    //! create an editcopy and initialize editing of the editcopy
    /*! This is called for an original object and creates an editcopy object.
       
        Calls DoStartEdit() in the end

        \param tool tool from which this function is called. Currently this is the a2dObjectEditTool
        \param editmode tobe used in derived object to switch between different way of editing 
              ( 0 means matrix mode of a2dCanvasObject )
        \param editstyle style of editing e.g. filled and stroked or with a wire frame.
    */
    virtual a2dCanvasObject* StartEdit( a2dBaseTool* tool, wxUint16 editmode, wxEditStyle editstyle = wxEDITSTYLE_COPY );

    //! cleanup an editcopy object
    /*! 
        This will Remove the editcopy from its parent.
        If editstyle is not wxEDITSTYLE_COPY, EditEnd is called for an original
        object, which is deprecated. The only tool using non wxEDITSTYLE_COPY is
        the wxMultEditTool, which will be changed.
        Calls DoEndEdit() first
    */
    virtual void EndEdit();

    //! to restart editing in a different mode
    void ReStartEdit( wxUint16 editmode );

    //! if this is an editcopy, return the orginal else NULL
    a2dCanvasObject* GetOriginal();

    //! set a2dHandle position with the given name
    a2dHandle* SetHandlePos( wxString name, double x, double y );

    //!redirect all mouse events for the canvas to this object
    void CaptureMouse( a2dIterC& ic );

    //!release the mouse capture for this object
    void ReleaseMouse( a2dIterC& ic );

    //!is the mouse captured for this object
    bool IsCapturedMouse( a2dIterC& ic ) const ;

    //! selected object itself or one of its recursive children 
    bool GetHasSelectedObjectsBelow() const { return m_flags.m_HasSelectedObjectsBelow; }

    //! selected object itself or one of its recursive children 
    void SetHasSelectedObjectsBelow(bool value) { m_flags.m_HasSelectedObjectsBelow = value; }

    //! tool object itself or one of its recursive children 
    bool GetHasToolObjectsBelow() const { return m_flags.m_HasToolObjectsBelow; }

    //! selected object itself or one of its recursive children 
    void SetHasToolObjectsBelow(bool value) { m_flags.m_HasToolObjectsBelow = value; }

    //!provide visual feedback by other objects that might participate in an editing
    /*!In some situations, e.g. when drawing wires or when draging objects in hierarchies,
       it is helpfull if other objects provide visual feedback, that they e.g. would
       accept the currently edited objects. If e.g. a wire is drawn, all pins that can
       accept the wire can turn green and all other pins can turn red. This function
       is usually called for the show object of a a2dCanvasView and goes down recursively.
       The id paramater identifies the editing situation. This is a a2dIdBase
       derived ID object, that is usually stored as a static member in a class.
       Objects that don't know a specific ID simply ignore it.
       Generally this function is called at least twice, once when the visual feedback
       should start, and once when it should end.


       Pins are tested for possible connection to pins on other objects. If some pin can connect 
       the EditFeedback() with the feedback id a2dPin::sm_feedbackCanConnect is called on it.
    */
    class A2DCANVASDLLEXP a2dFeedbackId : public a2dIdBase 
    {

    };

    //! feed back information of pins which can connect according to the 
    /*!

        When drawing new wires, pins that can accept a wire, can be set in a rendering mode to show this.
        This feedback set the pin rendering mode store as part of the feedback to a bin which is not yet connected
        and exists in the pin map table.
    */
    class A2DCANVASDLLEXP a2dFeedbackIdPinMapping : public a2dFeedbackId
    {
        public:

            //! constructor
            a2dFeedbackIdPinMapping()
            {
            }

            //! when a pin is found that fits the map, the rendering mode of the pin is set to this.
            void SetMode( int mode ) { m_mode = mode; }

            //! returns mode see  SetMode()
            int GetMode() { return m_mode; }

            //! Set task to perform
            void SetTask( a2dConnectTask task ) { m_task= task; }            

            //! get task to perform
            a2dConnectTask GetTask() { return m_task; }            

            //! Set mask
            void SetMask( wxUint32 mask ) { m_mask= mask; }            

            //! get mask
            wxUint32 GetMask() { return m_mask; }            

            //! set pinclass
            void SetPinClass( a2dPinClass * pinclass ) { m_pinclass = pinclass; }

            //! return the pin class of this pin
            a2dPinClass *GetPinClass() const { return m_pinclass; }

        protected:
        
            //! modifies rendering
            int m_mode;
            //! 
            a2dConnectTask m_task;

            //! pin class for task
            a2dPinClass* m_pinclass;

            //! mask for flags in pin
            wxUint32 m_mask;
    };

       //! tool editing feedback 
       /*!    
           \param ic iteration context
           \param id the id for the editing situation.
           \param currentEdit the currently edited object or another hint object
           \param depth recursion depth (0=this object, 1=this object+childs, ...)
           \param flags objects with this flag set ignore the depth limit
           \param x x world coordinate of mouse
           \param y y world coordinate of mouse
       */
       virtual void EditFeedback( a2dIterC& ic, const a2dFeedbackId *id, a2dCanvasObject *currentEdit=0, int depth=INT_MAX, a2dCanvasObjectFlagsMask flags = a2dCanvasOFlags::NON, double x=0, double y=0 );

    //\}
    //****************** END EDITING AND HIGHLIGHTING ******************/

    //****************** SERIALIZATION, IDs AND REFERENCES *****************/
    /*! \name Serialization, IDs and references
        In the CVG format one can store multiple references to one and the same object. 
        The object that is referenced is only written once, for the rest only
        the reference id is written to the CVG file.
        When loading a file in CVG, such references are resolved inside the document.
        So in the end the old reference is restored via by searching the object having that id.
        As such the refid attribute is just a place holder for a reference to the actual referenced object.
        The reason behind all this, is that the actual object might to be read yet, when a reference
        is encountered in the CVG file, and therefore the link can not be directly created.
        In other formats references are used in a simular manner, and to resolve them the same mechanism
        is used.
    */
    //\{
public:

    //!Check if this is a temporary object, which should not be saved
    virtual bool IsTemporary_DontSave() const;

#if wxART2D_USE_CVGIO

    //!write object specific CVGL data
    virtual void DoSave( wxObject* parent, a2dIOHandlerXmlSerOut &out, a2dXmlSer_flag xmlparts , a2dObjectList* towrite );

    //!load object specific CVG data
    virtual void DoLoad( wxObject* parent, a2dIOHandlerXmlSerIn& parser, a2dXmlSer_flag xmlparts );

    //! load one canvas object from a CVG file.
    void DoLoadOneObject( wxObject* parent, a2dIOHandlerXmlSerIn& parser, a2dXmlSer_flag xmlparts );

#endif //wxART2D_USE_CVGIO


    //\}
    //**************** END SERIALIZATION, IDs AND REFERENCES ***************/

    //********************** CONNECTION PINS AND WIRES *********************/
    /*! \name Connection via Pins and Wires

    - a a2dCanvasObject can have a2dPin objects as childs.
      These objects can connect to other a2dPin's and thus to other objects.

    - a2dPin objects know their parent, so that a communication path 
      a2dCanvasObject (has child) a2dPin (is connected to) a2dPin (has parent) a2dCanvasObject
      exists.

    - There are wire objects, that connect pins in objects and modify themselfes if the
      objects they connect move. A wire object overloads "IsConnect" to return true.

    - Note: There are two quite different wire classes: a2dWires and a2dWirePolylineL.
      a2dWires is more like a least-distance "airline" network used e.g. in routing applications to
      show unconnected nets.
      a2dWirePolylineL is a usual polyline with wire functioanlity.
      Some of the functions apply to one type, one to the other type.
    */
    //\{
public:

    //! return true, if this object is used to connect other object's using rubberband like structures.
    virtual bool IsConnect() const { return false; }

    //!used in case of flexible canvas objects (wires).
    /*!
        If another object connected to this object changes, and that has an effect on this
        object, return true;
    */
    virtual bool NeedsUpdateWhenConnected() const { return false; }

    //! if return true, connection with other object on this object its pins is allowed.
    /*! This is usually used for temporarily disabling connectivity */
    bool DoConnect() { return m_flags.m_doConnect; }

    //! If set to true this object may be connected to other object on its pins.
    /*! This is usually used for temporarily disabling connectivity */
    void DoConnect( bool doconnect ) { m_flags.m_doConnect = doconnect; }

    //! check connect to other object
    /*! After the call Pin objects which can connect, have their bin flag set.
    */
    bool CanConnectWith( a2dIterC &ic, a2dCanvasObject* toConnect, bool autocreate );

    //! is the given pin close enough to another a2dPin to allow connection?
    /*!
        The default searches for a2dPin children in this object, and a pointer to the one which 
        can connect with the given pin is returned. If non, returns NULL.

        Before trying to connect to the object DoCanConnectWith() is called, here the object can be prepared 
        to be able to connect to the given pin here. The default implementation asks the object to GeneratePins()
        if autoccreate is set true.

        \param ic iteration context
        \param pin pin to check for connection to this object
        \param margin pin as to be this close.
        \param autocreate when true, pins maybe be created at the position in a derived object.

    */
    a2dPin* CanConnectWith( a2dIterC &ic, a2dPin* pin, double margin, bool autocreate );

    //! Is the object connected ( Optinal to specific object ) ?
    /*!
        \param needsupdate if true, only return true when connected Object(s) need an update.
        \param toConnect when not ( NULL ), the object needs to be connected with toConnect.
    */
    bool IsConnected(bool needsupdate, a2dCanvasObject* toConnect = 0 );

    //! get connected objects that are connected to this object via its pins.
    /*!
         \param connected list to which connected objects will be added.
         \param needsupdate if true only connected objects which need updating will be added.
    */
    bool GetConnected(a2dCanvasObjectList* connected, bool needsupdate);

    //!Do connect with another a2dCanvasObject by pinname
    /*!
        If pinname is an empty string the pins that lie on top of each-other will be connected.
        Zero Length wires or objects (having pins on top of eachother) are not connected if already a connection exists.
        If needed (eg pin was already connected to another object) extra wires will be added to keep connection intact.
    */
    virtual bool ConnectWith( a2dCanvasObject* parent, a2dCanvasObject* toconnect, const wxString& pinname=wxT(""), double margin = 1, bool undo = false );

    //!Do connect with another a2dCanvasObject by pin pointer
    /*!
        Searches this object for a pin, which is at the same position as the one given.
        If that pin allows connection, those pins will be connected.
    */
    virtual bool ConnectWith( a2dCanvasObject* parent, a2dPin* pin, double margin = 1, bool undo = false );

    //! connect two pins
    /*! by creating a a2dWires object in between, unless already connected and
        they are exactly at the same position.
        They idea is to connect pins without changing there position, and keep already connected
        objects at the given pins connected also (to the wire object that is created ).
    */
    virtual void ConnectPinsCreateConnect( a2dCanvasObject* parent, a2dPin* pinc, a2dPin* pinother, bool undo = false );

    //! connect two pins which must be unconnected and at the same position
    /*! 
        This is a simple straight forward connection of the two pins.
        When Undo is true proper commands are issued to connect the pins.
        If the pins are already connected with something, they will be first disconnected.
    */
    void ConnectPins( a2dCanvasObject* parent, a2dPin* pinc, a2dPin* pinother, bool undo = false );

    //!Do Disconnect from another a2dCanvasObject by pin name
    /*!
        If toConnect = NULL all objects will be disconnected.
        If pinname is an empty string the pins connected to toConnect will be dis-connected,
        else only the ones with the pinname will be disconnected.
    */
    virtual bool DisConnectWith( a2dCanvasObject* parent, a2dCanvasObject* toConnect = NULL, const wxString& pinname = wxT("") );

    //!Do Disconnect from another a2dCanvasObject by pin pointer
    /*!
        Disconnect at pin (of object or of connected object).
    */
    virtual bool DisConnectAt( a2dCanvasObject* parent, a2dPin* pin );

    //! rewire the object to keep connection or to make connection with other objects
    void ReWireConnected( a2dCanvasObject* parent, bool undo = false );

    //! create wires on pins which do not have wires, but directly are connected to other objects.
    /*!
        This prepares the object for dragging/moving, while preserving the connection, since then wires will
        be rerouted when dragging.
    */
    bool CreateWiresOnPins( a2dCanvasObject* parent, bool undo );

    //! set connected pending or not pending
    /*!
         \param onoff set connected object pending or not pending
         \param needsupdateonly if true only connected object which need updating will treated.
    */
    bool SetConnectedPending( bool onoff, bool needsupdateonly );

    //!are there a2dPin derived children
    /*!
        \param realcheck if true checks all children else the flag m_flags.m_hasPins is returned
        \remark if realcheck is true also the m_flags.m_hasPins will be updated.
    */
    bool HasPins( bool realcheck = false );

    //!are there a2dPin derived children which matches the given pin name?
    /*!
        \param pinName the name of the pin to search for ( uses wxString::Matches() ).
        \param NotConnected if true the pin must be unconnected too.

        \return the a2dPin object found or NULL

        \remark the m_flags.m_hasPins is ignored here for the moment
    */
    a2dPin* HasPinNamed( const wxString pinName, bool NotConnected = false );

    //!How many a2dPin derived children are there.
    int GetPinCount();

    //! create pins in derived objects.
    /*!
        When wanting to connect to shapes which at construction have no pins, but still make sence
        to connect too, this function generates pins for the object, when connection is asked for by a tool.
        This is via EditFeedBack()

        The idea is to generate temporary pins for the tools, so the user sees where connection are possible.

        \param toConnectTo the pinClass to which the generated pin must be able to connect.
        \param task what/how to connect
        \param x x position of mouse or pin which wants/needs connection
        \param y y position of mouse or pin which wants/needs connection
    */
    virtual bool GeneratePins( a2dPinClass* WXUNUSED(toConnectTo), a2dConnectTask WXUNUSED(task), double WXUNUSED(x), double WXUNUSED(y) ) { return false; }

    //! Allow change in pin location when wiring things up.
    virtual bool AdjustPinLocation() { return false; }

    //! generates pins on all possible locations where the object can be connected.
    /*!
        Default calls pinClass->GetConnectionGenerator()->GeneratePossibleConnections()
        And that leads to calling a2dCanvasObject::GeneratePins()
        This way a a2dConnectionGenerator can limit the pins which are generated.

        \param pinClass if not NULL, only generate temporary pins that may connect to this pinClass.
        \param task what/how to connect
        \param x can be used to create pins depending on the poition of the mouse inside the object.
        \param y can be used to create pins depending on the poition of the mouse inside the object.
    */
    virtual bool GeneratePinsPossibleConnections( a2dPinClass* pinClass, a2dConnectTask task, double x, double y );

    //! based on the a2dPinClass's of eventually a2dPin's wanted in both objects, a
    /*! connection object will be delivered as a template to be cloned by the caller.
        In principle calling this->GetConnectTemplate() and other->GetConnectTemplate() 
        should result in the same.
        The default implementation uses a2dCanvasGlobals->GetPinClassMaps() which is a simple system
        to supply a template object based ob the two entry maps.
        You can override this function to define your own way of connections.
    */
    virtual a2dCanvasObject* GetConnectTemplate( a2dPinClass* mapThis, a2dCanvasObject* other, a2dPinClass* mapOther ) const;

    //! generates a connection object with pins and all.
    /*!
        Default calls pinThis->GetConnectionGenerator()->CreateConnectObject()
        This way a a2dConnectionGenerator can decide on the type of object to generate
        as a plugin.
    */
    virtual a2dCanvasObject* CreateConnectObject( a2dCanvasObject* parent, a2dPin* pinThis, a2dPin* pinOther, bool undo = false ) const;

    //! add a a2dPin as child
    /*!
        \param name name which the pin will get
        \param x x-position of pin
        \param y y-position of pin
        \param a2dpinFlags
                - a2dPin::dynamic if true pin will be dynamic
                - a2dPin::temporary if true pin will be temporary
                - a2dPin::objectPin if true pin is seen as part of an object and not a wire/connect
        \param pinClass pinClass of the pin, created pin cloned from a2dPinClass->GetPin()

        \return the pin that was created and added to the object.
    */
    a2dPin* AddPin( const wxString name, double x, double y, wxUint32 a2dpinFlags, a2dPinClass* pinClass );

    //! Remove all a2dPin children
    /*!
        \param NotConnected when true only pins which are not connected tp another pin will be deleted
        \param onlyTemporary when true only pins with the temporary flag set 
        using a2dPin::SetTemporaryPin() will be deleted.
        These type of pins are used in automatic connection situations, and often
        after an editing attempt of other objects need to be deleted in the end. 
        \param now if true remove pin object now!, else only delete flag is set, 
        and it will be deleted in idle time. 
    */
    void RemovePins( bool NotConnected = false, bool onlyTemporary = false, bool now = false );

    //! Set a2dPin children visible or not
    void ShowPins( bool onoff );

    //! Calls a2dPin::SetRenderConnected() for all pins
    /*! By default connected pins are not rendered, you can set it true for all pins here.
        But you can also set each pin individual.
    */
    void SetRenderConnectedPins( bool onoff );

    //! Find and clone all wires ( IsConnect()==true ) connected to this object or to such wires
    /*! After this function you must call copies->RestoreConnectionsAfterCloning()
        \param originals list of original wire objects
        \param copies list of wire object edit copies
    */
    void CreateWireEditCopies( a2dCanvasObjectList *originals, a2dCanvasObjectList *copies );

    //! Restore connections after cloning
    /*!  After cloning a tree of connected objects, this will restore
        the connections in the clone as they have been in the original
        \param cp if not 0, the connections are created by issuing a2dCommand_ConnectPins commands
    */
    virtual void RestoreConnectionsAfterCloning( class a2dCanvasCommandProcessor *cp = 0 );

    //! Remove all pin connections by issuing a2dCommand_ConnectPins commands
    /*! This should be done before a a2dCommand_ReleaseObject is issued.
        \param cp the command processor receiving the commands
    */
    virtual void ClearAllPinConnections( class a2dCanvasCommandProcessor *cp );

    //! set parent object of the pin or some other objects that needs a parent
    virtual void SetParent( a2dCanvasObject* WXUNUSED(parent) ) {};

protected:

    //! prepare an object for being connected to a given pin
    /*!
        Before trying to connect in CanConnectWith() to the object DoCanConnectWith() is called, 
        here thy object can be prepared to be able to connect to the given pin here. 
        The default implementation ask the object to GeneratePins() if autoccreate is set true.

        In a derived class one can do more complicated to decide if a pin needs to be created or not.
    */
    virtual bool DoCanConnectWith( a2dIterC &ic, a2dPin* pin, double margin, bool autocreate );

    //\}
    //******************** END CONNECTION PINS AND WIRES********************/

    //********************** PROPERTIES *********************/
    /*! \name Properties
        a a2dCanvasObject has a list of general named properties
    */
    //\{
public:

    //! a2dCanvasObject set as property will be rendered after all other child objects 
    //! when it is rendreed from a parent a2dCanvasObject
    inline void SetIsProperty(bool IsProperty ) { SetPending(true); m_flags.m_IsProperty = IsProperty; }

    //! a2dCanvasObject set as property will be rendered after all other child objects 
    //! when it is rendreed from a parent a2dCanvasObject
    inline bool GetIsProperty() const { return m_flags.m_IsProperty; }

    //! quickly set a property name __OBJECTTIP__
    /*!
        This function stores an OBJECTTIP property which will be shown when mouse is within an object.
        
        \param tip    the tip which should be shown
        \param x      x-pos of the tip
        \param y      y-pos of the tip
        \param size  font-size in world coordinates (font size of the font-param will be ignored, see a2dText documentation)
        \param angle rotation in degrees
        \param font the font to use

        \return a pointer to the a2dText object used to show the tip.  
    */
    a2dText* SetObjectTip( const wxString& tip, double x, double y,  double size = 30, double angle = 0, 
        const a2dFont& font = *a2dDEFAULT_CANVASFONT );

    //! quickly set a property a2dTipWindowProperty
    /*!
    This function stores a a2dTipWindowProperty property which will be shown when mouse is within an object.
    The function a2dCanvasObject::OnEnterObject() will show it.

    \param tip    the tip which should be shown
    */
    void SetTipWindow( const wxString& tip );

    //! quickly get first property with name __OBJECTTIP__
    a2dObject* GetObjectTip();

    //! edit properties of the object
    /*! 
        This default implementation distributes the a2dPropertyEditEvent with 
        id wxEVT_PROPOBJECT_EDITPROPERTIES_EVENT, to a2dDocviewGlobals->GetEventDistributer().

        This can be intercepted by any registrated class in order to edit the properties.
        When after return, the event its GetEdited() returns true, this indicates that the 
        properties where indeed edited.

        \param id If property id is set only matching properties are selected
        \param withUndo   If true, the changes can be undone later.        
    */
    virtual bool EditProperties( const a2dPropertyId *id, bool withUndo );

    //! This function is called after a property changed
    /*! This is overloaded to set e.g. a pending flag
    */
    void OnPropertyChanged( const a2dPropertyId* id );

    //\}
    //**************** END PROPERTIES ***************/

    //********************** FLAGS *********************/
    /*! \name Flags
        a a2dCanvasObject has some falgs for general and algorithmic use.
        Other flags have special meaning or are used internally. The flags with special
        meaning (e.g. m_visible) are detailed in the proper sections.
    */
    //\{
public:

    //!set all bit flags in object that or true in mask to true or false
    /*!
        set specific flags to true or false

        \remark the object is not setpending when something changed ( actually the pending flag can be set here also ) 

        \param setOrClear if true sets the flag to true else to false
        \param which set only those flags in object to true or false
    */
    void SetSpecificFlags( bool setOrClear, a2dCanvasObjectFlagsMask which );

    //!Compares all flags in object to the given mask and return true is the same.
    bool CheckMask(  a2dCanvasObjectFlagsMask mask) const;

    //!set bit flags of object (true or false) to given newmask values
    /*!
        \remark does not recurse into children

        \param newmask mask to set flags to in object (either true or false)
    */
    void SetFlags( a2dCanvasObjectFlagsMask newmask );

    //!get specific bitflag value
    bool GetFlag( const a2dCanvasObjectFlagsMask which ) const;

    //!get bitflags as an integer
    a2dCanvasObjectFlagsMask GetFlags() const;

    //!general flag use at will.
    /*!
        \remark
        This flag should only be used for temporarly purposes.
        This object uses this flag too and you might run into problems if you use this flag.
        It's a good practice to set this flag if you need it and reset this flag to <code>false</code>
        if you don't need it anymore. Another possibility might be to add a new property to this object
        if you want to be on the secure side.
    
        \param bin temporarely status information
    */
    inline void SetBin(bool bin) { m_flags.m_bin = bin; }

    //!general flag use at will.
    inline bool GetBin() const {return m_flags.m_bin;}

    //!get the groupA flag
    /*! used to define operands in operation on two groups of objects
    */
    bool GetGroupA() const { return m_flags.m_a; }

    //!set the groupA flag
    /*! used to define operands in operation on two groups of objects
        \param value true to set group flag A
    */
    void SetGroupA( bool value ) { SetPending(true); m_flags.m_a = value; }

    //!get the groupA flag
    /*! used to define operands in operation on two groups of objects
    */
    bool GetGroupB() const { return m_flags.m_b; }

    //!set the groupA flag
    /*! used to define operands in operation on two groups of objects
        \param value true to set group flag B
    */
    void SetGroupB( bool value ) { SetPending(true); m_flags.m_b = value; }

    //!get the GeneratePins flag
    /*! used to define operands in operation on two groups of objects
    */
    bool GetGeneratePins() const { return m_flags.m_generatePins; }

    //!set the GeneratePins flag
    /*! used to define operands in operation on two groups of objects
        \param value true to set group flag C
    */
    void SetGeneratePins( bool value ) { SetPending(true); m_flags.m_generatePins = value; }

    //!set IgnoreSetpending flag
    /*!If this flag is set, the object will be not be set pending in SetPending()*/
    void SetIgnoreSetpending( bool value = true ) { m_flags.m_ignoreSetpending = value; }

    //!get IgnoreSetpending flag
    /*!If this flag is set, the object will be not be set pending in SetPending()*/
    bool GetIgnoreSetpending( ) const { return m_flags.m_ignoreSetpending; }

    //!set static IgnoreAllSetpending flag
    /*!If this flag is set, all a2dCanvasObject will be not be set pending in SetPending()*/
    static void SetIgnoreAllSetpending( bool value = true ) { m_ignoreAllSetpending = value; }

    //!get static IgnoreSetpending flag
    /*!If this flag is set, all a2dCanvasObject will be not be set pending in SetPending()*/
    static bool GetIgnoreAllSetpending( ) { return m_ignoreAllSetpending; }

    void SetIgnoreLayer( bool value = true ) { m_flags.m_ignoreLayer = value; }

    bool GetIgnoreLayer( ) const { return m_flags.m_ignoreLayer; }

    void SetSubEdit( bool value ) { m_flags.m_subEdit = value; }
    bool GetSubEdit( ) const { return m_flags.m_subEdit; }
    void SetSubEditAsChild( bool value ) { m_flags.m_subEditAsChild = value; }
    bool GetSubEditAsChild( ) const { return m_flags.m_subEditAsChild; }
    void SetShowshadow( bool value ) { m_flags.m_showshadow = value; }
    bool GetShowshadow( ) const { return m_flags.m_showshadow; }
    void SetPushin( bool value ) { m_flags.m_pushin = value; }
    bool GetPushin( ) const { return m_flags.m_pushin; }
    void SetBin2( bool value ) { m_flags.m_bin2 = value; }
    bool GetBin2( ) const { return m_flags.m_bin2; }
    void SetPrerenderaschild( bool value ) { m_flags.m_prerenderaschild = value; }
    bool GetPrerenderaschild( ) const { return m_flags.m_prerenderaschild; }
    void SetVisiblechilds( bool value ) { m_flags.m_visiblechilds = value; }
    bool GetVisiblechilds( ) const  { return m_flags.m_visiblechilds; }
    void SetEditing( bool value ) { m_flags.m_editing = value; }
    bool GetEditing( ) const { return m_flags.m_editing; }
    void SetEditingRender( bool value ) { m_flags.m_editingCopy = value; }
    bool GetEditingRender( ) const { return m_flags.m_editingCopy; }
    void SetDoConnect( bool value ) { m_flags.m_doConnect = value; }
    bool GetDoConnect( ) const { return m_flags.m_doConnect; }
    void SetIsOnCorridorPath( bool value ) { m_flags.m_isOnCorridorPath = value; }
    bool GetIsOnCorridorPath( ) const { return m_flags.m_isOnCorridorPath; }
    void SetHasPins( bool value ) { m_flags.m_hasPins = value; }
    bool GetHasPins( ) const { return m_flags.m_hasPins; }
    void SetMouseInObject( bool value ) { m_flags.m_MouseInObject = value; }
    bool GetMouseInObject( ) const { return m_flags.m_MouseInObject; }
    void SetHighLight( bool value ) { m_flags.m_HighLight = value; }
    bool GetHighLight( ) const { return m_flags.m_HighLight; }

    //! sents a layer change event around.
    void SentChangeLayerEvent( wxUint16 layer );

protected:

    //\}
    //**************** END FLAGS ***************/

    //********************** LAYERS *********************/
    /*! \name Layers
        a a2dCanvasDocument is rendered in layers. Every canvas object belongs to excatly
        one layer.
    */
    //\{
public:
    
    //! Returns the layer index where this object is drawn upon.
    /*!
        The order of the a2dLayers in the root object decides if and when it will be drawn.
        
        \see a2dCanvasDocument::SetLayerSetup
        \see a2dLayers
    */
    inline wxUint16 GetLayer() const { return m_layer; }

    //!set layer index where this object is drawn upon.
    /*!
        Default is layer wxLAYER_DEFAULT (colours etc taken from layer list)
        Some layers are predefined and used for special purposes (i.e. for selection of 
        an object etc.). Please refer to wxLayerNames.
        If you want to define your own layer you should give it a value between 
        <code>wxLAYER_USER_FIRST</code> and <code>wxLAYER_USER_LAST</code>
        (<code>wxLAYER_USER_FIRST <= myLayerIndex <= wxLAYER_USER_LAST</code>)
    
        \see wxLayerNames
        \see a2dLayerInfo
        \see a2dLayers
    
        \param layer the index of the layer
    */
    virtual void SetLayer( wxUint16 layer );

    //\}
    //**************** END LAYERS ***************/

    //********************** APPLICATION SPECIFIC EXTENSIONS *********************/
    /*! \name Application specific extensions.
        The functions in this section can be used to extend the functionality of
        a2dCanvasObject without adding new virtual member functions to the base class.
    */
    //\{
public:

    //!call fp for each object
    void foreach_f(void (*fp) (a2dCanvasObject* item) );

    //!call fp for each object
    void foreach_mf(void (a2dCanvasObject::*mfp) () );

    //!can be used by the user to implement a function that affects all a2dCanvas  derived objects
    virtual bool UserBaseFunction() { return true;}

    //!can be used by the user to implement a function that affects all a2dCanvas derived objects
    /*!
       a2dIOHandler can be used to transfer data to the function, for example a a2dWalkerIOHandler handler
       can be used to iterate the document, and calll this function on every object wanted.

       \param function function id, to be able to use this function for more tasks.
       \param handler a2dIOHandler which was use to iterate the document
    */
    virtual bool UserBaseFunctionEx( int WXUNUSED(function), a2dIOHandler* WXUNUSED(handler) = NULL ) { return true; }

    //!can be used by the user to implement a function using a variable argument list that affects all a2dCanvas derived objects
    virtual bool UserBaseFunctionVar(...) { return true;}

    //!can be used by the user to implement a function using a variable argument list and format string that affects all a2dCanvas  derived objects
    virtual bool UserBaseFunctionFormat(wxString format,...) { return true;}

    //! This is used to recursively walk through an object tree
    void WalkerWithContext( a2dIterC& ic, wxObject* parent, a2dWalkerIOHandlerWithContext& handler );

protected:

    //! iterate over this object and its children
    /*!
        This function allows you to extend the functionality of all a2dCanvasObject classes
        in a a2dCanvasDocument, without adding extra members to these objects.
        
        Default functions are called on the a2dWalkerIOHandler, which redirect the
        calls to other functions based on this object its classname.
        On can register classes to a2dWalkerIOHandler or derived classes.
        This way for each unique object in the document there can be a function
        in a2dWalkerIOHandler.

        \return false if some object did not have a function attached via a2dWalkerIOHandler.
            
        See a2dWalkerIOHandler for more.
    */
    virtual void DoWalker( wxObject* parent, a2dWalkerIOHandler& handler );

    // used if context is needed.
    virtual void DoWalkerWithContext( a2dIterC& ic, wxObject* parent, a2dWalkerIOHandlerWithContext& handler );

    //\}
    //********************** END APPLICATION SEPCIFIC EXTENSIONS *********************/

    //********************** DEBUGGING *********************/
    /*! \name Debugging functions
        These functions are only enabled in Debug mode
    */
    //\{
public:
#ifdef _DEBUG

    //! Dump an Object with its childs and properties
    /*! Note: this function is not virtual, because virtual functions cannot
        be called from the debugger
    */
    void Dump( int indent = 0 );
    //! Called by Dump to Dump class specific stuff
    /*! Add class specific info to line or output line and create a new line */
    virtual void DoDump( int indent, wxString *line );

#endif
    //\}

    //! when implemented the object without its children, is converted to 
    /*!
        to a list of a2dVectorPath's. 
        Else wxNullCanvasObjectList is returned.
    */
    virtual a2dCanvasObjectList* GetAsCanvasVpaths( bool transform = true );

    void SetTemplate( bool b = true );
    void SetExternal( bool b = true );
    void SetUsed( bool b = true );

    bool GetTemplate() const ;
    bool GetExternal() const ;
    bool GetUsed() const ;

protected:

    bool ProcessCanvasEventChild( a2dIterC& ic, RenderChild& whichchilds, a2dHitEvent& hitEvent );

    bool ProcessCanvasEventChildOneLayer( a2dIterC& ic, RenderChild& whichchilds, a2dHitEvent& hitEvent );

public:
    
    //!only used for editable objects and under control of a editing tool.
    /*!
        If object is editable this function is used to initialize the object for editing.
        In general this means adding editing handles to the child list.
        In the event handling of the object those handles are hit and moved, the object itself
        is changed accordingly.

        \return true is this object can be edited and is initialized for that.
    */
    virtual bool DoStartEdit( wxUint16 editmode, wxEditStyle editstyle );

protected:

    virtual bool DoIgnoreIfNotMember( const a2dPropertyId &id );

    //!root group for rendering and accessing the canvas's also contains layer settings
    a2dCanvasDocument* m_root;

    //!holds flags for objects
    a2dCanvasOFlags m_flags;

    //!holds value for flags to initialize m_flags
    static a2dCanvasOFlags m_flagsInit;

    //!allow hits on basis of those flags
    a2dCanvasOHitFlags m_hitflags;

    //!boundingbox in world coordinates 
    a2dBoundingBox m_bbox;

    //! world extend in world coordinates. 
    /*! 
        Normally contains at least the stroke width when this is in world coordinates.
    */
    float m_worldExtend;

    //! Pixel extend
    /*! 
        In case of pixel object or partial pixel object or pixel strokes, 
        this will contain the needed oversize on top of the boundingbox.
        It is to be set in Update() or OnUpdate()
    */
    wxUint16 m_pixelExtend;

    //!layer of object, default wxLAYER_DEFAULT
    wxUint16 m_layer;

    //!used for positioning the object (x,y,ang,scale etc.)
    a2dAffineMatrix m_lworld;

    //!holds child objects
    a2dCanvasObjectList* m_childobjects;

    //! parse Cvg transform of object
    bool ParseCvgTransForm( a2dAffineMatrix& result, a2dIOHandlerXmlSerIn& parser );

    //!called by addPending
    virtual void DoAddPending( a2dIterC& ic );

    //! In derived object this should be overriden to calculate the boundingbox of the object without its children.
    /*!
        The default return a non Valid boundingbox.
        
        The real boundingbox of the object is often less desirable for editing. e.g. a rectangle with a contour,  
        one does not want editing handles on the contour, instead they  should still be on the basic rectangle.
    */
    virtual a2dBoundingBox DoGetUnTransformedBbox( a2dBboxFlags flags = a2dCANOBJ_BBOX_NON ) const;

    //!Update derived Object specific things ( mainly boundingbox)
    /*!
    Calculates the boundingbox of the object (exclusif base class child objects but with other nested objects).

    \param mode way to update the objects
    \param childbox size of children boundingbox
    \param clipbox clip to this
    \param propbox size of properties boundingbox 
    
    \remark in a derived class this function can also be used to update object specific cache data.

    \remark force may or may not have direct influence on the object itself, if this function is called directly
    for some reason (e.g from derived objects), you must invalidate the boudingbox yourself.
        GetDrawerBox()->SetValid( false );
    */
    virtual bool DoUpdate( UpdateMode mode, const a2dBoundingBox& childbox, const a2dBoundingBox& clipbox, const a2dBoundingBox& propbox );

    //!only used for editable objects and under control of a editing tool.
    /*!
        Do a clean up at the end of an editing sesion of the object.
        In general this means, remove editing handles from child list.
    */
    virtual void DoEndEdit() {};

public:

    //! when set all SetPending() calss are supressed.
    static bool m_ignoreAllSetpending;

    // member ids
    static a2dPropertyIdMatrix* PROPID_TransformMatrix;
    static a2dPropertyIdPoint2D* PROPID_Position;
    static a2dPropertyIdUint16* PROPID_Layer;
    static a2dPropertyIdBool* PROPID_Selected;
    static a2dPropertyIdBool* PROPID_Selectable;
    static a2dPropertyIdBool* PROPID_SubEdit;
    static a2dPropertyIdBool* PROPID_SubEditAsChild;
    static a2dPropertyIdBool* PROPID_Visible;
    static a2dPropertyIdBool* PROPID_Draggable;
    static a2dPropertyIdBool* PROPID_Showshadow;
    static a2dPropertyIdBool* PROPID_Filled;
    static a2dPropertyIdBool* PROPID_GroupA;
    static a2dPropertyIdBool* PROPID_GroupB;
    static a2dPropertyIdBool* PROPID_GeneratePins;
    static a2dPropertyIdBool* PROPID_Bin;
    static a2dPropertyIdBool* PROPID_Bin2;
    static a2dPropertyIdBool* PROPID_Pending;
    static a2dPropertyIdBool* PROPID_Snap;
    static a2dPropertyIdBool* PROPID_SnapTo;
    static a2dPropertyIdBool* PROPID_Pushin;
    static a2dPropertyIdBool* PROPID_Prerenderaschild;
    static a2dPropertyIdBool* PROPID_Visiblechilds;
    static a2dPropertyIdBool* PROPID_Editable;
    static a2dPropertyIdBool* PROPID_Editing;
    static a2dPropertyIdBool* PROPID_EditingRender;
    static a2dPropertyIdBool* PROPID_ChildrenOnSameLayer;
    static a2dPropertyIdBool* PROPID_DoConnect;
    static a2dPropertyIdBool* PROPID_IsOnCorridorPath;
    static a2dPropertyIdBool* PROPID_HasPins;
    static a2dPropertyIdBool* PROPID_IsProperty;
    static a2dPropertyIdBool* PROPID_MouseInObject;
    static a2dPropertyIdBool* PROPID_HighLight;
    static a2dPropertyIdBool* PROPID_Template;
    static a2dPropertyIdBool* PROPID_External;
    static a2dPropertyIdBool* PROPID_Used;
    static a2dPropertyIdBool* PROPID_Release;

    // commonly used member ids in derived classes
    static a2dPropertyIdCanvasObject* PROPID_Begin;
    static a2dPropertyIdCanvasObject* PROPID_End;
    static a2dPropertyIdDouble* PROPID_EndScaleX;
    static a2dPropertyIdDouble* PROPID_EndScaleY;
    static a2dPropertyIdBool* PROPID_Spline;
    static a2dPropertyIdDouble* PROPID_ContourWidth;

    // property ids
    static a2dPropertyIdBool* PROPID_Allowrotation;
    static a2dPropertyIdBool* PROPID_Allowsizing;
    static a2dPropertyIdBool* PROPID_Allowskew;
    static a2dPropertyIdBool* PROPID_IncludeChildren;
    static a2dPropertyIdRefObjectAutoZero* PROPID_Controller;
    static a2dPropertyIdCanvasObject* PROPID_Original;
    static a2dPropertyIdCanvasObject* PROPID_Editcopy;
    static a2dPropertyIdCanvasObject* PROPID_Parent;
    static a2dPropertyIdCanvasObject* PROPID_Objecttip;
    static a2dPropertyIdUint16* PROPID_Editmode;
    static a2dPropertyIdUint16* PROPID_Editstyle;
    static a2dPropertyIdUint16* PROPID_Index;
    static a2dPropertyIdCanvasShadowStyle* PROPID_Shadowstyle;
    static a2dPropertyIdFill* PROPID_Fill;
    static a2dPropertyIdStroke* PROPID_Stroke;
    static a2dPropertyIdInt32* PROPID_UpdateImmediatePriority;
    static a2dPropertyIdUint32* PROPID_RefDesCount;
    static a2dPropertyIdUint32* PROPID_RefDesNr;

    //! set for objects that act as tool decorations, when a tool is in action.
    static a2dPropertyIdBool* PROPID_ToolDecoration;

    //! set for objects that act as tool object, when a tool is in action.
    static a2dPropertyIdVoidPtr* PROPID_ToolObject;

    //! set for objects that do not have to be saved 
    static a2dPropertyIdBool* PROPID_TemporaryObject;

    //! used to store state ( redraw area) of the object as it was before a change
    static a2dPropertyIdBoundingBox* PROPID_BoundingBox;

    static a2dPropertyIdColour* PROPID_StrokeColour;
    static a2dPropertyIdColour* PROPID_FillColour;

    //! when an object should only be rendered in the view pointed to by this property.
    //! This is tipically used when using tool object.
    static a2dPropertyIdRefObject* PROPID_ViewSpecific;

    //! set in Startedit(), to be used to detect first (mouse)event sent to object. 
    static a2dPropertyIdBool* PROPID_FirstEventInObject;

    //! used in GDSII and KEY format to specify the DATATYPE of elements
    /*! GDSII compatible to sub identify this object.
        you can use it as a special tagged object 
    */
    static a2dPropertyIdUint16* PROPID_Datatype;

    //! used for objects that depend on 'aView' view when it comes to size. 
    static a2dPropertyIdRefObject* PROPID_ViewDependent;
    //! used for objects with* PROPID_viewDependent but only for internal area
    static a2dPropertyIdMatrix* PROPID_IntViewDependTransform;

    //! when an object is removed from a layer, 
    const static wxEventType sm_changedLayer;

    //! some time property which a user wants to store
    static a2dPropertyIdDateTime* PROPID_DateTime;

    static a2dPropertyIdDateTime* PROPID_ModificationDateTime;

    static a2dPropertyIdDateTime* PROPID_AccessDateTime;

    //! when set used for popup menu by default in OnPopUpEvent()
    static a2dPropertyIdMenu* PROPID_PopupMenu;

    //! when set used for tip window by default in OnCanvasMouseEvent()
    static a2dPropertyIdWindow* PROPID_TipWindow;

    DECLARE_PROPERTIES()

private:
    //!this is a not implemented copy constructor that avoids automatic creation of one
    a2dCanvasObject( const a2dCanvasObject &other );
};


bool operator < (const a2dCanvasObjectPtr& a, const a2dCanvasObjectPtr& b);

typedef bool (*a2dCanvasObjectSorter) ( const a2dCanvasObjectPtr& x, const a2dCanvasObjectPtr& y);
A2DCANVASDLLEXP extern a2dCanvasObjectSorter s_a2dCanvasObjectSorter;

#ifdef _DEBUG
// Here are two globals that can be used as registers in the debugger
extern a2dCanvasObject *_dbco1;
extern a2dCanvasObject *_dbco2;
#endif



//! class use by a2dIterC to filter objects for rendering.
/*!
    From a2dCanvasDocument render cycles for the document are initiated.
    An iteration context is set up, and this context can have an object filter set,
    only a2dCanvasObject objects that return true, will be rendered. 

    The idea is to derived from this class, and defined your own Filter()

    This object can contain dynamic properties which can be used for filtering.
    It is also refcounted for use with smart pointers.  
*/
class A2DCANVASDLLEXP a2dCanvasObjectFilter : public a2dPropObject
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilter() {};

    ~a2dCanvasObjectFilter() {};

    //! called from a2dCanvasObject to filter objects for rendering
    virtual bool Filter( a2dIterC& WXUNUSED(ic), a2dCanvasObject* WXUNUSED(canvasObject) ) { return true; }

    //! called from a2dCanvasObject to reset filtering feature when filtered object goes out of context.
    virtual void EndFilter( a2dIterC& WXUNUSED(ic), a2dCanvasObject* WXUNUSED(canvasObject) ) {}
};

#if defined(WXART2D_USINGDLL)
template class A2DCANVASDLLEXP a2dSmrtPtr<a2dCanvasObjectFilter>;

#endif 

//! filter on this layer and mask.
class A2DCANVASDLLEXP a2dCanvasObjectFilterLayerMask : public a2dCanvasObjectFilter 
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterLayerMask( wxUint16 layer, a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL, a2dCanvasObjectFlagsMask antimask = a2dCanvasOFlags::NON ) 
    {
        m_layer = layer;
        m_mask = mask;
        m_antimask = antimask;
    }

    ~a2dCanvasObjectFilterLayerMask() {}

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

protected:

    wxUint16 m_layer;
    a2dCanvasObjectFlagsMask m_mask; 
    a2dCanvasObjectFlagsMask m_antimask; 
};

//! objects with m_editingcopy or m_toolobject are skipped.
class A2DCANVASDLLEXP a2dCanvasObjectFilterLayerMaskNoToolNoEdit : public a2dCanvasObjectFilterLayerMask
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterLayerMaskNoToolNoEdit( wxUint16 layer, a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL, a2dCanvasObjectFlagsMask antimask = a2dCanvasOFlags::NON ) 
        : a2dCanvasObjectFilterLayerMask( layer, mask, antimask )
    {
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

};

//! object not fitting the mask are drawn blind.
class A2DCANVASDLLEXP a2dCanvasObjectFilterOnlyNoMaskBlind : public a2dCanvasObjectFilter
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterOnlyNoMaskBlind( a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL ) 
        : a2dCanvasObjectFilter()
    {
        m_mask = mask;
        m_maskedCanvasObject = 0;
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

protected:

    a2dCanvasObjectFlagsMask m_mask; 
    a2dCanvasObjectPtr m_maskedCanvasObject;
};

//! objects not fitting the property are not drawn, inclusif its children.
/*!
     Mask is still checked for objects with that property and its children
     The drawing is only enabled by the filter, the top in a2dCanvasDocument sets it off at start. 
*/
class A2DCANVASDLLEXP a2dCanvasObjectFilterPropertyNoMaskBlind : public a2dCanvasObjectFilterOnlyNoMaskBlind
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterPropertyNoMaskBlind( const a2dPropertyId *id, a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL ) 
        : a2dCanvasObjectFilterOnlyNoMaskBlind( mask )
    {
        m_id = id;
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

protected:

     const a2dPropertyId *m_id;
};

//! filter for selected a2dCanvasObject's
/*!
 
*/
class A2DCANVASDLLEXP a2dCanvasObjectFilterSelected : public a2dCanvasObjectFilterOnlyNoMaskBlind
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterSelected( a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL ) 
        : a2dCanvasObjectFilterOnlyNoMaskBlind( mask )
    {
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

protected:
};

//! filter for selected a2dCanvasObject's
/*!
 
*/
class A2DCANVASDLLEXP a2dCanvasObjectFilterHighLighted : public a2dCanvasObjectFilterOnlyNoMaskBlind
{
public:

    //! 
    /*!
    */
    a2dCanvasObjectFilterHighLighted( a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL ) 
        : a2dCanvasObjectFilterOnlyNoMaskBlind( mask )
    {
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

protected:
};

//! filter for tool related a2dCanvasObject's
/*!
 
*/
class A2DCANVASDLLEXP a2dCanvasObjectFilterToolObjects : public a2dCanvasObjectFilterOnlyNoMaskBlind
{
public:

    //!constructor 
    /*!
    */
    a2dCanvasObjectFilterToolObjects( const a2dPropertyId *id, a2dCanvasObjectFlagsMask mask = a2dCanvasOFlags::ALL ) 
        : a2dCanvasObjectFilterOnlyNoMaskBlind( mask )
    {
        m_id = id;
    }

    virtual bool Filter( a2dIterC& ic, a2dCanvasObject* canvasObject ); 

    virtual void EndFilter( a2dIterC& ic, a2dCanvasObject* canvasObject );

protected:

     const a2dPropertyId *m_id;
};

//! An object of this class will update a a2dIterC with the required information
/*! As iteration goes down the child hierarchy, a a2dIterCU is created to
    update a a2dIterC. It will update the parent list as well as the matrix

Assume the following object tree

\verbatim
     A
   /   \
  B     C
 / \   / \
D   E F   G
\endverbatim

  The constructors / destructors are called in the following order, and the values
of GetParent and GetPreviousSibling, GetPreviousOrParent and GetPreviousDeep are shown
(time is going from left to right):

\verbatim
Const:    A   B   D       E           C   F       G   
Destr:                D       E   B           F       G   C   A

Parent: X   0   A   B   A   B   A   0   A   C   A   C   A   0   X

PrevSi: X   0   0   0   0   D   0   0   B   0   B   F   B   0   X

PrevOP: X   0   A   B   A   D   A   0   B   C   B   F   B   0   X

PrevD:  X   0   0   0   D   D   E   B   B   B   F   F   G   C   A

Stack:  -   A   A   A   A   A   A   A   A   A   A   A   A   A   -
        -   -   B   B   B   B   B   -   C   C   C   C   C   -   -
        -   -   -   D   -   E   -   -   -   F   -   G   -   -   -

\endverbatim

\see a2dIterC
*/
class A2DCANVASDLLEXP a2dIterCU 
{
    friend class a2dIterC;
public:
    //! Update iteration context
    /*! Create an object of this type locally in a a2dCanvasObject child tree
        iteration function at each recusion level. This will update the iteration
        context and restore it later
    */
    a2dIterCU( a2dIterC &ic, a2dCanvasObject *object, OVERLAP clip = _IN );

    //! construction of intitial 
    a2dIterCU( a2dIterC &ic, const a2dAffineMatrix& matrix = a2dIDENTITY_MATRIX, OVERLAP clip = _IN );

    //! copy constructor
    a2dIterCU( const a2dIterCU& cu );

    //! Restore the iteration context
    ~a2dIterCU();

    //! Get the current object
    a2dCanvasObject *GetObject() { return m_object; }

    //! get the parent of this instance of a2dIterCU
    a2dIterCU* GetParent() { return m_parent; }

    //! Get the accumulated transforms up to and including m_object->m_lworld
    const a2dAffineMatrix &GetTransform() { return m_relativetransform; }

    //! Get the accumulated transforms up to and including m_object->m_lworld
    const a2dAffineMatrix &GetInverseTransform() { return m_inverseRelativetransform; }

private:
    //! the canvas object at the current level of iteration
    a2dCanvasObject *m_object;

    //! the previous direct child object of m_object (used for GetPreviousSameLevel)
    a2dCanvasObject *m_previous;

    //! the context update of the parent
    a2dIterCU *m_parent;
    
    //! the accumulated transforms up to and including m_object->m_lworld
    a2dAffineMatrix m_relativetransform;
    
    //! inverse of m_relativetransform
    a2dAffineMatrix m_inverseRelativetransform;

    //! the correpsonding iteration context
    a2dIterC *m_iterC;

    //! indicates type of constructor used.
    bool m_objectLevel;

    //! how far this object in the view being rendered
    OVERLAP m_clip;
};


//! mask flags for a2dIterC
/*!
    \ingroup canvasobject
*/
typedef unsigned int wxIterCFlagsMask ;

//! while iterating a a2dCanvasDocument, this holds the context. 
/*!
    The context is a collection of information, which might be needed when 
    traversing the document.
    e.g. Transforms for drawing and conversion to absolute coordinates are stored here.

    Specific information in the context can be valid or not.
    If the information is set and is valid, a flag is set too.
    This flag is checked when information is asked for. Asking for non valid information
    will result in an assert.
*/
class A2DCANVASDLLEXP a2dIterC
{
    friend class a2dIterCU;
    friend class a2dCorridor;

public:

    //! constructor used when drawer is not known
    a2dIterC();

    //! constructor used when drawer is known ( usually the case )
    /*!
        \param drawer the drawer that is currently in use.
        \param level how deep is the starting object to render from the ShowObject of the a2dCanvasView.
    */
    a2dIterC( a2dCanvasView* drawer, int level = 0 );

    //! destructor
    ~a2dIterC();

    //! when true, disable inversion of matrixes
    /*!
        e.g. when rendering a document the inverted matrix is not needed, so we disable the calculation to gain speed.
    */
    void SetDisableInvert( bool disableInvert ) { m_disableInvert = disableInvert; }

    //! see SetDisableInvert()
    inline bool GetDisableInvert() { return m_disableInvert; }

    //! Reset this object for beeing reused. It will keep the drawer but NULL object infos
    void Reset();

    //! used to extend a hittest with the number of pixels.
    /*! to be able to hit a line of width zero, a margin is needed to hit it,
        which is set here.
        In fact this value is directly converted to a value in world coordinates, 
        using the current GetDrawer2D(). GetHitMarginWorld() returns this value.

        \remark default value is taken from a2dCanvasView or a2dCanvasGlobal
    */
    void SetHitMarginDevice( int pixels );

    //! used to extend a hittest with the given margin in world coordinates.
    /*! to be able to hit a line of width zero, a margin is needed to hit it,
        which is set here.

        \remark default value is taken from a2dCanvasGlobal::GetHitMarginWorld
    */
    void SetHitMarginWorld( double world );

    //! Get HitMargin in World units.
    double GetHitMarginWorld();

    //! Transform a pixel extend from device to world units
    /*! If no drawer is there (e.g. command procesing) the return value will be zero */
    double ExtendDeviceToWorld( int extend );

    //! transformed to object its coordinate system
    double GetTransformedHitMargin();

    //! get the layer that is to be rendered
    inline wxUint16 GetLayer() { return m_layer; }

    //! set the layer that is to be rendered
    /*!
        wxLAYER_ALL has the special meaning that it renderers all layers at once.
    */
    void SetLayer( wxUint16 layer ) { m_layer = layer; }

    //! get setting for command generation or not.
    inline bool GetGenerateCommands() { return m_generateCommands; }

    //! set to generate command or not in certain situations.
    /*!
    */
    void SetGenerateCommands( bool generateCommands ) { m_generateCommands = generateCommands; }

    //!get the mapping matrix
    const a2dAffineMatrix& GetMappingTransform() const;

    //! get matrix which transforms directly from relative world coordinates to device 
    const a2dAffineMatrix& GetUserToDeviceTransform() const; 

    //! get current a2dCanvasView 
    a2dCanvasView* GetCanvasView() const;

    //! get current a2dDrawer2D 
    a2dDrawer2D* GetDrawer2D() const;

    //!set drawstyle used for rendering the document
    /*!
        The drawstyle is set in a2dCanvasDocument when rendering parts of the document.
        
        \param drawstyle one of the draw styles
    */
    void SetDrawStyle( a2dDocumentRenderStyle drawstyle ) { m_drawstyle = drawstyle; }

    //!get drawstyles used for drawing the document
    a2dDocumentRenderStyle GetDrawStyle() { return m_drawstyle; }

    //! when traversing tree this the object one level higher.
    /*!
        Used internal during rendering etc.
        During recursive traversing a a2dCanvasDocument from top group that is displayed
        this holds the a2dCanvasObject that is one level higher in the branch that is traversed
        used during rendering etc., to know what is the parent object in a branch that is being rendered
    */
    a2dCanvasObject* GetParent();

    //! the object where the iterative context is currently
    a2dCanvasObject* GetObject();

    //! Get the last object, for which the recursive function was called
    a2dCanvasObject* GetPreviousDeep();

    //! Get the last sibling, for which the recursive function was called
    a2dCanvasObject* GetPreviousSibling();

    //! Like GetPreviousSibling, but returns the Parent if PreviousSibling is 0
    a2dCanvasObject* GetPreviousOrParent();

    //! Get the accumulated transform up to and including m_lworld of the current object
    /*! This converts from relative local coordinates of the current object to world coordinates.
        This matrix transforms all drawing primitives used to draw a a2dCanvasObject from relative
        world coordinates to absolute world coordinates.
    */
    const a2dAffineMatrix& GetTransform() const;

    //! Inverse of GetTransform()
    const a2dAffineMatrix& GetInverseTransform() const; 

    //! Get the accumulated transform up to but NOT including m_lworld of the current obejct
    /*! This converts from local coordinates of the curent object to world coordinates
        !!!! I am not sure if it should contains the view transform (world->device) as well !!!!
    */
    const a2dAffineMatrix& GetParentTransform() const;

    //! inverse of GetParentTransform()
    const a2dAffineMatrix& GetInverseParentTransform() const;

    //! number of levels deep we are inside a document as seen from the m_top
    int GetLevel() const { return m_levels; }

    //! to set corridor path ( also to captured object), its a2dCanvasOFlags::IsOnCorridorPath flag is set on or off.
    /*!
        The iteration context knows its parent object via its m_bottom and m_parent a2dIterCU.
        Each a2dIterCU added when going deeper into the drawing hierarchy, knows from which object it came.
        This way, it is possible to iterate back to the top/show object in a a2dCanvasView.
        All canvasobjects passed that way is called the event path.
        Of course when going up in hierarchy, the event path is becoming smaller again. And when arriving at the top
        it will be zero.
        To preserve the event path to a specific canvas object, a flag can be set along the canvas objects in
        the current event path. Those flags will be kept intact inside the canvasobjects, even if the event path
        is changing after setting the flags.           
        The a2dCanvasOFlags::IsOnCorridorPath set this way, is/can be used to find and redirect events to the 
        objects along or at the end of this path. The path created like this is called the Corridor path.

        When capturing an object, the corridor is used to redirect events to that object, even
        if the object is a deeper nested child. A non captured corridor also redirects 
        events to the last object in the corridor, but still does normal event processing
        from that point on. So only a positive hittest will really make the event go to the object.
        When also capturing the object at the end of a corridor, the mouse event is always going to that object,
        even if it does not hit it.

        \param OnOff to set the corridor path on or off.
        \param captureObject to set this as a captured object at the end of the corridor, if NULL non is captured.
    */
    void SetCorridorPath( bool OnOff, a2dCanvasObject* captureObject = NULL );

    /* set corridor path to parent of current iteration context */
    void SetCorridorPathToParent();

    //! leaves corridorpath as is, but resets the capture object at the end of the corridor to
    //! the given object. If NULL, the corridor is set to non captured.
    void SetCorridorPathCaptureObject( a2dCanvasObject* captureObject );

    //! when there is a corridor path set, this return if end has bin found while iterating.
    bool GetFoundCorridorEnd() { return m_foundCorridorEnd; }

    //! when there is a corridorPath set, this is used internal to set this flag to indicate that the end of it was found.
    void SetFoundCorridorEnd( bool foundCorridorEnd ) { m_foundCorridorEnd = foundCorridorEnd; }

    //! Set strokeworld extend of last added object, used in a2dCanvasObject::DoIsHitWorld()
    /*!
        Holds the size/width of the Stroke in world coordinates, else 0. 
        This can be used in derived a2dCanvasObject to do a proper hittest. 
        If the stroke is of type pixel, that value will be converted into world coordinates.
    */
    void SetStrokeWorldExtend( double worldStrokeExtend ) { m_worldStrokeExtend = worldStrokeExtend; }

    //! \see SetWorldStrokeExtend()
    double GetWorldStrokeExtend() { return m_worldStrokeExtend; }

    //! what is the clipping withing the current view for the last added object in context
    OVERLAP GetClipStatus() const;

    //! what is the clipping withing the current view for the second last added object in context
    OVERLAP GetParentClipStatus() const;

    //! set the clipping withing the current view for the last added object in context
    void SetClipStatus( OVERLAP status );

    //! get the filter set for the iteration context.
    a2dCanvasObjectFilter* GetObjectFilter() { return m_objectFilter; }

    //! set object filter class.
    void SetObjectFilter( a2dCanvasObjectFilter* filter ) { m_objectFilter = filter; }

    //! apply object filter 
    bool FilterObject( a2dCanvasObject* canvasObject ); 

    //! called when filter ends
    void EndFilterObject( a2dCanvasObject* canvasObject ); 

    //! if set the rendering is done layers by layer from the top
    void SetPerLayerMode( bool value ) { m_perLayerMode = value; }

    //! if set the rendering is done layers by layer from the top
    bool GetPerLayerMode() { return m_perLayerMode; }

    //! when set child object in derived a2dCanvasObject are rendered, else only the object itself.
    void SetRenderChildDerived( bool value ) { m_renderChildDerived = value; }

    //! when set child object in derived a2dCanvasObject are rendered, else only the object itself.
    bool GetRenderChildDerived() { return m_renderChildDerived; }

    //! set during event processing down the hierarchy, to the deepest object that was hit
    void SetDeepestHit( a2dCanvasObject* canvasObject ) { m_deepestHit = canvasObject; }

    //! get deepest object that was hit during event processing down the hierarchy.
    a2dCanvasObject* GetDeepestHit() const { return m_deepestHit; } 

private:

    //! if true no inversion on matrixes is done.
    bool m_disableInvert;

    //!world to device coordinate mapping
    a2dAffineMatrix m_mapping;

    //!relative world to device transform matrix ( so includes mapping matrix )
    a2dAffineMatrix m_usertodevice;

    //! when traversing a group within a tree this points to the previous object that was traverersed
    /*! 
        Used for GetPreviousDeep
        Used internal during rendering etc.
        This is set in the destructor of a2dIterCU, so it is always the object, for which the
        correspsonding recursive function was left last.
    */
    a2dSmrtPtr<a2dCanvasObject> m_previous;

    //! during event processing down the hierarchy, this is set to deepest object hit.
    a2dSmrtPtr<a2dCanvasObject> m_deepestHit;

    //! from which a2dCanvasView the iteration started.
    a2dSmrtPtr<a2dCanvasView> m_drawer;

    //! how close in pixles does a hit need to be to the object you are trying to hit.
    /*! this is in world units */
    double m_hitmargin_world;

    //! The top of the list of context update objects.
    a2dIterCU *m_top;

    //! The bottom of the list of context update objects.
    a2dIterCU *m_bottom;

    //! How much child levels deep are we, seen from the ShowObject of the a2dCanvasView.
    int m_levels;

    //! when there is a corridorPath set, this is set when end is found.
    bool m_foundCorridorEnd;

    //! \see SetWorldExtend()
    double m_worldStrokeExtend;

    //! drawstyles used to render document
    a2dDocumentRenderStyle m_drawstyle;

    //! for filtering objects when e.g. rendering 
    a2dSmrtPtr<a2dCanvasObjectFilter> m_objectFilter;

    //! the layer that is currently rendered.
    wxUint16 m_layer;

    //! see SetGenerateCommands()
    bool m_generateCommands;

    bool m_ownDrawer;

    //! if set the rendering is done layers by layer from the top
    bool m_perLayerMode;

    //! when set child object in derived a2dCanvasObject are rendered, else only the object itself.
    bool m_renderChildDerived;

};

#endif    // WXCANOBJ

canobj.h Source File -- Tue Aug 31 17:56:21 2010 -- 31 Aug 2010 -- 1.5.5 -- wxArt2D -- . -- Reference Documentation