001/* An attribute that creates an editor to open a doc viewer on its container's container.
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.actor.gui;
029
030import java.awt.Frame;
031import java.net.URL;
032import java.util.List;
033
034import ptolemy.data.expr.FileParameter;
035import ptolemy.kernel.attributes.URIAttribute;
036import ptolemy.kernel.util.IllegalActionException;
037import ptolemy.kernel.util.InternalErrorException;
038import ptolemy.kernel.util.NameDuplicationException;
039import ptolemy.kernel.util.NamedObj;
040import ptolemy.util.MessageHandler;
041
042///////////////////////////////////////////////////////////////////
043//// LiveLink
044
045/**
046 An attribute that provides a link to a specified URL.
047 This can be contained by any Ptolemy II object, and when a
048 user double clicks on the icon for that object, the result is to open
049 the specified URL. To set the URL, you either Alt-double click
050 on the container, right click on an icon
051 for this parameter and select Configure,
052 or right click on the container and select Configure.
053 <p>
054 A common way to use this attribute is to put
055 a text annotation in a model with text something like
056 "See also Foo", where "Foo" is the name of another
057 related model. Drag an instance of this LiveLink attribute
058 onto the text annotation. Alt double click (or right click
059 and select Configure) on the text
060 annotation to set the file name for the model Foo to
061 link to a file or a URL to link to a web page.
062 The file name can be relative to the location of
063 the model containing the annotation. It can also
064 have any of the forms supported by
065 {@link FileParameter}. For example, a file name
066 can begin with $PTII, indicating that the file
067 is in the Ptolemy II installation tree.
068 <p>
069 The default URL is "http://ptolemy.org#in_browser", which is
070 the home page of the Ptolemy Project with an additional
071 annotation indicating that the page should be opened
072 in a browser. The suffix "#in_browser" will always
073 be interpreted this way. Without this suffix, Vergil
074 will be used to open the URL. Note that Vergil's HTML
075 viewer does not handle many modern pages well.
076
077 <p> See also ptolemy.vergil.basic.export.web.IconLink.</p>
078
079 @author Edward A. Lee
080 @version $Id$
081 @since Ptolemy II 10.0
082 @Pt.ProposedRating Yellow (eal)
083 @Pt.AcceptedRating Red (cxh)
084 */
085public class LiveLink extends FileParameter implements Editable {
086
087    /** Construct a factory with the specified container and name.
088     *  @param container The container.
089     *  @param name The name of the factory.
090     *  @exception IllegalActionException If the factory is not of an
091     *   acceptable attribute for the container.
092     *  @exception NameDuplicationException If the name coincides with
093     *   an attribute already in the container.
094     */
095    public LiveLink(NamedObj container, String name)
096            throws IllegalActionException, NameDuplicationException {
097        super(container, name);
098
099        setExpression("http://ptolemy.org#in_browser");
100    }
101
102    ///////////////////////////////////////////////////////////////////
103    ////                         public methods                    ////
104
105    /** Create an editor.
106     *  This editor will have no parent window.
107     */
108    @Override
109    public void createEditor() {
110        throw new InternalErrorException(this, null,
111                "createEditor() should not be called.");
112    }
113
114    /** Create an editor for configuring the specified object.
115     *  This editor will have no parent window.
116     *  @param object The object to configure.
117     */
118    @Override
119    public void createEditor(NamedObj object) {
120        createEditor(object, null);
121    }
122
123    /** Create a doc viewer for the specified object with the
124     *  specified parent window.
125     *  @param object The object to configure, which is required to
126     *   an instance of DocAttribute.
127     *  @param parent The parent window, which is required to be an
128     *   instance of TableauFrame.
129     */
130    @Override
131    public void createEditor(NamedObj object, Frame parent) {
132        Configuration configuration = (Configuration) Configuration
133                .findEffigy(object.getContainer()).toplevel();
134        try {
135            // To find a base for relative references, find
136            // the URIAttribute contained by the toplevel.
137            NamedObj toplevel = toplevel();
138            URL base = null;
139            List<URIAttribute> attributes = toplevel
140                    .attributeList(URIAttribute.class);
141            if (attributes != null && attributes.size() > 0) {
142                base = attributes.get(0).getURL();
143            }
144            URL toOpen = asURL();
145            configuration.openModel(base, toOpen, toOpen.toExternalForm());
146        } catch (Exception e) {
147            MessageHandler.error("Unable to open specified URI", e);
148        }
149    }
150}