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