org.jhotdraw.draw
Interface Figure

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

CompositeFigure, ConnectionFigure, DecoratedFigure, Drawing, ImageHolderFigure, ODGFigure, SVGFigure, TextHolderFigure

All Known Implementing Classes:

AbstractAttributedCompositeFigure, AbstractAttributedDecoratedFigure, AbstractAttributedFigure, AbstractCompositeFigure, AbstractDrawing, AbstractFigure, BezierFigure, BorderRectangleFigure, DefaultDrawing, DependencyFigure, DiamondFigure, EllipseFigure, GraphicalCompositeFigure, GroupFigure, ImageFigure, LabeledLineConnectionFigure, LabelFigure, LineConnectionFigure, LineFigure, ListFigure, NodeFigure, ODGAttributedFigure, ODGBezierFigure, ODGDrawing, ODGEllipseFigure, ODGGroupFigure, ODGPathFigure, ODGRectFigure, QuadTreeCompositeFigure, QuadTreeDrawing, RectangleFigure, RoundRectangleFigure, SeparatorLineFigure, StraightLineFigure, SVGAttributedFigure, SVGBezierFigure, SVGEllipseFigure, SVGGroupFigure, SVGImageFigure, SVGPathFigure, SVGRectFigure, SVGTextAreaFigure, SVGTextFigure, TaskFigure, TextAreaFigure, TextFigure, TriangleFigure

@NotNull
public interface Figure
extends java.lang.Cloneable, java.io.Serializable

A figure is a graphical element of a Drawing. A figure can be only in one drawing at a time.

Figure provides the following functionality:

• Figure knows its bounds and it can draw itself.
• Figures can have an open ended set of attributes. An attribute is identified by an AttributeKey.
• A figure can have Connectors that define how to locate a connection point on the figure.
• A figure can create a set of Handles which can interactively manipulate aspects of the figure.
• A figure can return a set of actions associated with a specific point on the figure.
• A figure can be composed of other figures. If this is the case, the object implementing the Figure interface usually also implements the CompositeFigure interface.
• A figure can create a clone of itself.

Design Patterns

Framework
The following interfaces define the contracts of a framework for structured drawing editors:
Contract: Drawing, Figure, DrawingView, DrawingEditor, Handle and Tool.

Composite
Composite figures can be composed of other figures.
Component: Figure; Composite: 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: Figure, ConnectionFigure, Connector.

Decorator
Decorated figures can be adorned with another figure.
Component: DecoratedFigure; Decorator: Figure.

Observer
State changes of figures can be observed by other objects. Specifically CompositeFigure observes area invalidations of its child figures. And DrawingView observers area invalidations of its drawing object.
Subject: Figure; Observer: FigureListener; Event: FigureEvent; Concrete Observer: CompositeFigure, DrawingView.

Prototype
The creation tool creates new figures by cloning a prototype figure object. That's the reason why Figure extends the Cloneable interface.
Prototype: Figure; Client: CreationTool.

Strategy
The location of the start and end points of a connection figure are determined by Connectors which are owned by the connected figures.
Context: Figure, ConnectionFigure; Strategy: Connector.

Strategy
Locator encapsulates a strategy for locating a point on a Figure.
Strategy: Locator; Context: Figure.

Version:

$Id: Figure.java 654 2010-06-25 13:27:08Z rawcoder $

Author:

Werner Randelshofer

Field Summary

static java.lang.String	CONNECTABLE_PROPERTY The name of the "connectable" property.
static java.lang.String	REMOVABLE_PROPERTY The name of the "removable" property.
static java.lang.String	SELECTABLE_PROPERTY The name of the "selectable" property.
static java.lang.String	TRANSFORMABLE_PROPERTY The name of the "transformable" property.

Method Summary

