JHotDraw 6.0b1

org.jhotdraw.standard
Class CompositeFigure

java.lang.Object
  extended by org.jhotdraw.standard.AbstractFigure
      extended by org.jhotdraw.standard.CompositeFigure
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.EventListener, Figure, FigureChangeListener, Storable
Direct Known Subclasses:
GraphicalCompositeFigure, GroupFigure, PertFigure, StandardDrawing

public abstract class CompositeFigure
extends AbstractFigure
implements FigureChangeListener

A Figure that is composed of several figures. A CompositeFigure doesn't define any layout behavior. It is up to subclassers to arrange the contained figures.


Design Patterns

 o Composite
CompositeFigure enables to treat a composition of figures like a single figure.

See Also:
Figure, Serialized Form

Field Summary
protected  int _nHighestZ
           
protected  int _nLowestZ
           
protected  java.util.List fFigures
          The figures that this figure is composed of
 
Constructor Summary
protected CompositeFigure()
           
 
Method Summary
 Figure add(Figure figure)
          Adds a figure to the list of figures.
 void addAll(FigureEnumeration fe)
          Adds a FigureEnumeration of figures.
 void addAll(java.util.List newFigures)
          Deprecated. use addAll(FigureEnumeration) instead
protected  void basicMoveBy(int x, int y)
          Moves all the given figures by x and y.
 void bringToFront(Figure figure)
          Brings a figure to the front.
 boolean containsFigure(Figure checkFigure)
          Check whether a given figure is a child figure of this CompositeFigure.
 void draw(java.awt.Graphics g)
          Draws all the contained figures
 void draw(java.awt.Graphics g, FigureEnumeration fe)
          Draws only the given figures
 Figure figureAt(int i)
          Gets a figure at the given index.
 void figureChanged(FigureChangeEvent e)
          Sent when a figure changed
 int figureCount()
          Gets number of child figures.
 void figureInvalidated(FigureChangeEvent e)
          Propagates the figureInvalidated event to my listener.
 void figureRemoved(FigureChangeEvent e)
          Sent when a figure was removed
 void figureRequestRemove(FigureChangeEvent e)
          Propagates the removeFromDrawing request up to the container.
 void figureRequestUpdate(FigureChangeEvent e)
          Propagates the requestUpdate request up to the container.
 FigureEnumeration figures()
          Returns an Enumeration for accessing the contained 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 given bounds.
 FigureEnumeration figuresReverse()
          Returns an Enumeration for accessing the contained figures in the reverse drawing order.
 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).
 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.
 Figure orphan(Figure figure)
          Removes a figure from the figure list, but doesn't release it.
 void orphanAll(FigureEnumeration fe)
           
 void orphanAll(java.util.List newFigures)
          Deprecated. use orphanAll(FigureEnumeration) instead
 void read(StorableInput dr)
          Reads the contained figures from StorableInput.
 void release()
          Releases the figure and all its children.
 Figure remove(Figure figure)
          Removes a figure from the composite.
 void removeAll()
          Removes all children.
 void removeAll(FigureEnumeration fe)
          Removes a FigureEnumeration of figures.
 void removeAll(java.util.List figures)
          Deprecated. use removeAll(FigureEnumeration) instead
 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 write(StorableOutput dw)
          Writes the contained figures to the StorableOutput.
 
Methods inherited from class org.jhotdraw.standard.AbstractFigure
addDependendFigure, addFigureChangeListener, addToContainer, basicDisplayBox, canConnect, center, changed, clone, connectedTextLocator, connectionInsets, connectorAt, connectorVisibility, containsPoint, decompose, displayBox, displayBox, displayBox, getAttribute, getAttribute, getDecoratedFigure, getDependendFigures, getTextHolder, getZValue, handles, invalidate, invalidateRectangle, isEmpty, listener, moveBy, removeDependendFigure, removeFigureChangeListener, removeFromContainer, setAttribute, setAttribute, setZValue, size, visit, willChange
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

fFigures

protected java.util.List fFigures
The figures that this figure is composed of

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

_nLowestZ

protected int _nLowestZ

_nHighestZ

protected int _nHighestZ
Constructor Detail

CompositeFigure

protected CompositeFigure()
Method Detail

add

public Figure add(Figure figure)
Adds a figure to the list of figures. Initializes the the figure's container.

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

