JHotDraw 6.0b1

org.jhotdraw.framework
Interface Drawing

All Superinterfaces:
java.util.EventListener, FigureChangeListener, java.io.Serializable, Storable
All Known Implementing Classes:
BouncingDrawing, StandardDrawing

public interface Drawing
extends Storable, FigureChangeListener, java.io.Serializable

Drawing is a container for figures.

Drawing sends out DrawingChanged events to DrawingChangeListeners whenever a part of its area was invalidated.


Design Patterns

 o Observer
The Observer pattern is used to decouple the Drawing from its views and to enable multiple views.


See Also:
Figure, DrawingView, FigureChangeListener

Method Summary
 Figure add(Figure figure)
          Adds a figure and sets its container to refer to this drawing.
 void addAll(FigureEnumeration fe)
          Adds a FigureEnumeration of figures.
 void addAll(java.util.List newFigures)
          Deprecated. use addAll(FigureEnumeration) instead
 void addDrawingChangeListener(DrawingChangeListener listener)
          Adds a listener for this drawing.
 void bringToFront(Figure figure)
          Brings a figure to the front.
 boolean containsFigure(Figure figure)
          Check whether a given figure is a (direct) child figure of this CompositeFigure.
 void draw(java.awt.Graphics g)
          Draws all the figures back to front.
 void draw(java.awt.Graphics g, FigureEnumeration fe)
          Draws only the given figures.
 java.util.Iterator drawingChangeListeners()
          Gets the listeners of a drawing.
 FigureEnumeration figures()
          Returns an enumeration to iterate in Z-order back to front over the figures.
 FigureEnumeration figures(java.awt.Rectangle viewRectangle)
          Returns an enumeration to iterate in Z-order back to front over the figures that lie within the absolute bounds.
 FigureEnumeration figuresReverse()
          Returns an enumeration to iterate in Z-order front to back over the figures.
 Figure findFigure(int x, int y)
          Finds a top level Figure.
 Figure findFigure(java.awt.Rectangle r)
          Finds a top level Figure that intersects the given rectangle.
 Figure findFigure(java.awt.Rectangle r, Figure without)
          Finds a top level Figure that intersects the given rectangle.
 Figure findFigureInside(int x, int y)
          Finds a figure but descends into a figure's children.
 Figure findFigureInsideWithout(int x, int y, Figure without)
          Finds a figure but descends into a figure's children.
 Figure findFigureWithout(int x, int y, Figure without)
          Finds a top level Figure, but supresses the passed in figure.
 Figure getFigureFromLayer(int layerNr)
          Gets the figure from a certain layer.
 int getLayer(Figure figure)
          Gets the layer for a certain figure (first occurrence).
 java.lang.String getTitle()
           
 boolean includes(Figure figure)
          Checks if the composite figure has the argument as one of its children.
 void init(java.awt.Rectangle viewRectangle)
          Used to optimize rendering.
 void lock()
          Acquires the drawing lock.
 Figure orphan(Figure figure)
          Removes a figure from the figure list, but doesn't release it.
 void orphanAll(FigureEnumeration fe)
          Removes a FigureEnumeration of figures from the figure's list without releasing the figures.
 void orphanAll(java.util.List orphanFigures)
          Deprecated. use orphanAll(FigureEnumeration) instead
 void release()
          Releases the drawing and its contained figures.
 Figure remove(Figure figure)
          Removes the figure from the drawing and releases it.
 void removeAll(FigureEnumeration fe)
          Removes a FigureEnumeration of figures.
 void removeAll(java.util.List figures)
          Deprecated. use removeAll(FigureEnumeration) instead
 void removeDrawingChangeListener(DrawingChangeListener listener)
          Removes a listener from this drawing.
 Figure replace(Figure figure, Figure replacement)
          Replaces a figure in the drawing without removing it from the drawing.
 void sendToBack(Figure figure)
          Sends a figure to the back of the drawing.
 void sendToLayer(Figure figure, int layerNr)
          Sends a figure to a certain layer within a drawing.
 void setTitle(java.lang.String name)
           
 void unlock()
          Releases the drawing lock.
 
Methods inherited from interface org.jhotdraw.util.Storable
read, write
 
Methods inherited from interface org.jhotdraw.framework.FigureChangeListener
figureChanged, figureInvalidated, figureRemoved, figureRequestRemove, figureRequestUpdate
 

Method Detail

release

void release()
Releases the drawing and its contained figures.


figures

FigureEnumeration figures()
Returns an enumeration to iterate in Z-order back to front over the figures.


figures

FigureEnumeration figures(java.awt.Rectangle viewRectangle)
Returns an enumeration to iterate in Z-order back to front over the figures that lie within the absolute bounds.


figuresReverse

FigureEnumeration figuresReverse()
Returns an enumeration to iterate in Z-order front to back over the figures.


findFigure

Figure findFigure(int x,
                  int y)
Finds a top level Figure. Use this call for hit detection that should not descend into the figure's children.


findFigure

Figure findFigure(java.awt.Rectangle r)
Finds a top level Figure that intersects the given rectangle.


findFigureWithout

Figure findFigureWithout(int x,
                         int y,
                         Figure without)
Finds a top level Figure, but supresses the passed in figure. Use this method to ignore a figure that is temporarily inserted into the drawing.

Parameters:
x - the x coordinate
y - the y coordinate
without - the figure to be ignored during the find.

findFigure

Figure findFigure(java.awt.Rectangle r,
                  Figure without)
Finds a top level Figure that intersects the given rectangle. It supresses the passed in figure. Use this method to ignore a figure that is temporarily inserted into the drawing.


