bundles/org.simantics.g2d/src/org/simantics/g2d/diagram/IDiagram.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.g2d.diagram;
  13
  14 import java.util.Comparator;
  15 import java.util.List;
  16
  17 import org.simantics.g2d.diagram.impl.Diagram;
  18 import org.simantics.g2d.diagram.participant.ZOrderHandler;
  19 import org.simantics.g2d.element.IElement;
  20 import org.simantics.utils.datastructures.hints.IHintContext;
  21
  22 /**
  23  * Diagram is a flat ordered composition of elements.
  24  * <p>
  25  * Diagram may only be accessed from canvas thread.
  26  * <p>
  27  * Diagram variables are persistent.
  28  * <p>
  29  * Elements are ordered according to their z-value
  30  *
  31  * @see Diagram Default implementation
  32  * @see IElement
  33  * @see ZOrderHandler
  34  * @author Toni Kalajainen
  35  */
  36 public interface IDiagram extends IHintContext {
  37
  38     public interface CompositionVetoListener {
  39         /**
  40          * Invoked before an element is actually added on to a diagram. This
  41          * provides the possibility to veto the addition by returning
  42          * <code>false</code>.
  43          *
  44          * @param d the diagram to be changed
  45          * @param e the element to be added
  46          * @return <code>true</code> to allow the addition or <code>false</code>
  47          *         to veto the addition
  48          */
  49         boolean beforeElementAdded(IDiagram d, IElement e);
  50
  51         /**
  52          * Invoked before an element is actually removed from a diagram. This
  53          * provides the possibility to veto the addition by returning
  54          * <code>false</code>.
  55          *
  56          * @param d the diagram to be changed
  57          * @param e the element to be removed
  58          * @return <code>true</code> to allow the removal or <code>false</code>
  59          *         to veto the removal
  60          */
  61         boolean beforeElementRemoved(IDiagram d, IElement e);
  62     }
  63
  64     public interface CompositionListener {
  65         /**
  66          * @param d
  67          * @param e
  68          */
  69         void onElementAdded(IDiagram d, IElement e);
  70
  71         /**
  72          * @param d
  73          * @param e
  74          */
  75         void onElementRemoved(IDiagram d, IElement e);
  76     }
  77
  78     /**
  79      * Add a composition listener that can veto element addition/removal
  80      * @param listener
  81      */
  82     void addCompositionVetoListener(CompositionVetoListener listener);
  83     /**
  84      * Remove composition veto listener
  85      * @param listener
  86      */
  87     void removeCompositionVetoListener(CompositionVetoListener listener);
  88
  89     /**
  90      * Add a composition listener that notifies about element composition
  91      * @param listener
  92      */
  93     void addCompositionListener(CompositionListener listener);
  94     /**
  95      * Remove composition listener
  96      * @param listener
  97      */
  98     void removeCompositionListener(CompositionListener listener);
  99
 100     /**
 101      * Get diagram class
 102      * @return diagram class
 103      */
 104     DiagramClass getDiagramClass();
 105
 106     /**
 107      * Get a snapshot of elements. The list is z-ordered, where
 108      * top most elements are at the end of the list.
 109      * @return a snapshot of elements
 110      */
 111     List<IElement> getSnapshot();
 112
 113     /**
 114      * Get z-ordered list of the elements. The return value is not intended for
 115      * direct modification.
 116      *
 117      * @return
 118      */
 119     List<IElement> getElements();
 120
 121     /**
 122      * Reorder the contained diagram elements using the specified comparator.
 123      *
 124      * @param comparator
 125      */
 126     void sort(Comparator<IElement> comparator);
 127
 128     /**
 129      * Add an element to the diagram.
 130      *
 131      * @param element the element to add
 132      * @return element of class
 133      */
 134     void addElement(IElement element);
 135
 136     /**
 137      * Checks if a diagram contains an element.
 138      * @return true if diagram contains the element.
 139      */
 140     boolean containsElement(IElement element);
 141
 142     /**
 143      * Remove an element from the diagram
 144      * @param element element to remove
 145      */
 146     void removeElement(IElement element);
 147
 148     /**
 149      * Destroy the diagram from the world permanently.
 150      * Destroys all contained elements as well.
 151      */
 152     void destroy();
 153     void dispose();
 154
 155     // Z-Order
 156     boolean bringUp(IElement e);
 157     boolean sendDown(IElement e);
 158     boolean bringToTop(IElement e);
 159     boolean sendToBottom(IElement e);
 160
 161     /**
 162      * @param e
 163      * @param position
 164      * @return <code>true</code> if the position changed
 165      */
 166     boolean moveTo(IElement e, int position);
 167
 168 }