void	addFigureListener(FigureListener l) Adds a listener for FigureEvent's.
void	addNotify(Drawing d) Informs a figure, that it has been added to a drawing.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a PropertyChangeListener which can optionally be wrapped into a WeakPropertyChangeListener.
void	changed() Informs that a Figure changed its visual representation and needs to be redrawn.
java.lang.Object	clone() Returns a clone of the figure, with clones of all aggregated figures, such as children and decorators.
boolean	contains(java.awt.geom.Point2D.Double p) Checks if a point is contained by the figure.
java.util.Collection<Handle>	createHandles(int detailLevel) Creates handles used to manipulate the figure.
void	draw(java.awt.Graphics2D g) Draws the figure.
Connector	findCompatibleConnector(Connector c, boolean isStartConnector) Gets a compatible connector.
Connector	findConnector(java.awt.geom.Point2D.Double p, ConnectionFigure prototype) Gets a connector for this figure at the given location.
Figure	findFigureInside(java.awt.geom.Point2D.Double p) Finds the innermost figure at the specified location.
<T> T	get(AttributeKey<T> key) Gets an attribute from the Figure.
java.util.Collection<javax.swing.Action>	getActions(java.awt.geom.Point2D.Double p) Returns a collection of Action's for the specified location on the figure.
java.util.Map<AttributeKey,java.lang.Object>	getAttributes() Returns a view to all attributes of this figure.
java.lang.Object	getAttributesRestoreData() Gets data which can be used to restore the attributes of the figure after a set has been applied to it.
java.awt.geom.Rectangle2D.Double	getBounds() Returns the untransformed logical bounds of the figure as a Rectangle.
java.util.Collection<Connector>	getConnectors(ConnectionFigure prototype) Returns all connectors of this Figure for the specified prototype of a ConnectionFigure.
java.awt.Cursor	getCursor(java.awt.geom.Point2D.Double p) Returns a cursor for the specified location.
java.util.Collection<Figure>	getDecomposition() Returns a decompositon of a figure into its parts.
java.awt.geom.Rectangle2D.Double	getDrawingArea() Returns the drawing area of the figure as a Rectangle.
java.awt.geom.Point2D.Double	getEndPoint() Returns the untransformed logical end point of the bounds.
int	getLayer() Gets the layer number of the figure.
Dimension2DDouble	getPreferredSize() The preferred size is used by Layouter to determine the preferred size of a Figure.
java.awt.geom.Point2D.Double	getStartPoint() Returns the untransformed logical start point of the bounds.
Tool	getTool(java.awt.geom.Point2D.Double p) Returns a specialized tool for the specified location.
java.lang.String	getToolTipText(java.awt.geom.Point2D.Double p) Returns a tooltip for the specified location on the figure.
java.lang.Object	getTransformRestoreData() 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.
boolean	handleDrop(java.awt.geom.Point2D.Double p, java.util.Collection<Figure> droppedFigures, DrawingView view) Handles a drop.
boolean	handleMouseClick(java.awt.geom.Point2D.Double p, java.awt.event.MouseEvent evt, DrawingView view) Handles a mouse click.
boolean	includes(Figure figure) Checks whether the given figure is contained in this figure.
boolean	isConnectable() Returns true if this Figure can be connected to a ConnectionFigure.
boolean	isRemovable() Returns true, if the user may remove this figure.
boolean	isSelectable() Returns true, if the user may select this figure.
boolean	isTransformable() Returns true, if the user may transform this figure.
boolean	isVisible() A Figure is only drawn by a CompositeFigure, if it is visible.
void	remap(java.util.Map<Figure,Figure> oldToNew, boolean disconnectIfNotInMap) After cloning a collection of figures, the ConnectionFigures contained in this collection still connect to the original figures instead of to the clones.
void	removeFigureListener(FigureListener l) Removes a listener for FigureEvent's.
void	removeNotify(Drawing d) Informs a figure, that it has been removed from a drawing.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes a PropertyChangeListener.
void	requestRemove() Fires a FigureListener.figureRequestRemove event.
void	restoreAttributesTo(java.lang.Object restoreData) Restores the attributes of the figure to a previously stored state.
void	restoreTransformTo(java.lang.Object restoreData) Restores the transform of the figure to a previously stored state.
<T> void	set(AttributeKey<T> key, T value) Sets an attribute on the figure and calls attributeChanged on all registered FigureListeners if the attribute value has changed.
void	setBounds(java.awt.geom.Point2D.Double start, java.awt.geom.Point2D.Double end) Sets the logical and untransformed bounds of the figure.
void	transform(java.awt.geom.AffineTransform tx) Transforms the shape of the Figure.
void	willChange() Informs that the figure is about to change its visual representation (for example, its shape, or its color).

Field Detail

CONNECTABLE_PROPERTY

static final java.lang.String CONNECTABLE_PROPERTY

The name of the "connectable" property.

See Also:

Constant Field Values

REMOVABLE_PROPERTY

static final java.lang.String REMOVABLE_PROPERTY

