/* $Id: ArgoDiagram.java 17850 2010-01-12 19:53:35Z linus $

  *****************************************************************************

  * Copyright (c) 2009 Contributors - see below

  * All rights reserved. This program and the accompanying materials

  * are made available under the terms of the Eclipse Public License v1.0

  * which accompanies this distribution, and is available at

  * http://www.eclipse.org/legal/epl-v10.html

  *

  * Contributors:

  *    bobtarling

  *****************************************************************************

  *

  * Some portions of this file was previously release using the BSD License:

  */

 // Copyright (c) 2007-2008 The Regents of the University of California. All

 // Rights Reserved. Permission to use, copy, modify, and distribute this

 // software and its documentation without fee, and without a written

 // agreement is hereby granted, provided that the above copyright notice

 // and this paragraph appear in all copies. This software program and

 // documentation are copyrighted by The Regents of the University of

 // California. The software program and documentation are supplied "AS

 // IS", without any accompanying services from The Regents. The Regents

 // does not warrant that the operation of the program will be

 // uninterrupted or error-free. The end-user understands that the program

 // was developed for research purposes and is advised not to rely

 // exclusively on the program for any reason. IN NO EVENT SHALL THE

 // UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,

 // SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,

 // ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF

 // THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF

 // SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY

 // WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE

 // PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF

 // CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,

 // UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

 package org.argouml.uml.diagram;

 import java.awt.Rectangle;

 import java.beans.PropertyChangeEvent;

 import java.beans.PropertyChangeListener;

 import java.beans.PropertyVetoException;

 import java.beans.VetoableChangeListener;

 import java.util.Iterator;

 import java.util.List;

 import org.argouml.application.events.ArgoDiagramAppearanceEventListener;

 import org.argouml.application.events.ArgoNotationEventListener;

 import org.argouml.kernel.Project;

 import org.argouml.util.ItemUID;

 import org.tigris.gef.base.LayerPerspective;

 import org.tigris.gef.graph.GraphModel;

 import org.tigris.gef.presentation.Fig;

 import org.tigris.gef.presentation.FigNode;

 /**

  * An interface to decouple ArgoUML from GEF and to untangle the Project <->

  * ArgoDiagram ball of string.

  * <p>

  * Although this interface is implemented by {@link ArgoDiagramImpl}, it does

  * <em>NOT</em> extend any GEF interfaces (since GEF is made up entirely of

  * concrete classes), so any new methods which are added to

  * {@link org.tigris.gef.base.Diagram} and which are needed by ArgoUML will need

  * to be added to this interface manually.

  * 

  * @author Tom Morris <tfmorris@gmail.com>

  * @since 0.25.4 when it replaced the implementation class of the same name

  */

 public interface ArgoDiagram extends ArgoNotationEventListener,

     ArgoDiagramAppearanceEventListener {

     /**

      * Set the rendering settings for this diagram.

      * 

      * @param settings the new diagram settings

      */

     public void setDiagramSettings(DiagramSettings settings);

     /**

      * @return the current DiagramSettings object

      */

     public DiagramSettings getDiagramSettings();

     /*

      * @see org.tigris.gef.base.Diagram#setName(java.lang.String)

      */

     public void setName(String n) throws PropertyVetoException;

     /**

      * @param i the new id

      */

     public void setItemUID(ItemUID i);

     /**

      * USED BY pgml.tee!!

      * @return the item UID

      */

     public ItemUID getItemUID();

     /**

      * The bean property name denoting the diagram's namespace. Value is a

      * String.

      */

     public static final String NAMESPACE_KEY = "namespace";

     /**

      * The bean property name denoting the diagram's name. Value is a

      * String.

      */

     public static final String NAME_KEY = "name";

     /**

      * TODO: The reference to the method

      * org.argouml.uml.ui.VetoablePropertyChange#getVetoMessage(String)

      * was here but the class does exist anymore. Where is it?

      * This method is never used!

      *

      * @param propertyName is the name of the property

      * @return a message or null if not applicable.

      */

     public String getVetoMessage(String propertyName);

     /**

      * Finds the presentation (the Fig) for some object. If the object

      * is a modelelement that is contained in some other modelelement

      * that has its own fig, that fig is returned. It extends

      * presentationFor that only gets the fig belonging to the node

      * obj.<p>

      *

      * @author jaap.branderhorst@xs4all.nl

      * @return the Fig for the object

      * @param obj is th object

      */

     public Fig getContainingFig(Object obj);

     /**

      * This will mark the entire visible area of all Editors to be repaired

      *  from any damage - i.e. repainted.

      */

     public void damage();

     /**

      * Get all the model elements in this diagram that are represented

      * by a FigEdge.

      * @see org.tigris.gef.base.Diagram#getEdges()

      */

     public List getEdges();

     /**

      * Get all the model elements in this diagram that are represented

      * by a FigNode.

      * @see org.tigris.gef.base.Diagram#getNodes()

      */

     public List getNodes();

     /**

      * We hang our heads in shame. There are still bugs in ArgoUML

      * and/or GEF that cause corruptions in the model.

      * Before a save takes place we repair the model in order to

      * be as certain as possible that the saved file will reload.

      * TODO: Split into small inner classes for each fix.

      *

      * @return A text that explains what is repaired.

      */

     public String repair();

     /**

      * Find all the Figs that visualise the given model element in

      * this layer, or null if there is none.

      * 

      * TODO: once GEF includes this same method in Diagram then this can go

      * 

      * @see org.tigris.gef.base.Diagram#presentationsFor(java.lang.Object)

      */

     public List presentationsFor(Object obj);

     /**

      * Remove this diagram from existence.

      * 

      * TODO: Move to GEF

      */

     public void remove();

     /**

      * Keeps track of the project that contains this diagram. 

      * The Project determines many settings that reflect 

      * the way the diagram is painted, such as font size.

      * 

      * @param p the project that contains this diagram

      */

     public void setProject(Project p);

     /**

      * @return the Project which owns this diagram

      */

     public Project getProject();

     /**

      * Called when the user releases a dragged FigNode.

      * 

      * @param enclosed the enclosed FigNode that was dragged into the encloser

      * @param oldEncloser the previous encloser

      * @param newEncloser the FigNode that encloses the dragged FigNode

      */

     public void encloserChanged(FigNode enclosed, FigNode oldEncloser,

             FigNode newEncloser);

     /**

      * This method shall return any UML modelelements

      * that should be deleted when the diagram gets deleted,

      * or null if there are none. The default implementation returns null;

      * e.g. a statechart diagram should return its statemachine.

      *

      * @author mvw@tigris.org

      *

      * @return the dependent element - in the general case there aren't, so null

      */

     public Object getDependentElement();

     /**

      * TODO: MVW: I am not completely sure of the following:<p>

      * The "namespace" of the diagram is e.g. used when creating new elements

      * that are shown on the diagram; they will have their namespace set

      * according this. It is NOT necessarily equal to the "owner". 

      * 

      * @return the namespace for the diagram

      */

     public Object getNamespace();

     /**

      * Sets the namespace of the Diagram, and

      * adds the diagram as a listener of its namespace in the UML model

      * (so that it can delete itself when the model element is deleted).

      *

      * @param ns the namespace for the diagram

      */

     public void setNamespace(Object ns);

     /**

      * Set the namespace of a model element to the owner of

      * the given namespace. If the namespace is null

      * the namespace of the diagram is used instead.

      * If the modelElement is not valid in the given namespace

      * this method takes no action.

      * @param modelElement the model element

      * @param ns the namespace

      */

     public void setModelElementNamespace(Object modelElement, Object ns);

     /**

      * This diagram listens to events from its namespace ModelElement;

      * when the modelelement is removed, we also want to delete this

      * diagram.  <p>

      *

      * There is also a risk that if this diagram was the one shown in

      * the diagram panel, then it will remain after it has been

      * deleted. So we need to deselect this diagram. 

      * There are other things to take care of, so all this is delegated to 

      * {@link org.argouml.kernel.Project#moveToTrash(Object)}.

      * 

      * @param evt A PropertyChangeEvent object describing the event source

      * and the property that has changed.

      *

      * @see PropertyChangeListener#propertyChange(PropertyChangeEvent)

      */

     public void propertyChange(PropertyChangeEvent evt);

     /**

      * The owner of a diagram is the modelelement that is saved

      * with the project in the pgml file, and binds it to the model. <p>

      * 

      * This value is shown in the diagram's properties panel

      * as the "Home model".

      *

      * @return the home model

      */

     public Object getOwner();

     /**

      * @return an iterator which iterates over all Figs in Diagram

      */

     public Iterator<Fig> getFigIterator();

     /**

      * Create a diagram element suitable for the base diagram type

      * @param modelElement the model element the diagram element

      * will represent

      * @param bounds the bounds of the newly created diagram element

      * @return the newly created diagram element.

      */

     public DiagramElement createDiagramElement(

             final Object modelElement,

             final Rectangle bounds);

     ///////////////// GEF Methods ////////////////////////////

     // TODO: These should really be picked up automatically from

     // some GEF interface that we extend, but there is no such

     // thing.  NOTE: We've only added methods used by ArgoUML,

     // so it's possible that external consumers need other methods.

     /**

      * @param listener

      * @see org.tigris.gef.base.Diagram#addVetoableChangeListener(VetoableChangeListener)

      */

     public void addVetoableChangeListener(VetoableChangeListener listener);

     /**

      * @param listener

      * @see org.tigris.gef.base.Diagram#removeVetoableChangeListener(VetoableChangeListener)

      */

     public void removeVetoableChangeListener(VetoableChangeListener listener);

     /**

      * @param property

      * @param listener

      * @see org.tigris.gef.base.Diagram#addPropertyChangeListener(String, PropertyChangeListener)

      */

     public void addPropertyChangeListener(String property,

             PropertyChangeListener listener);

     /**

      * @param property

      * @param listener

      * @see org.tigris.gef.base.Diagram#removePropertyChangeListener(String, PropertyChangeListener)

      */

     public void removePropertyChangeListener(String property,

             PropertyChangeListener listener);

     /**

      * @return the GEF graphmodel for this diagram

      * @see org.tigris.gef.base.Diagram#getGraphModel()

      */

     public GraphModel getGraphModel();

     /**

      * @return the GEF LayerPerspective of this diagram

      * @see org.tigris.gef.base.Diagram#getLayer()

      */

     public LayerPerspective getLayer();

     /**

      * @param figures list of Figures to check for in diagram

      * @return count of figures contained in this diagram

      * @see org.tigris.gef.base.Diagram#countContained(List)

      */

     public int countContained(List figures);

     /**

      * @param o The object which owns the fig

      * @return the corresponding fig

      * @see org.tigris.gef.base.Diagram#presentationFor(Object)

      */

     public Fig presentationFor(Object o);

     /**

      * @param f Fig to be added

      * @see org.tigris.gef.base.Diagram#add(Fig)

      */

     public void add(Fig f);

     /**

      * Used by "argo.tee".

      * 

      * @return the name of the diagram

      * @see org.tigris.gef.base.Diagram#getName()

      */

     public String getName();

     /**

      * Perform any pre-save actions.

      * @see org.tigris.gef.base.Diagram#preSave()

      */

     public void preSave();

     /**

      * Perform any post-save actions.

      * @see org.tigris.gef.base.Diagram#postSave()

      */

     public void postSave();

     /**

      * Perform any post-load actions.

      * @see org.tigris.gef.base.Diagram#postLoad()

      */

     public void postLoad();

     /////////////////// End GEF methods ////////////////////////

 }