AcmCLeader

AcmCLeader

This abstract class is very important for proper symbol behavior. It defines the interface for all possible leader implementations. If a particular symbol class doesn't override the addLeader member function of the AcmSymbol class, then the general symbol leader is used. Otherwise more specialized types of leaders can be used.

There is also a supplementary class called AcmCLeaderNodeIterator.

Setting and Querying General Leader Properties

All leader data are primarily set according to the standard. Those values are used to override the standard setting.

virtual ~AcmCLeader();

virtual void getCoordSystem(AcGePoint3d&, AcGeVector3d&, AcGeVector3d&, AcGeVector3d&) const = 0;

virtual Acm::ErrorStatus setArrowType (Acm::ArrowType type) = 0;

virtual Acm::ArrowType ar 20320n1322u rowType () const = 0;

The setting of this variable to any value will override the standard setting. That means if you change it, subsequent changes of the standard setting will not change the arrowhead of this symbol. To restore this feature you must set kByStandard. If the current implementation of the leader doesn't support changing arrowhead type, it will return the eNotSupported error code when you try to set a different type than kByStandard.

See also "Acm::ArrowType"

virtual Acm::ErrorStatus getLineTypeId (AcDbObjectId& linetypeId) const = 0;

virtual Acm::ErrorStatus setLineTypeId (const AcDbObjectId& linetypeId) = 0;

These functions control the appearance of the leader. It is always standard override if you set any non-null id. If the current leader doesn't support changing the line type; it will return the eNotSupported error code. The general leader doesn't support setting different line type ids.

virtual double symbolScale() const = 0;

Used to get the arrowhead scale of the leader. For that we need to know the actual symbol scale, which controls the arrowhead scale as well.

virtual Acm::ErrorStatus getColor (Adesk::UInt16& color) const = 0;

virtual Acm::ErrorStatus setColor(Adesk::UInt16 v) = 0;

Used to specify the color of the leader. If the get function returns kByStandard, it means the current leader uses the color set by the standard.

Setting and Querying Geometry

virtual AcGePoint3d tipPoint () const = 0;

virtual Acm::ErrorStatus setTipPoint (const AcGePoint3d& newPt) = 0;

The tip is where the leader is connected to the symbol - it is usually the last leader point. The origin is usually where an annotation is attached.

virtual AcGeVector3d landing() const = 0;

virtual Acm::ErrorStatus setLanding (const AcGeVector3d &landing) = 0;

These functions handle landing. The general AcmSymbol leader doesn't provide this functionality, so it will always return eNotImplementedYet if you try to retrieve or set a new landing. Derived classes should override these functions if the landing changes have to be followed by changes to other parts of the leader or symbol.

virtual Acm::ErrorStatus appendPoint (const AcGePoint3d &endPoint) = 0;

virtual Acm::ErrorStatus appendPoints (const AcGePoint3dArray &endPoint) =0;

These functions append a new point to the leader, so that its tip will become the new point. They internally call setTipPoint, which initiates the leaderTipPointChange notification. In cases where multiple points are appended at the same time, notification is called at the end of the appending process.

virtual Acm::ErrorStatus removePoint () = 0;

Checks to determine whether the tip point can be removed, and if so, removes just the tip point of the current leader.

virtual Acm::ErrorStatus getNonDrawingDistance (double& v) const = 0;

virtual Acm::ErrorStatus setNonDrawingDistance (double v) = 0;

Used to specify the distance from the tip point, which is not drawn. The general AcmSymbol leader doesn't provide this functionality, so it will always return eNotImplementedYet if you try to retrieve or set new values. Derived classes should override these functions if the landing changes have to be followed by changes to other parts of the leader or symbol. One example of this is the leader of a balloon.

virtual AcmCLeaderNodeIterator* newNodeIterator() const = 0;

Returns objects for working with the internal leader structure. Using the iterator you can locate the closest node, walk through all node trees and append new leader segments, set geometry reference, trim the tree structure and so on.