The name of the "removable" property.

See Also:

Constant Field Values

SELECTABLE_PROPERTY

static final java.lang.String SELECTABLE_PROPERTY

The name of the "selectable" property.

See Also:

Constant Field Values

TRANSFORMABLE_PROPERTY

static final java.lang.String TRANSFORMABLE_PROPERTY

The name of the "transformable" property.

See Also:

Constant Field Values

Method Detail

draw

void draw(java.awt.Graphics2D g)

Draws the figure.

Parameters:

g - The Graphics2D to draw to.

getLayer

int getLayer()

Gets the layer number of the figure. The layer is used to determine the z-ordering of a figure inside of a drawing. Figures with a higher layer number are drawn after figures with a lower number. The z-order of figures within the same layer is determined by the sequence the figures were added to a drawing. Figures added later to a drawn after figures which have been added before. If a figure changes its layer, it must fire a FigureListener.figureChanged event to its figure listeners.

isVisible

boolean isVisible()

A Figure is only drawn by a CompositeFigure, if it is visible. Layouter's should ignore invisible figures too.

setBounds

void setBounds(java.awt.geom.Point2D.Double start,
               java.awt.geom.Point2D.Double end)

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();
 

Parameters:

start - the start point of the bounds

end - the end point of the bounds

See Also:

getBounds()

getStartPoint

java.awt.geom.Point2D.Double getStartPoint()

Returns the untransformed logical start point of the bounds.

See Also:

setBounds(java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double)

getEndPoint

java.awt.geom.Point2D.Double getEndPoint()

Returns the untransformed logical end point of the bounds.

See Also:

setBounds(java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double)

getBounds

java.awt.geom.Rectangle2D.Double getBounds()

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.

getDrawingArea

java.awt.geom.Rectangle2D.Double getDrawingArea()

Returns the drawing area of the figure as a Rectangle.

The drawing area is used to inform 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.

getPreferredSize

Dimension2DDouble getPreferredSize()

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.

contains

boolean contains(java.awt.geom.Point2D.Double p)

Checks if a point is contained by the figure.

This is used for hit testing by Tool's.

getTransformRestoreData

java.lang.Object getTransformRestoreData()

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 Also:

transform(AffineTransform)

restoreTransformTo

void restoreTransformTo(java.lang.Object restoreData)

Restores the transform of the figure to a previously stored state.

transform

void transform(java.awt.geom.AffineTransform tx)

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();
 

Parameters:

tx - The transformation.

See Also:

getTransformRestoreData(), restoreTransformTo(java.lang.Object)

set

<T> void set(AttributeKey<T> key,
             @Nullable
             T value)

Sets an attribute on the figure and calls attributeChanged on all registered FigureListeners 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 key.set(figure, value); or

 figure.willChange();
 figure.set(...);
 figure.changed();
 

See Also:

AttributeKey.set(org.jhotdraw.draw.Figure, T)

get

@Nullable
<T> T get(AttributeKey<T> key)

Gets an attribute from the Figure.

Returns:

Returns the attribute value. If the Figure does not have an attribute with the specified key, returns key.getDefaultValue().

See Also:

AttributeKey.get(org.jhotdraw.draw.Figure)

getAttributes

java.util.Map<AttributeKey,java.lang.Object> getAttributes()

Returns a view to all attributes of this figure. By convention, an unmodifiable map is returned.

getAttributesRestoreData

java.lang.Object getAttributesRestoreData()

Gets data which can be used to restore the attributes of the figure after a set has been applied to it.

restoreAttributesTo

void restoreAttributesTo(java.lang.Object restoreData)

Restores the attributes of the figure to a previously stored state.

isSelectable

boolean isSelectable()

Returns true, if the user may select this figure. If this operation returns false, Tool's should not select this figure on behalf of the user.

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.

isRemovable

boolean isRemovable()

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.

isTransformable

boolean isTransformable()

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 Also:

transform(java.awt.geom.AffineTransform)

createHandles

java.util.Collection<Handle> createHandles(int detailLevel)

Creates handles used to manipulate the figure.

Parameters:

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.

Returns:

a Collection of handles

See Also:

Handle

getCursor

java.awt.Cursor getCursor(java.awt.geom.Point2D.Double p)

Returns a cursor for the specified location.

getActions

java.util.Collection<javax.swing.Action> getActions(java.awt.geom.Point2D.Double p)

