/*

 * Copyright (c) 1997, 2006, 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.Component;

import java.awt.ComponentOrientation;

import java.awt.Container;

import java.awt.Dimension;

import java.awt.Graphics;

import java.awt.Insets;

import java.awt.LayoutManager;

import java.awt.LayoutManager2;

import java.awt.event.*;

import java.beans.*;

import javax.swing.border.Border;

import javax.swing.plaf.*;

import javax.accessibility.*;

import java.io.Serializable;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import java.util.Hashtable;

/**

 * <code>JToolBar</code> provides a component that is useful for

 * displaying commonly used <code>Action</code>s or controls.

 * For examples and information on using tool bars see

 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/toolbar.html">How to Use Tool Bars</a>,

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

 *

 * <p>

 * With most look and feels,

 * the user can drag out a tool bar into a separate window

 * (unless the <code>floatable</code> property is set to <code>false</code>).

 * For drag-out to work correctly, it is recommended that you add

 * <code>JToolBar</code> instances to one of the four "sides" of a

 * container whose layout manager is a <code>BorderLayout</code>,

 * and do not add children to any of the other four "sides".

 * <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}.

 *

 * @beaninfo

 *   attribute: isContainer true

 * description: A component which displays commonly used controls or Actions.

 *

 * @author Georges Saab

 * @author Jeff Shapiro

 * @see Action

 */

public class JToolBar extends JComponent implements SwingConstants, Accessible

{

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "ToolBarUI";

    private    boolean   paintBorder              = true;

    private    Insets    margin                   = null;

    private    boolean   floatable                = true;

    private    int       orientation              = HORIZONTAL;

    /**

     * Creates a new tool bar; orientation defaults to <code>HORIZONTAL</code>.

     */

    public JToolBar()

    {

        this( HORIZONTAL );

    }

    /**

     * Creates a new tool bar with the specified <code>orientation</code>.

     * The <code>orientation</code> must be either <code>HORIZONTAL</code>

     * or <code>VERTICAL</code>.

     *

     * @param orientation  the orientation desired

     */

    public JToolBar( int orientation )

    {

        this(null, orientation);

    }

    /**

     * Creates a new tool bar with the specified <code>name</code>.  The

     * name is used as the title of the undocked tool bar.  The default

     * orientation is <code>HORIZONTAL</code>.

     *

     * @param name the name of the tool bar

     * @since 1.3

     */

    public JToolBar( String name ) {

        this(name, HORIZONTAL);

    }

    /**

     * Creates a new tool bar with a specified <code>name</code> and

     * <code>orientation</code>.

     * All other constructors call this constructor.

     * If <code>orientation</code> is an invalid value, an exception will

     * be thrown.

     *

     * @param name  the name of the tool bar

     * @param orientation  the initial orientation -- it must be

     *          either <code>HORIZONTAL</code> or <code>VERTICAL</code>

     * @exception IllegalArgumentException if orientation is neither

     *          <code>HORIZONTAL</code> nor <code>VERTICAL</code>

     * @since 1.3

     */

    public JToolBar( String name , int orientation) {

        setName(name);

        checkOrientation( orientation );

        this.orientation = orientation;

        DefaultToolBarLayout layout =  new DefaultToolBarLayout( orientation );

        setLayout( layout );

        addPropertyChangeListener( layout );

        updateUI();

    }

    /**

     * Returns the tool bar's current UI.

     * @see #setUI

     */

    public ToolBarUI getUI() {

        return (ToolBarUI)ui;

    }

    /**

     * Sets the L&F object that renders this component.

     *

     * @param ui  the <code>ToolBarUI</code> L&amp;F object

     * @see UIDefaults#getUI

     * @beaninfo

     *        bound: true

     *       hidden: true

     *    attribute: visualUpdate true

     *  description: The UI object that implements the Component's LookAndFeel.

     */

    public void setUI(ToolBarUI ui) {

        super.setUI(ui);

    }

    /**

     * Notification from the <code>UIFactory</code> that the L&amp;F has changed.

     * Called to replace the UI with the latest version from the

     * <code>UIFactory</code>.

     *

     * @see JComponent#updateUI

     */

