org.jhotdraw.draw
Interface Drawing

All Superinterfaces:

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

All Known Implementing Classes:

AbstractDrawing, DefaultDrawing, ODGDrawing, QuadTreeDrawing

@NotNull
public interface Drawing
extends CompositeFigure, java.io.Serializable, DOMStorable

A drawing is a container for Figures. A drawing can hold multiple figures, but a figure can only be in one drawing at a time. A drawing can be in one or multiple DrawingViews.

Drawing is essentially a CompositeFigure with a number of additional functionality:

• A drawing notifies a figure and its CompositeFigureListener's when the figure is added or removed from it. Like with CompositeFigure basic add and remove methods are supplied for use cases where this is not desired - for example when figures need to be temporarily removed in order to group or ungroup them.
• A drawing can find contained figures given a point or a rectangular region. Specialized implementations of the Drawing interface can use optimized strategies and data structures to find figures faster.
• The drawing object is used by Figure, Tool and Handle as a mediator for undoable edit events. This way, undoable edit listeners only need to register on the drawing object in order to receive all undoable edit events related to changes made in the drawing.
• Drawing can hold a number of InputFormats and OutputFormats, allowing to read and write a drawing from/to a stream, a file or the clipboard.

Design Patterns

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

Model-View-Controller
The following classes implement together the Model-View-Controller design pattern:
Model: Drawing; View: DrawingView; Controller: DrawingEditor.

Strategy
org.jhotdraw.draw.io.OutputFormat encapsulates a strategy for writing drawings to output streams.
Strategy: OutputFormat; Context: Drawing.

Strategy
org.jhotdraw.draw.io.InputFormat encapsulates a strategy for reading drawings from input streams.
Strategy: InputFormat; Context: Drawing.

Version:

$Id: Drawing.java 674 2010-07-29 11:11:42Z rawcoder $

Author:

Werner Randelshofer

Field Summary

Fields inherited from interface org.jhotdraw.draw.CompositeFigure

LAYOUT_INSETS

Fields inherited from interface org.jhotdraw.draw.Figure

CONNECTABLE_PROPERTY, REMOVABLE_PROPERTY, SELECTABLE_PROPERTY, TRANSFORMABLE_PROPERTY

Method Summary

boolean	add(Figure figure) Adds a figure to the drawing.
void	add(int index, Figure figure) Adds a figure to the drawing.
void	addAll(java.util.Collection<? extends Figure> figures) Adds a collection of figures to the drawing.
void	addAll(int index, java.util.Collection<? extends Figure> figures) Adds a collection of figures to the drawing.
void	addInputFormat(InputFormat format) Adds an input format to the drawing.
void	addOutputFormat(OutputFormat format) Adds an output format to the drawing.
void	addUndoableEditListener(javax.swing.event.UndoableEditListener l) Adds a listener for undooable edit events.
void	basicAdd(Figure figure) Reinserts a figure which was temporarily removed using basicRemove.
void	basicAdd(int index, Figure figure) Reinserts a figure which was temporarily removed using basicRemove.
void	basicAddAll(int index, java.util.Collection<? extends Figure> figures) Reinserts the specified figures which were temporarily removed from the drawing.
int	basicRemove(Figure figure) Removes a figure temporarily from the drawing.
void	basicRemoveAll(java.util.Collection<? extends Figure> figures) Removes the specified figures temporarily from the drawing.
void	bringToFront(Figure figure) Brings a figure to the front.
void	drawCanvas(java.awt.Graphics2D g) Draws on the canvas area.
Figure	findFigure(java.awt.geom.Point2D.Double p) Finds a top level Figure.
Figure	findFigureBehind(java.awt.geom.Point2D.Double p, java.util.Collection<? extends Figure> figures) Finds a top level Figure which is behind the specified Figures.
Figure	findFigureBehind(java.awt.geom.Point2D.Double p, Figure figure) Finds a top level Figure which is behind the specified Figure.
Figure	findFigureExcept(java.awt.geom.Point2D.Double p, java.util.Collection<? extends Figure> ignore) Finds a top level Figure.
Figure	findFigureExcept(java.awt.geom.Point2D.Double p, Figure ignore) Finds a top level Figure.
Figure	findFigureInside(java.awt.geom.Point2D.Double p) Finds the innermost figure at the specified location.
java.util.List<Figure>	findFigures(java.awt.geom.Rectangle2D.Double bounds) Returns all figures that lie within or intersect the specified bounds.
java.util.List<Figure>	findFiguresWithin(java.awt.geom.Rectangle2D.Double bounds) Returns all figures that lie within the specified bounds.
void	fireUndoableEditHappened(javax.swing.undo.UndoableEdit edit) Notify all listenerList that have registered interest for notification on this event type.
java.util.List<Figure>	getFiguresFrontToBack() Returns a list of the figures in Z-Order from front to back.
java.awt.font.FontRenderContext	getFontRenderContext() Returns the font render context used to do text leyout and text drawing.
java.util.List<InputFormat>	getInputFormats() Gets input formats for the Drawing in order of preferred formats.
java.lang.Object	getLock() Returns the lock object on which all threads acting on Figures in this drawing synchronize to prevent race conditions.
java.util.List<OutputFormat>	getOutputFormats() Gets output formats for the Drawing in order of preferred formats.
boolean	remove(Figure figure) Removes a figure from the drawing.
void	removeAll(java.util.Collection<? extends Figure> figures) Removes the specified figures from the drawing.
void	removeUndoableEditListener(javax.swing.event.UndoableEditListener l) Removes a listener for undoable edit events.
void	sendToBack(Figure figure) Sends a figure to the back of the drawing.
void	setFontRenderContext(java.awt.font.FontRenderContext frc) Sets the font render context used to do text leyout and text drawing.
void	setInputFormats(java.util.List<InputFormat> formats) Sets input formats for the Drawing in order of preferred formats.
void	setOutputFormats(java.util.List<OutputFormat> formats) Sets output formats for the Drawing in order of preferred formats.
java.util.List<Figure>	sort(java.util.Collection<? extends Figure> figures) Returns a copy of the provided collection which is sorted in z order from back to front.

