/*

 * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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 General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.swing;

import java.awt.Color;

import java.awt.Graphics;

import java.text.Format;

import java.text.NumberFormat;

import java.io.Serializable;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.swing.event.*;

import javax.accessibility.*;

import javax.swing.plaf.ProgressBarUI;

/**

 * A component that visually displays the progress of some task.  As the task

 * progresses towards completion, the progress bar displays the

 * task's percentage of completion.

 * This percentage is typically represented visually by a rectangle which

 * starts out empty and gradually becomes filled in as the task progresses.

 * In addition, the progress bar can display a textual representation of this

 * percentage.

 * <p>

 * {@code JProgressBar} uses a {@code BoundedRangeModel} as its data model,

 * with the {@code value} property representing the "current" state of the task,

 * and the {@code minimum} and {@code maximum} properties representing the

 * beginning and end points, respectively.

 * <p>

 * To indicate that a task of unknown length is executing,

 * you can put a progress bar into indeterminate mode.

 * While the bar is in indeterminate mode,

 * it animates constantly to show that work is occurring.

 * As soon as you can determine the task's length and amount of progress,

 * you should update the progress bar's value

 * and switch it back to determinate mode.

 *

 * <p>

 *

 * Here is an example of creating a progress bar,

 * where <code>task</code> is an object (representing some piece of work)

 * which returns information about the progress of the task:

 *

 *<pre>

 *progressBar = new JProgressBar(0, task.getLengthOfTask());

 *progressBar.setValue(0);

 *progressBar.setStringPainted(true);

 *</pre>

 *

 * Here is an example of querying the current state of the task, and using

 * the returned value to update the progress bar:

 *

 *<pre>

 *progressBar.setValue(task.getCurrent());

 *</pre>

 *

 * Here is an example of putting a progress bar into

 * indeterminate mode,

 * and then switching back to determinate mode

 * once the length of the task is known:

 *

 *<pre>

 *progressBar = new JProgressBar();

 *<em>...//when the task of (initially) unknown length begins:</em>

 *progressBar.setIndeterminate(true);

 *<em>...//do some work; get length of task...</em>

 *progressBar.setMaximum(newLength);

 *progressBar.setValue(newValue);

 *progressBar.setIndeterminate(false);

 *</pre>

 *

 * <p>

 *

 * For complete examples and further documentation see

 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/progress.html" target="_top">How to Monitor Progress</a>,

 * a section in <em>The Java Tutorial.</em>

 *

 * <p>

 * <strong>Warning:</strong> Swing is not thread safe. For more

 * information see <a

 * href="package-summary.html#threading">Swing's Threading

 * Policy</a>.

 * <p>

 * <strong>Warning:</strong>

 * Serialized objects of this class will not be compatible with

 * future Swing releases. The current serialization support is

 * appropriate for short term storage or RMI between applications running

 * the same version of Swing.  As of 1.4, support for long term storage

 * of all JavaBeans™

 * has been added to the <code>java.beans</code> package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @see javax.swing.plaf.basic.BasicProgressBarUI

 * @see javax.swing.BoundedRangeModel

 * @see javax.swing.SwingWorker

 *

 * @beaninfo

 *      attribute: isContainer false

 *    description: A component that displays an integer value.

 *

 * @author Michael C. Albers

 * @author Kathy Walrath

 */

public class JProgressBar extends JComponent implements SwingConstants, Accessible

{

    /**

     * @see #getUIClassID

     */

    private static final String uiClassID = "ProgressBarUI";

    /**

     * Whether the progress bar is horizontal or vertical.

     * The default is <code>HORIZONTAL</code>.

     *

     * @see #setOrientation

     */

    protected int orientation;

    /**

     * Whether to display a border around the progress bar.

     * The default is <code>true</code>.

     *

     * @see #setBorderPainted

     */

    protected boolean paintBorder;

    /**

     * The object that holds the data for the progress bar.

     *

     * @see #setModel

     */

    protected BoundedRangeModel model;

    /**

     * An optional string that can be displayed on the progress bar.

     * The default is <code>null</code>. Setting this to a non-<code>null</code>

     * value does not imply that the string will be displayed.

     * To display the string, {@code paintString} must be {@code true}.

     *

     * @see #setString

     * @see #setStringPainted

     */

    protected String progressString;

    /**

     * Whether to display a string of text on the progress bar.

     * The default is <code>false</code>.

     * Setting this to <code>true</code> causes a textual

     * display of the progress to be rendered on the progress bar. If

     * the <code>progressString</code> is <code>null</code>,

     * the percentage of completion is displayed on the progress bar.

     * Otherwise, the <code>progressString</code> is

     * rendered on the progress bar.

     *

     * @see #setStringPainted

     * @see #setString

     */

    protected boolean paintString;

    /**

     * The default minimum for a progress bar is 0.

     */

    static final private int defaultMinimum = 0;

