1 /*

     2  * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package jdk.javadoc.internal.doclets.formats.html;

    27 

    28 import javax.lang.model.element.PackageElement;

    29 

    30 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;

    31 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;

    32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;

    33 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;

    34 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;

    35 import jdk.javadoc.internal.doclets.toolkit.Content;

    36 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;

    37 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;

    38 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;

    39 

    40 

    41 /**

    42  * Generate the package index for the left-hand frame in the generated output.

    43  * A click on the package name in this frame will update the page in the bottom

    44  * left hand frame with the listing of contents of the clicked package.

    45  *

    46  *  <p><b>This is NOT part of any supported API.

    47  *  If you write code that depends on this, you do so at your own risk.

    48  *  This code and its internal interfaces are subject to change or

    49  *  deletion without notice.</b>

    50  *

    51  * @author Atul M Dambalkar

    52  */

    53 public class PackageIndexFrameWriter extends AbstractPackageIndexWriter {

    54     /**

    55      * The heading (h1 or h2) to use for the module list,

    56      * set by addNavigationBarHeader depending on whether or not there

    57      * is an additional initial heading.

    58      */

    59     private HtmlTag packageListHeading;

    60 

    61     /**

    62      * Construct the PackageIndexFrameWriter object.

    63      *

    64      * @param filename Name of the package index file to be generated.

    65      */

    66     public PackageIndexFrameWriter(HtmlConfiguration configuration, DocPath filename) {

    67         super(configuration, filename);

    68     }

    69 

    70     /**

    71      * Generate the package index file named "overview-frame.html".

    72      * @throws DocFileIOException

    73      */

    74     public static void generate(HtmlConfiguration configuration) throws DocFileIOException {

    75         DocPath filename = DocPaths.OVERVIEW_FRAME;

    76         PackageIndexFrameWriter packgen = new PackageIndexFrameWriter(configuration, filename);

    77         packgen.buildPackageIndexFile("doclet.Window_Overview",

    78                 "package index (frame)",

    79                 false);

    80     }

    81 

    82     /**

    83      * {@inheritDoc}

    84      */

    85     @Override

    86     protected void addPackagesList(Content main) {

    87         Content heading = HtmlTree.HEADING(packageListHeading, true,

    88                 contents.packagesLabel);

    89         HtmlTree htmlTree = HtmlTree.DIV(HtmlStyle.indexContainer, heading);

    90         HtmlTree ul = new HtmlTree(HtmlTag.UL);

    91         ul.setTitle(contents.packagesLabel);

    92         for (PackageElement aPackage : packages) {

    93             // Do not list the package if -nodeprecated option is set and the

    94             // package is marked as deprecated.

    95             if (aPackage != null &&

    96                 (!(configuration.nodeprecated && utils.isDeprecated(aPackage)))) {

    97                 ul.add(getPackage(aPackage));

    98             }

    99         }

   100         htmlTree.add(ul);

   101         main.add(htmlTree);

   102     }

   103 

   104     /**

   105      * Returns each package name as a separate link.

   106      *

   107      * @param pe PackageElement

   108      * @return content for the package link

   109      */

   110     protected Content getPackage(PackageElement pe) {

   111         Content packageLinkContent;

   112         Content packageLabel;

   113         if (pe.isUnnamed()) {

   114             packageLabel = new StringContent("<unnamed package>");

   115             packageLinkContent = links.createLink(DocPaths.PACKAGE_FRAME,

   116                     packageLabel, "", "packageFrame");

   117         } else {

   118             packageLabel = getPackageLabel(pe.getQualifiedName());

   119             packageLinkContent = links.createLink(pathString(pe,

   120                      DocPaths.PACKAGE_FRAME), packageLabel, "",

   121                     "packageFrame");

   122         }

   123         Content li = HtmlTree.LI(packageLinkContent);

   124         return li;

   125     }

   126 

   127     /**

   128      * {@inheritDoc}

   129      */

   130     @Override

   131     protected void addNavigationBarHeader(Content header) {

   132         Content headerContent;

   133         if (configuration.packagesheader.length() > 0) {

   134             headerContent = new RawHtml(replaceDocRootDir(configuration.packagesheader));

   135         } else {

   136             headerContent = new RawHtml(replaceDocRootDir(configuration.header));

   137         }

   138         if (!headerContent.isEmpty()) {

   139             Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, true,

   140                     HtmlStyle.bar, headerContent);

   141             header.add(heading);

   142             packageListHeading = Headings.IndexFrames.PACKAGE_HEADING;

   143         } else {

   144             packageListHeading = Headings.PAGE_TITLE_HEADING;

   145         }

   146     }

   147 

   148     /**

   149      * Do nothing as there is no overview information in this page.

   150      */

   151     @Override

   152     protected void addOverviewHeader(Content body) {

   153     }

   154 

   155     /**

   156      * Adds "All Classes" link for the top of the left-hand frame page to the

   157      * documentation tree.

   158      *

   159      * @param ul the Content object to which the "All Classes" link should be added

   160      */

   161     @Override

   162     protected void addAllClassesLink(Content ul) {

   163         Content linkContent = links.createLink(DocPaths.ALLCLASSES_FRAME,

   164                 contents.allClassesLabel, "", "packageFrame");

   165         Content li = HtmlTree.LI(linkContent);

   166         ul.add(li);

   167     }

   168 

   169     /**

   170      * Adds "All Modules" link for the top of the left-hand frame page to the

   171      * documentation tree.

   172      *

   173      * @param ul the Content object to which the "All Modules" link should be added

   174      */

   175     @Override

   176     protected void addAllModulesLink(Content ul) {

   177         Content linkContent = links.createLink(DocPaths.MODULE_OVERVIEW_FRAME,

   178                 contents.allModulesLabel, "", "packageListFrame");

   179         Content li = HtmlTree.LI(linkContent);

   180         ul.add(li);

   181     }

   182 

   183     /**

   184      * {@inheritDoc}

   185      */

   186     @Override

   187     protected void addNavigationBarFooter(Content footer) {

   188         Content p = HtmlTree.P(Contents.SPACE);

   189         footer.add(p);

   190     }

   191 }