001/* An interface that find documentation.
002
003 Copyright (c) 2006-2013 The Regents of the University of California.
004 All rights reserved.
005
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the above
009 copyright notice and the following two paragraphs appear in all copies
010 of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024 */
025
026package ptolemy.vergil.actor;
027
028import java.awt.Frame;
029import java.net.URL;
030import java.util.List;
031
032import ptolemy.actor.gui.Effigy;
033import ptolemy.kernel.util.Attribute;
034import ptolemy.kernel.util.NamedObj;
035import ptolemy.util.ExecuteCommands;
036
037///////////////////////////////////////////////////////////////////
038//// DocApplicationSpecializer
039
040/**
041 An interface that specializes the documentation system to the application.
042
043 <p>The docClassNameToURL() method used by {@link DocManager} and other
044 classes to convert class names to URLs.  The buildCommands() method
045 is used by {@link DocBuilder} to set up the build environment to
046 build the documentation system if necessary.
047
048 <p>If an application would like more control over how documentation
049 is found and built, then the application can implement this interface and set
050 the _docApplicationSpecializer parameter in the configuration to name
051 the implementation class.
052
053 @author Chad Berkley
054 @version $Id$
055 @since Ptolemy II 5.2
056 @Pt.ProposedRating Red (cxh)
057 @Pt.AcceptedRating Red (cxh)
058 */
059public interface DocApplicationSpecializer {
060
061    ///////////////////////////////////////////////////////////////////
062    ////                         public methods                    ////
063
064    /** Given a dot separated class name, return the URL of the
065     *  documentation.
066     *  @param remoteDocumentationURLBase If non-null, the URL of the
067     *  documentation.  Usually, this is set by reading the
068     *  _remoteDocumentationBase parameter from the configuration in the
069     *  caller.
070     *  @param className The dot separated class name.
071     *  @param lookForPtDoc True if we should look for ptdoc .xml files.
072     *  @param lookForJavadoc True if we should look for javadoc files.
073     *  @param lookForSource True if we should look for source files.
074     *  @param lookForActorIndex True if we should look for the actor
075     *  index.
076     *  @return The URL of the documentation, if any.  If no documentation
077     *  was found, return null.
078     */
079    public URL docClassNameToURL(String remoteDocumentationURLBase,
080            String className, boolean lookForPtDoc, boolean lookForJavadoc,
081            boolean lookForSource, boolean lookForActorIndex);
082
083    /** Set up the commands necessary to build the documentation.
084     *  @param executeCommands  The command execution environment necessary
085     *  to build the documentation.
086     *  @return A List of Strings, where each String represents the a
087     *  command to be executed.
088     */
089    public List buildCommands(ExecuteCommands executeCommands);
090
091    /** Return the class name of the attribute that this specializer
092     *  uses to store documentation.
093     *  @return the name of the class of the specialized documentation
094     *  attribute
095     */
096    public String getDocumentationAttributeClassName();
097
098    /** Create a gui to edit the documentation in the attribute.
099     * @param owner the editors gui parent
100     * @param attribute the documentation attribute to edit
101     * @param target the parent component to the attribute
102     */
103    public void editDocumentation(Frame owner, Attribute attribute,
104            NamedObj target);
105
106    /** Handle the state where there is no documentation attribute and
107     * the user tried to view the documentation.
108     * @param classname the name of the class
109     * @param effigy the effigy of the entity that does not have a doc
110     * attribute
111     */
112    public void handleDocumentationNotFound(String classname, Effigy effigy);
113
114    /** Handle the state where the documentation attribute does not
115     * exist and the user tried to edit the docs.
116     * @param owner the editors gui parent
117     * @param target the parent component to the attribute
118     */
119    public void handleDocumentationAttributeDoesNotExist(Frame owner,
120            NamedObj target);
121}