addAll

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

Adds a list of figures.

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

addAll

public 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

public Figure remove(Figure figure)
Removes a figure from the composite.

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)
See Also:
removeAll(java.util.List)

removeAll

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

Removes a list of figures.

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

removeAll

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

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

removeAll

public void removeAll()
Removes all children.

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

orphan

public 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

public void orphanAll(java.util.List newFigures)
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

public void orphanAll(FigureEnumeration fe)

replace

public Figure replace(Figure figure,
                      Figure replacement)
Replaces a figure in the drawing without removing it from 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

public void sendToBack(Figure figure)
Sends a figure to the back of the drawing.

Parameters:
figure - that is part of the drawing

bringToFront

public void bringToFront(Figure figure)
Brings a figure to the front.

Parameters:
figure - that is part of the drawing

sendToLayer

public 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

public 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

public 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

public void draw(java.awt.Graphics g)
Draws all the contained figures

Specified by:
draw in interface Figure
Parameters:
g - the Graphics to draw into
See Also:
Figure.draw(java.awt.Graphics)

draw

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

See Also:
Figure.draw(java.awt.Graphics)

figureAt

public Figure figureAt(int i)
Gets a figure at the given index.


figures

public FigureEnumeration figures()
Returns an Enumeration for accessing the contained figures. The enumeration is a snapshot of the current contained figures and is not a "live" enumeration and does not take subsequent changes of the CompositeFigure into account. The figures are returned in the drawing order.

Specified by:
figures in interface Figure
Overrides:
figures in class AbstractFigure
See Also:
CompositeFigure

figures

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


figureCount

public int figureCount()
Gets number of child figures.


containsFigure

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


figuresReverse

public final FigureEnumeration figuresReverse()
Returns an Enumeration for accessing the contained figures in the reverse drawing order.


findFigure

public 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

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


findFigureWithout

public 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

public 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

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

Specified by:
findFigureInside in interface Figure
Overrides:
findFigureInside in class AbstractFigure
See Also:
AbstractFigure.containsPoint(int, int)

findFigureInsideWithout

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


includes

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

Specified by:
includes in interface Figure
Overrides:
includes in class AbstractFigure
Returns:
true if the figure is part of this CompositeFigure, else otherwise

basicMoveBy

protected void basicMoveBy(int x,
                           int y)
Moves all the given figures by x and y. Doesn't announce any changes. Subclassers override basicMoveBy. Clients usually call moveBy.

Specified by:
basicMoveBy in class AbstractFigure
See Also:
AbstractFigure.moveBy(int, int)

release

public void release()
Releases the figure and all its children.

Specified by:
release in interface Figure
Overrides:
release in class AbstractFigure
See Also:
Figure.release()

figureInvalidated

public void figureInvalidated(FigureChangeEvent e)
Propagates the figureInvalidated event to my listener.

Specified by:
figureInvalidated in interface FigureChangeListener
See Also:
FigureChangeListener

figureRequestRemove

public void figureRequestRemove(FigureChangeEvent e)
Propagates the removeFromDrawing request up to the container.

Specified by:
figureRequestRemove in interface FigureChangeListener
See Also:
FigureChangeListener

figureRequestUpdate

public void figureRequestUpdate(FigureChangeEvent e)
Propagates the requestUpdate request up to the container.

Specified by:
figureRequestUpdate in interface FigureChangeListener
See Also:
FigureChangeListener

figureChanged

public void figureChanged(FigureChangeEvent e)
Description copied from interface: FigureChangeListener
Sent when a figure changed

Specified by:
figureChanged in interface FigureChangeListener

figureRemoved

public void figureRemoved(FigureChangeEvent e)
Description copied from interface: FigureChangeListener
Sent when a figure was removed

Specified by:
figureRemoved in interface FigureChangeListener

write

public void write(StorableOutput dw)
Writes the contained figures to the StorableOutput.

Specified by:
write in interface Storable
Overrides:
write in class AbstractFigure

read

public void read(StorableInput dr)
          throws java.io.IOException
Reads the contained figures from StorableInput.

Specified by:
read in interface Storable
Overrides:
read in class AbstractFigure
Throws:
java.io.IOException

init

public 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. Don't forget to call this after loading or creating a new CompositeFigure. If you forget, drawing performance may suffer.


JHotDraw 6.0b1