jpicedt.graphic.model
Interface Element

All Known Subinterfaces:

CustomizerFactory, NodeableElement, PicMultiCurveConvertable

All Known Implementing Classes:

AbstractCurve, AbstractElement, BranchElement, DefaultSelectionHandler, Drawing.BoundingBox, Drawing.RootElement, PicCircleFrom3Points, PicEllipse, PicGroup, PicMultiCurve, PicNodeConnection, PicParallelogram, PicPsCurve, PicSmoothPolygon, PicText, TextEditable

public interface Element

This interface specifies the general contract for models of graphic elements that may be added to a Drawing.

A MODEL of graphic element basically comprises :

• A set of (possibly virtual, see implementation hints below) user-controlled points that helps the "user" alter the geometry of the element ; these points are made accessible by means of the various get/setCtrlPt() methods, using an index ranging from getFirstPointIndex() to getLastPointIndex() inclusive. These methods may be used e.g. by the UI machinery when processing mouse-events, or by parsers when building a new Drawing from scratch.
• Amid this set, some points may serve as anchor-points for grid alignment (see PointIterator).
• An attribute set that allows binding the element's geometry to a set of colour, stroke, etc… attributes.
• A parent and possibly children once the element has been added to a tree defining a Drawing's model. This allows us to let the root element only hold state about the tree while still maintaining the ability for a child to retrieve this state at any time through a (possibly recursive) call to getParent.
• Besides, each Element may have a View attached to it (but this is not necessary as long as it has not to be rendered), which is responsible for rendering the element to a graphic context. View's are usually created by a ViewFactory that's suited for the kind of content the model represents (e.g. PostScript, LaTeX, JPIC-XML, …).

Implementation hints : under the hood, the geometry may be backed e.g. by an array of points (in which case these may be the control-points as well), by a java.awt.Shape, or by any other kind of mechanism the developper thinks is appropriate to the particular model she wants to implement.

Since:

PicEdt 1.0

Version:

$Id: Element.java,v 1.25 2013/03/27 07:02:38 vincentb1 Exp $

Author:

Sylvain Reynal

Method Summary

PointIndexIterator	anchorPointsIterator() Return an Iterator over user-controlled point indexes that can for instance serve as anchor points for grid alignment.
Element	clone() Return a deep copy of this element.
Shape	createShape() Creates a Shape that reflects the geometry of this model.
<T> T	getAttribute(PicAttributeName<T> name) Return the value for the given attribute name
PicAttributeSet	getAttributeSet() Returns the AttributeSet for this Element
Rectangle2D	getBoundingBox(Rectangle2D r)
PicPoint	getCtrlPt(int index, PicPoint dest) Return the user-controlled point having the given index.
CtrlPtSubset	getCtrlPtSubset(ConvexZoneGroup csg, BitSet czExtension) Renvoie un la partie des points de contrôle qui satisfont à l'un des deux critères suivants: ceux compris dans l'ensemble de zones convexes csg, et ceux en relation avec les points de contrôle satisfaisant au première critère selon une relation définies par czExtension
Drawing	getDrawing() Retrieves the underlying drawing
int	getFirstPointIndex() Return the index of the first user-controlled point that can be retrieved by getCtrlPt()
int	getLastPointIndex() Return the index of the last user-controlled point that can be retrieved by getCtrlPt()
String	getName() Return a non-localised string representing this element's name.
BranchElement	getParent() Gets the parent of the element.
View	getView()
void	mirror(PicPoint ptOrg, PicVector normalVector) Effectue une réflexion de l'objet this relativement à la droite passant par le point ptOrg et normale au vecteur normalVector.
void	removeView() remove the view that render this element ; this may be used to remove any reference to the view, and render it eligible for garbage collection ; if no View, does nothing.
void	replaceBy(Element by, boolean replaceInSelection) La méthode replaceBy remplace dans le dessin l'élément this par l'élément by.
void	rotate(PicPoint ptOrg, double angle) Rotate this Element by the given angle along the given point
void	scale(double ptOrgX, double ptOrgY, double sx, double sy) Scale this object by (sx,sy) using (ptOrgX,ptOrgY) as origin sx and sy can be negative.
void	scale(double ptOrgX, double ptOrgY, double sx, double sy, UserConfirmationCache ucc) Pareil que scale(double ptOrgX, double ptOrgY, double sx, double sy) sauf que dans le cas d'une dilatation non conforme — c'est à dire ne conservant pas les proportions —, et d'une forme supposée à proportions contraintes (comme par exemple PicCircleFrom3Points) on demande, sauf préférences utilisateurs contraires, son avis à l'utilisateur.
void	scale(PicPoint ptOrg, double sx, double sy) Scale this object by (sx,sy) using ptOrg as origin sx and sy may be negative.
void	scale(PicPoint ptOrg, double sx, double sy, UserConfirmationCache ucc)
<T> void	setAttribute(PicAttributeName<T> name, T value) Sets the given attribute name to the given value for this Element
void	setAttributeSet(PicAttributeSet attributeSet) Sets a new AttributeSet for this Element ; this actually make a deep copy of the given attribute set beforehands.
void	setCtrlPt(int index, PicPoint pt) Set the user-controlled point indexed by "index" to the given value.
void	setCtrlPt(int index, PicPoint pt, EditPointConstraint constraint) Set the user-controlled point indexed by "index" to the given value, using the specified geometrical constraint.
void	setParent(BranchElement p) Sets the parent of the element.
void	setViewFromFactory(ViewFactory f) set the view for this Element from the given view factory
void	shear(PicPoint ptOrg, double shx, double shy) Shear this Element by the given params wrt to the given origin
void	shear(PicPoint ptOrg, double shx, double shy, UserConfirmationCache ucc) Pareil que shear(PicPoint ptOrg, double shx, double shy) sauf que dans le cas d'une dilatation non conforme — c'est à dire ne conservant pas les proportions —, et d'une forme supposée à proportions contraintes (comme par exemple PicCircleFrom3Points) on demande, sauf préférences utilisateurs contraires, son avis à l'utilisateur.
void	syncArrowGeometry(ArrowView v, ArrowView.Direction d) Helper for the associated View.
void	translate(double dx, double dy) Translate this object by (dx,dy)

