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 | package Torello.JavaDoc; import java.lang.annotation.*; /** * <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"; } |