Returns a collection of Action's for the specified location on the figure.

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.

getTool

@Nullable
Tool getTool(java.awt.geom.Point2D.Double p)

Returns a specialized tool for the specified location.

Returns null, if no specialized tool is available.

getToolTipText

java.lang.String getToolTipText(java.awt.geom.Point2D.Double p)

Returns a tooltip for the specified location on the figure.

isConnectable

boolean isConnectable()

Returns true if this Figure can be connected to a ConnectionFigure.

findConnector

Connector findConnector(java.awt.geom.Point2D.Double p,
                        @Nullable
                        ConnectionFigure prototype)

Gets a connector for this figure at the given location. A figure can have different connectors at different locations.

Parameters:

p - the location of the connector.

prototype - The prototype used to create a connection or null if unknown. This allows for specific connectors for different connection figures.

findCompatibleConnector

@Nullable
Connector findCompatibleConnector(Connector c,
                                           boolean isStartConnector)

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.

getConnectors

java.util.Collection<Connector> getConnectors(@Nullable
                                              ConnectionFigure prototype)

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.

Parameters:

prototype - The prototype used to create a connection or null if unknown. This allows for specific connectors for different connection figures.

includes

boolean includes(Figure figure)

Checks whether the given figure is contained in this figure. A figure includes itself.

findFigureInside

@Nullable
Figure findFigureInside(java.awt.geom.Point2D.Double p)

Finds the innermost figure at the specified location.

In case of a 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.

Parameters:

p - A location on the drawing.

Returns:

Returns the innermost figure at the location, or null if the location is not contained in a figure.

getDecomposition

java.util.Collection<Figure> getDecomposition()

Returns a decompositon of a figure into its parts. A figure is considered as a part of itself.

clone

java.lang.Object clone()

Returns a clone of the figure, with clones of all aggregated figures, such as children and decorators. The cloned figure does not clone the list of FigureListeners from its original.

remap

void remap(java.util.Map<Figure,Figure> oldToNew,
           boolean disconnectIfNotInMap)

After cloning a collection of figures, the ConnectionFigures contained in this collection still connect to the original figures instead of to the clones. Using This operation and providing a map, which maps from the original collection of figures to the new collection, connections can be remapped to the new figures.

addNotify

void addNotify(Drawing d)

Informs a figure, that it has been added to a drawing. The figure must inform all FigureListeners that it has been added.

removeNotify

void removeNotify(Drawing d)

Informs a figure, that it has been removed from a drawing. The figure must inform all FigureListeners that it has been removed.

willChange

void willChange()

Informs that the figure is about to change its visual representation (for example, its shape, or its color).

Note: willChange and changed are typically used as pairs before and after invoking one or multiple basic-methods on the Figure.

See Also:

changed()

changed

void changed()

Informs that a Figure changed its visual representation and needs to be redrawn.

This fires a FigureListener.figureChanged event for the current display bounds of the figure.

Note: willChange and changed are typically used as pairs before and after invoking one or multiple basic-methods on the Figure.

See Also:

willChange()

requestRemove

void requestRemove()

Fires a FigureListener.figureRequestRemove event.

handleDrop

boolean handleDrop(java.awt.geom.Point2D.Double p,
                   java.util.Collection<Figure> droppedFigures,
                   DrawingView view)

Handles a drop.

Parameters:

p - The location of the mouse event.

droppedFigures - The dropped figures.

view - The drawing view which is the source of the mouse event.

Returns:

Returns true, if the figures should snap back to the location they were dragged from.

handleMouseClick

boolean handleMouseClick(java.awt.geom.Point2D.Double p,
                         java.awt.event.MouseEvent evt,
                         DrawingView view)

Handles a mouse click.

Parameters:

p - The location of the mouse event.

evt - The mouse event.

view - The drawing view which is the source of the mouse event.

Returns:

Returns true, if the event was consumed.

addFigureListener

void addFigureListener(FigureListener l)

Adds a listener for FigureEvent's.

removeFigureListener

void removeFigureListener(FigureListener l)

Removes a listener for FigureEvent's.

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a PropertyChangeListener which can optionally be wrapped into a WeakPropertyChangeListener.

Parameters:

listener -

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes a PropertyChangeListener. If the listener was added wrapped into a WeakPropertyChangeListener, the WeakPropertyChangeListener is removed.

Parameters:

listener -