Method Detail

getName

String getName()

Return a non-localised string representing this element's name. This may be used by a UI to display some information related to this element, or by a localizer to fetch a i18n'd string.

clone

Element clone()

Return a deep copy of this element.

getDrawing

Drawing getDrawing()

Retrieves the underlying drawing

Returns:

the drawing ; null if this Element doesn't belong to any drawing yet.

getParent

BranchElement getParent()

Gets the parent of the element.

Returns:

the parent

replaceBy

void replaceBy(Element by,
               boolean replaceInSelection)

La méthode replaceBy remplace dans le dessin l'élément this par l'élément by. Sans effet si this.getParent() renvoie null. Si replaceInSelection est true et que this est dans la sélection, alors il est également remplacé par by dans la sélection.

Parameters:

by - l'Element servant de remplacement.

replaceInSelection - indique que this est également à remplacer dans la selection.

setParent

void setParent(BranchElement p)

Sets the parent of the element.

getCtrlPt

PicPoint getCtrlPt(int index,
                   PicPoint dest)

Return the user-controlled point having the given index. The general contract is to return an IMMUTABLE instance of PicPoint, so that the only way to alter the geometry of this element is by calling the setPoint method.

Parameters:

index - the point index, should be greater or equal to the value returned by getFirstPointIndex, and lower or equal to getLastPointIndex.

Returns:

the point indexed by index ; if dest is null, concrete implementation of this method should allocate a new PicPoint and return it, otherwise directly modify dest and return it as well for convenience.

Since:

PicEdt 1.0 [todo] change name to getControlPoint() or getUserPoint() or whatever seems more appropriate.

getFirstPointIndex

int getFirstPointIndex()

Return the index of the first user-controlled point that can be retrieved by getCtrlPt()

getLastPointIndex

int getLastPointIndex()

Return the index of the last user-controlled point that can be retrieved by getCtrlPt()

setCtrlPt

void setCtrlPt(int index,
               PicPoint pt)

Set the user-controlled point indexed by "index" to the given value. This should be a convenience call to setCtrlPt(index,pt,null), i.e. using no particular geometrical constraint.

setCtrlPt

void setCtrlPt(int index,
               PicPoint pt,
               EditPointConstraint constraint)

Set the user-controlled point indexed by "index" to the given value, using the specified geometrical constraint. Constraints depend on the particular concrete implementation, and may involve restricting movement along a particular direction, moving several points at once to preserve parallelism,…

Parameters:

constraint - a geometry constraint, or null if no particular constraint is being imposed (aka default).

anchorPointsIterator

PointIndexIterator anchorPointsIterator()

Return an Iterator over user-controlled point indexes that can for instance serve as anchor points for grid alignment. This is up to concrete implementations to decide what subset of user-controlled points is most appropriate for grid alignment.

translate

void translate(double dx,
               double dy)

Translate this object by (dx,dy)

Parameters:

dx - The X coordinate of translation vector

dy - The Y coordinate of translation vector

Since:

PicEdt 1.0 [todo] add an "apply(Transform t)" method as replacement to "translate()" and "scale()", where Transform may possibly inherit from java.awt.geom.AffineTransform [syd : 5/8/2002]

getCtrlPtSubset

CtrlPtSubset getCtrlPtSubset(ConvexZoneGroup csg,
                             BitSet czExtension)

Renvoie un la partie des points de contrôle qui satisfont à l'un des deux critères suivants:

