1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128 | package Torello.JavaDoc.Annotations;
import java.lang.annotation.*;
// @JDHeaderBackgroundImg Annotation
//
// EXPORTS:
// String[] CSSClass() default { };
// String[] EmbedTagFileID() default { };
//
// * package Torello.JDUInternal.Features.EXTERNAL_HTML_FILES
// The classes in this package do the processing for inserting the HTML from External-HTML
// Files into Java-Doc '.html' Output-Files. It places an HTML <IMG SRC=...> at the top of
// the page. The Imge contains a Wooden-Panel, and the User's JDHBI HTML for that class is
// then placed on top of / over the Wood-Paneling
/**
* <B STYLE='color:darkred;'>Java-Annotation:</B>
*
* A Java-Annotation for inserting a Wooden-Plank Background Image at the top of a Java-Doc
* Page using External-HTML File's; the image used is configurable, and my be changed by
* assigning the Annotation-Element Values appropriately.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// NOTE: THIS ACTUALLY IS A "SELF-ANNOTATING" ANNOTATION...
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
@JDHeaderBackgroundImg
public @interface JDHeaderBackgroundImg
{
/**
* This Annotation-Element is optional. It is intended to contain the CSS-Class the user
* would like associated with the Java-Doc Header-Background Image Divider
* (the {@code '<DIV>'} element).
*
* <BR /><BR />This Optional-Element has a default-value, and that is to use a CSS-Class which
* contains an image of a "Dark Wooden Board" for a background-image. This image will serve as
* the background for an HTML divider {@code '<DIV>'} element that is placed at the top of the
* Java-Doc HTML Page for the type/class being annotated.
*
* <BR /><BR />Note that the {@code default} value for this element is, indeed, an Empty
* {@code String[]}-Array. The JavaDoc Upgrader will interpret this as a request to use the
* default {@code CSS CLASS}, which is {@code "JDWoodBoardDark"}. Click
* {@link #DEFAULT_CSS_CLASS} to view (or retrieve} this {@code String}
*
* <BR /><BR /><B CLASS=JDDescLabel>IMPORTANT:</B>
*
* <BR >It is advisable not to change the default value for this {@code CSS CLASS}. Though
* there shouldn't be any problems in using an alternate image, <I>it will require (and,
* hopefully this is obvious) ... it will require writing your own definition for that
* {@code CSS-Class} and inserting it into your {@code JavaDoc.css} style-definitions page.</I>
*
* <BR /><BR /><B CLASS=JDDescLabel>Multiple {@code CSS-Classes}</B>
*
* <BR />This Annotation-Element is, indeed, a {@code String[]}-Array, rather than just a
* simple-{@code String}. You may choose to provide mltiple {@code CSS-Classes} to this
* Annotation, and if you do - <I>the HTML-{@code <DIV>} will have a {@code 'CLASS'}
* attribute with multiple {@code CSS CLASS's} assigned.</I>
*
* <BR /><BR />This example shows assigning the default-background to a Java {@code class}.
* Since there is no {@code EmbedTagFileID} assigned to that element, the default Dark
* Wooden Plank will be used as a background. The Ugrader will look for the external-HTML
* in the default-directory location, which is listed first (followed by the example)
*
* <BR/><SPAN CLASS=JDFileDirName>
* "SrcPackageDirectory/upgrade-files/external-html/JDHBI/MyClass.html"
* </SPAN>
*
* <!--
* <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET>
* @ JDHeaderBackgroundImg
* public class MyClass
* { ... }
* </EXTERNALCODESNIPPET></DIV>
* -->
*
* <BR /><BR />This example shows how to assign an alternate CSS-Class to the HTML
* {@code <DIV>} element that is inserted. In this example, two user-provided CSS classes
* are going to be applied to the {@code <DIV>}. Again, as in the previous example, the
* Ugrader will look for the External-HTML file in the default location:
*
* <!--
* <BR /><DIV CLASS=SNIP>{@code
* JDHeaderBackgroundImg(CSSClass={"MyOwnBeachesBackground", "ImportantCSSClass"})
* }</DIV>
* -->
*/
String[] CSSClass() default { };
/**
* This Annotation-Element is also optional. If used, it must contain a valid {@code FILE-ID}
* that is listed in either the {@code Package-Local}, or the {@code Global} Embed-Tags Map.
* This {@code FILE-ID} maps to the external HTML File that contains the HTML which is to be
* inserted on top of the Header-Banner containing the background image.
*
* <BR /><BR />If the Empty-String ({@code ""}) is passed to this Annotation-Element, or if the
* default value (which is the Empty-String) is passed, then the JavaDoc Upgrader will look for
* the HTML inside the {@code 'upgrade-files/'} directory:
*
* <BR /><BR /><SPAN CLASS=JDFileDirName>
* "PackageSrcDirectory/upgrade-files/external-html/JDHBI/"
* </SPAN>
*
* <BR /><BR />For a file-name that matches the name of the CIET / Type (The 'ClassName'),
* but ending with the suffix {@code '.html'}. For instance, in the following snippet:
*
* <!--
* <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET>
* JDHeaderBackgroundImg(EmbedTagFileID="MyHTML")
* </EXTERNALCODESNIPPET></DIV>
* -->
*
* <BR /><BR />The Upgrader would reference the {@code external-html-ids.properties} file
* which contained the definition.
*/
String[] EmbedTagFileID() default { };
/** This is the default CSS-Class used for the {@code <DIV>} that is inserted. */
public static final String DEFAULT_CSS_CLASS = "JDWoodBoardDark";
}
|