001package Torello.JavaDoc;
002
003import java.lang.annotation.*;
004
005/**
006 * <B STYLE='color:darkred;'>Java-Annotation:</B>
007 * 
008 * A Java-Annotation for inserting a Wooden-Plank Background Image at the top of a Java-Doc
009 * Page using External-HTML File's; the image used is configurable, and my be changed by
010 * assigning the Annotation-Element Values appropriately.
011 */
012
013@Target(ElementType.TYPE)
014@Retention(RetentionPolicy.SOURCE)
015
016// NOTE: THIS ACTUALLY IS A "SELF-ANNOTATING" ANNOTATION...
017@JDHeaderBackgroundImg
018
019public @interface JDHeaderBackgroundImg
020{
021    /**
022     * This Annotation-Element is optional.  It is intended to contain the CSS-Class the user
023     * would like associated with the Java-Doc Header-Background Image Divider
024     * (the {@code '<DIV>'} element).  
025     * 
026     * <BR /><BR />This Optional-Element has a default-value, and that is to use a CSS-Class which
027     * contains an image of a "Dark Wooden Board" for a background-image.  This image will serve as
028     * the background for an HTML divider {@code '<DIV>'} element that is placed at the top of the
029     * Java-Doc HTML Page for the type/class being annotated.
030     * 
031     * <BR /><BR />Note that the {@code default} value for this element is, indeed, an Empty
032     * {@code String[]}-Array.  The JavaDoc Upgrader will interpret this as a request to use the
033     * default {@code CSS CLASS}, which is {@code "JDWoodBoardDark"}.  Click
034     * {@link #DEFAULT_CSS_CLASS} to view (or retrieve} this {@code String}
035     * 
036     * <BR /><BR /><B CLASS=JDDescLabel>IMPORTANT:</B>
037     * 
038     * <BR >It is advisable not to change the default value for this {@code CSS CLASS}.  Though
039     * there shouldn't be any problems in using an alternate image, <I>it will require (and, 
040     * hopefully this is obvious) ... it will require writing your own definition for that
041     * {@code CSS-Class} and inserting it into your {@code JavaDoc.css} style-definitions page.</I>
042     * 
043     * <BR /><BR /><B CLASS=JDDescLabel>Multiple {@code CSS-Classes}</B>
044     * 
045     * <BR />This Annotation-Element is, indeed, a {@code String[]}-Array, rather than just a
046     * simple-{@code String}.  You may choose to provide mltiple {@code CSS-Classes} to this 
047     * Annotation, and if you do - <I>the HTML-{@code <DIV>} will have a {@code 'CLASS'}
048     * attribute with multiple {@code CSS CLASS's} assigned.</I>
049     * 
050     * <BR /><BR />This example shows assigning the default-background to a Java {@code class}.
051     * Since there is no {@code EmbedTagFileID} assigned to that element, the default Dark
052     * Wooden Plank will be used as a background.  The Ugrader will look for the external-HTML
053     * in the default-directory location, which is listed first (followed by the example)
054     * 
055     * <BR/><SPAN CLASS=JDFileDirName>
056     * "SrcPackageDirectory/upgrade-files/external-html/JDHBI/MyClass.html"
057     * </SPAN>
058     * 
059     * <!--
060     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET> 
061     * @ JDHeaderBackgroundImg
062     * public class MyClass
063     * { ... }
064     * </EXTERNALCODESNIPPET></DIV>
065     * -->
066     * 
067     * <BR /><BR />This example shows how to assign an alternate CSS-Class to the HTML
068     * {@code <DIV>} element that is inserted.  In this example, two user-provided CSS classes
069     * are going to be applied to the {@code <DIV>}.  Again, as in the previous example, the
070     * Ugrader will look for the External-HTML file in the default location:
071     * 
072     * <!--
073     * <BR /><DIV CLASS=SNIP>{@code
074     * JDHeaderBackgroundImg(CSSClass={"MyOwnBeachesBackground", "ImportantCSSClass"})
075     * }</DIV>
076     * -->
077     */
078    String[] CSSClass() default { };
079
080    /**
081     * This Annotation-Element is also optional.  If used, it must contain a valid {@code FILE-ID}
082     * that is listed in either the {@code Package-Local}, or the {@code Global} Embed-Tags Map.
083     * This {@code FILE-ID} maps to the external HTML File that contains the HTML which is to be
084     * inserted on top of the Header-Banner containing the background image.
085     * 
086     * <BR /><BR />If the Empty-String ({@code ""}) is passed to this Annotation-Element, or if the
087     * default value (which is the Empty-String) is passed, then the JavaDoc Upgrader will look for
088     * the HTML inside the {@code 'upgrade-files/'} directory:
089     * 
090     * <BR /><BR /><SPAN CLASS=JDFileDirName>
091     * "PackageSrcDirectory/upgrade-files/external-html/JDHBI/"
092     * </SPAN>
093     * 
094     * <BR /><BR />For a file-name that matches the name of the CIET / Type (The 'ClassName'),
095     * but ending with the suffix {@code '.html'}.  For instance, in the following snippet:
096     * 
097     * <!--
098     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET>
099     * JDHeaderBackgroundImg(EmbedTagFileID="MyHTML")
100     * </EXTERNALCODESNIPPET></DIV>
101     * -->
102     * 
103     * <BR /><BR />The Upgrader would reference the {@code external-html-ids.properties} file
104     * which contained the definition.
105     */
106    String[] EmbedTagFileID() default { };
107
108    /** This is the default CSS-Class used for the {@code <DIV>} that is inserted. */
109    public static final String DEFAULT_CSS_CLASS = "JDWoodBoardDark";
110}