Grip Points Support

This object is usually part of a symbol and so we need to have a good way to work with grip points. We need to get all grips and we need to identify their precise order. Grips are usually placed at the node points for general leader implementation. If users want to create their own leader for a symbol, they need to create a new class inherited from the AcmCLeader class. The same method is used for GS markers.

virtual int numOfGripPoints() = 0;

Returns the total number of points directly or indirectly connected to this node. This number can be used to calculate the grip index.

virtual Acad::ErrorStatus getGripPoints(AcGePoint3dArray& gripPoints,

AcDbIntArray& osnapModes,

AcDbIntArray& geomIds) const = 0;

virtual Acad::ErrorStatus moveGripPoints(const AcDbIntArray& indices,

const AcGeVector3d& offset) = 0;

These two member functions are used for working with grip points. Users may be familiar with them from the AcDbEntity interface.

virtual Acad::ErrorStatus getOsnapPoints(AcDb::OsnapMode osnapMode, int gsSelectionMark, const AcGePoint3d& pickPoint, const AcGePoint3d& lastPoint, const AcGeMatrix3d& viewXform, AcGePoint3dArray& snapPoints, AcDbIntArray& geomIds) const = 0;

virtual Acad::ErrorStatus moveStretchPointsAt(const AcDbIntArray& indices, const AcGeVector3d& offset) = 0;

GS Marker Support

This object is usually part of a symbol and so we need to work with its parts - for intersecting, exploding and for other purposes. The GS Marker is set to 1 for the line going from the tip node and then incremented for all lines (connecting two nodes) in the leader tree structure.

All member functions will be overridden only for very special purposes.

virtual int numOfGsMarkers() const = 0;

Returns the total number of lines directly or indirectly connected to this node. This number can be used to calculate GS marker range. This function can be used to check if the incoming GS marker corresponds to any line in the leader. If the symbol has more than one leader, the next one will start with the last GS marker increased by one. Then for the first one this member function will return Adesk::kFalse. Then the number of markers in the first leader will decrease the marker value and the member function will be called for next leader. This calculation is the responsibility of the container class - a symbol implementation.

virtual Acm::ErrorStatus getSegFromGSMarker(int marker, AcmCAuxEntity*&) const = 0;

Geometry Reference Support

There are two levels of geometry reference support - the general leader level and the detailed node level. The general leader level will take place if there is just one geometry reference and if it is just the general symbol leader. If users want specific behavior here, they need to create their own leaders and override this member function.

virtual Acm::ErrorStatus attachGeomRef(const void* pGeometry,

const AcDbObjectId& view,

const AcGePoint3d& prevLocation ,

Adesk::Boolean hasReactor = Adesk::kFalse) = 0;

virtual Acm::ErrorStatus attachGeomRef(const void* pGeometry,

const AcGePoint3d& prevLocation ,

Adesk::Boolean hasReactor = Adesk::kFalse) = 0;

These functions create a geometry reference for the leader arrowhead and change its position to the newArrowHeadLocation point. The geometry reference is associated with the drawing view. All necessary notifications are going from that view.

If other geometry is already attached to the leader, these functions will return eGeometryAlreadyAttached. If there is more than one arrowhead, it will return eMultipleArrowheads. If any of these situations occur, callers must use AcmCLeaderNodeIterator.

The second function is used to attach the leader in the model space.

virtual Acm::ErrorStatus detachGeomRef() = 0;

Detaches all geometry references. If the leader contains more than one geometry reference and you want to remove only some of them, they must use the AcmCLeaderNodeIterator member function.

virtual void releaseGeomRef() = 0;

AcmCLeaderNodeIterator

This abstract class is very important for specialized leader operations. It allows you to walk through any possible leader implementations and simplify the interface. If users create their own leader implementations, they might want to create their own version of the node iterator as well.

virtual ~AcmCLeaderNodeIterator();