findFigureInside

Figure findFigureInside(int x,
                        int y)
Finds a figure but descends into a figure's children. Use this method to implement click-through hit detection, that is, you want to detect the inner most figure containing the given point.


findFigureInsideWithout

Figure findFigureInsideWithout(int x,
                               int y,
                               Figure without)
Finds a figure but descends into a figure's children. It supresses the passed in figure. Use this method to ignore a figure that is temporarily inserted into the drawing.

Parameters:
x - the x coordinate
y - the y coordinate
without - the figure to be ignored during the find.

includes

boolean includes(Figure figure)
Checks if the composite figure has the argument as one of its children.

Parameters:
figure - figure to be searched in all descendants
Returns:
true if the figure is part of this Drawing, else otherwise

containsFigure

boolean containsFigure(Figure figure)
Check whether a given figure is a (direct) child figure of this CompositeFigure.

Parameters:
figure - figure to be searched in all direct descendents
Returns:
true if the figure is a direct child of this Drawing, else otherwise

addDrawingChangeListener

void addDrawingChangeListener(DrawingChangeListener listener)
Adds a listener for this drawing.


removeDrawingChangeListener

void removeDrawingChangeListener(DrawingChangeListener listener)
Removes a listener from this drawing.


drawingChangeListeners

java.util.Iterator drawingChangeListeners()
Gets the listeners of a drawing.

Returns:
new iterator of all registered change listener

add

Figure add(Figure figure)
Adds a figure and sets its container to refer to this drawing.

Parameters:
figure - to be added to the drawing
Returns:
the figure that was inserted (might be different from the figure specified).

addAll

void addAll(java.util.List newFigures)
Deprecated. use addAll(FigureEnumeration) instead

Adds a list of figures.


addAll

void addAll(FigureEnumeration fe)
Adds a FigureEnumeration of figures.

Parameters:
fe - (unused) enumeration containing all figures to be added
See Also:
add(org.jhotdraw.framework.Figure)

remove

Figure remove(Figure figure)
Removes the figure from the drawing and releases it.

Parameters:
figure - that is part of the drawing and should be removed
Returns:
the figure that has been removed (might be different from the figure specified)

orphan

Figure orphan(Figure figure)
Removes a figure from the figure list, but doesn't release it. Use this method to temporarily manipulate a figure outside of the drawing.

Parameters:
figure - that is part of the drawing and should be added

orphanAll

void orphanAll(java.util.List orphanFigures)
Deprecated. use orphanAll(FigureEnumeration) instead

Removes a list of figures from the figure's list without releasing the figures.

See Also:
orphan(org.jhotdraw.framework.Figure)

orphanAll

void orphanAll(FigureEnumeration fe)
Removes a FigureEnumeration of figures from the figure's list without releasing the figures.

See Also:
orphan(org.jhotdraw.framework.Figure)

removeAll

void removeAll(java.util.List figures)
Deprecated. use removeAll(FigureEnumeration) instead

Removes a list of figures .

See Also:
remove(org.jhotdraw.framework.Figure)

removeAll

void removeAll(FigureEnumeration fe)
Removes a FigureEnumeration of figures.

See Also:
remove(org.jhotdraw.framework.Figure)

replace

Figure replace(Figure figure,
               Figure replacement)
Replaces a figure in the drawing without removing it from the drawing. The figure to be replaced must be part of the drawing.

Parameters:
figure - figure to be replaced
replacement - figure that should replace the specified figure
Returns:
the figure that has been inserted (might be different from the figure specified)

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

sendToLayer

void sendToLayer(Figure figure,
                 int layerNr)
Sends a figure to a certain layer within a drawing. Each figure lays in a unique layer and the layering order decides which figure is drawn on top of another figure. Figures with a higher layer number have usually been added later and may overlay figures in lower layers. Layers are counted from to (the number of figures - 1). The figure is removed from its current layer (if it has been already part of this drawing) and is transferred to the specified layers after all figures between the original layer and the new layer are shifted to one layer below to fill the layer sequence. It is not possible to skip a layer number and if the figure is sent to a layer beyond the latest layer it will be added as the last figure to the drawing and its layer number will be set to the be the one beyond the latest layer so far.

Parameters:
figure - figure to be sent to a certain layer
layerNr - target layer of the figure

getLayer

int getLayer(Figure figure)
Gets the layer for a certain figure (first occurrence). The number returned is the number of the layer in which the figure is placed.

Parameters:
figure - figure to be queried for its layering place
Returns:
number of the layer in which the figure is placed and -1 if the figure could not be found.
See Also:
sendToLayer(org.jhotdraw.framework.Figure, int)

getFigureFromLayer

Figure getFigureFromLayer(int layerNr)
Gets the figure from a certain layer.

Parameters:
layerNr - number of the layer which figure should be returned
Returns:
figure from the layer specified, null, if the layer nr was outside the number of possible layer (0...(number of figures - 1))
See Also:
sendToLayer(org.jhotdraw.framework.Figure, int)

draw

void draw(java.awt.Graphics g)
Draws all the figures back to front.


draw

void draw(java.awt.Graphics g,
          FigureEnumeration fe)
Draws only the given figures.


lock

void lock()
Acquires the drawing lock.


unlock

void unlock()
Releases the drawing lock.


init

void init(java.awt.Rectangle viewRectangle)
Used to optimize rendering. Rendering of many objects may be slow until this method is called. The view rectangle should at least approximately enclose the CompositeFigure. If the view rectangle is too small or too large, performance may suffer.


getTitle

java.lang.String getTitle()

setTitle

void setTitle(java.lang.String name)

JHotDraw 6.0b1