001/* A base class for visible attributes.
002
003 Copyright (c) 2006-2014 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.vergil.kernel.attributes;
029
030import ptolemy.data.BooleanToken;
031import ptolemy.data.expr.Parameter;
032import ptolemy.data.expr.SingletonParameter;
033import ptolemy.kernel.util.Attribute;
034import ptolemy.kernel.util.IllegalActionException;
035import ptolemy.kernel.util.NameDuplicationException;
036import ptolemy.kernel.util.NamedObj;
037import ptolemy.kernel.util.Settable;
038import ptolemy.kernel.util.SingletonAttribute;
039
040///////////////////////////////////////////////////////////////////
041//// VisibleAttribute
042
043/**
044 Base class for attributes that are shown in vergil with their own icons.
045 This base class contains an attribute that results in its name being
046 hidden, and also handles commands to send it to the back or the front.
047 <p>
048 @author Edward A. Lee
049 @version $Id$
050 @since Ptolemy II 5.2
051 @Pt.ProposedRating Yellow (eal)
052 @Pt.AcceptedRating Red (cxh)
053 */
054public abstract class VisibleAttribute extends Attribute {
055    /** Construct an attribute with the given name contained by the
056     *  specified container. The container argument must not be null, or a
057     *  NullPointerException will be thrown.  This attribute will use the
058     *  workspace of the container for synchronization and version counts.
059     *  If the name argument is null, then the name is set to the empty
060     *  string. Increment the version of the workspace.
061     *  @param container The container.
062     *  @param name The name of this attribute.
063     *  @exception IllegalActionException If the attribute is not of an
064     *   acceptable class for the container, or if the name contains a period.
065     *  @exception NameDuplicationException If the name coincides with
066     *   an attribute already in the container.
067     */
068    public VisibleAttribute(NamedObj container, String name)
069            throws IllegalActionException, NameDuplicationException {
070        super(container, name);
071
072        // Hide the name.
073        SingletonParameter hide = new SingletonParameter(this, "_hideName");
074        hide.setToken(BooleanToken.TRUE);
075        hide.setVisibility(Settable.EXPERT);
076
077        // No need to display any parameters when the "_showParameters"
078        // preference asks for such display because presumably all the
079        // parameters are reflected in the visual display already.
080        Parameter hideAllParameters = new Parameter(this, "_hideAllParameters");
081        hideAllParameters.setVisibility(Settable.EXPERT);
082        hideAllParameters.setExpression("true");
083    }
084
085    ///////////////////////////////////////////////////////////////////
086    ////                         public methods                    ////
087
088    /** Move this object to the first position in the list
089     *  of attributes of the container. This overrides the base
090     *  class to create  an attribute named "_renderFirst" and to
091     *  remove an attribute named "_renderLast", if it is present.
092     *  This attribute is recognized by vergil, which then renders this
093     *  attribute before entities, connections, and other attributes.
094     *  This method gets write access on workspace
095     *  and increments the version.
096     *  @return The index of the specified object prior to moving it,
097     *   or -1 if it is not moved.
098     *  @exception IllegalActionException If this object has
099     *   no container.
100     */
101    @Override
102    public int moveToFirst() throws IllegalActionException {
103        try {
104            new SingletonAttribute(this, "_renderFirst");
105            Attribute renderLast = getAttribute("_renderLast");
106
107            if (renderLast != null) {
108                renderLast.setContainer(null);
109            }
110        } catch (NameDuplicationException e) {
111            // Ignore.  This will result in a rendering error,
112            // but that is better than trashing user data.
113        }
114
115        return super.moveToFirst();
116    }
117
118    /** Move this object to the last position in the list
119     *  of attributes of the container. This overrides the base
120     *  class to create  an attribute named "_renderLast" and to
121     *  remove an attribute named "_renderFirst" if it is present.
122     *  This attribute is recognized by vergil, which then renders this
123     *  attribute after entities, connections, and other attributes.
124     *  This method gets write access on workspace
125     *  and increments the version.
126     *  @return The index of the specified object prior to moving it,
127     *   or -1 if it is not moved.
128     *  @exception IllegalActionException If this object has
129     *   no container.
130     */
131    @Override
132    public int moveToLast() throws IllegalActionException {
133        try {
134            new SingletonAttribute(this, "_renderLast");
135            Attribute renderFirst = getAttribute("_renderFirst");
136
137            if (renderFirst != null) {
138                renderFirst.setContainer(null);
139            }
140        } catch (NameDuplicationException e) {
141            // Ignore.  This will result in a rendering error,
142            // but that is better than trashing user data.
143        }
144
145        return super.moveToLast();
146    }
147}