/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/JXPanel_API.java
/*
 * $Id: JXPanel_API.html 1351 2006-08-22 22:09:30Z 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.AlphaComposite;
import java.awt.Color;
import java.awt.Component;
import java.awt.Composite;
import java.awt.Dimension;
import java.awt.GradientPaint;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.Insets;
import java.awt.LayoutManager;
import java.awt.Rectangle;
import java.awt.image.BufferedImage;

import javax.swing.JPanel;
import javax.swing.RepaintManager;
import javax.swing.Scrollable;
import org.jdesktop.swingx.painter.Painter;

/**
 * <p><code>JXPanel</code> is a simple extension of {@link JPanel} adding transparency
 * support, custom painting through delegation, and the ability to use the
 * <code>JXPanel</code> in a {@link JScrollPane}.</p>
 * 
 * <h2>Transparency</h2>
 * <p>The <code>JXPanel</code>'s <code>alpha</code> property is used to set the
 * level of transparency. A value of ".1" means 10% visible. A value of "1" means
 * 100% visible, or fully opaque. A value of "0" means 0% visible, or fully hidden.</p>
 * 
 * <p>Note that <i>opacity</i> is different from <i>transparency</i>. Swing components
 * declare themselves as opaque if they will paint every pixel within their bounds
 * as a solid (non transparent) color. Therefore, a transparent component <em>must</em>
 * be non-opaque. Further, a fully "shown" component with an alpha of 1 may still
 * be non-opaque.</p>
 * 
 * <p>When a <code>JXPanel</code> has an alpha of < 1, it will always report
 * <code>false</code> to <code>isOpaque()</code>. When the <code>JXPanel</code>
 * has an alpha of 1, it will report the value of the opaque property in the
 * <code>isOpaque()</code> call.</p>
 * 
 * <p>When an <code>alpha</code> level is set for a <code>JXPanel</code>, it is
 * honored by all of the child Components as well. For example, a
 * <code>JXPanel</code> containing a <code>JButton</code> would show both the
 * panel and the button as transparent, based on the alpha level of the panel.</p>
 * 
 * <p>Sometimes you may not want all components to have the alpha applied. To
 * facilitate this, <code>JXPanel</code> has the <code>inheritAlpha</code> property.
 * This property allows the <code>JXPanel</code> to decide whether it will honor
 * the alpha property of any parent <code>JXPanel</code>s. By default this value is
 * <code>true</code>.</p>
 * 
 * <p>To determine the alpha value that will be applied when painted, the
 * {@link #getEffectiveAlpha} method may be called.</p>
 * 
 * <p>In order for transparent painting to always work, it is necessary to install
 * a custom {@link RepaintManager}. This <code>RepaintManager</code> is reponsible
 * for ensuring that the alpha value gets set on the Graphics2D used for painting.
 * Since you may be using a custom <code>RepaintManager</code>,
 * <code>JXPanel</code> only installs the {@link RepaintManagerX} if another
 * <code>RepaintManager</code> with the {@link TranslucentRepaintManager} annotation
 * is not currently installed.</p>
 * 
 * <h2>Custom Painting Delegates</h2>
 * <p>The <code>JXPanel</code> supports custom painting delegates called
 * {@link Painter}s. Call {@link #setBackgroundPainter(Painter)} to set this
 * delegate. Because a <code>Painter</code> may not be opaque, setting a background
 * painter will cause the opaque property to be set to <code>false</code>.</p>
 * 
 * <p>In addition, if a background <code>Painter</code> is specified, it will do
 * all of the painting for the panel. Otherwise, the panel falls back onto the
 * normal painting algorithm based on the current look and feel.</p>
 * 
 * <p>Using the background <code>Painter</code> mechanism is <strong>not</strong>
 * intended as a replacement for using a look and feel UI delegate. Rather, it is
 * intended for situations where previously you would have had to subclass
 * <code>JPanel</code> and overridden the <code>paintComponent</code> method.
 * See {@link Painter} and {@link AbstractPainter} for more information.</p>
 * 
 * <h2>JScrollPane Support</h2>
 * <p><code>JXPanel</code> supports being embedded directly in a <code>JScrollPane</code>
 * by implementing the <code>Scrollable</code> interface. <code>Scrollable</code>
 * defines the following methods:
 * <ul>
 *  <li>getPreferredScrollableViewportSize()</li>
 *  <li>getScrollableBlockIncrement(...)</li>
 *  <li>getScrollableTracksViewportHeight()</li>
 *  <li>getScrollableTracksViewportWidth()</li>
 *  <li>getScrollableUnitIncrement(...)</li>
 * </ul></p>
 * 
 * <p><code>JXPanel simply implements these methods, and provides corrosponding setter
 * methods so developers can specify how the panel should behave in the
 * <code>JScrollPane</code>. Both <code>getScrollableBlockIncrement</code> and
 * <code>getScrollableUnitIncrement</code> are not Java Bean methods because they
 * require parameters. For these, bean setter methods have also been created.</p>
 * 
 * <p>One exception is the <code>getPreferredScrollableViewportSize</code> method. This
 * will return the preferred size of the <code>JXPanel</code>.</p>
 * 
 * <p>For example, to specify the scrollable block increment:
 * <pre><code>
 *      JXPanel panel = new JXPanel();
 *      panel.setScrollableBlockIncrement(50);
 *      System.out.println(panel.getScrollableBlockIncrement()); //prints out "50"
 *      System.out.println(panel.getScrollableBlockIncrement(rect, SwingConstants.VERTICAL, 1)); //prints out "50" 
 * </code></pre></p>
 * 
 * @author rbair
 */