Methods inherited from interface org.jhotdraw.draw.CompositeFigure

addCompositeFigureListener, basicRemoveAllChildren, basicRemoveChild, contains, getChild, getChildCount, getChildren, getLayouter, indexOf, layout, removeAllChildren, removeChild, removeCompositeFigureListener, setLayouter

Methods inherited from interface org.jhotdraw.draw.Figure

addFigureListener, addNotify, addPropertyChangeListener, changed, clone, contains, createHandles, draw, findCompatibleConnector, findConnector, get, getActions, getAttributes, getAttributesRestoreData, getBounds, getConnectors, getCursor, getDecomposition, getDrawingArea, getEndPoint, getLayer, getPreferredSize, getStartPoint, getTool, getToolTipText, getTransformRestoreData, handleDrop, handleMouseClick, includes, isConnectable, isRemovable, isSelectable, isTransformable, isVisible, remap, removeFigureListener, removeNotify, removePropertyChangeListener, requestRemove, restoreAttributesTo, restoreTransformTo, set, setBounds, transform, willChange

Methods inherited from interface org.jhotdraw.xml.DOMStorable

read, write

Method Detail

drawCanvas

void drawCanvas(java.awt.Graphics2D g)

Draws on the canvas area. The canvas is the background area onto which the drawing is drawn.

By convention this method is only invoked by DrawingView.

AttributeKeys defines a number of attribute keys which can be used to determine what to draw on the canvas.

add

boolean add(Figure figure)

Adds a figure to the drawing. The drawing sends an addNotify message to the figure after it has been added.

Specified by:

add in interface CompositeFigure

Parameters:

figure - to be added to the drawing

Returns:

true if this CompositeFigure changed as a result of the call

See Also:

Figure.addNotify(org.jhotdraw.draw.Drawing)

add

void add(int index,
         Figure figure)

Adds a figure to the drawing. The drawing sends an addNotify message to the figure after it has been added.

Specified by:

add in interface CompositeFigure

Parameters:

index - The z-index of the figure.

figure - to be added to the drawing

See Also:

Figure.addNotify(org.jhotdraw.draw.Drawing)

addAll

void addAll(java.util.Collection<? extends Figure> figures)

Adds a collection of figures to the drawing. The drawing sends an addNotify message to each figure after it has been added.

Parameters:

figures - to be added to the drawing

See Also:

Figure.addNotify(org.jhotdraw.draw.Drawing)

addAll

void addAll(int index,
            java.util.Collection<? extends Figure> figures)

Adds a collection of figures to the drawing. The drawing sends an addNotify message to each figure after it has been added.

Parameters:

index - The z-index of the figure.

figures - to be added to the drawing

See Also:

Figure.addNotify(org.jhotdraw.draw.Drawing)

remove

boolean remove(Figure figure)

Removes a figure from the drawing. The drawing sends a removeNotify message to the figure before it is removed.

Specified by:

remove in interface CompositeFigure

Parameters:

figure - that is part of the drawing and should be removed

See Also:

Figure.removeNotify(org.jhotdraw.draw.Drawing)

removeAll

void removeAll(java.util.Collection<? extends Figure> figures)

Removes the specified figures from the drawing. The drawing sends a removeNotify message to each figure before it is removed.

Parameters:

figures - A collection of figures which are part of the drawing and should be removed

See Also:

Figure.removeNotify(org.jhotdraw.draw.Drawing)

basicRemove

int basicRemove(Figure figure)

Removes a figure temporarily from the drawing.

Specified by:

basicRemove in interface CompositeFigure

Parameters:

figure - that is part of the drawing and should be removed

See Also:

basicAdd(Figure)

basicRemoveAll

void basicRemoveAll(java.util.Collection<? extends Figure> figures)

Removes the specified figures temporarily from the drawing.

