org.jhotdraw.draw
Interface Figure

All Superinterfaces:

java.lang.Cloneable, DOMStorable, 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

public interface Figure
extends java.lang.Cloneable, java.io.Serializable, DOMStorable

A Figure knows its bounds and it can draw itself. A figure is an element of a Drawing.

A figure has a set of Handles to manipulate its shape or attributes. A figure has one or more Connectors that define how to locate a connection point.

Figures can have an open ended set of attributes. An attribute is identified by an AttributeKey.

Specialized subinterfaces of Figure allow to compose a figure from several figures, to connect a figure to other figures, to hold text or an image, and to layout a figure.

Version:

7.0.1 2008-02-13 Fixed comments on setAttribute and getAttribute methods.
7.0 2008-02-13 Huw Jones: Added method isTransformable.
6.0 2007-12-19 Removed method invalidate.
5.0 2007-07-24 Removed method isSelectable and added isSelectable and isRemovable instead.
4.2 2007-05-19 Removed setConnectorsVisible, isConnectorsVisible method due to changes in Connector interface.
4.1 2007-05-18 Removed addUndoableEditListener, removeUndoableEditListener methods. They are not needed anymore, due to the removal of the basicSet methods for undoable attributes.
4.0 2007-05-12 Replaced set.../basicSet... design for undoable attributes by setAttribute/getAttributesRestoreData/restoreAttributesTo design.
3.1 2007-04-14 Method handleMouseClick is now required to consume an event, if it returns true.
3.0 2006-01-20 Reworked for J2SE 1.5.

Author:

Werner Randelshofer

See Also:

Drawing, Handle, Connector

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.
boolean	canConnect() Checks if this Figure can be connected.
void	changed() Informs that a Figure changed its shape.
java.lang.Object	clone() Returns a clone of the figure, with clones of all aggregated figures, such as chilrend 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) Returns the figure that contains the given point.
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.lang.Object	getAttribute(AttributeKey key) Gets an attribute from 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 setAttribute has been applied to it.
java.awt.geom.Rectangle2D.Double	getBounds() Returns the untransformed logicalbounds 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	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) 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	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.
void	setAttribute(AttributeKey key, java.lang.Object value) Sets an attribute of the figure and calls attributeChanged on all registered FigureListener's.
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 a Figure is about to change its shape.

Methods inherited from interface org.jhotdraw.xml.DOMStorable

read, write

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:

 aFigure.willChange();
 aFigure.setBounds(...);
 aFigure.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 logicalbounds of the figure as a Rectangle. The handle 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 improve the performance of GraphicView, for example for clipping of repaints and for clipping of mouse events.

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:

 aFigure.willChange();
 aFigure.transform(...);
 aFigure.changed();
 

Parameters:

tx - The transformation.

See Also:

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

setAttribute

void setAttribute(AttributeKey key,
                  java.lang.Object value)

Sets an attribute of the figure and calls attributeChanged on all registered FigureListener's.

This method is not typesafe, you should never call it directly, use AttributeKey.set instead.

See Also:

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

getAttribute

java.lang.Object getAttribute(AttributeKey key)

Gets an attribute from the Figure.

This method is not typesafe, you should never call it directly, use AttributeKey.get instead.

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 setAttribute 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.

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

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.

canConnect

boolean canConnect()

Checks if this Figure can be connected.

findConnector

Connector findConnector(java.awt.geom.Point2D.Double p,
                        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

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. Return null, if no compatible connector is available.

getConnectors

java.util.Collection<Connector> getConnectors(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

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

Returns the figure that contains the given point.

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 chilrend and decorators. The cloned figure does not clone the list of FigureListeners from its original.

remap

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

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 a Figure is about to change its shape.

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

changed

void changed()

Informs that a Figure changed its shape. This fires a FigureListener.figureChanged event for the current display bounds of 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.