    /**

     * The default maximum for a progress bar is 100.

     */

    static final private int defaultMaximum = 100;

    /**

     * The default orientation for a progress bar is <code>HORIZONTAL</code>.

     */

    static final private int defaultOrientation = HORIZONTAL;

    /**

     * Only one <code>ChangeEvent</code> is needed per instance since the

     * event's only interesting property is the immutable source, which

     * is the progress bar.

     * The event is lazily created the first time that an

     * event notification is fired.

     *

     * @see #fireStateChanged

     */

    protected transient ChangeEvent changeEvent = null;

    /**

     * Listens for change events sent by the progress bar's model,

     * redispatching them

     * to change-event listeners registered upon

     * this progress bar.

     *

     * @see #createChangeListener

     */

    protected ChangeListener changeListener = null;

    /**

     * Format used when displaying percent complete.

     */

    private transient Format format;

    /**

     * Whether the progress bar is indeterminate (<code>true</code>) or

     * normal (<code>false</code>); the default is <code>false</code>.

     *

     * @see #setIndeterminate

     * @since 1.4

     */

    private boolean indeterminate;

   /**

     * Creates a horizontal progress bar

     * that displays a border but no progress string.

     * The initial and minimum values are 0,

     * and the maximum is 100.

     *

     * @see #setOrientation

     * @see #setBorderPainted

     * @see #setStringPainted

     * @see #setString

     * @see #setIndeterminate

     */

    public JProgressBar()

    {

        this(defaultOrientation);

    }

   /**

     * Creates a progress bar with the specified orientation,

     * which can be

     * either {@code SwingConstants.VERTICAL} or

     * {@code SwingConstants.HORIZONTAL}.

     * By default, a border is painted but a progress string is not.

     * The initial and minimum values are 0,

     * and the maximum is 100.

     *

     * @param orient  the desired orientation of the progress bar

     * @throws IllegalArgumentException if {@code orient} is an illegal value

     *

     * @see #setOrientation

     * @see #setBorderPainted

     * @see #setStringPainted

     * @see #setString

     * @see #setIndeterminate

     */

    public JProgressBar(int orient)

    {

        this(orient, defaultMinimum, defaultMaximum);

    }

    /**

     * Creates a horizontal progress bar

     * with the specified minimum and maximum.

     * Sets the initial value of the progress bar to the specified minimum.

     * By default, a border is painted but a progress string is not.

     * <p>

     * The <code>BoundedRangeModel</code> that holds the progress bar's data

     * handles any issues that may arise from improperly setting the

     * minimum, initial, and maximum values on the progress bar.

     * See the {@code BoundedRangeModel} documentation for details.

     *

     * @param min  the minimum value of the progress bar

     * @param max  the maximum value of the progress bar

     *

     * @see BoundedRangeModel

     * @see #setOrientation

     * @see #setBorderPainted

     * @see #setStringPainted

     * @see #setString

     * @see #setIndeterminate

     */

    public JProgressBar(int min, int max)

    {

        this(defaultOrientation, min, max);

    }

    /**

     * Creates a progress bar using the specified orientation,

     * minimum, and maximum.

     * By default, a border is painted but a progress string is not.

     * Sets the initial value of the progress bar to the specified minimum.

     * <p>

     * The <code>BoundedRangeModel</code> that holds the progress bar's data

     * handles any issues that may arise from improperly setting the

     * minimum, initial, and maximum values on the progress bar.

     * See the {@code BoundedRangeModel} documentation for details.

     *

     * @param orient  the desired orientation of the progress bar

     * @param min  the minimum value of the progress bar

     * @param max  the maximum value of the progress bar

     * @throws IllegalArgumentException if {@code orient} is an illegal value

     *

     * @see BoundedRangeModel

     * @see #setOrientation

     * @see #setBorderPainted

     * @see #setStringPainted

     * @see #setString

     * @see #setIndeterminate

     */

    public JProgressBar(int orient, int min, int max)

    {

        // Creating the model this way is a bit simplistic, but

        //  I believe that it is the the most common usage of this

        //  component - it's what people will expect.

        setModel(new DefaultBoundedRangeModel(min, 0, min, max));

        updateUI();

        setOrientation(orient);      // documented with set/getOrientation()

        setBorderPainted(true);      // documented with is/setBorderPainted()

        setStringPainted(false);     // see setStringPainted

        setString(null);             // see getString

        setIndeterminate(false);     // see setIndeterminate

    }

    /**

     * Creates a horizontal progress bar

     * that uses the specified model

     * to hold the progress bar's data.

     * By default, a border is painted but a progress string is not.

     *

     * @param newModel  the data model for the progress bar

     *

     * @see #setOrientation

     * @see #setBorderPainted

     * @see #setStringPainted

     * @see #setString

     * @see #setIndeterminate

     */

    public JProgressBar(BoundedRangeModel newModel)

