org.jhotdraw.draw
Interface Figure

All Superinterfaces:

java.lang.Cloneable, DOMStorable, java.io.Serializable

All Known Subinterfaces:

CompositeFigure, ConnectionFigure, SVGFigure, TextHolder

All Known Implementing Classes:

AbstractAttributedCompositeFigure, AbstractCompositeFigure, AbstractFigure, AttributedFigure, BezierFigure, BorderRectangleFigure, DependencyFigure, DiamondFigure, EllipseFigure, GraphicalCompositeFigure, GroupFigure, LabeledLineConnectionFigure, LabelFigure, LineConnectionFigure, LineFigure, ListFigure, NodeFigure, RectangleFigure, RoundRectangleFigure, SeparatorLineFigure, SVGEllipse, SVGGroup, SVGImage, SVGLine, SVGPath, SVGRect, SVGText, TaskFigure, TextAreaFigure, TextFigure, TriangleFigure

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

The interface of a graphical figure.

A Figure knows its display box and can draw itself. A figure can be composed of several figures. To interact and manipulate with a figure it can provide Handles and Connectors.

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.

Default implementations for the Figure interface are provided by AbstractFigure.

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 the specified drawing.
void	addUndoableEditListener(javax.swing.event.UndoableEditListener l) Adds a listener for UndoableEdit events.
void	basicSetAttribute(AttributeKey key, java.lang.Object value) Sets an attribute of the figure without firing events.
void	basicSetBounds(java.awt.geom.Point2D.Double start, java.awt.geom.Point2D.Double end) Sets the logical bounds of the figure and of its decorator figure.
void	basicTransform(java.awt.geom.AffineTransform tx) Transforms the shape of the Figure.
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.
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 and its decorator 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.
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.awt.geom.Rectangle2D.Double	getBounds() Returns the logical bounds of the figure as a Rectangle.
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.
Figure	getDecorator() Gets the decorator figure.
java.awt.geom.Rectangle2D.Double	getDrawBounds() Returns the drawing bounding box of the figure and of its decorator figure.
java.awt.geom.Point2D.Double	getEndPoint() Returns the end point of the bounds.
int	getLayer() Gets the layer of the figure.
Dimension2DDouble	getPreferredSize() The preferred size is used by Layouter to determine the preferred size of a Figure.
java.lang.Object	getRestoreData() Gets data which can be used to restore the shape of the figure after a basicTransform has been applied to it.
java.awt.geom.Point2D.Double	getStartPoint() Returns the start point of the bounds.
Tool	getTool(java.awt.geom.Point2D.Double p) Returns a specialized tool for the specified location.
java.lang.String	getTooltip(java.awt.geom.Point2D.Double p) Returns a tooltip for the specified location.
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.
void	invalidate() Informs that a Figure has invalidated its display area and needs to be drawn.
boolean	isConnectorsVisible() Returns true, if this figure draws its connectors.
boolean	isInteractive() Returns true, if the user can manipulate this figure.
boolean	isVisible() A Figure is only drawn by a Drawing and by 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 the specified drawing.
void	removeUndoableEditListener(javax.swing.event.UndoableEditListener l) Removes a listener for UndoableEdit events.
void	requestRemove() Fires a FigureListener.figureRequestRemove event.
void	restoreTo(java.lang.Object restoreData) Restores the shape of the figure to a previously stored state.
void	setAttribute(AttributeKey key, java.lang.Object value) Sets an attribute of the figure.
void	setConnectorsVisible(boolean isVisible, ConnectionFigure courtingConnection) Sets whether the connectors should be visible for the specified courting connector.
void	setDecorator(Figure newValue) Sets a decorator figure.
void	setVisible(boolean newValue) Changes the visible state 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 and its decorator figure.

Parameters:

g - The Graphics2D to draw to.

getLayer

int getLayer()

Gets the layer 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. FIXME - Replace int value by a Layer object.

isVisible

boolean isVisible()

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

setVisible

void setVisible(boolean newValue)

Changes the visible state of the Figure.

The Figure fires FigureListener.figureChanged and UndoableEditListener.undoableEditHappened, if this operation changed its visible state.

basicSetBounds

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

Sets the logical bounds of the figure and of its decorator 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.

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 start point of the bounds.

See Also:

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

getEndPoint

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

Returns the end point of the bounds.

See Also:

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

getBounds

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

Returns the logical bounds of the figure as a Rectangle. The logical bounds are used by some Handle objects for adjusting the figure.

getDrawBounds

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

Returns the drawing bounding box of the figure and of its decorator figure. This takes line width, line caps and other decorations into account. Note: getDrawBounds must include the logical 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.

getRestoreData

java.lang.Object getRestoreData()

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

See Also:

basicTransform(AffineTransform)

restoreTo

void restoreTo(java.lang.Object restoreData)

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

basicTransform

void basicTransform(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 getRestoreData() restoreTo() to provide lossless undo/redo functionality. After the transform has finished, the bounds of the decorator figure are changed to match the transformed bounds of the figure.

This is a basic operation which does not fire events.

Parameters:

tx - The transformation.

setAttribute

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

Sets an attribute of the figure. AttributeKey name and semantics are defined by the class implementing the Figure interface.

On an attribute change, the Figure fires FigureListener.figureAttributeChanged, UndoableEditListener.undoableEditHappened. If the shape is affected by an attribute change, FigureListener.figureChanged is fired too.

basicSetAttribute

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

Sets an attribute of the figure without firing events. AttributeKey name and semantics are defined by the class implementing the Figure interface.

Use AttributeKey.set() for typesafe access to this method.

See Also:

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

getAttribute

java.lang.Object getAttribute(AttributeKey key)

Gets an attribute from the Figure.

Use AttributeKey.get() for typesafe access to this method.

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.

isInteractive

boolean isInteractive()

Returns true, if the user can manipulate this figure. If this operation returns false, Tool's should not interact with this figure.

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.

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.

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.

getTooltip

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

Returns a tooltip for the specified location.

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.

setConnectorsVisible

void setConnectorsVisible(boolean isVisible,
                          ConnectionFigure courtingConnection)

Sets whether the connectors should be visible for the specified courting connector. Connectors can be optionally visible.

isConnectorsVisible

boolean isConnectorsVisible()

Returns true, if this figure draws its connectors.

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.

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 the specified 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 the specified 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()

invalidate

void invalidate()

Informs that a Figure has invalidated its display area and needs to be drawn. Fires a FigureListener.areaInvalidated event.

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 figure consumed the mouse click.

addFigureListener

void addFigureListener(FigureListener l)

Adds a listener for FigureEvent's.

removeFigureListener

void removeFigureListener(FigureListener l)

Removes a listener for FigureEvent's.

addUndoableEditListener

void addUndoableEditListener(javax.swing.event.UndoableEditListener l)

Adds a listener for UndoableEdit events.

removeUndoableEditListener

void removeUndoableEditListener(javax.swing.event.UndoableEditListener l)

Removes a listener for UndoableEdit events.

setDecorator

void setDecorator(Figure newValue)

Sets a decorator figure. Set this to null, if no decorator is desired. The decorator will use the same logical bounds as this figure. It will be drawn when the figure is drawn.

getDecorator

Figure getDecorator()

Gets the decorator figure.