/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 "wins" * * @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(); }