public class JXPanel extends JPanel implements Scrollable {
    /** 
     * Creates a new instance of JXPanel
     */
    public JXPanel();
    
    /**
     * @param isDoubleBuffered
     */
    public JXPanel(boolean isDoubleBuffered);

    /**
     * @param layout
     */
    public JXPanel(LayoutManager layout);

    /**
     * @param layout
     * @param isDoubleBuffered
     */
    public JXPanel(LayoutManager layout, boolean isDoubleBuffered);
    
    /**
     * Set the transparency level for this component. This automatically
     * causes a repaint of the component. A value of ".1" means "10% visible".
     * Values are specified between 0 and 1 inclusive.
     *
     * @param alpha must be a value between 0 and 1 inclusive.
     */
    public void setAlpha(float alpha);
    
    /**
     * @return the transparency level for this component. This will be
     * a value between 0 and 1, inclusive.
     */
    public float getAlpha();

    /**
     * Returns the alpha to use when painting.
     * 
     * Unlike other properties, alpha can be set on a component, or on one of
     * its parents. If the alpha of a parent component is .4, and the alpha on
     * this component is .5, effectively the alpha for this component is .4
     * because the lowest alpha in the heirarchy &quot;wins&quot;
     * 
     * @return the alpha value to use when painting.
     */ 
    public float getEffectiveAlpha();
    
    /**
     * Gets whether to inherit the alpha value from a parent <code>JXPanel</code>
     * 
     * @return inheritAlpha property
     */
    public boolean isInheritAlpha();
    
    /**
     * Sets whether to inherit the alpha value from a parent.
     * 
     * @param val
     */
    public void setInheritAlpha(boolean val);
    
    /**
     * @inheritDoc
     */
    public boolean getScrollableTracksViewportHeight();
    
    /**
     * <p>Sets whether a viewport should always force the height of this 
     * <code>JXPanel</code> to match the height of the viewport. If true, vertical
     * scrolling is essentially disabled.</p>
     * 
     * @param scrollableTracksViewportHeight The scrollableTracksViewportHeight to set.
     */
    public void setScrollableTracksViewportHeight(boolean scrollableTracksViewportHeight);
    
    /**
     * @inheritDoc
     */
    public boolean getScrollableTracksViewportWidth();
    
    /**
     * <p>Sets whether a viewport should always force the width of this 
     * <code>JXPanel</code> to match the width of the viewport. If true, horizontal
     * scrolling is essentially disabled.</p>
     * 
     * @param scrollableTracksViewportWidth The scrollableTracksViewportWidth to set.
     */
    public void setScrollableTracksViewportWidth(boolean scrollableTracksViewportWidth);

    /**
     * @inheritDoc
     */
    public Dimension getPreferredScrollableViewportSize();
    
    /**
     * @inheritDoc
     */
    public int getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction);
    
    /**
     * <p>Gets the amount to move the scroll pane for one "block". In a text document,
     * this might represent a page of text.</p>
     * 
     * @return the amount to scroll by a block
     */
    public int getScrollableBlockIncrement();
    
    /**
     * <p>Sets the amount to move the scroll pane for one "block". In a text document,
     * this might represent a page of text.</p>
     * 
     * @param increment amount to move one "block". Negative values are permissible,
     *        though extremely uncommon.
     */
    public void setScrollableBlockIncrement(int increment);
    
    /**
     * @inheritDoc
     */
    public int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction);

    /**
     * Gets the minimum amount to scroll by. This is in pixels.
     * 
     * @return the minimum amount to scroll by
     */
    public int getScrollableUnitIncrement();
    
    /**
     * Sets the minimum amount to scroll by in pixels.
     * 
     * @param increment the minimum increment to scroll by, in pixels.
     */
    public void setScrollableUnitIncrement(int increment);
    
    /**
     * Specifies a Painter to use to paint the background of this JXPanel.
     * If <code>p</code> is not null, then setOpaque(false) will be called
     * as a side effect. A component should not be opaque if painters are
     * being used, because Painters may paint transparent pixels or not
     * paint certain pixels, such as around the border insets.
     * 
     * @param p the <code>Painter</code> to use. May be null.
     */
    public void setBackgroundPainter(Painter p);
    
    /**
     * Gets the <code>Painter</code> to use for painting the panel's background.
     * 
     * @return the <code>Painter</code> to use for the background. May be null.
     */
    public Painter getBackgroundPainter();
}