Parameters:

figures - A collection of figures which are part of the drawing and should be removed

See Also:

basicAddAll(int, Collection)

basicAdd

void basicAdd(Figure figure)

Reinserts a figure which was temporarily removed using basicRemove.

This is a convenience method for calling basicAdd(size(), figure).

Specified by:

basicAdd in interface CompositeFigure

Parameters:

figure - that is part of the drawing and should be removed

See Also:

basicRemove(Figure)

basicAdd

void basicAdd(int index,
              Figure figure)

Reinserts a figure which was temporarily removed using basicRemove.

Specified by:

basicAdd in interface CompositeFigure

Parameters:

figure - that is part of the drawing and should be removed

See Also:

basicRemove(Figure)

basicAddAll

void basicAddAll(int index,
                 java.util.Collection<? extends Figure> figures)

Reinserts the specified figures which were temporarily removed from the drawing.

Parameters:

index - The insertion index.

figures - A collection of figures which are part of the drawing and should be reinserted.

See Also:

basicRemoveAll(Collection)

findFigures

java.util.List<Figure> findFigures(java.awt.geom.Rectangle2D.Double bounds)

Returns all figures that lie within or intersect the specified bounds. The figures are returned in Z-order from back to front.

findFiguresWithin

java.util.List<Figure> findFiguresWithin(java.awt.geom.Rectangle2D.Double bounds)

Returns all figures that lie within the specified bounds. The figures are returned in Z-order from back to front.

findFigure

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

Finds a top level Figure. Use this call for hit detection that should not descend into children of composite figures.

Use findFigureInside(java.awt.geom.Point2D.Double) If you need to descend into children of composite figures.

findFigureExcept

Figure findFigureExcept(java.awt.geom.Point2D.Double p,
                        Figure ignore)

Finds a top level Figure. Use this call for hit detection that should not descend into the figure's children.

findFigureExcept

Figure findFigureExcept(java.awt.geom.Point2D.Double p,
                        java.util.Collection<? extends Figure> ignore)

Finds a top level Figure. Use this call for hit detection that should not descend into the figure's children.

findFigureBehind

Figure findFigureBehind(java.awt.geom.Point2D.Double p,
                        Figure figure)

Finds a top level Figure which is behind the specified Figure.

findFigureBehind

Figure findFigureBehind(java.awt.geom.Point2D.Double p,
                        java.util.Collection<? extends Figure> figures)

Finds a top level Figure which is behind the specified Figures.

getFiguresFrontToBack

java.util.List<Figure> getFiguresFrontToBack()

Returns a list of the figures in Z-Order from front to back.

findFigureInside

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

Finds the innermost figure at the specified location.

In case a CompositeFigure is at the specified location, 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 in the Figure interface. Since it is often used from a drawing object as the starting point, and since Drawing defines other find methods as well, it is defined here again for clarity.

Specified by:

findFigureInside in interface Figure

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.

sendToBack

void sendToBack(Figure figure)

Sends a figure to the back of the drawing.

Parameters:

figure - that is part of the drawing

bringToFront

void bringToFront(Figure figure)

Brings a figure to the front.

Parameters:

figure - that is part of the drawing

sort

java.util.List<Figure> sort(java.util.Collection<? extends Figure> figures)

Returns a copy of the provided collection which is sorted in z order from back to front.

addUndoableEditListener

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

Adds a listener for undooable edit events.

removeUndoableEditListener

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

Removes a listener for undoable edit events.

fireUndoableEditHappened

void fireUndoableEditHappened(javax.swing.undo.UndoableEdit edit)

Notify all listenerList that have registered interest for notification on this event type.

getFontRenderContext

java.awt.font.FontRenderContext getFontRenderContext()

Returns the font render context used to do text leyout and text drawing.

setFontRenderContext

void setFontRenderContext(java.awt.font.FontRenderContext frc)

Sets the font render context used to do text leyout and text drawing.

getLock

java.lang.Object getLock()

Returns the lock object on which all threads acting on Figures in this drawing synchronize to prevent race conditions.

addInputFormat

void addInputFormat(InputFormat format)

Adds an input format to the drawing.

addOutputFormat

void addOutputFormat(OutputFormat format)

Adds an output format to the drawing.

setInputFormats

void setInputFormats(java.util.List<InputFormat> formats)

Sets input formats for the Drawing in order of preferred formats.

The input formats are used for loading the Drawing from a file and for pasting Figures from the clipboard into the Drawing.

getInputFormats

java.util.List<InputFormat> getInputFormats()

Gets input formats for the Drawing in order of preferred formats.

setOutputFormats

void setOutputFormats(java.util.List<OutputFormat> formats)

Sets output formats for the Drawing in order of preferred formats.

The output formats are used for saving the Drawing into a file and for cutting and copying Figures from the Drawing into the clipboard.

getOutputFormats

java.util.List<OutputFormat> getOutputFormats()

Gets output formats for the Drawing in order of preferred formats.