001/*
002@Copyright (c) 2010-2016 The Regents of the University of California.
003All rights reserved.
004
005Permission is hereby granted, without written agreement and without
006license or royalty fees, to use, copy, modify, and distribute this
007software and its documentation for any purpose, provided that the
008above copyright notice and the following two paragraphs appear in all
009copies of this software.
010
011IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015SUCH DAMAGE.
016
017THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022ENHANCEMENTS, OR MODIFICATIONS.
023
024                                                PT_COPYRIGHT_VERSION_2
025                                                COPYRIGHTENDKEY
026
027
028 */
029package ptolemy.vergil.actor;
030
031import diva.graph.GraphController;
032import ptolemy.kernel.util.IllegalActionException;
033import ptolemy.kernel.util.NameDuplicationException;
034import ptolemy.kernel.util.NamedObj;
035import ptolemy.vergil.toolbox.FigureAction;
036
037/**
038 * An interface for defining additional gui interaction for specific actor types.
039 * Once the interface is implemented, it can be used by adding an
040 * _actorInteractionAddon parameter to the configuration and setting the value
041 * to the name of the class that implements this interface.
042 *
043 * @author Lyle Holsinger
044 * @since Ptolemy II 10.0
045 * @version $Id$
046 * @Pt.ProposedRating red (lholsing)
047 * @Pt.AcceptedRating red (lholsing)
048 */
049public interface ActorInteractionAddon {
050
051    /** Determine of a given actor is of interest for a desired action.
052     *
053     * @param actor The actor of interest.
054     * @return True if the actor is of interest for the "Look Inside" action for
055     * actors, False otherwise.
056     */
057    abstract boolean isActorOfInterestForLookInside(NamedObj actor);
058
059    /**
060     * The action to be taken when looking inside an actor.
061     * @param figureAction The FigureAction from which the call is being made.
062     * @param actor The actor being opened.
063     * @exception IllegalActionException If the container is incompatible
064     *   with this attribute.
065     * @exception NameDuplicationException If the name coincides with
066     *   an attribute already in the container.
067     */
068    abstract void lookInsideAction(FigureAction figureAction, NamedObj actor)
069            throws IllegalActionException, NameDuplicationException;
070
071    /** Determine of a given actor is of interest for a desired action.
072     *
073     * @param actor The actor of interest.
074     * @return True if the actor is of interest for the "Open Instance" action for
075     * actors, False otherwise.
076     */
077    abstract boolean isActorOfInterestForOpenInstance(NamedObj actor);
078
079    /**
080     * The action to be taken when looking inside an actor.
081     * @param figureAction The FigureAction from which the call is being made.
082     * @param actor The actor being opened.
083     * @exception IllegalActionException If the container is incompatible
084     *   with this attribute.
085     * @exception NameDuplicationException If the name coincides with
086     *   an attribute already in the container.
087     */
088    abstract void openInstanceAction(FigureAction figureAction, NamedObj actor)
089            throws IllegalActionException, NameDuplicationException;
090
091    /**
092     * Get an instance of the
093     * {@link ptolemy.vergil.actor.ActorController ActorController}
094     * for a given actor.  This assumes
095     * Full access.
096     * @param controller The associated graph controller.
097     * @return An instance of the appropriate controller.
098     */
099    abstract ActorController getControllerInstance(GraphController controller);
100
101    /**
102     * Get an instance of the
103     * {@link ptolemy.vergil.actor.ActorController ActorController}
104     * for a given actor.
105     * @param controller The associated graph controller.
106     * @param fullAccess Indication if the controller should be instantiated
107     *                  with Full access.
108     * @return An instance of the appropriate controller.
109     */
110    abstract ActorController getControllerInstance(GraphController controller,
111            boolean fullAccess);
112
113    /** Determine of a given actor is of interest for a desired action.
114     *
115     * @param actor The actor of interest.
116     * @return True if the actor is of interest for use of a special controller,
117     * False otherwise.
118     */
119    abstract boolean isActorOfInterestForAddonController(NamedObj actor);
120
121}