001/* Interface for objects that can can be moved in a list of objects.
002
003 Copyright (c) 2004-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.kernel.util;
029
030///////////////////////////////////////////////////////////////////
031//// Moveable
032
033/**
034 This is an interface for objects that can be moved in a list of
035 objects in a container.
036
037 @author Edward A. Lee
038 @version $Id$
039 @since Ptolemy II 4.1
040 @Pt.ProposedRating Green (eal)
041 @Pt.AcceptedRating Green (hyzheng)
042 */
043public interface Moveable {
044    ///////////////////////////////////////////////////////////////////
045    ////                         public methods                    ////
046
047    /** Move this object down by one in the list of
048     *  objects in its container. If the object is already last
049     *  on the list, then it is not moved.
050     *  @return The index of this object prior to moving it,
051     *   or -1 if it is not moved.
052     *  @exception IllegalActionException If this object has
053     *   no container.
054     */
055    public int moveDown() throws IllegalActionException;
056
057    /** Move this object to the first position in the list of
058     *  objects in its container.  If the object is already
059     *  first on the list, then it is not moved.
060     *  @return The index of this object prior to moving it,
061     *   or -1 if it is not moved.
062     *  @exception IllegalActionException If this object has
063     *   no container.
064     */
065    public int moveToFirst() throws IllegalActionException;
066
067    /** Move this object to the specified position in the list of
068     *  objects in its container, where 0 is the first position.
069     *  If the object is already at the specified
070     *  position, then it is not moved.
071     *  @param index The position to which to move the object.
072     *  @return The index of this object prior to moving it,
073     *   or -1 if it is not moved.
074     *  @exception IllegalActionException If this object has
075     *   no container or if the index is out of range.
076     */
077    public int moveToIndex(int index) throws IllegalActionException;
078
079    /** Move this object to the last position in the list of
080     *  objects in its container.  If the object is already
081     *  last on the list, then it is not moved.
082     *  @return The index of this object prior to moving it,
083     *   or -1 if it was not moved.
084     *  @exception IllegalActionException If this object has
085     *   no container.
086     */
087    public int moveToLast() throws IllegalActionException;
088
089    /** Move this object up by one in the list of
090     *  objects in its container.  If the object is already first
091     *  on the list, then it is not moved.
092     *  @return The index of this object prior to moving it,
093     *   or -1 if it was not moved.
094     *  @exception IllegalActionException If this object has
095     *   no container.
096     */
097    public int moveUp() throws IllegalActionException;
098}