1 /*
2 * Copyright (c) 1997, 2016, 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 java.io.*;
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.toolkit.Content;
34 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
35 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
36 import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException;
37
38
39 /**
40 * Generate the documentation in the Html "frame" format in the browser. The
41 * generated documentation will have two or three frames depending upon the
42 * number of packages on the command line. In general there will be three frames
43 * in the output, a left-hand top frame will have a list of all packages with
44 * links to target left-hand bottom frame. The left-hand bottom frame will have
45 * the particular package contents or the all-classes list, where as the single
46 * right-hand frame will have overview or package summary or class file. Also
47 * take care of browsers which do not support Html frames.
48 *
49 * <p><b>This is NOT part of any supported API.
50 * If you write code that depends on this, you do so at your own risk.
51 * This code and its internal interfaces are subject to change or
52 * deletion without notice.</b>
53 *
54 * @author Atul M Dambalkar
55 */
56 public class FrameOutputWriter extends HtmlDocletWriter {
57
58 /**
59 * Number of packages specified on the command line.
60 */
61 int noOfPackages;
62
63 /**
64 * Constructor to construct FrameOutputWriter object.
65 *
66 * @param configuration for this run
67 * @param filename File to be generated.
68 * @throws java.io.IOException
69 */
70 public FrameOutputWriter(ConfigurationImpl configuration, DocPath filename) throws IOException {
71 super(configuration, filename);
72 noOfPackages = configuration.packages.size();
73 }
74
75 /**
76 * Construct FrameOutputWriter object and then use it to generate the Html
77 * file which will have the description of all the frames in the
78 * documentation. The name of the generated file is "index.html" which is
79 * the default first file for Html documents.
80 * @throws DocletAbortException
81 */
82 public static void generate(ConfigurationImpl configuration) {
83 FrameOutputWriter framegen;
84 DocPath filename = DocPath.empty;
85 try {
86 filename = DocPaths.INDEX;
87 framegen = new FrameOutputWriter(configuration, filename);
88 framegen.generateFrameFile();
89 framegen.close();
90 } catch (IOException exc) {
91 configuration.standardmessage.error(
92 "doclet.exception_encountered",
93 exc.toString(), filename);
94 throw new DocletAbortException(exc);
95 }
96 }
97
98 /**
99 * Generate the constants in the "index.html" file. Print the frame details
100 * as well as warning if browser is not supporting the Html frames.
101 */
102 protected void generateFrameFile() throws IOException {
103 Content frame = getFrameDetails();
104 HtmlTree body = new HtmlTree(HtmlTag.BODY);
105 if (configuration.allowTag(HtmlTag.MAIN)) {
106 HtmlTree main = HtmlTree.MAIN(frame);
107 body.addContent(main);
108 } else {
109 body.addContent(frame);
110 }
111 if (configuration.windowtitle.length() > 0) {
112 printFramesDocument(configuration.windowtitle, configuration,
113 body);
114 } else {
115 printFramesDocument(configuration.getText("doclet.Generated_Docs_Untitled"),
116 configuration, body);
117 }
118 }
119
120 /**
121 * Get the frame sizes and their contents.
122 *
123 * @return a content tree for the frame details
124 */
125 protected Content getFrameDetails() {
126 HtmlTree leftContainerDiv = new HtmlTree(HtmlTag.DIV);
127 HtmlTree rightContainerDiv = new HtmlTree(HtmlTag.DIV);
128 leftContainerDiv.addStyle(HtmlStyle.leftContainer);
129 rightContainerDiv.addStyle(HtmlStyle.rightContainer);
130 if (noOfPackages <= 1) {
131 addAllClassesFrameTag(leftContainerDiv);
132 } else if (noOfPackages > 1) {
133 addAllPackagesFrameTag(leftContainerDiv);
134 addAllClassesFrameTag(leftContainerDiv);
135 }
136 addClassFrameTag(rightContainerDiv);
137 HtmlTree mainContainer = HtmlTree.DIV(HtmlStyle.mainContainer, leftContainerDiv);
138 mainContainer.addContent(rightContainerDiv);
139 return mainContainer;
140 }
141
142 /**
143 * Add the IFRAME tag for the frame that lists all packages.
144 *
145 * @param contentTree the content tree to which the information will be added
146 */
147 private void addAllPackagesFrameTag(Content contentTree) {
148 HtmlTree frame = HtmlTree.IFRAME(DocPaths.OVERVIEW_FRAME.getPath(),
149 "packageListFrame", configuration.getText("doclet.All_Packages"));
150 HtmlTree leftTop = HtmlTree.DIV(HtmlStyle.leftTop, frame);
151 contentTree.addContent(leftTop);
152 }
153
154 /**
155 * Add the IFRAME tag for the frame that lists all classes.
156 *
157 * @param contentTree the content tree to which the information will be added
158 */
159 private void addAllClassesFrameTag(Content contentTree) {
160 HtmlTree frame = HtmlTree.IFRAME(DocPaths.ALLCLASSES_FRAME.getPath(),
161 "packageFrame", configuration.getText("doclet.All_classes_and_interfaces"));
162 HtmlTree leftBottom = HtmlTree.DIV(HtmlStyle.leftBottom, frame);
163 contentTree.addContent(leftBottom);
164 }
165
166 /**
167 * Add the IFRAME tag for the frame that describes the class in detail.
168 *
169 * @param contentTree the content tree to which the information will be added
170 */
171 private void addClassFrameTag(Content contentTree) {
172 HtmlTree frame = HtmlTree.IFRAME(configuration.topFile.getPath(), "classFrame",
173 configuration.getText("doclet.Package_class_and_interface_descriptions"));
174 frame.addStyle(HtmlStyle.rightIframe);
175 contentTree.addContent(frame);
176 }
177 }