/Users/richardallenbair/Documents/Source/Projects/nonsense/jxheader/swingx/src/java/org/jdesktop/swingx/JXHeader_API.java
/*
 * $Id: JXHeader_API.html 1391 2006-09-12 22:30:47Z rbair $
 *
 * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
 * Santa Clara, California 95054, U.S.A. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

package org.jdesktop.swingx;

import java.awt.Color;
import java.awt.Font;
import java.awt.GridBagConstraints;
import java.awt.GridBagLayout;
import java.awt.Insets;
import javax.swing.Icon;
import javax.swing.ImageIcon;
import javax.swing.JLabel;
import javax.swing.SwingUtilities;
import javax.swing.UIManager;
import org.jdesktop.swingx.painter.gradient.BasicGradientPainter;
import org.jdesktop.swingx.plaf.HeaderUI;
import org.jdesktop.swingx.plaf.JXHeaderAddon;
import org.jdesktop.swingx.plaf.LookAndFeelAddons;

/**
 * <p><code>JXHeader is a simple component consisting of a title, a description, 
 * and an icon. An example of such a component can be seen on
 * <a href="http://jext.free.fr/header.png">Romain Guys ProgX website</a></p>
 *
 * <p><code>JXHeader</code> is a simple component that is also sufficiently 
 * configurable to be useable. The description area
 * accepts HTML conforming to version 3.2 of the HTML standard. The icon, title,
 * and description are all configurable. <code>JXHeader</code> itself extends 
 * {@link JXPanel}, providing translucency and painting delegates.</p>
 *
 * <p>If I were to reconstruct the ui shown in the above screenshot, I might
 * do so like this:<br/>
 * <pre><code>
 *      JXHeader header = new JXHeader();
 *      header.setTitle("Timing Framework Spline Editor");
 *      header.setDescription("Drag control points in the display to change the " +
 *          "shape of the spline\n" +
 *          "Click the Copy Code button to generate the corrosponding Java code.");
 *      Icon icon = new ImageIcon(getClass().getResource("tools.png"));
 *      header.setIcon(icon);
 * </code></pre></p>
 * 
 * Note: The HTML support doesn't exist yet. The UI delegate needs to discover whether
 * the text supplied is HTML or not, and change the content type of the editor pane
 * being used. The problem is that if "text/html" is always used, the font is wrong.
 * This same situation will be found in other parts of the code (JXErrorPane, for instance),
 * so this needs to be dealt with.
 * 
 * @status UNREVIEWED
 * @author rbair
 */
public class JXHeader extends JXPanel {
    /**
     * JXTaskPane pluggable UI key <i>swingx/TaskPaneUI</i>
     */
    public final static String uiClassID = "HeaderUI";
    
    /** Creates a new instance of JXHeader */
    public JXHeader() {
    }
    
    //------------------------------------------------------------- UI Logic
    
    /**
     * @inheritDoc
     */
    public HeaderUI getUI();
    
    /**
     * Sets the look and feel (L&F) object that renders this component.
     *
     * @param ui the HeaderUI L&F object
     * @see javax.swing.UIDefaults#getUI
     */
    public void setUI(HeaderUI ui);
    
    /**
     * Returns the name of the L&F class that renders this component.
     *
     * @return the string {@link #uiClassID}
     * @see javax.swing.JComponent#getUIClassID
     * @see javax.swing.UIDefaults#getUI
     */
    public String getUIClassID();
    
    /**
     * Sets the title to use. This may be either plain text, or a simplified
     * version of HTML, as JLabel would use.
     * 
     * This property is bound.
     * 
     * @param title the Title. May be null.
     */
    public void setTitle(String title);
    
    /**
     * Gets the title.
     * @return the title. May be null.
     */
    public String getTitle();
    
    /**
     * Sets the description for this header. This may use HTML, such as
     * that supported by JEditorPane (version 3.2 of the HTML spec).
     * 
     * This property is bound.
     * 
     * @param description the description. May be null, may be HTML or plain text.
     */
    public void setDescription(String description);
    
    /**
     * Gets the description.
     * 
     * @return description
     */
    public String getDescription();
    
    /**
     * Sets the icon to use for the header. It is generally recommended that this 
     * be an image 64x64 pixels in size, and that the icon have no gaps at the top.
     * 
     * This property is bound.
     * 
     * @param icon may be null
     */
    public void setIcon(Icon icon);
    
    /**
     * Gets the icon.
     * 
     * @return the Icon being used. May be null.
     */
    public Icon getIcon();
}