1 /*

     2  * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.

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

     4  *

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

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

     7  * published by the Free Software Foundation.  Sun designates this

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

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package javax.swing;

    27 

    28 import java.awt.*;

    29 import java.awt.event.*;

    30 import java.beans.*;

    31 import java.util.*;

    32 import javax.swing.event.*;

    33 import javax.swing.plaf.*;

    34 import javax.accessibility.*;

    35 import sun.swing.SwingUtilities2;

    36 

    37 import java.io.Serializable;

    38 import java.io.ObjectOutputStream;

    39 import java.io.ObjectInputStream;

    40 import java.io.IOException;

    41 

    42 /**

    43  * A component that lets the user switch between a group of components by

    44  * clicking on a tab with a given title and/or icon.

    45  * For examples and information on using tabbed panes see

    46  * <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/tabbedpane.html">How to Use Tabbed Panes</a>,

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

    48  * <p>

    49  * Tabs/components are added to a <code>TabbedPane</code> object by using the

    50  * <code>addTab</code> and <code>insertTab</code> methods.

    51  * A tab is represented by an index corresponding

    52  * to the position it was added in, where the first tab has an index equal to 0

    53  * and the last tab has an index equal to the tab count minus 1.

    54  * <p>

    55  * The <code>TabbedPane</code> uses a <code>SingleSelectionModel</code>

    56  * to represent the set

    57  * of tab indices and the currently selected index.  If the tab count

    58  * is greater than 0, then there will always be a selected index, which

    59  * by default will be initialized to the first tab.  If the tab count is

    60  * 0, then the selected index will be -1.

    61  * <p>

    62  * The tab title can be rendered by a <code>Component</code>.

    63  * For example, the following produce similar results:

    64  * <pre>

    65  * // In this case the look and feel renders the title for the tab.

    66  * tabbedPane.addTab("Tab", myComponent);

    67  * // In this case the custom component is responsible for rendering the

    68  * // title of the tab.

    69  * tabbedPane.addTab(null, myComponent);

    70  * tabbedPane.setTabComponentAt(0, new JLabel("Tab"));

    71  * </pre>

    72  * The latter is typically used when you want a more complex user interaction

    73  * that requires custom components on the tab.  For example, you could

    74  * provide a custom component that animates or one that has widgets for

    75  * closing the tab.

    76  * <p>

    77  * If you specify a component for a tab, the <code>JTabbedPane</code>

    78  * will not render any text or icon you have specified for the tab.

    79  * <p>

    80  * <strong>Note:</strong>

    81  * Do not use <code>setVisible</code> directly on a tab component to make it visible,

    82  * use <code>setSelectedComponent</code> or <code>setSelectedIndex</code> methods instead.

    83  * <p>

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

    85  * information see <a

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

    87  * Policy</a>.

    88  * <p>

    89  * <strong>Warning:</strong>

    90  * Serialized objects of this class will not be compatible with

    91  * future Swing releases. The current serialization support is

    92  * appropriate for short term storage or RMI between applications running

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

    94  * of all JavaBeans<sup><font size="-2">TM</font></sup>

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

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

    97  *

    98  * @beaninfo

    99  *      attribute: isContainer true

   100  *    description: A component which provides a tab folder metaphor for

   101  *                 displaying one component from a set of components.

   102  *

   103  * @author Dave Moore

   104  * @author Philip Milne

   105  * @author Amy Fowler

   106  *

   107  * @see SingleSelectionModel

   108  */

   109 public class JTabbedPane extends JComponent

   110        implements Serializable, Accessible, SwingConstants {

   111 

   112    /**

   113     * The tab layout policy for wrapping tabs in multiple runs when all

   114     * tabs will not fit within a single run.

   115     */

   116     public static final int WRAP_TAB_LAYOUT = 0;

   117 

   118    /**

   119     * Tab layout policy for providing a subset of available tabs when all

   120     * the tabs will not fit within a single run.  If all the tabs do

   121     * not fit within a single run the look and feel will provide a way

   122     * to navigate to hidden tabs.

   123     */

   124     public static final int SCROLL_TAB_LAYOUT = 1;

   125 

   126 

   127     /**

   128      * @see #getUIClassID

   129      * @see #readObject

   130      */

   131     private static final String uiClassID = "TabbedPaneUI";

   132 

   133     /**

   134      * Where the tabs are placed.

   135      * @see #setTabPlacement

   136      */

   137     protected int tabPlacement = TOP;

   138 

   139     private int tabLayoutPolicy;

   140 

   141     /** The default selection model */

   142     protected SingleSelectionModel model;

   143 

   144     private boolean haveRegistered;

   145 

   146     /**

   147      * The <code>changeListener</code> is the listener we add to the

   148      * model.

   149      */

   150     protected ChangeListener changeListener = null;

   151 

   152     private final java.util.List<Page> pages;

   153 

   154     /* The component that is currently visible */

   155     private Component visComp = null;

   156 

   157     /**

   158      * Only one <code>ChangeEvent</code> is needed per <code>TabPane</code>

   159      * instance since the

   160      * event's only (read-only) state is the source property.  The source

   161      * of events generated here is always "this".

   162      */

   163     protected transient ChangeEvent changeEvent = null;

   164 

   165     /**

   166      * Creates an empty <code>TabbedPane</code> with a default

   167      * tab placement of <code>JTabbedPane.TOP</code>.

   168      * @see #addTab

   169      */

   170     public JTabbedPane() {

   171         this(TOP, WRAP_TAB_LAYOUT);

   172     }

   173 

   174     /**

   175      * Creates an empty <code>TabbedPane</code> with the specified tab placement

   176      * of either: <code>JTabbedPane.TOP</code>, <code>JTabbedPane.BOTTOM</code>,

   177      * <code>JTabbedPane.LEFT</code>, or <code>JTabbedPane.RIGHT</code>.

   178      *

   179      * @param tabPlacement the placement for the tabs relative to the content

   180      * @see #addTab

   181      */

   182     public JTabbedPane(int tabPlacement) {

   183         this(tabPlacement, WRAP_TAB_LAYOUT);

   184     }

   185 

   186     /**

   187      * Creates an empty <code>TabbedPane</code> with the specified tab placement

   188      * and tab layout policy.  Tab placement may be either:

   189      * <code>JTabbedPane.TOP</code>, <code>JTabbedPane.BOTTOM</code>,

   190      * <code>JTabbedPane.LEFT</code>, or <code>JTabbedPane.RIGHT</code>.

   191      * Tab layout policy may be either: <code>JTabbedPane.WRAP_TAB_LAYOUT</code>

   192      * or <code>JTabbedPane.SCROLL_TAB_LAYOUT</code>.

   193      *

   194      * @param tabPlacement the placement for the tabs relative to the content

   195      * @param tabLayoutPolicy the policy for laying out tabs when all tabs will not fit on one run

   196      * @exception IllegalArgumentException if tab placement or tab layout policy are not

   197      *            one of the above supported values

   198      * @see #addTab

   199      * @since 1.4

   200      */

   201     public JTabbedPane(int tabPlacement, int tabLayoutPolicy) {

   202         setTabPlacement(tabPlacement);

   203         setTabLayoutPolicy(tabLayoutPolicy);

   204         pages = new ArrayList<Page>(1);

   205         setModel(new DefaultSingleSelectionModel());

   206         updateUI();

   207     }

   208 

   209     /**

   210      * Returns the UI object which implements the L&F for this component.

   211      *

   212      * @return a <code>TabbedPaneUI</code> object

   213      * @see #setUI

   214      */

   215     public TabbedPaneUI getUI() {

   216         return (TabbedPaneUI)ui;

   217     }

   218 

   219     /**

   220      * Sets the UI object which implements the L&F for this component.

   221      *

   222      * @param ui the new UI object

   223      * @see UIDefaults#getUI

   224      * @beaninfo

   225      *        bound: true

   226      *       hidden: true

   227      *    attribute: visualUpdate true

   228      *  description: The UI object that implements the tabbedpane's LookAndFeel

   229      */

   230     public void setUI(TabbedPaneUI ui) {

   231         super.setUI(ui);

   232         // disabled icons are generated by LF so they should be unset here

   233         for (int i = 0; i < getTabCount(); i++) {

   234             Icon icon = pages.get(i).disabledIcon;

   235             if (icon instanceof UIResource) {

   236                 setDisabledIconAt(i, null);

   237             }

   238         }

   239     }

   240 

   241     /**

   242      * Resets the UI property to a value from the current look and feel.

   243      *

   244      * @see JComponent#updateUI

   245      */

   246     public void updateUI() {

   247         setUI((TabbedPaneUI)UIManager.getUI(this));

   248     }

   249 

   250 

   251     /**

   252      * Returns the name of the UI class that implements the

   253      * L&F for this component.

   254      *

   255      * @return the string "TabbedPaneUI"

   256      * @see JComponent#getUIClassID

   257      * @see UIDefaults#getUI

   258      */

   259     public String getUIClassID() {

   260         return uiClassID;

   261     }

   262 

   263 

   264     /**

   265      * We pass <code>ModelChanged</code> events along to the listeners with

   266      * the tabbedpane (instead of the model itself) as the event source.

   267      */

   268     protected class ModelListener implements ChangeListener, Serializable {

   269         public void stateChanged(ChangeEvent e) {

   270             fireStateChanged();

   271         }

   272     }

   273 

   274     /**

   275      * Subclasses that want to handle <code>ChangeEvents</code> differently

   276      * can override this to return a subclass of <code>ModelListener</code> or

   277      * another <code>ChangeListener</code> implementation.

   278      *

   279      * @see #fireStateChanged

   280      */

   281     protected ChangeListener createChangeListener() {

   282         return new ModelListener();

   283     }

   284 

   285     /**

   286      * Adds a <code>ChangeListener</code> to this tabbedpane.

   287      *

   288      * @param l the <code>ChangeListener</code> to add

   289      * @see #fireStateChanged

   290      * @see #removeChangeListener

   291      */

   292     public void addChangeListener(ChangeListener l) {

   293         listenerList.add(ChangeListener.class, l);

   294     }

   295 

   296     /**

   297      * Removes a <code>ChangeListener</code> from this tabbedpane.

   298      *

   299      * @param l the <code>ChangeListener</code> to remove

   300      * @see #fireStateChanged

   301      * @see #addChangeListener

   302      */

   303     public void removeChangeListener(ChangeListener l) {

   304         listenerList.remove(ChangeListener.class, l);

   305     }

   306 

   307    /**

   308      * Returns an array of all the <code>ChangeListener</code>s added

   309      * to this <code>JTabbedPane</code> with <code>addChangeListener</code>.

   310      *

   311      * @return all of the <code>ChangeListener</code>s added or an empty

   312      *         array if no listeners have been added

   313      * @since 1.4

   314      */

   315     public ChangeListener[] getChangeListeners() {

   316         return (ChangeListener[])listenerList.getListeners(

   317                 ChangeListener.class);

   318     }

   319 

   320     /**

   321      * Sends a {@code ChangeEvent}, with this {@code JTabbedPane} as the source,

   322      * to each registered listener. This method is called each time there is

   323      * a change to either the selected index or the selected tab in the

   324      * {@code JTabbedPane}. Usually, the selected index and selected tab change

   325      * together. However, there are some cases, such as tab addition, where the

   326      * selected index changes and the same tab remains selected. There are other

   327      * cases, such as deleting the selected tab, where the index remains the

   328      * same, but a new tab moves to that index. Events are fired for all of

   329      * these cases.

   330      *

   331      * @see #addChangeListener

   332      * @see EventListenerList

   333      */

   334     protected void fireStateChanged() {

   335         /* --- Begin code to deal with visibility --- */

   336 

   337         /* This code deals with changing the visibility of components to

   338          * hide and show the contents for the selected tab. It duplicates

   339          * logic already present in BasicTabbedPaneUI, logic that is

   340          * processed during the layout pass. This code exists to allow

   341          * developers to do things that are quite difficult to accomplish

   342          * with the previous model of waiting for the layout pass to process

   343          * visibility changes; such as requesting focus on the new visible

   344          * component.

   345          *

   346          * For the average code, using the typical JTabbedPane methods,

   347          * all visibility changes will now be processed here. However,

   348          * the code in BasicTabbedPaneUI still exists, for the purposes

   349          * of backward compatibility. Therefore, when making changes to

   350          * this code, ensure that the BasicTabbedPaneUI code is kept in

   351          * synch.

   352          */

   353 

   354         int selIndex = getSelectedIndex();

   355 

   356         /* if the selection is now nothing */

   357         if (selIndex < 0) {

   358             /* if there was a previous visible component */

   359             if (visComp != null && visComp.isVisible()) {

   360                 /* make it invisible */

   361                 visComp.setVisible(false);

   362             }

   363 

   364             /* now there's no visible component */

   365             visComp = null;

   366 

   367         /* else - the selection is now something */

   368         } else {

   369             /* Fetch the component for the new selection */

   370             Component newComp = getComponentAt(selIndex);

   371 

   372             /* if the new component is non-null and different */

   373             if (newComp != null && newComp != visComp) {

   374                 boolean shouldChangeFocus = false;

   375 

   376                 /* Note: the following (clearing of the old visible component)

   377                  * is inside this if-statement for good reason: Tabbed pane

   378                  * should continue to show the previously visible component

   379                  * if there is no component for the chosen tab.

   380                  */

   381 

   382                 /* if there was a previous visible component */

   383                 if (visComp != null) {

   384                     shouldChangeFocus =

   385                         (SwingUtilities.findFocusOwner(visComp) != null);

   386 

   387                     /* if it's still visible */

   388                     if (visComp.isVisible()) {

   389                         /* make it invisible */

   390                         visComp.setVisible(false);

   391                     }

   392                 }

   393 

   394                 if (!newComp.isVisible()) {

   395                     newComp.setVisible(true);

   396                 }

   397 

   398                 if (shouldChangeFocus) {

   399                     SwingUtilities2.tabbedPaneChangeFocusTo(newComp);

   400                 }

   401 

   402                 visComp = newComp;

   403             } /* else - the visible component shouldn't changed */

   404         }

   405 

   406         /* --- End code to deal with visibility --- */

   407 

   408         // Guaranteed to return a non-null array

   409         Object[] listeners = listenerList.getListenerList();

   410         // Process the listeners last to first, notifying

   411         // those that are interested in this event

   412         for (int i = listeners.length-2; i>=0; i-=2) {

   413             if (listeners[i]==ChangeListener.class) {

   414                 // Lazily create the event:

   415                 if (changeEvent == null)

   416                     changeEvent = new ChangeEvent(this);

   417                 ((ChangeListener)listeners[i+1]).stateChanged(changeEvent);

   418             }

   419         }

   420     }

   421 

   422     /**

   423      * Returns the model associated with this tabbedpane.

   424      *

   425      * @see #setModel

   426      */

   427     public SingleSelectionModel getModel() {

   428         return model;

   429     }

   430 

   431     /**

   432      * Sets the model to be used with this tabbedpane.

   433      *

   434      * @param model the model to be used

   435      * @see #getModel

   436      * @beaninfo

   437      *       bound: true

   438      * description: The tabbedpane's SingleSelectionModel.

   439      */

   440     public void setModel(SingleSelectionModel model) {

   441         SingleSelectionModel oldModel = getModel();

   442 

   443         if (oldModel != null) {

   444             oldModel.removeChangeListener(changeListener);

   445             changeListener = null;

   446         }

   447 

   448         this.model = model;

   449 

   450         if (model != null) {

   451             changeListener = createChangeListener();

   452             model.addChangeListener(changeListener);

   453         }

   454 

   455         firePropertyChange("model", oldModel, model);

   456         repaint();

   457     }

   458 

   459     /**

   460      * Returns the placement of the tabs for this tabbedpane.

   461      * @see #setTabPlacement

   462      */

   463     public int getTabPlacement() {

   464         return tabPlacement;

   465     }

   466 

   467     /**

   468      * Sets the tab placement for this tabbedpane.

   469      * Possible values are:<ul>

   470      * <li><code>JTabbedPane.TOP</code>

   471      * <li><code>JTabbedPane.BOTTOM</code>

   472      * <li><code>JTabbedPane.LEFT</code>

   473      * <li><code>JTabbedPane.RIGHT</code>

   474      * </ul>

   475      * The default value, if not set, is <code>SwingConstants.TOP</code>.

   476      *

   477      * @param tabPlacement the placement for the tabs relative to the content

   478      * @exception IllegalArgumentException if tab placement value isn't one

   479      *                          of the above valid values

   480      *

   481      * @beaninfo

   482      *    preferred: true

   483      *        bound: true

   484      *    attribute: visualUpdate true

   485      *         enum: TOP JTabbedPane.TOP

   486      *               LEFT JTabbedPane.LEFT

   487      *               BOTTOM JTabbedPane.BOTTOM

   488      *               RIGHT JTabbedPane.RIGHT

   489      *  description: The tabbedpane's tab placement.

   490      *

   491      */

   492     public void setTabPlacement(int tabPlacement) {

   493         if (tabPlacement != TOP && tabPlacement != LEFT &&

   494             tabPlacement != BOTTOM && tabPlacement != RIGHT) {

   495             throw new IllegalArgumentException("illegal tab placement: must be TOP, BOTTOM, LEFT, or RIGHT");

   496         }

   497         if (this.tabPlacement != tabPlacement) {

   498             int oldValue = this.tabPlacement;

   499             this.tabPlacement = tabPlacement;

   500             firePropertyChange("tabPlacement", oldValue, tabPlacement);

   501             revalidate();

   502             repaint();

   503         }

   504     }

   505 

   506     /**

   507      * Returns the policy used by the tabbedpane to layout the tabs when all the

   508      * tabs will not fit within a single run.

   509      * @see #setTabLayoutPolicy

   510      * @since 1.4

   511      */

   512     public int getTabLayoutPolicy() {

   513         return tabLayoutPolicy;

   514     }

   515 

   516    /**

   517      * Sets the policy which the tabbedpane will use in laying out the tabs

   518      * when all the tabs will not fit within a single run.

   519      * Possible values are:

   520      * <ul>

   521      * <li><code>JTabbedPane.WRAP_TAB_LAYOUT</code>

   522      * <li><code>JTabbedPane.SCROLL_TAB_LAYOUT</code>

   523      * </ul>

   524      *

   525      * The default value, if not set by the UI, is <code>JTabbedPane.WRAP_TAB_LAYOUT</code>.

   526      * <p>

   527      * Some look and feels might only support a subset of the possible

   528      * layout policies, in which case the value of this property may be

   529      * ignored.

   530      *

   531      * @param tabLayoutPolicy the policy used to layout the tabs

   532      * @exception IllegalArgumentException if layoutPolicy value isn't one

   533      *                          of the above valid values

   534      * @see #getTabLayoutPolicy

   535      * @since 1.4

   536      *

   537      * @beaninfo

   538      *    preferred: true

   539      *        bound: true

   540      *    attribute: visualUpdate true

   541      *         enum: WRAP_TAB_LAYOUT JTabbedPane.WRAP_TAB_LAYOUT

   542      *               SCROLL_TAB_LAYOUT JTabbedPane.SCROLL_TAB_LAYOUT

   543      *  description: The tabbedpane's policy for laying out the tabs

   544      *

   545      */

   546     public void setTabLayoutPolicy(int tabLayoutPolicy) {

   547         if (tabLayoutPolicy != WRAP_TAB_LAYOUT && tabLayoutPolicy != SCROLL_TAB_LAYOUT) {

   548             throw new IllegalArgumentException("illegal tab layout policy: must be WRAP_TAB_LAYOUT or SCROLL_TAB_LAYOUT");

   549         }

   550         if (this.tabLayoutPolicy != tabLayoutPolicy) {

   551             int oldValue = this.tabLayoutPolicy;

   552             this.tabLayoutPolicy = tabLayoutPolicy;

   553             firePropertyChange("tabLayoutPolicy", oldValue, tabLayoutPolicy);

   554             revalidate();

   555             repaint();

   556         }

   557     }

   558 

   559     /**

   560      * Returns the currently selected index for this tabbedpane.

   561      * Returns -1 if there is no currently selected tab.

   562      *

   563      * @return the index of the selected tab

   564      * @see #setSelectedIndex

   565      */

   566     public int getSelectedIndex() {

   567         return model.getSelectedIndex();

   568     }

   569 

   570     /**

   571      * Sets the selected index for this tabbedpane. The index must be

   572      * a valid tab index or -1, which indicates that no tab should be selected

   573      * (can also be used when there are no tabs in the tabbedpane).  If a -1

   574      * value is specified when the tabbedpane contains one or more tabs, then

   575      * the results will be implementation defined.

   576      *

   577      * @param index  the index to be selected

   578      * @exception IndexOutOfBoundsException if index is out of range

   579      *            (index < -1 || index >= tab count)

   580      *

   581      * @see #getSelectedIndex

   582      * @see SingleSelectionModel#setSelectedIndex

   583      * @beaninfo

   584      *   preferred: true

   585      * description: The tabbedpane's selected tab index.

   586      */

   587     public void setSelectedIndex(int index) {

   588         if (index != -1) {

   589             checkIndex(index);

   590         }

   591         setSelectedIndexImpl(index, true);

   592     }

   593 

   594 

   595     private void setSelectedIndexImpl(int index, boolean doAccessibleChanges) {

   596         int oldIndex = model.getSelectedIndex();

   597         Page oldPage = null, newPage = null;

   598         String oldName = null;

   599 

   600         doAccessibleChanges = doAccessibleChanges && (oldIndex != index);

   601 

   602         if (doAccessibleChanges) {

   603             if (accessibleContext != null) {

   604                 oldName = accessibleContext.getAccessibleName();

   605             }

   606 

   607             if (oldIndex >= 0) {

   608                 oldPage = pages.get(oldIndex);

   609             }

   610 

   611             if (index >= 0) {

   612                 newPage = pages.get(index);

   613             }

   614         }

   615 

   616         model.setSelectedIndex(index);

   617 

   618         if (doAccessibleChanges) {

   619             changeAccessibleSelection(oldPage, oldName, newPage);

   620         }

   621     }

   622 

   623     private void changeAccessibleSelection(Page oldPage, String oldName, Page newPage) {

   624         if (accessibleContext == null) {

   625             return;

   626         }

   627 

   628         if (oldPage != null) {

   629             oldPage.firePropertyChange(AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

   630                                        AccessibleState.SELECTED, null);

   631         }

   632 

   633         if (newPage != null) {

   634             newPage.firePropertyChange(AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

   635                                        null, AccessibleState.SELECTED);

   636         }

   637 

   638         accessibleContext.firePropertyChange(

   639             AccessibleContext.ACCESSIBLE_NAME_PROPERTY,

   640             oldName,

   641             accessibleContext.getAccessibleName());

   642     }

   643 

   644     /**

   645      * Returns the currently selected component for this tabbedpane.

   646      * Returns <code>null</code> if there is no currently selected tab.

   647      *

   648      * @return the component corresponding to the selected tab

   649      * @see #setSelectedComponent

   650      */

   651     public Component getSelectedComponent() {

   652         int index = getSelectedIndex();

   653         if (index == -1) {

   654             return null;

   655         }

   656         return getComponentAt(index);

   657     }

   658 

   659     /**

   660      * Sets the selected component for this tabbedpane.  This

   661      * will automatically set the <code>selectedIndex</code> to the index

   662      * corresponding to the specified component.

   663      *

   664      * @exception IllegalArgumentException if component not found in tabbed

   665      *          pane

   666      * @see #getSelectedComponent

   667      * @beaninfo

   668      *   preferred: true

   669      * description: The tabbedpane's selected component.

   670      */

   671     public void setSelectedComponent(Component c) {

   672         int index = indexOfComponent(c);

   673         if (index != -1) {

   674             setSelectedIndex(index);

   675         } else {

   676             throw new IllegalArgumentException("component not found in tabbed pane");

   677         }

   678     }

   679 

   680     /**

   681      * Inserts a new tab for the given component, at the given index,

   682      * represented by the given title and/or icon, either of which may

   683      * be {@code null}.

   684      *

   685      * @param title the title to be displayed on the tab

   686      * @param icon the icon to be displayed on the tab

   687      * @param component the component to be displayed when this tab is clicked.

   688      * @param tip the tooltip to be displayed for this tab

   689      * @param index the position to insert this new tab

   690      *       ({@code > 0 and <= getTabCount()})

   691      *

   692      * @throws IndexOutOfBoundsException if the index is out of range

   693      *         ({@code < 0 or > getTabCount()})

   694      *

   695      * @see #addTab

   696      * @see #removeTabAt

   697      */

   698     public void insertTab(String title, Icon icon, Component component, String tip, int index) {

   699         int newIndex = index;

   700 

   701         // If component already exists, remove corresponding

   702         // tab so that new tab gets added correctly

   703         // Note: we are allowing component=null because of compatibility,

   704         // but we really should throw an exception because much of the

   705         // rest of the JTabbedPane implementation isn't designed to deal

   706         // with null components for tabs.

   707         int removeIndex = indexOfComponent(component);

   708         if (component != null && removeIndex != -1) {

   709             removeTabAt(removeIndex);

   710             if (newIndex > removeIndex) {

   711                 newIndex--;

   712             }

   713         }

   714 

   715         int selectedIndex = getSelectedIndex();

   716 

   717         pages.add(

   718             newIndex,

   719             new Page(this, title != null? title : "", icon, null, component, tip));

   720 

   721 

   722         if (component != null) {

   723             addImpl(component, null, -1);

   724             component.setVisible(false);

   725         } else {

   726             firePropertyChange("indexForNullComponent", -1, index);

   727         }

   728 

   729         if (pages.size() == 1) {

   730             setSelectedIndex(0);

   731         }

   732 

   733         if (selectedIndex >= newIndex) {

   734             setSelectedIndexImpl(selectedIndex + 1, false);

   735         }

   736 

   737         if (!haveRegistered && tip != null) {

   738             ToolTipManager.sharedInstance().registerComponent(this);

   739             haveRegistered = true;

   740         }

   741 

   742         if (accessibleContext != null) {

   743             accessibleContext.firePropertyChange(

   744                     AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

   745                     null, component);

   746         }

   747         revalidate();

   748         repaint();

   749     }

   750 

   751     /**

   752      * Adds a <code>component</code> and <code>tip</code>

   753      * represented by a <code>title</code> and/or <code>icon</code>,

   754      * either of which can be <code>null</code>.

   755      * Cover method for <code>insertTab</code>.

   756      *

   757      * @param title the title to be displayed in this tab

   758      * @param icon the icon to be displayed in this tab

   759      * @param component the component to be displayed when this tab is clicked

   760      * @param tip the tooltip to be displayed for this tab

   761      *

   762      * @see #insertTab

   763      * @see #removeTabAt

   764      */

   765     public void addTab(String title, Icon icon, Component component, String tip) {

   766         insertTab(title, icon, component, tip, pages.size());

   767     }

   768 

   769     /**

   770      * Adds a <code>component</code> represented by a <code>title</code>

   771      * and/or <code>icon</code>, either of which can be <code>null</code>.

   772      * Cover method for <code>insertTab</code>.

   773      *

   774      * @param title the title to be displayed in this tab

   775      * @param icon the icon to be displayed in this tab

   776      * @param component the component to be displayed when this tab is clicked

   777      *

   778      * @see #insertTab

   779      * @see #removeTabAt

   780      */

   781     public void addTab(String title, Icon icon, Component component) {

   782         insertTab(title, icon, component, null, pages.size());

   783     }

   784 

   785     /**

   786      * Adds a <code>component</code> represented by a <code>title</code>

   787      * and no icon.

   788      * Cover method for <code>insertTab</code>.

   789      *

   790      * @param title the title to be displayed in this tab

   791      * @param component the component to be displayed when this tab is clicked

   792      *

   793      * @see #insertTab

   794      * @see #removeTabAt

   795      */

   796     public void addTab(String title, Component component) {

   797         insertTab(title, null, component, null, pages.size());

   798     }

   799 

   800     /**

   801      * Adds a <code>component</code> with a tab title defaulting to

   802      * the name of the component which is the result of calling

   803      * <code>component.getName</code>.

   804      * Cover method for <code>insertTab</code>.

   805      *

   806      * @param component the component to be displayed when this tab is clicked

   807      * @return the component

   808      *

   809      * @see #insertTab

   810      * @see #removeTabAt

   811      */

   812     public Component add(Component component) {

   813         if (!(component instanceof UIResource)) {

   814             addTab(component.getName(), component);

   815         } else {

   816             super.add(component);

   817         }

   818         return component;

   819     }

   820 

   821     /**

   822      * Adds a <code>component</code> with the specified tab title.

   823      * Cover method for <code>insertTab</code>.

   824      *

   825      * @param title the title to be displayed in this tab

   826      * @param component the component to be displayed when this tab is clicked

   827      * @return the component

   828      *

   829      * @see #insertTab

   830      * @see #removeTabAt

   831      */

   832     public Component add(String title, Component component) {

   833         if (!(component instanceof UIResource)) {

   834             addTab(title, component);

   835         } else {

   836             super.add(title, component);

   837         }

   838         return component;

   839     }

   840 

   841     /**

   842      * Adds a <code>component</code> at the specified tab index with a tab

   843      * title defaulting to the name of the component.

   844      * Cover method for <code>insertTab</code>.

   845      *

   846      * @param component the component to be displayed when this tab is clicked

   847      * @param index the position to insert this new tab

   848      * @return the component

   849      *

   850      * @see #insertTab

   851      * @see #removeTabAt

   852      */

   853     public Component add(Component component, int index) {

   854         if (!(component instanceof UIResource)) {

   855             // Container.add() interprets -1 as "append", so convert

   856             // the index appropriately to be handled by the vector

   857             insertTab(component.getName(), null, component, null,

   858                       index == -1? getTabCount() : index);

   859         } else {

   860             super.add(component, index);

   861         }

   862         return component;

   863     }

   864 

   865     /**

   866      * Adds a <code>component</code> to the tabbed pane.

   867      * If <code>constraints</code> is a <code>String</code> or an

   868      * <code>Icon</code>, it will be used for the tab title,

   869      * otherwise the component's name will be used as the tab title.

   870      * Cover method for <code>insertTab</code>.

   871      *

   872      * @param component the component to be displayed when this tab is clicked

   873      * @param constraints the object to be displayed in the tab

   874      *

   875      * @see #insertTab

   876      * @see #removeTabAt

   877      */

   878     public void add(Component component, Object constraints) {

   879         if (!(component instanceof UIResource)) {

   880             if (constraints instanceof String) {

   881                 addTab((String)constraints, component);

   882             } else if (constraints instanceof Icon) {

   883                 addTab(null, (Icon)constraints, component);

   884             } else {

   885                 add(component);

   886             }

   887         } else {

   888             super.add(component, constraints);

   889         }

   890     }

   891 

   892     /**

   893      * Adds a <code>component</code> at the specified tab index.

   894      * If <code>constraints</code> is a <code>String</code> or an

   895      * <code>Icon</code>, it will be used for the tab title,

   896      * otherwise the component's name will be used as the tab title.

   897      * Cover method for <code>insertTab</code>.

   898      *

   899      * @param component the component to be displayed when this tab is clicked

   900      * @param constraints the object to be displayed in the tab

   901      * @param index the position to insert this new tab

   902      *

   903      * @see #insertTab

   904      * @see #removeTabAt

   905      */

   906     public void add(Component component, Object constraints, int index) {

   907         if (!(component instanceof UIResource)) {

   908 

   909             Icon icon = constraints instanceof Icon? (Icon)constraints : null;

   910             String title = constraints instanceof String? (String)constraints : null;

   911             // Container.add() interprets -1 as "append", so convert

   912             // the index appropriately to be handled by the vector

   913             insertTab(title, icon, component, null, index == -1? getTabCount() : index);

   914         } else {

   915             super.add(component, constraints, index);

   916         }

   917     }

   918 

   919     /**

   920      * Removes the tab at <code>index</code>.

   921      * After the component associated with <code>index</code> is removed,

   922      * its visibility is reset to true to ensure it will be visible

   923      * if added to other containers.

   924      * @param index the index of the tab to be removed

   925      * @exception IndexOutOfBoundsException if index is out of range

   926      *            (index < 0 || index >= tab count)

   927      *

   928      * @see #addTab

   929      * @see #insertTab

   930      */

   931     public void removeTabAt(int index) {

   932         checkIndex(index);

   933 

   934         Component component = getComponentAt(index);

   935         boolean shouldChangeFocus = false;

   936         int selected = getSelectedIndex();

   937         String oldName = null;

   938 

   939         /* if we're about to remove the visible component */

   940         if (component == visComp) {

   941             shouldChangeFocus = (SwingUtilities.findFocusOwner(visComp) != null);

   942             visComp = null;

   943         }

   944 

   945         if (accessibleContext != null) {

   946             /* if we're removing the selected page */

   947             if (index == selected) {

   948                 /* fire an accessible notification that it's unselected */

   949                 pages.get(index).firePropertyChange(

   950                     AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

   951                     AccessibleState.SELECTED, null);

   952 

   953                 oldName = accessibleContext.getAccessibleName();

   954             }

   955 

   956             accessibleContext.firePropertyChange(

   957                     AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

   958                     component, null);

   959         }

   960 

   961         // Force the tabComponent to be cleaned up.

   962         setTabComponentAt(index, null);

   963         pages.remove(index);

   964 

   965         // NOTE 4/15/2002 (joutwate):

   966         // This fix is implemented using client properties since there is

   967         // currently no IndexPropertyChangeEvent.  Once

   968         // IndexPropertyChangeEvents have been added this code should be

   969         // modified to use it.

   970         putClientProperty("__index_to_remove__", new Integer(index));

   971 

   972         /* if the selected tab is after the removal */

   973         if (selected > index) {

   974             setSelectedIndexImpl(selected - 1, false);

   975 

   976         /* if the selected tab is the last tab */

   977         } else if (selected >= getTabCount()) {

   978             setSelectedIndexImpl(selected - 1, false);

   979             Page newSelected = (selected != 0)

   980                 ? pages.get(selected - 1)

   981                 : null;

   982 

   983             changeAccessibleSelection(null, oldName, newSelected);

   984 

   985         /* selected index hasn't changed, but the associated tab has */

   986         } else if (index == selected) {

   987             fireStateChanged();

   988             changeAccessibleSelection(null, oldName, pages.get(index));

   989         }

   990 

   991         // We can't assume the tab indices correspond to the

   992         // container's children array indices, so make sure we

   993         // remove the correct child!

   994         if (component != null) {

   995             Component components[] = getComponents();

   996             for (int i = components.length; --i >= 0; ) {

   997                 if (components[i] == component) {

   998                     super.remove(i);

   999                     component.setVisible(true);

  1000                     break;

  1001                 }

  1002             }

  1003         }

  1004 

  1005         if (shouldChangeFocus) {

  1006             SwingUtilities2.tabbedPaneChangeFocusTo(getSelectedComponent());

  1007         }

  1008 

  1009         revalidate();

  1010         repaint();

  1011     }

  1012 

  1013     /**

  1014      * Removes the specified <code>Component</code> from the

  1015      * <code>JTabbedPane</code>. The method does nothing

  1016      * if the <code>component</code> is null.

  1017      *

  1018      * @param component the component to remove from the tabbedpane

  1019      * @see #addTab

  1020      * @see #removeTabAt

  1021      */

  1022     public void remove(Component component) {

  1023         int index = indexOfComponent(component);

  1024         if (index != -1) {

  1025             removeTabAt(index);

  1026         } else {

  1027             // Container#remove(comp) invokes Container#remove(int)

  1028             // so make sure JTabbedPane#remove(int) isn't called here

  1029             Component children[] = getComponents();

  1030             for (int i=0; i < children.length; i++) {

  1031                 if (component == children[i]) {

  1032                     super.remove(i);

  1033                     break;

  1034                 }

  1035             }

  1036         }

  1037     }

  1038 

  1039     /**

  1040      * Removes the tab and component which corresponds to the specified index.

  1041      *

  1042      * @param index the index of the component to remove from the

  1043      *          <code>tabbedpane</code>

  1044      * @exception IndexOutOfBoundsException if index is out of range

  1045      *            (index < 0 || index >= tab count)

  1046      * @see #addTab

  1047      * @see #removeTabAt

  1048      */

  1049     public void remove(int index) {

  1050         removeTabAt(index);

  1051     }

  1052 

  1053     /**

  1054      * Removes all the tabs and their corresponding components

  1055      * from the <code>tabbedpane</code>.

  1056      *

  1057      * @see #addTab

  1058      * @see #removeTabAt

  1059      */

  1060     public void removeAll() {

  1061         setSelectedIndexImpl(-1, true);

  1062 

  1063         int tabCount = getTabCount();

  1064         // We invoke removeTabAt for each tab, otherwise we may end up

  1065         // removing Components added by the UI.

  1066         while (tabCount-- > 0) {

  1067             removeTabAt(tabCount);

  1068         }

  1069     }

  1070 

  1071     /**

  1072      * Returns the number of tabs in this <code>tabbedpane</code>.

  1073      *

  1074      * @return an integer specifying the number of tabbed pages

  1075      */

  1076     public int getTabCount() {

  1077         return pages.size();

  1078     }

  1079 

  1080     /**

  1081      * Returns the number of tab runs currently used to display

  1082      * the tabs.

  1083      * @return an integer giving the number of rows if the

  1084      *          <code>tabPlacement</code>

  1085      *          is <code>TOP</code> or <code>BOTTOM</code>

  1086      *          and the number of columns if

  1087      *          <code>tabPlacement</code>

  1088      *          is <code>LEFT</code> or <code>RIGHT</code>,

  1089      *          or 0 if there is no UI set on this <code>tabbedpane</code>

  1090      */

  1091     public int getTabRunCount() {

  1092         if (ui != null) {

  1093             return ((TabbedPaneUI)ui).getTabRunCount(this);

  1094         }

  1095         return 0;

  1096     }

  1097 

  1098 

  1099 // Getters for the Pages

  1100 

  1101     /**

  1102      * Returns the tab title at <code>index</code>.

  1103      *

  1104      * @param index  the index of the item being queried

  1105      * @return the title at <code>index</code>

  1106      * @exception IndexOutOfBoundsException if index is out of range

  1107      *            (index < 0 || index >= tab count)

  1108      * @see #setTitleAt

  1109      */

  1110     public String getTitleAt(int index) {

  1111         return pages.get(index).title;

  1112     }

  1113 

  1114     /**

  1115      * Returns the tab icon at <code>index</code>.

  1116      *

  1117      * @param index  the index of the item being queried

  1118      * @return the icon at <code>index</code>

  1119      * @exception IndexOutOfBoundsException if index is out of range

  1120      *            (index < 0 || index >= tab count)

  1121      *

  1122      * @see #setIconAt

  1123      */

  1124     public Icon getIconAt(int index) {

  1125         return pages.get(index).icon;

  1126     }

  1127 

  1128     /**

  1129      * Returns the tab disabled icon at <code>index</code>.

  1130      * If the tab disabled icon doesn't exist at <code>index</code>

  1131      * this will forward the call to the look and feel to construct

  1132      * an appropriate disabled Icon from the corresponding enabled

  1133      * Icon. Some look and feels might not render the disabled Icon,

  1134      * in which case it won't be created.