package Torello.JavaDoc;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import Torello.HTML.TagNode;

import java.lang.annotation.Repeatable;

import static java.lang.annotation.RetentionPolicy.SOURCE;
import static java.lang.annotation.ElementType.*;

// @IntoHTMLTable Annotation:
// 
// EXPORTS:
//      public Background background() default Background.Blue;
//      public String title() default "";
//      public String divCSSClass() default "";
//      public String tableCSSClass() default "";
// 
// 
// The following files are all related to this Java-Doc Upgrader Annotation:
// 
// * Torello.JDUInternal.SimpleFeatures.IntoHTMLTableProc
//      This is the primary or "Work Horse" Method for Generating the HTML-Table that is inserted
//      into the Detail-Entry "description()" section.
// 
// * User-Annotations.css
//      For the CSS Color Choices/Options/Definitions
//      Since there are a suite of Color-Choices which have been presented to the user
// 
// * Torello.JavaDoc.IntoHTMLTable
//      For the actual annotation definition.
//      This is the actual @interface for the @IntoHTMLTable Annotation
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Mirror.IHTMirror
//      The Data-Contents of the Annotation that has been placed by the User on the Entity
//      (Entity: Method, Field, Constructor, Enum-Constant, Annotation-Element)
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Processor.IntoHTMLTableProcessor
//      The Annotation-Processor that is invoked by 'javac' when compiling a class that uses the
//      @IntoHTMLTable Annotation.  It's a very minimalist processor that actually does very little
//      There is no way to do very much meaningful Error-Checking when invoked by 'javac'
//      Until the Java-Doc Upgrader is running, you cannot even identify errors.

/**
 * Requests that the Java-Doc Upgrader convert the Description area of a Java-Doc Web-Page
 * Detail-Section into an HTML {@code <TABLE>} Element.  The Description portion of the Detail
 * Description <B STYLE='color: red;'><I>MUST</I></B> be initially loaded with a series lines 
 * which begin with HTML {@code <BR />} elements.
 * 
 * <BR /><BR />The following documentation example should help elucidate how this annotation may 
 * be used.  This example is copied from the {@link IntoHTMLTable.Background} enum documentaion.
 * To view all examples of using this annotation, please review the color selections which are
 * offered in the Nested-Enum (again, named '{@link IntoHTMLTable.Background Background}') for this
 * class.
 * 
 * @see Background
 */
@Retention(SOURCE)
@Target({FIELD, CONSTRUCTOR, METHOD})
@CSSLinks(FileNames="IHTBackground.css")
public @interface IntoHTMLTable 
{
    /**
     * This is the complete list of values that may be assigned to the Annotation-Element
     * named {@link #background()}.
     * 
     * <BR /><BR />The Documentation for the below Enum-Constants contains explicit examples for
     * how to use this Annotation, along with how each of the provided Color-Choices are rendered
     * inside of a Web-Browser Tabl.
     */
    public enum Background
    {
        /** 
         * This is the "default" color-assignment which is used whenever no value is
         * provided to the background value.
         * 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_STANDARD_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_STANDARD_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BROWN_SPAN>
         */
        Standard(new TagNode("<DIV CLASS='block IHTA Standard'>")),

        /**
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_D_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_D_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_SPAN>
         */
        BlueDither (new TagNode("<DIV CLASS='block IHTA BlueDither'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_D_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_D_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_SPAN>
         */
        GreenDither (new TagNode("<DIV CLASS='block IHTA GreenDither'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_D_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_D_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_SPAN>
         */
        GrayDither (new TagNode("<DIV CLASS='block IHTA GrayDither'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BROWN_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BROWN_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BROWN_SPAN>
         */
        Brown (new TagNode("<DIV CLASS='block IHTA Brown'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BLUE_SPAN>
         */
        Blue (new TagNode("<DIV CLASS='block IHTA Blue'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GREEN_SPAN>
         */
        Green (new TagNode("<DIV CLASS='block IHTA Green'>")),

        /** 
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_EX>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_DIV>
         * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_GRAY_SPAN>
         */
        Gray (new TagNode("<DIV CLASS='block IHTA Gray'>"));

        /**
         * The HTML {@code <DIV>} Tag which is used to wrap the contents of the
         * Description-Box.
         */
        public final TagNode DIV;

        private Background(TagNode DIV)
        { this.DIV = DIV; }
    };

    /**
     * Allows a user to select the CSS-Class, and therefore the Colors, assigned to both the 
     * HTML-Table, and the Title-Background for the Description-Area of this Detail-Element.
     * 
     * <BR /><BR />This is the "default" color-assignment which is used whenever no value is
     * provided to the background value.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_STANDARD_EX>
     * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_STANDARD_DIV>
     * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_BROWN_SPAN>
     */
    public Background background() default Background.Standard;

    /**
     * This is the Title-{@code String} that is placed at the top of the HTML-Table.  It will be
     * placed onto a small background Text-Box that is mono-colored according to the settings which
     * are assigned to the {@link Background} passed to this Annotation (or the default 
     * {@code Background}, if no such color is passed or requeted to the {@link #background()} 
     * Annotation-Element.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Title-{@code String} Rules:</B>
     * 
     * <BR /><UL CLASS=JDUL>
     *  <LI>This {@code String} may not contain the characters: '\t', '\n' or '\r'</LI>
     *  <LI>May it be more than <B STYLE='color:red;'>{@code 300} Characters</B> long.</LI>
     * </UL>
     */
    public String title() default "";

    /**
     * This is an Optional Annotation-Element that should only be used if they provided
     * Color-Settings that are offered by the {@link Background} 'enum' do not contain a sufficient
     * number of choices to properly render the HTML-Table which needs to be rendered.
     * 
     * <BR /><BR />It is expected that the value provided to this {@code String} be a valid CSS
     * {@code 'Class-Name'}.  The Error-Checking Logic for the processor of this annotation will, 
     * indeed check the {@code String} that is provided.
     * 
     * <BR /><BR />This is, likely, a lesser used feature of the {@code IntoHTMLTable}-Annotation.
     * It provides for the ability to assign a self-designated CSS-Class to the
     * Primary-{@code <DIV>} element.  <B><I>It is usually much easier to either:</B></I>
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>Provide a value to the {@link #background()} Annotation-Element</LI>
     * <LI>Provided no value, and allow that the default
     *      {@link Background#Standard Background}-Value be assigned.</LI>
     * </UL>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Multiple CSS Classes</B>
     * 
     * <BR />It is permissible to pass multiple CSS-Classes to this {@code String}-Element.  In 
     * order to apply multiple classes, simple separate them with white-space characters, in such
     * a way no different than if they had been used or applied inside of an Inline-CSS
     * {@code STYLE}-Attribute.
     */
    public String divCSSClass() default "";

    /**
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=IHT_TABLE_CSS_CLASS>
     */
    public String tableCSSClass() default "";
}