    {

        setModel(newModel);

        updateUI();

        setOrientation(defaultOrientation);  // see setOrientation()

        setBorderPainted(true);              // see setBorderPainted()

        setStringPainted(false);             // see setStringPainted

        setString(null);                     // see getString

        setIndeterminate(false);             // see setIndeterminate

    }

    /**

     * Returns {@code SwingConstants.VERTICAL} or

     * {@code SwingConstants.HORIZONTAL}, depending on the orientation

     * of the progress bar. The default orientation is

     * {@code SwingConstants.HORIZONTAL}.

     *

     * @return <code>HORIZONTAL</code> or <code>VERTICAL</code>

     * @see #setOrientation

     */

    public int getOrientation() {

        return orientation;

    }

   /**

     * Sets the progress bar's orientation to <code>newOrientation</code>,

     * which must be {@code SwingConstants.VERTICAL} or

     * {@code SwingConstants.HORIZONTAL}. The default orientation

     * is {@code SwingConstants.HORIZONTAL}.

     *

     * @param  newOrientation  <code>HORIZONTAL</code> or <code>VERTICAL</code>

     * @exception      IllegalArgumentException    if <code>newOrientation</code>

     *                                              is an illegal value

     * @see #getOrientation

     *

     * @beaninfo

     *    preferred: true

     *        bound: true

     *    attribute: visualUpdate true

     *  description: Set the progress bar's orientation.

     */

    public void setOrientation(int newOrientation) {

        if (orientation != newOrientation) {

            switch (newOrientation) {

            case VERTICAL:

            case HORIZONTAL:

                int oldOrientation = orientation;

                orientation = newOrientation;

                firePropertyChange("orientation", oldOrientation, newOrientation);

                if (accessibleContext != null) {

                    accessibleContext.firePropertyChange(

                            AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

                            ((oldOrientation == VERTICAL)

                             ? AccessibleState.VERTICAL

                             : AccessibleState.HORIZONTAL),

                            ((orientation == VERTICAL)

                             ? AccessibleState.VERTICAL

                             : AccessibleState.HORIZONTAL));

                }

                break;

            default:

                throw new IllegalArgumentException(newOrientation +

                                             " is not a legal orientation");

            }

            revalidate();

        }

    }

    /**

     * Returns the value of the <code>stringPainted</code> property.

     *

     * @return the value of the <code>stringPainted</code> property

     * @see    #setStringPainted

     * @see    #setString

     */

    public boolean isStringPainted() {

        return paintString;

    }

    /**

     * Sets the value of the <code>stringPainted</code> property,

     * which determines whether the progress bar

     * should render a progress string.

     * The default is <code>false</code>, meaning

     * no string is painted.

     * Some look and feels might not support progress strings

     * or might support them only when the progress bar is in determinate mode.

     *

     * @param   b       <code>true</code> if the progress bar should render a string

     * @see     #isStringPainted

     * @see     #setString

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: Whether the progress bar should render a string.

     */

    public void setStringPainted(boolean b) {

        //PENDING: specify that string not painted when in indeterminate mode?

        //         or just leave that to the L&F?

        boolean oldValue = paintString;

        paintString = b;

        firePropertyChange("stringPainted", oldValue, paintString);

        if (paintString != oldValue) {

            revalidate();

            repaint();

        }

    }

    /**

     * Returns a {@code String} representation of the current progress.

     * By default, this returns a simple percentage {@code String} based on

     * the value returned from {@code getPercentComplete}.  An example

     * would be the "42%".  You can change this by calling {@code setString}.

     *

     * @return the value of the progress string, or a simple percentage string

     *         if the progress string is {@code null}

     * @see    #setString

     */

    public String getString(){

        if (progressString != null) {

            return progressString;

        } else {

            if (format == null) {

                format = NumberFormat.getPercentInstance();

            }

            return format.format(new Double(getPercentComplete()));

        }

    }

    /**

     * Sets the value of the progress string. By default,

     * this string is <code>null</code>, implying the built-in behavior of

     * using a simple percent string.

     * If you have provided a custom progress string and want to revert to

     * the built-in behavior, set the string back to <code>null</code>.

     * <p>

     * The progress string is painted only if

     * the <code>isStringPainted</code> method returns <code>true</code>.

     *

     * @param  s       the value of the progress string

     * @see    #getString

     * @see    #setStringPainted

     * @see    #isStringPainted

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: Specifies the progress string to paint

     */

    public void setString(String s){

        String oldValue = progressString;

        progressString = s;

        firePropertyChange("string", oldValue, progressString);

        if (progressString == null || oldValue == null || !progressString.equals(oldValue)) {

            repaint();

        }

    }

    /**

     * Returns the percent complete for the progress bar.

     * Note that this number is between 0.0 and 1.0.

     *

     * @return the percent complete for this progress bar

     */

    public double getPercentComplete() {