    public void updateUI() {

        setUI((ToolBarUI)UIManager.getUI(this));

        // GTKLookAndFeel installs a different LayoutManager, and sets it

        // to null after changing the look and feel, so, install the default

        // if the LayoutManager is null.

        if (getLayout() == null) {

            setLayout(new DefaultToolBarLayout(getOrientation()));

        }

        invalidate();

    }

    /**

     * Returns the name of the L&F class that renders this component.

     *

     * @return the string "ToolBarUI"

     * @see JComponent#getUIClassID

     * @see UIDefaults#getUI

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

     * Returns the index of the specified component.

     * (Note: Separators occupy index positions.)

     *

     * @param c  the <code>Component</code> to find

     * @return an integer indicating the component's position,

     *          where 0 is first

     */

    public int getComponentIndex(Component c) {

        int ncomponents = this.getComponentCount();

        Component[] component = this.getComponents();

        for (int i = 0 ; i < ncomponents ; i++) {

            Component comp = component[i];

            if (comp == c)

                return i;

        }

        return -1;

    }

    /**

     * Returns the component at the specified index.

     *

     * @param i  the component's position, where 0 is first

     * @return   the <code>Component</code> at that position,

     *          or <code>null</code> for an invalid index

     *

     */

    public Component getComponentAtIndex(int i) {

        int ncomponents = this.getComponentCount();

        if ( i >= 0 && i < ncomponents) {

            Component[] component = this.getComponents();

            return component[i];

        }

        return null;

    }

     /**

      * Sets the margin between the tool bar's border and

      * its buttons. Setting to <code>null</code> causes the tool bar to

      * use the default margins. The tool bar's default <code>Border</code>

      * object uses this value to create the proper margin.

      * However, if a non-default border is set on the tool bar,

      * it is that <code>Border</code> object's responsibility to create the

      * appropriate margin space (otherwise this property will

      * effectively be ignored).

      *

      * @param m an <code>Insets</code> object that defines the space

      *         between the border and the buttons

      * @see Insets

      * @beaninfo

      * description: The margin between the tool bar's border and contents

      *       bound: true

      *      expert: true

      */

     public void setMargin(Insets m)

     {

         Insets old = margin;

         margin = m;

         firePropertyChange("margin", old, m);

         revalidate();

         repaint();

     }

     /**

      * Returns the margin between the tool bar's border and

      * its buttons.

      *

      * @return an <code>Insets</code> object containing the margin values

      * @see Insets

      */

     public Insets getMargin()

     {

         if(margin == null) {

             return new Insets(0,0,0,0);

         } else {

             return margin;

         }

     }

     /**

      * Gets the <code>borderPainted</code> property.

      *

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

      * @see #setBorderPainted

      */

     public boolean isBorderPainted()

     {

         return paintBorder;

     }

     /**

      * Sets the <code>borderPainted</code> property, which is

      * <code>true</code> if the border should be painted.

      * The default value for this property is <code>true</code>.

      * Some look and feels might not implement painted borders;

      * they will ignore this property.

      *

      * @param b if true, the border is painted

      * @see #isBorderPainted

      * @beaninfo

      * description: Does the tool bar paint its borders?

      *       bound: true

      *      expert: true

      */

     public void setBorderPainted(boolean b)

     {

         if ( paintBorder != b )

         {

             boolean old = paintBorder;

             paintBorder = b;

             firePropertyChange("borderPainted", old, b);

             revalidate();

             repaint();

         }

     }

     /**

      * Paints the tool bar's border if the <code>borderPainted</code> property

      * is <code>true</code>.

      *

      * @param g  the <code>Graphics</code> context in which the painting

      *         is done

      * @see JComponent#paint

      * @see JComponent#setBorder

      */

     protected void paintBorder(Graphics g)

     {

         if (isBorderPainted())

         {

             super.paintBorder(g);

         }

     }

    /**

     * Gets the <code>floatable</code> property.

     *

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

     *

     * @see #setFloatable

     */

    public boolean isFloatable()

    {

        return floatable;

    }