Walking Through

virtual void start(Adesk::Boolean only leafNodes = Adesk::kFalse) = 0;

The leafNodes parameter indicates whether you're interested just in leaf nodes. In this case you cannot add a new node, but you can remove a node.

virtual void step( Adesk::Boolean backwards = Adesk::kFalse) = 0;

The backwards parameter indicates whether to step backward or forward.

virtual Adesk::Boolean done() const = 0;

Indicates all nodes have been walked through. If you want to go once more, you must call start again.

virtual Adesk::Boolean parent() = 0;

Finding Node

virtual Acm::ErrorStatus find(const AcGePoint3d& pt, bool fromTipPoint = true)=0;

Finds the node with vertex that is the same as the one specified. Uses the system tolerance value when comparing values.

virtual Acm::ErrorStatus findClosest(const AcGePoint3d& pt)=0;

Finds the node that is closest to the specified point in the leader's plane. If the point doesn't lie in leader's plane, it is transformed first. If two nodes have the same distance, then the node closest to the tip point is used. Uses the system's tolerance value when comparing points.

virtual Acm::ErrorStatus findByGrip(int indice)=0;

Finds the node using its grip index. The tip usually has the first one.

Setting and Querying Node

virtual int numOfBranches() const = 0;

Returns the number of branches. Branches are segments connected to current vertex.

virtual AcmCLeaderNodeIterator* newNodeIterator(int segment) const = 0;

Creates the leader iterator, which will iterate through the leader segment connected to this node.

virtual Acm::ErrorStatus addLeader(const AcGePoint3dArray &ptrArray);

Creates a new leader segment connected to the current node using the supplied points. If this function is not overloaded, it will create just a simple leader, which doesn't support landing and whose first segment is drawn up to the tip point.

virtual Acm::ErrorStatus removeLeader();

Removes the leader connected to the node. If the leader doesn't exist, the function returns eInvalidInput.

virtual Acm::ErrorStatus insertBefore(const AcGePoint3d &pt) = 0;

Inserts the node before the current node. If the node is the tip, then the setTipPoint member function of the leader is called.

virtual Acm::ErrorStatus remove() = 0;

Removes the current node from the node structure.

virtual Acm::ErrorStatus trim() = 0;

Trims all connected nodes and makes the current node a leaf node.

virtual Adesk::Boolean isLeafNode() = 0;

Trims all connected nodes and makes the current node a leaf node.

virtual AcGePoint3d vertex() = 0;

virtual Acm::ErrorStatus setVertex(AcGePoint3d& newPoint) =0;

Returns and sets the node's point.

Geometry Reference Support

virtual Adesk::Boolean isAttachedToView(AcDbObjectId& viewId) const = 0;

virtual Adesk::Boolean isAttachedNoView() const = 0;

Returns status information about current attachments. If it is called for a non-leaf node, it will return an error code.

virtual AcDbObjectId viewId() const = 0;

Returns the id of the view the node is associated to.

virtual Acm::ErrorStatus attachGeomRef(const AcRfGeom* pGeometry,

const AcDbObjectId& view,

const AcGePoint3d& prevLocation,

Adesk::Boolean hasReactor = Adesk::kFalse) = 0;

virtual Acm::ErrorStatus attachGeomRef(const AcRfGeom* pGeometry,

const AcGePoint3d& prevLocation,

Adesk::Boolean hasReactor = Adesk::kFalse) = 0;

These functions create a geometry reference. The iterator must be positioned at a leaf node and there must not be a geometry reference already attached. If another geometry reference is already attached, these functions will return eGeometryAlreadyAttached. The second version of the member function is used to attach the node in model space.

virtual Acm::ErrorStatus detachGeomRef() = 0;

Detaches all geometry references. The iterator must be positioned at a leaf node (eInvalidContext) and there must be a geometry reference already attached (eNoGeometryReference).

virtual void releaseGeomRef() = 0;