1. ceux compris dans l'ensemble de zones convexes csg, et
2. ceux en relation avec les points de contrôle satisfaisant au première critère selon une relation définies par czExtension

Parameters:

csg - un ensemble de zones convexes

czExtension - un BitSet permettant d'étendre l'ensemble des points de contrôle compris dans l'ensemble de zones convexes csg. La signification des bit est selon l'énuméré CtrlPtSubset.CZExtension.

scale

void scale(PicPoint ptOrg,
           double sx,
           double sy)

Scale this object by (sx,sy) using ptOrg as origin sx and sy may be negative. This can be implemented as a convenience call to scale(double,double,double,double)

scale

void scale(double ptOrgX,
           double ptOrgY,
           double sx,
           double sy)

Scale this object by (sx,sy) using (ptOrgX,ptOrgY) as origin sx and sy can be negative.

scale

void scale(double ptOrgX,
           double ptOrgY,
           double sx,
           double sy,
           UserConfirmationCache ucc)

Pareil que scale(double ptOrgX, double ptOrgY, double sx, double sy) sauf que dans le cas d'une dilatation non conforme — c'est à dire ne conservant pas les proportions —, et d'une forme supposée à proportions contraintes (comme par exemple PicCircleFrom3Points) on demande, sauf préférences utilisateurs contraires, son avis à l'utilisateur.

Parameters:

ucc - une valeur UserConfirmationCache permettant de demander à l'utilisateur confirmation, de se souvenir de la dernière confirmation qu'il a donné, ou de ses préférences.

scale

void scale(PicPoint ptOrg,
           double sx,
           double sy,
           UserConfirmationCache ucc)

rotate

void rotate(PicPoint ptOrg,
            double angle)

Rotate this Element by the given angle along the given point

Parameters:

angle - rotation angle in radians

shear

void shear(PicPoint ptOrg,
           double shx,
           double shy)

Shear this Element by the given params wrt to the given origin

shear

void shear(PicPoint ptOrg,
           double shx,
           double shy,
           UserConfirmationCache ucc)

Pareil que shear(PicPoint ptOrg, double shx, double shy) sauf que dans le cas d'une dilatation non conforme — c'est à dire ne conservant pas les proportions —, et d'une forme supposée à proportions contraintes (comme par exemple PicCircleFrom3Points) on demande, sauf préférences utilisateurs contraires, son avis à l'utilisateur.

Parameters:

ucc - une valeur UserConfirmationCache permettant de demander à l'utilisateur confirmation, de se souvenir de la dernière confirmation qu'il a donné, ou de ses préférences.

mirror

void mirror(PicPoint ptOrg,
            PicVector normalVector)

Effectue une réflexion de l'objet this relativement à la droite passant par le point ptOrg et normale au vecteur normalVector. C'est à dire que tout point de contrôle pt est remplacé par: pt - 2 * produit_scalaire(pt - ptOrg, normalVector) Si normalVector n'est pas de norme euclidienne 1, alors mirror fait donc en plus une dilatation de coefficient égal à la norme euclidienne de normalVector.

Parameters:

ptOrg - a PicPoint value

normalVector - a PicVector value

getBoundingBox

Rectangle2D getBoundingBox(Rectangle2D r)

Returns:

the bounding box (i.e. the surrounding rectangle) in double precision Used e.g. to determine the arguments of the \\begin{picture} command. If r is null, allocate a new rectangle and returns it. Otherwise the source rectangle is modified and returned for convenience. [todo:reynal] this really need to be improved : this method would probably better be moved to the attached view, since the latter knows exactly what the TRUE bounding box is.

Since:

PicEdt 1.0

getView

View getView()

Returns:

the View that's responsible for rendering this Element

setViewFromFactory

void setViewFromFactory(ViewFactory f)

set the view for this Element from the given view factory

removeView

void removeView()

remove the view that render this element ; this may be used to remove any reference to the view, and render it eligible for garbage collection ; if no View, does nothing.

createShape

Shape createShape()

Creates a Shape that reflects the geometry of this model.

syncArrowGeometry

void syncArrowGeometry(ArrowView v,
                       ArrowView.Direction d)

Helper for the associated View. Synchronizes the state (aka location and direction) of the given ArrowView with this model, if applicable (the model is indeed the most knowledgeable about these data). Otherwise does nothing, for instance if the associated geometry is closed and does not support arrows.

getAttributeSet

PicAttributeSet getAttributeSet()

Returns the AttributeSet for this Element

setAttributeSet

void setAttributeSet(PicAttributeSet attributeSet)

Sets a new AttributeSet for this Element ; this actually make a deep copy of the given attribute set beforehands.

setAttribute

<T> void setAttribute(PicAttributeName<T> name,
                      T value)

Sets the given attribute name to the given value for this Element

getAttribute

<T> T getAttribute(PicAttributeName<T> name)

Return the value for the given attribute name