     /**

      * Sets the <code>floatable</code> property,

      * which must be <code>true</code> for the user to move the tool bar.

      * Typically, a floatable tool bar can be

      * dragged into a different position within the same container

      * or out into its own window.

      * The default value of this property is <code>true</code>.

      * Some look and feels might not implement floatable tool bars;

      * they will ignore this property.

      *

      * @param b if <code>true</code>, the tool bar can be moved;

      *          <code>false</code> otherwise

      * @see #isFloatable

      * @beaninfo

      * description: Can the tool bar be made to float by the user?

      *       bound: true

      *   preferred: true

      */

    public void setFloatable( boolean b )

    {

        if ( floatable != b )

        {

            boolean old = floatable;

            floatable = b;

            firePropertyChange("floatable", old, b);

            revalidate();

            repaint();

        }

    }

    /**

     * Returns the current orientation of the tool bar.  The value is either

     * <code>HORIZONTAL</code> or <code>VERTICAL</code>.

     *

     * @return an integer representing the current orientation -- either

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

     * @see #setOrientation

     */

    public int getOrientation()

    {

        return this.orientation;

    }

    /**

     * Sets the orientation of the tool bar.  The orientation must have

     * either the value <code>HORIZONTAL</code> or <code>VERTICAL</code>.

     * If <code>orientation</code> is

     * an invalid value, an exception will be thrown.

     *

     * @param o  the new orientation -- either <code>HORIZONTAL</code> or

     *                  <code>VERTICAL</code>

     * @exception IllegalArgumentException if orientation is neither

     *          <code>HORIZONTAL</code> nor <code>VERTICAL</code>

     * @see #getOrientation

     * @beaninfo

     * description: The current orientation of the tool bar

     *       bound: true

     *   preferred: true

     *        enum: HORIZONTAL SwingConstants.HORIZONTAL

     *              VERTICAL   SwingConstants.VERTICAL

     */

    public void setOrientation( int o )

    {

        checkOrientation( o );

        if ( orientation != o )

        {

            int old = orientation;

            orientation = o;

            firePropertyChange("orientation", old, o);

            revalidate();

            repaint();

        }

    }

    /**

     * Sets the rollover state of this toolbar. If the rollover state is true

     * then the border of the toolbar buttons will be drawn only when the

     * mouse pointer hovers over them. The default value of this property

     * is false.

     * <p>

     * The implementation of a look and feel may choose to ignore this

     * property.

     *

     * @param rollover true for rollover toolbar buttons; otherwise false

     * @since 1.4

     * @beaninfo

     *        bound: true

     *    preferred: true

     *    attribute: visualUpdate true

     *  description: Will draw rollover button borders in the toolbar.

     */

    public void setRollover(boolean rollover) {

        putClientProperty("JToolBar.isRollover",

                          rollover ? Boolean.TRUE : Boolean.FALSE);

    }

    /**

     * Returns the rollover state.

     *

     * @return true if rollover toolbar buttons are to be drawn; otherwise false

     * @see #setRollover(boolean)

     * @since 1.4

     */

    public boolean isRollover() {

        Boolean rollover = (Boolean)getClientProperty("JToolBar.isRollover");

        if (rollover != null) {

            return rollover.booleanValue();

        }

        return false;

    }

    private void checkOrientation( int orientation )

    {

        switch ( orientation )

        {

            case VERTICAL:

            case HORIZONTAL:

                break;

            default:

                throw new IllegalArgumentException( "orientation must be one of: VERTICAL, HORIZONTAL" );

        }

    }

    /**

     * Appends a separator of default size to the end of the tool bar.

     * The default size is determined by the current look and feel.

     */

    public void addSeparator()

    {

        addSeparator(null);

    }

    /**

     * Appends a separator of a specified size to the end

     * of the tool bar.

     *

     * @param size the <code>Dimension</code> of the separator

     */

    public void addSeparator( Dimension size )

    {

        JToolBar.Separator s = new JToolBar.Separator( size );

        add(s);

    }

    /**

     * Adds a new <code>JButton</code> which dispatches the action.

     *

     * @param a the <code>Action</code> object to add as a new menu item

     * @return the new button which dispatches the action

     */

    public JButton add(Action a) {

        JButton b = createActionComponent(a);

        b.setAction(a);

        add(b);

        return b;

    }

    /**

     * Factory method which creates the <code>JButton</code> for

     * <code>Action</code>s added to the <code>JToolBar</code>.

     * The default name is empty if a <code>null</code> action is passed.

     *