/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/JXStatusBar_API.java
/*
 * $Id: JXStatusBar_API.html 1344 2006-08-22 17:40:35Z 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.Component;
import java.awt.Container;
import java.awt.Dimension;
import java.awt.Insets;
import java.awt.LayoutManager2;
import java.util.HashMap;
import java.util.Map;
import javax.swing.JSeparator;
import javax.swing.SwingConstants;
import org.jdesktop.swingx.plaf.JXStatusBarAddon;
import org.jdesktop.swingx.plaf.LookAndFeelAddons;
import org.jdesktop.swingx.plaf.StatusBarUI;

/**
 * <p>A container for {@link javax.swing.JComponent}s that is typically placed at
 * the bottom of a form and runs the entire width of the form. There are 3
 * important functions that <code>JXStatusBar</code> provides.
 * First, <code>JXStatusBar</code> provides a hook for a pluggable look.
 * There is a definite look associated with status bars on windows, for instance.
 * By implementing a subclass of {@link JComponent}, we provide a way for the
 * pluggable look and feel system to modify the look of the status bar.</p>
 *
 * <p>Second, <code>JXStatusBar</code> comes with its own layout manager. Each item is added to
 * the <code>JXStatusBar</code> with a <code>JXStatusBar.Constraint</code>
 * as the constraint argument. The <code>JXStatusBar.Constraint</code> contains 
 * an <code>Insets</code> object, as well as a "weight". The weight
 * is used the same as the <code>GridBagLayout</code>. All the weights of each
 * constraint is added together to form a total weight. Each individual weight then
 * is used as a percentage of the whole. For example:
 * <pre><code>
 *  //a will get 30% of the free space because .3 + .3 + .4 = 1.0 and 1.0 * .3 = 30%
 *  bar.add(a, new JXStatusBar.Constraints(.3));
 *  //b will get 30% of the free space because .3 + .3 + .4 = 1.0 and 1.0 * .3 = 30%
 *  bar.add(b, new JXStatusBar.Constraints(.3));
 *  //c will get 40% of the free space because .3 + .3 + .4 = 1.0 and 1.0 * .4 = 40%
 *  bar.add(c, new JXStatusBar.Constraints(.4));
 * </code></pre></p>
 * 
 * <p>Constructing a <code>JXStatusBar</code> is very straitforward:
 * <pre><code>
 *      JXStatusBar bar = new JXStatusBar();
 *      JLabel statusLabel = new JLabel("Ready");
 *      bar.add(statusLabel, new JXStatusBar.Constraints(1.0); //weight of 0.0 and no insets
 *      JProgressBar pbar = new JProgressBar();
 *      bar.add(pbar); //weight of 0.0 and no insets
 * </code></pre></p>
 *
 * <p>Two common use cases for status bars include tracking application status and
 * progress. <code>JXStatusBar</code> does not manage these tasks, but instead special components
 * exist or can be created that do manage these tasks. For example, if your application
 * has a TaskManager or some other repository of currently running jobs, you could
 * easily create a TaskManagerProgressBar that tracks those jobs. This component
 * could then be added to the <code>JXStatusBar</code> like any other component.</p>
 *
 * @author pdoubleya
 * @author rbair
 */
public class JXStatusBar_API extends JXPanel {
    /**
     * @see #getUIClassID
     * @see #readObject
     */
    public static final String uiClassID = "StatusBarUI";
    
    /**
     * Creates a new JXStatusBar
     */
    public JXStatusBar();

    /**
     * Returns the look and feel (L&F) object that renders this component.
     * 
     * @return the StatusBarUI object that renders this component
     */
    @Override
    public StatusBarUI getUI();

    /**
     * Sets the look and feel (L&F) object that renders this component.
     * 
     * @param ui
     *            the StatusBarUI L&F object
     * @see javax.swing.UIDefaults#getUI
     * @beaninfo bound: true hidden: true attribute: visualUpdate true
     *           description: The UI object that implements the Component's
     *           LookAndFeel.
     */
    public void setUI(StatusBarUI ui);

    /**
     * Returns a string that specifies the name of the L&F class that renders
     * this component.
     * 
     * @return "StatusBarUI"
     * @see javax.swing.JComponent#getUIClassID
     * @see javax.swing.UIDefaults#getUI
     * @beaninfo expert: true description: A string that specifies the name of
     *           the L&F class.
     */
    @Override
    public String getUIClassID();

    /**
     * Notification from the <code>UIManager</code> that the L&F has changed.
     * Replaces the current UI object with the latest version from the
     * <code>UIManager</code>.
     * 
     * @see javax.swing.JComponent#updateUI
     */
    @Override
    public void updateUI();

    /**
     * Adds a {@link JSeparator} component. The component will be configured
     * properly based on the look and feel.
     */
    public void addSeparator();
    
    /**
     * The constraint object to be used with the <code>JXStatusBar</code>. It takes
     * both a weight and Insets. @see JXStatusBar class documentation.
     */
    public static class Constraint {
        /**
         * Creates a new Constraint with no weight and no insets.
         */
        public Constraint();
        
        /**
         * Creates a new Constraint with no weight and the given insets
         * 
         * @param insets may be null. If null, an Insets with 0 values will be used.
         */
        public Constraint(Insets insets);
        
        /**
         * Creats a new Constraint with the given weight and no insets
         * 
         * @param weight must be >= 0
         */
        public Constraint(double weight);
        
        /**
         * Creates a new Constraint with the specified weight and insets.
         * 
         * @param weight must be >= 0
         * @param insets may be null. If null, an Insets with 0 values will be used.
         */
        public Constraint(double weight, Insets insets);
        
        /**
         * Returns the weight.
         * 
         * @return weight
         */
        public double getWeight();
        
        /**
         * Returns the insets.
         * 
         * @return insets
         */
        public Insets getInsets();
    }
}