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.markup;
27
28 import javax.lang.model.element.ModuleElement;
29 import javax.lang.model.element.PackageElement;
30 import javax.lang.model.element.TypeElement;
31
32 import jdk.javadoc.internal.doclets.formats.html.HtmlConfiguration;
33 import jdk.javadoc.internal.doclets.formats.html.SectionName;
34 import jdk.javadoc.internal.doclets.toolkit.Content;
35 import jdk.javadoc.internal.doclets.toolkit.Messages;
36 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
37 import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
38 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
39 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
40
41
42 /**
43 * Class for the Html Format Code Generation specific to JavaDoc.
44 * This Class contains methods related to the Html Code Generation which
45 * are used by the Sub-Classes in the package jdk.javadoc.internal.tool.standard.
46 *
47 * <p><b>This is NOT part of any supported API.
48 * If you write code that depends on this, you do so at your own risk.
49 * This code and its internal interfaces are subject to change or
50 * deletion without notice.</b>
51 *
52 * @author Atul M Dambalkar
53 * @author Robert Field
54 */
55 public abstract class HtmlDocWriter {
56
57 private final HtmlConfiguration configuration;
58
59 /**
60 * Constructor.
61 *
62 * @param configuration the configuration for this doclet
63 * @param filename the path for the output file
64 */
65 public HtmlDocWriter(HtmlConfiguration configuration, DocPath filename) {
66 this.configuration = configuration;
67 Messages messages = configuration.getMessages();
68 messages.notice("doclet.Generating_0",
69 DocFile.createFileForOutput(configuration, filename).getPath());
70 }
71
72 public Content getHyperLink(DocPath link, String label) {
73 return getHyperLink(link, new StringContent(label), false, "", "", "");
74 }
75
76 /**
77 * Get Html Hyper Link Content.
78 *
79 * @param where Position of the link in the file. Character '#' is not
80 * needed.
81 * @param label Tag for the link.
82 * @return a content tree for the hyper link
83 */
84 public Content getHyperLink(String where,
85 Content label) {
86 return getHyperLink(getDocLink(where), label, "", "");
87 }
88
89 /**
90 * Get Html Hyper Link Content.
91 *
92 * @param sectionName The section name to which the link will be created.
93 * @param label Tag for the link.
94 * @return a content tree for the hyper link
95 */
96 public Content getHyperLink(SectionName sectionName,
97 Content label) {
98 return getHyperLink(getDocLink(sectionName), label, "", "");
99 }
100
101 /**
102 * Get Html Hyper Link Content.
103 *
104 * @param sectionName The section name combined with where to which the link
105 * will be created.
106 * @param where The fragment combined with sectionName to which the link
107 * will be created.
108 * @param label Tag for the link.
109 * @return a content tree for the hyper link
110 */
111 public Content getHyperLink(SectionName sectionName, String where,
112 Content label) {
113 return getHyperLink(getDocLink(sectionName, where), label, "", "");
114 }
115
116 /**
117 * Get the link.
118 *
119 * @param where Position of the link in the file.
120 * @return a DocLink object for the hyper link
121 */
122 public DocLink getDocLink(String where) {
123 return DocLink.fragment(getName(where));
124 }
125
126 /**
127 * Get the link.
128 *
129 * @param sectionName The section name to which the link will be created.
130 * @return a DocLink object for the hyper link
131 */
132 public DocLink getDocLink(SectionName sectionName) {
133 return DocLink.fragment(sectionName.getName());
134 }
135
136 /**
137 * Get the link.
138 *
139 * @param sectionName The section name combined with where to which the link
140 * will be created.
141 * @param where The fragment combined with sectionName to which the link
142 * will be created.
143 * @return a DocLink object for the hyper link
144 */
145 public DocLink getDocLink(SectionName sectionName, String where) {
146 return DocLink.fragment(sectionName.getName() + getName(where));
147 }
148
149 /**
150 * Convert the name to a valid HTML name.
151 *
152 * @param name the name that needs to be converted to valid HTML name.
153 * @return a valid HTML name string.
154 */
155 public String getName(String name) {
156 /* The HTML 4 spec at http://www.w3.org/TR/html4/types.html#h-6.2 mentions
157 * that the name/id should begin with a letter followed by other valid characters.
158 * The HTML 5 spec (draft) is more permissive on names/ids where the only restriction
159 * is that it should be at least one character long and should not contain spaces.
160 * The spec draft is @ http://www.w3.org/html/wg/drafts/html/master/dom.html#the-id-attribute.
161 *
162 * For HTML 4, we need to check for non-characters at the beginning of the name and
163 * substitute it accordingly, "_" and "$" can appear at the beginning of a member name.
164 * The method substitutes "$" with "Z:Z:D" and will prefix "_" with "Z:Z".
165 */
166
167 if (configuration.isOutputHtml5()) {
168 return name.replaceAll(" +", "");
169 }
170
171 StringBuilder sb = new StringBuilder();
172 for (int i = 0; i < name.length(); i++) {
173 char ch = name.charAt(i);
174 switch (ch) {
175 case '(':
176 case ')':
177 case '<':
178 case '>':
179 case ',':
180 sb.append('-');
181 break;
182 case ' ':
183 case '[':
184 break;
185 case ']':
186 sb.append(":A");
187 break;
188 // Any appearance of $ needs to be substituted with ":D" and not with hyphen
189 // since a field name "P$$ and a method P(), both valid member names, can end
190 // up as "P--". A member name beginning with $ needs to be substituted with
191 // "Z:Z:D".
192 case '$':
193 if (i == 0)
194 sb.append("Z:Z");
195 sb.append(":D");
196 break;
197 // A member name beginning with _ needs to be prefixed with "Z:Z" since valid anchor
198 // names can only begin with a letter.
199 case '_':
200 if (i == 0)
201 sb.append("Z:Z");
202 sb.append(ch);
203 break;
204 default:
205 sb.append(ch);
206 }
207 }
208 return sb.toString();
209 }
210
211 /**
212 * Get Html hyperlink.
213 *
214 * @param link path of the file.
215 * @param label Tag for the link.
216 * @return a content tree for the hyper link
217 */
218 public Content getHyperLink(DocPath link, Content label) {
219 return getHyperLink(link, label, "", "");
220 }
221
222 public Content getHyperLink(DocLink link, Content label) {
223 return getHyperLink(link, label, "", "");
224 }
225
226 public Content getHyperLink(DocPath link,
227 Content label, boolean strong,
228 String stylename, String title, String target) {
229 return getHyperLink(new DocLink(link), label, strong,
230 stylename, title, target);
231 }
232
233 public Content getHyperLink(DocLink link,
234 Content label, boolean strong,
235 String stylename, String title, String target) {
236 Content body = label;
237 if (strong) {
238 body = HtmlTree.SPAN(HtmlStyle.typeNameLink, body);
239 }
240 if (stylename != null && stylename.length() != 0) {
241 HtmlTree t = new HtmlTree(HtmlTag.FONT, body);
242 t.addAttr(HtmlAttr.CLASS, stylename);
243 body = t;
244 }
245 HtmlTree l = HtmlTree.A(link.toString(), body);
246 if (title != null && title.length() != 0) {
247 l.addAttr(HtmlAttr.TITLE, title);
248 }
249 if (target != null && target.length() != 0) {
250 l.addAttr(HtmlAttr.TARGET, target);
251 }
252 return l;
253 }
254
255 /**
256 * Get Html Hyper Link.
257 *
258 * @param link String name of the file.
259 * @param label Tag for the link.
260 * @param title String that describes the link's content for accessibility.
261 * @param target Target frame.
262 * @return a content tree for the hyper link.
263 */
264 public Content getHyperLink(DocPath link, Content label, String title, String target) {
265 return getHyperLink(new DocLink(link), label, title, target);
266 }
267
268 public Content getHyperLink(DocLink link, Content label, String title, String target) {
269 HtmlTree anchor = HtmlTree.A(link.toString(), label);
270 if (title != null && title.length() != 0) {
271 anchor.addAttr(HtmlAttr.TITLE, title);
272 }
273 if (target != null && target.length() != 0) {
274 anchor.addAttr(HtmlAttr.TARGET, target);
275 }
276 return anchor;
277 }
278
279 public Content getModuleFramesHyperLink(ModuleElement mdle, Content label, String target) {
280 DocLink mdlLink = new DocLink(DocPaths.moduleFrame(mdle));
281 DocLink mtFrameLink = new DocLink(DocPaths.moduleTypeFrame(mdle));
282 DocLink cFrameLink = new DocLink(DocPaths.moduleSummary(mdle));
283 HtmlTree anchor = HtmlTree.A(mdlLink.toString(), label);
284 String onclickStr = "updateModuleFrame('" + mtFrameLink + "','" + cFrameLink + "');";
285 anchor.addAttr(HtmlAttr.TARGET, target);
286 anchor.addAttr(HtmlAttr.ONCLICK, onclickStr);
287 return anchor;
288 }
289
290 /**
291 * Get the enclosed name of the package
292 *
293 * @param te TypeElement
294 * @return the name
295 */
296 public String getEnclosingPackageName(TypeElement te) {
|
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.markup;
27
28 import javax.lang.model.element.ModuleElement;
29 import javax.lang.model.element.PackageElement;
30 import javax.lang.model.element.TypeElement;
31
32 import jdk.javadoc.internal.doclets.formats.html.HtmlConfiguration;
33 import jdk.javadoc.internal.doclets.toolkit.Content;
34 import jdk.javadoc.internal.doclets.toolkit.Messages;
35 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
36 import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
37 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
38 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
39
40
41 /**
42 * Class for the Html Format Code Generation specific to JavaDoc.
43 * This Class contains methods related to the Html Code Generation which
44 * are used by the Sub-Classes in the package jdk.javadoc.internal.tool.standard.
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 * @author Robert Field
53 */
54 public abstract class HtmlDocWriter {
55
56 private final HtmlConfiguration configuration;
57
58 /**
59 * Constructor.
60 *
61 * @param configuration the configuration for this doclet
62 * @param filename the path for the output file
63 */
64 public HtmlDocWriter(HtmlConfiguration configuration, DocPath filename) {
65 this.configuration = configuration;
66 Messages messages = configuration.getMessages();
67 messages.notice("doclet.Generating_0",
68 DocFile.createFileForOutput(configuration, filename).getPath());
69 }
70
71 public Content getModuleFramesHyperLink(ModuleElement mdle, Content label, String target) {
72 DocLink mdlLink = new DocLink(DocPaths.moduleFrame(mdle));
73 DocLink mtFrameLink = new DocLink(DocPaths.moduleTypeFrame(mdle));
74 DocLink cFrameLink = new DocLink(DocPaths.moduleSummary(mdle));
75 HtmlTree anchor = HtmlTree.A(mdlLink.toString(), label);
76 String onclickStr = "updateModuleFrame('" + mtFrameLink + "','" + cFrameLink + "');";
77 anchor.addAttr(HtmlAttr.TARGET, target);
78 anchor.addAttr(HtmlAttr.ONCLICK, onclickStr);
79 return anchor;
80 }
81
82 /**
83 * Get the enclosed name of the package
84 *
85 * @param te TypeElement
86 * @return the name
87 */
88 public String getEnclosingPackageName(TypeElement te) {
|