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}