* {@code Figure} provides the following functionality: *
Framework
* The following interfaces define the contracts of a framework for structured
* drawing editors:
* Contract: {@link Drawing}, {@link Figure}, {@link DrawingView},
* {@link DrawingEditor}, {@link org.jhotdraw.draw.handle.Handle} and
* {@link org.jhotdraw.draw.tool.Tool}.
*
*
Composite
* Composite figures can be composed of other figures.
* Component: {@link Figure}; Composite: {@link CompositeFigure}.
*
*
Framework
* Two figures can be connected using a connection figure. The location of
* the start or end point of the connection is handled by a connector object
* at each connected figure.
* Contract: {@link org.jhotdraw.draw.Figure},
* {@link ConnectionFigure},
* {@link org.jhotdraw.draw.connector.Connector}.
*
*
Decorator
* Decorated figures can be adorned with another figure.
* Component: {@link DecoratedFigure}; Decorator: {@link Figure}.
*
*
Observer
* State changes of figures can be observed by other objects. Specifically
* {@code CompositeFigure} observes area invalidations of its child figures. And
* {@code DrawingView} observers area invalidations of its drawing object.
* Subject: {@link Figure}; Observer:
* {@link org.jhotdraw.draw.event.FigureListener}; Event: {@link org.jhotdraw.draw.event.FigureEvent}; Concrete Observer:
* {@link CompositeFigure}, {@link DrawingView}.
*
*
Prototype
* The creation tool creates new figures by cloning a prototype figure object.
* That's the reason why {@code Figure} extends the {@code Cloneable} interface.
*
* Prototype: {@link Figure}; Client: {@link org.jhotdraw.draw.tool.CreationTool}.
*
*
Strategy
* The location of the start and end points of a connection figure are determined
* by {@code Connector}s which are owned by the connected figures.
* Context: {@link Figure}, {@link ConnectionFigure};
* Strategy: {@link org.jhotdraw.draw.connector.Connector}.
*
*
Strategy
* {@code Locator} encapsulates a strategy for locating a point on a
* {@code Figure}.
* Strategy: {@link org.jhotdraw.draw.locator.Locator}; Context: {@link Figure}.
*
FigureListener.figureChanged event to
* its figure listeners.
*/
public int getLayer();
/**
* A Figure is only drawn by a CompositeFigure, if it is visible.
* Layouter's should ignore invisible figures too.
*/
public boolean isVisible();
// BOUNDS
/**
* Sets the logical and untransformed bounds of the figure.
* * This is used by Tool's which create a new Figure and by Tool's which * connect a Figure to another Figure. *
* This is a basic operation which does not fire events. Use the following * code sequence, if you need event firing: *
* figure.willChange();
* figure.setBounds(...);
* figure.changed();
*
*
*
* @param start the start point of the bounds
* @param end the end point of the bounds
* @see #getBounds
*/
public void setBounds(Point2D.Double start, Point2D.Double end);
/**
* Returns the untransformed logical start point of the bounds.
*
*
*
* @see #setBounds
*/
public Point2D.Double getStartPoint();
/**
* Returns the untransformed logical end point of the bounds.
*
*
*
* @see #setBounds
*/
public Point2D.Double getEndPoint();
/**
* Returns the untransformed logical bounds of the figure as a Rectangle.
* * The bounds are used by Handle objects for adjusting the * figure and for aligning the figure on a grid. */ public Rectangle2D.Double getBounds(); /** * Returns the drawing area of the figure as a Rectangle. *
* The drawing area is used to inform {@link DrawingView} about the * area that is needed to draw this figure. *
* The drawing area needs to be large enough, to take line width, line caps * and other decorations into account that exceed the bounds of the Figure. */ public Rectangle2D.Double getDrawingArea(); /** * The preferred size is used by Layouter to determine the preferred * size of a Figure. For most Figure's this is the same as the * dimensions returned by getBounds. */ public Dimension2DDouble getPreferredSize(); /** * Checks if a point is contained by the figure. *
* This is used for hit testing by Tool's. */ public boolean contains(Point2D.Double p); // TRANSFORMING /** * Gets data which can be used to restore the transformation of the figure * without loss of precision, after a transform has been applied to it. * * @see #transform(AffineTransform) */ public Object getTransformRestoreData(); /** * Restores the transform of the figure to a previously stored state. */ public void restoreTransformTo(Object restoreData); /** * Transforms the shape of the Figure. Transformations using double * precision arithmethics are inherently lossy operations. Therefore it is * recommended to use getTransformRestoreData() restoreTransformTo() to * provide lossless undo/redo functionality. *
* This is a basic operation which does not fire events. Use the following * code sequence, if you need event firing: *
* figure.willChange();
* figure.transform(...);
* figure.changed();
*
*
*
* @param tx The transformation.
* @see #getTransformRestoreData
* @see #restoreTransformTo
*/
public void transform(AffineTransform tx);
// ATTRIBUTES
/**
* Sets an attribute on the figure and calls {@code attributeChanged}
* on all registered {@code FigureListener}s if the attribute value
* has changed.
* * For efficiency reasons, the drawing is not automatically repainted. * If you want the drawing to be repainted when the attribute is changed, * you can either use {@code key.set(figure, value); } or *
* figure.willChange();
* figure.set(...);
* figure.changed();
*
*
* @see AttributeKey#set
*/
public * Please note, that even if this method returns false, the Figure * may become part of a selection for other reasons. For example, * if the Figure is part of a GroupFigure, then the Figure is * indirectly part of the selection, when the user selects the * GroupFigure. */ public boolean isSelectable(); /** * Returns true, if the user may remove this figure. * If this operation returns false, Tool's should not remove this * figure on behalf of the user. *
* Please note, that even if this method returns false, the Figure * may be removed from the Drawing for other reasons. For example, * if the Figure is used to display a warning message, the Figure * can be removed from the Drawing, when the warning message is * no longer relevant. */ public boolean isRemovable(); /** * Returns true, if the user may transform this figure. * If this operation returns false, Tool's should not transform this * figure on behalf of the user. *
* Please note, that even if this method returns false, the Figure
* may be transformed for other reasons. For example, if the Figure takes
* part in an animation.
*
* @see #transform
*/
public boolean isTransformable();
/**
* Creates handles used to manipulate the figure.
*
* @param detailLevel The detail level of the handles. Usually this is 0 for
* bounding box handles and 1 for point handles. The value -1 is used
* by the SelectAreaTracker and the HandleTracker to highlight figures, over which the mouse
* pointer is hovering.
* @return a Collection of handles
* @see Handle
*/
public Collection The collection may contain null entries. These entries are used
* interpreted as separators in the popup menu.
* Actions can use the property Figure.ACTION_SUBMENU to specify a
* submenu.
*/
public Collection Returns null, if no specialized tool is available.
*/
@Nullable public Tool getTool(Point2D.Double p);
/**
* Returns a tooltip for the specified location on the figure.
*/
public String getToolTipText(Point2D.Double p);
// CONNECTING
/**
* Returns true if this Figure can be connected to a {@link ConnectionFigure}.
*/
public boolean isConnectable();
/**
* Gets a connector for this figure at the given location.
* A figure can have different connectors at different locations.
*
* @param p the location of the connector.
* @param prototype The prototype used to create a connection or null if
* unknown. This allows for specific connectors for different
* connection figures.
*/
public Connector findConnector(Point2D.Double p, @Nullable ConnectionFigure prototype);
/**
* Gets a compatible connector.
* If the provided connector is part of this figure, return the connector.
* If the provided connector is part of another figure, return a connector
* with the same semantics for this figure.
* Returns null, if no compatible connector is available.
*/
@Nullable public Connector findCompatibleConnector(Connector c, boolean isStartConnector);
/**
* Returns all connectors of this Figure for the specified prototype of
* a ConnectionFigure.
*
* This is used by connection tools and connection handles
* to visualize the connectors when the user is about to
* create a ConnectionFigure to this Figure.
*
* @param prototype The prototype used to create a connection or null if
* unknown. This allows for specific connectors for different
* connection figures.
*/
public Collection
* In case of a {@code CompositeFigure}, this method descends into its
* children and into its children's children until the innermost figure is
* found.
*
* This functionality is implemented using the Chain of
* Responsibility design pattern. A figure which is not composed
* of other figures returns itself if the point is contained by the figure.
* Composed figures pass the method call down to their children.
*
* @param p A location on the drawing.
* @return Returns the innermost figure at the location, or null if the
* location is not contained in a figure.
*/
@Nullable public Figure findFigureInside(Point2D.Double p);
/**
* Returns a decompositon of a figure into its parts.
* A figure is considered as a part of itself.
*/
public Collection
* Note:
* This fires a
* Note: willChange and changed are typically used
* as pairs before and after invoking one or multiple basic-methods on
* the Figure.
*
* @see #changed
*/
public void willChange();
/**
* Informs that a Figure changed its visual representation and needs to
* be redrawn.
* FigureListener.figureChanged
* event for the current display bounds of the figure.
* willChange and changed are typically used
* as pairs before and after invoking one or multiple basic-methods on
* the Figure.
*
* @see #willChange
*/
public void changed();
/**
* Fires a FigureListener.figureRequestRemove event.
*/
public void requestRemove();
/**
* Handles a drop.
*
* @param p The location of the mouse event.
* @param droppedFigures The dropped figures.
* @param view The drawing view which is the source of the mouse event.
* @return Returns true, if the figures should snap back to the location
* they were dragged from.
*/
public boolean handleDrop(Point2D.Double p, Collection