/*
 * @(#)Drawing.java
 *
 * Copyright (c) 1996-2010 by the original authors of JHotDraw and all its
 * contributors. All rights reserved.
 *
 * You may not use, copy or modify this file, except in compliance with the 
 * license agreement you entered into with the copyright holders. For details
 * see accompanying license terms.
 */
package org.jhotdraw.draw;

import edu.umd.cs.findbugs.annotations.Nullable;
import java.awt.Graphics2D;
import org.jhotdraw.draw.io.InputFormat;
import org.jhotdraw.draw.io.OutputFormat;
import org.jhotdraw.xml.*;

import java.awt.font.*;
import java.awt.geom.*;
import java.util.*;
import javax.swing.undo.*;
import javax.swing.event.*;
import java.io.*;

/**
 * A drawing is a container for {@link Figure}s. 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 {@link DrawingView}s.
 * 

* {@code Drawing} is essentially a {@link CompositeFigure} with a number of * additional functionality: *

* *
* Design Patterns * *

Framework
* The following interfaces define the contracts of a framework for structured * drawing editors:
* Contract: {@link Drawing}, {@link Figure}, {@link DrawingView}, * {@link DrawingEditor}, {@link org.jhotdraw.draw.handle.Handle} and * {@link org.jhotdraw.draw.tool.Tool}. * *

Model-View-Controller
* The following classes implement together the Model-View-Controller design * pattern:
* Model: {@link Drawing}; View: {@link DrawingView}; Controller: * {@link DrawingEditor}. * *

Strategy
* {@code org.jhotdraw.draw.io.OutputFormat} encapsulates a strategy for writing drawings to * output streams.
* Strategy: {@link org.jhotdraw.draw.io.OutputFormat}; Context: {@link Drawing}. * *

Strategy
* {@code org.jhotdraw.draw.io.InputFormat} encapsulates a strategy for * reading drawings from input streams.
* Strategy: {@link org.jhotdraw.draw.io.InputFormat}; Context: {@link Drawing}. *


* * @author Werner Randelshofer * @version $Id: Drawing.java 717 2010-11-21 12:30:57Z rawcoder $ */ public interface Drawing extends CompositeFigure, Serializable, DOMStorable { /** 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 {@link DrawingView}. *

* {@link AttributeKeys} defines a number of attribute keys which can be * used to determine what to draw on the canvas. */ public void drawCanvas(Graphics2D g); /** * Adds a figure to the drawing. * The drawing sends an {@code addNotify} message to the figure * after it has been added. * * @see Figure#addNotify * * @param figure to be added to the drawing */ @Override boolean add(Figure figure); /** * Adds a figure to the drawing. * The drawing sends an {@code addNotify} message to the figure * after it has been added. * * @see Figure#addNotify * * @param index The z-index of the figure. * @param figure to be added to the drawing */ @Override void add(int index, Figure figure); /** * Adds a collection of figures to the drawing. * The drawing sends an {@code addNotify} message to each figure * after it has been added. * * @see Figure#addNotify * * @param figures to be added to the drawing */ void addAll(Collection figures); /** * Adds a collection of figures to the drawing. * The drawing sends an {@code addNotify} message to each figure * after it has been added. * * @see Figure#addNotify * * @param index The z-index of the figure. * @param figures to be added to the drawing */ void addAll(int index, Collection figures); /** * Removes a figure from the drawing. * The drawing sends a {@code removeNotify} message to the figure * before it is removed. * * @see Figure#removeNotify * * @param figure that is part of the drawing and should be removed */ @Override boolean remove(Figure figure); /** * Removes the specified figures from the drawing. * The drawing sends a {@code removeNotify} message to each figure * before it is removed. * * @see Figure#removeNotify * * @param figures A collection of figures which are part of the drawing * and should be removed */ void removeAll(Collection figures); /** * Removes a figure temporarily from the drawing. * * @see #basicAdd(Figure) * * @param figure that is part of the drawing and should be removed */ @Override int basicRemove(Figure figure); /** * Removes the specified figures temporarily from the drawing. * * @see #basicAddAll(int, Collection) * @param figures A collection of figures which are part of the drawing * and should be removed */ void basicRemoveAll(Collection figures); /** * Reinserts a figure which was temporarily removed using basicRemove. *

* This is a convenience method for calling * {@code basicAdd(size(), figure)}. * * @param figure that is part of the drawing and should be removed * @see #basicRemove(Figure) */ @Override void basicAdd(Figure figure); /** * Reinserts a figure which was temporarily removed using basicRemove. * * @see #basicRemove(Figure) * @param figure that is part of the drawing and should be removed */ @Override void basicAdd(int index, Figure figure); /** * Reinserts the specified figures which were temporarily removed from * the drawing. * * * @param index The insertion index. * @param figures A collection of figures which are part of the drawing * and should be reinserted. * @see #basicRemoveAll(Collection) */ void basicAddAll(int index, Collection figures); /** * Returns all figures that lie within or intersect the specified * bounds. The figures are returned in Z-order from back to front. */ List

findFigures(Rectangle2D.Double bounds); /** * Returns all figures that lie within the specified * bounds. The figures are returned in Z-order from back to front. */ List
findFiguresWithin(Rectangle2D.Double bounds); /** * Finds a top level Figure. Use this call for hit detection that * should not descend into children of composite figures. *

* Use {@link #findFigureInside} If you need to descend into children of * composite figures. */ @Nullable Figure findFigure(Point2D.Double p); /** * Finds a top level Figure. Use this call for hit detection that * should not descend into the figure's children. */ @Nullable Figure findFigureExcept(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. */ @Nullable Figure findFigureExcept(Point2D.Double p, Collection ignore); /** * Finds a top level Figure which is behind the specified Figure. */ @Nullable Figure findFigureBehind(Point2D.Double p, Figure figure); /** * Finds a top level Figure which is behind the specified Figures. */ @Nullable Figure findFigureBehind(Point2D.Double p, Collection figures); /** * Returns a list of the figures in Z-Order from front to back. */ List

getFiguresFrontToBack(); /** * Finds the innermost figure at the specified location. *

* In case a {@code 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 {@code Figure} interface. * Since it is often used from a drawing object as the starting point, * and since {@code Drawing} defines other find methods as well, it is * defined here again for clarity. * * @param p A location on the drawing. * @return Returns the innermost figure at the location, or null if the * location is not contained in a figure. */ @Override @Nullable Figure findFigureInside(Point2D.Double p); /** * Sends a figure to the back of the drawing. * * @param figure that is part of the drawing */ void sendToBack(Figure figure); /** * Brings a figure to the front. * * @param figure that is part of the drawing */ void bringToFront(Figure figure); /** * Returns a copy of the provided collection which is sorted * in z order from back to front. */ List

sort(Collection figures); /** * Adds a listener for undooable edit events. */ void addUndoableEditListener(UndoableEditListener l); /** * Removes a listener for undoable edit events. */ void removeUndoableEditListener(UndoableEditListener l); /** * Notify all listenerList that have registered interest for * notification on this event type. */ void fireUndoableEditHappened(UndoableEdit edit); /** * Returns the font render context used to do text leyout and text drawing. */ FontRenderContext getFontRenderContext(); /** * Sets the font render context used to do text leyout and text drawing. */ void setFontRenderContext(FontRenderContext frc); /** * Returns the lock object on which all threads acting on Figures in this * drawing synchronize to prevent race conditions. */ Object getLock(); /** * Adds an input format to the drawing. */ void addInputFormat(InputFormat format); /** * Adds an output format to the drawing. */ void addOutputFormat(OutputFormat format); /** * 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. */ void setInputFormats(List formats); /** * Gets input formats for the Drawing in order of preferred formats. */ List getInputFormats(); /** * 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. */ void setOutputFormats(List formats); /** * Gets output formats for the Drawing in order of preferred formats. */ List getOutputFormats(); }

Ads help maintain this website.