1 /*
   2  * Copyright (c) 1997, 2014, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing;
  27 
  28 import java.util.List;
  29 import java.util.ArrayList;
  30 import java.util.Collection;
  31 import java.util.Iterator;
  32 import javax.swing.plaf.*;
  33 import javax.accessibility.*;
  34 
  35 import java.awt.Component;
  36 import java.awt.Container;
  37 import java.awt.DefaultFocusTraversalPolicy;
  38 import java.awt.FocusTraversalPolicy;
  39 import java.awt.Window;
  40 import java.io.ObjectOutputStream;
  41 import java.io.ObjectInputStream;
  42 import java.io.IOException;
  43 import java.beans.PropertyVetoException;
  44 import java.util.Set;
  45 import java.util.TreeSet;
  46 /**
  47  * A container used to create a multiple-document interface or a virtual desktop.
  48  * You create <code>JInternalFrame</code> objects and add them to the
  49  * <code>JDesktopPane</code>. <code>JDesktopPane</code> extends
  50  * <code>JLayeredPane</code> to manage the potentially overlapping internal
  51  * frames. It also maintains a reference to an instance of
  52  * <code>DesktopManager</code> that is set by the UI
  53  * class for the current look and feel (L&amp;F).  Note that <code>JDesktopPane</code>
  54  * does not support borders.
  55  * <p>
  56  * This class is normally used as the parent of <code>JInternalFrames</code>
  57  * to provide a pluggable <code>DesktopManager</code> object to the
  58  * <code>JInternalFrames</code>. The <code>installUI</code> of the
  59  * L&amp;F specific implementation is responsible for setting the
  60  * <code>desktopManager</code> variable appropriately.
  61  * When the parent of a <code>JInternalFrame</code> is a <code>JDesktopPane</code>,
  62  * it should delegate most of its behavior to the <code>desktopManager</code>
  63  * (closing, resizing, etc).
  64  * <p>
  65  * For further documentation and examples see
  66  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/internalframe.html">How to Use Internal Frames</a>,
  67  * a section in <em>The Java Tutorial</em>.
  68  * <p>
  69  * <strong>Warning:</strong> Swing is not thread safe. For more
  70  * information see <a
  71  * href="package-summary.html#threading">Swing's Threading
  72  * Policy</a>.
  73  * <p>
  74  * <strong>Warning:</strong>
  75  * Serialized objects of this class will not be compatible with
  76  * future Swing releases. The current serialization support is
  77  * appropriate for short term storage or RMI between applications running
  78  * the same version of Swing.  As of 1.4, support for long term storage
  79  * of all JavaBeans&trade;
  80  * has been added to the <code>java.beans</code> package.
  81  * Please see {@link java.beans.XMLEncoder}.
  82  *
  83  * @see JInternalFrame
  84  * @see JInternalFrame.JDesktopIcon
  85  * @see DesktopManager
  86  *
  87  * @author David Kloba
  88  * @since 1.2
  89  */
  90 @SuppressWarnings("serial") // Same-version serialization only
  91 public class JDesktopPane extends JLayeredPane implements Accessible
  92 {
  93     /**
  94      * @see #getUIClassID
  95      * @see #readObject
  96      */
  97     private static final String uiClassID = "DesktopPaneUI";
  98 
  99     transient DesktopManager desktopManager;
 100 
 101     private transient JInternalFrame selectedFrame = null;
 102 
 103     /**
 104       * Indicates that the entire contents of the item being dragged
 105       * should appear inside the desktop pane.
 106       *
 107       * @see #OUTLINE_DRAG_MODE
 108       * @see #setDragMode
 109       */
 110     public static final int LIVE_DRAG_MODE = 0;
 111 
 112     /**
 113       * Indicates that an outline only of the item being dragged
 114       * should appear inside the desktop pane.
 115       *
 116       * @see #LIVE_DRAG_MODE
 117       * @see #setDragMode
 118       */
 119     public static final int OUTLINE_DRAG_MODE = 1;
 120 
 121     private int dragMode = LIVE_DRAG_MODE;
 122     private boolean dragModeSet = false;
 123     private transient List<JInternalFrame> framesCache;
 124     private boolean componentOrderCheckingEnabled = true;
 125     private boolean componentOrderChanged = false;
 126 
 127     /**
 128      * Creates a new <code>JDesktopPane</code>.
 129      */
 130     public JDesktopPane() {
 131         setUIProperty("opaque", Boolean.TRUE);
 132         setFocusCycleRoot(true);
 133 
 134         setFocusTraversalPolicy(new LayoutFocusTraversalPolicy() {
 135             public Component getDefaultComponent(Container c) {
 136                 JInternalFrame jifArray[] = getAllFrames();
 137                 Component comp = null;
 138                 for (JInternalFrame jif : jifArray) {
 139                     comp = jif.getFocusTraversalPolicy().getDefaultComponent(jif);
 140                     if (comp != null) {
 141                         break;
 142                     }
 143                 }
 144                 return comp;
 145             }
 146         });
 147         updateUI();
 148     }
 149 
 150     /**
 151      * Returns the L&amp;F object that renders this component.
 152      *
 153      * @return the <code>DesktopPaneUI</code> object that
 154      *   renders this component
 155      */
 156     public DesktopPaneUI getUI() {
 157         return (DesktopPaneUI)ui;
 158     }
 159 
 160     /**
 161      * Sets the L&amp;F object that renders this component.
 162      *
 163      * @param ui  the DesktopPaneUI L&amp;F object
 164      * @see UIDefaults#getUI
 165      * @beaninfo
 166      *        bound: true
 167      *       hidden: true
 168      *    attribute: visualUpdate true
 169      *  description: The UI object that implements the Component's LookAndFeel.
 170      */
 171     public void setUI(DesktopPaneUI ui) {
 172         super.setUI(ui);
 173     }
 174 
 175     /**
 176      * Sets the "dragging style" used by the desktop pane.
 177      * You may want to change to one mode or another for
 178      * performance or aesthetic reasons.
 179      *
 180      * @param dragMode the style of drag to use for items in the Desktop
 181      *
 182      * @see #LIVE_DRAG_MODE
 183      * @see #OUTLINE_DRAG_MODE
 184      *
 185      * @beaninfo
 186      *        bound: true
 187      *  description: Dragging style for internal frame children.
 188      *         enum: LIVE_DRAG_MODE JDesktopPane.LIVE_DRAG_MODE
 189      *               OUTLINE_DRAG_MODE JDesktopPane.OUTLINE_DRAG_MODE
 190      * @since 1.3
 191      */
 192     public void setDragMode(int dragMode) {
 193         int oldDragMode = this.dragMode;
 194         this.dragMode = dragMode;
 195         firePropertyChange("dragMode", oldDragMode, this.dragMode);
 196         dragModeSet = true;
 197      }
 198 
 199     /**
 200      * Gets the current "dragging style" used by the desktop pane.
 201      * @return either <code>Live_DRAG_MODE</code> or
 202      *   <code>OUTLINE_DRAG_MODE</code>
 203      * @see #setDragMode
 204      * @since 1.3
 205      */
 206      public int getDragMode() {
 207          return dragMode;
 208      }
 209 
 210     /**
 211      * Returns the <code>DesktopManger</code> that handles
 212      * desktop-specific UI actions.
 213      */
 214     public DesktopManager getDesktopManager() {
 215         return desktopManager;
 216     }
 217 
 218     /**
 219      * Sets the <code>DesktopManger</code> that will handle
 220      * desktop-specific UI actions. This may be overridden by
 221      * {@code LookAndFeel}.
 222      *
 223      * @param d the <code>DesktopManager</code> to use
 224      *
 225      * @beaninfo
 226      *        bound: true
 227      *  description: Desktop manager to handle the internal frames in the
 228      *               desktop pane.
 229      */
 230     public void setDesktopManager(DesktopManager d) {
 231         DesktopManager oldValue = desktopManager;
 232         desktopManager = d;
 233         firePropertyChange("desktopManager", oldValue, desktopManager);
 234     }
 235 
 236     /**
 237      * Notification from the <code>UIManager</code> that the L&amp;F has changed.
 238      * Replaces the current UI object with the latest version from the
 239      * <code>UIManager</code>.
 240      *
 241      * @see JComponent#updateUI
 242      */
 243     public void updateUI() {
 244         setUI((DesktopPaneUI)UIManager.getUI(this));
 245     }
 246 
 247 
 248     /**
 249      * Returns the name of the L&amp;F class that renders this component.
 250      *
 251      * @return the string "DesktopPaneUI"
 252      * @see JComponent#getUIClassID
 253      * @see UIDefaults#getUI
 254      */
 255     public String getUIClassID() {
 256         return uiClassID;
 257     }
 258 
 259     /**
 260      * Returns all <code>JInternalFrames</code> currently displayed in the
 261      * desktop. Returns iconified frames as well as expanded frames.
 262      *
 263      * @return an array of <code>JInternalFrame</code> objects
 264      */
 265     public JInternalFrame[] getAllFrames() {
 266         return getAllFrames(this).toArray(new JInternalFrame[0]);
 267     }
 268 
 269     private static Collection<JInternalFrame> getAllFrames(Container parent) {
 270         int i, count;
 271         Collection<JInternalFrame> results = new ArrayList<JInternalFrame>();
 272         count = parent.getComponentCount();
 273         for (i = 0; i < count; i++) {
 274             Component next = parent.getComponent(i);
 275             if (next instanceof JInternalFrame) {
 276                 results.add((JInternalFrame) next);
 277             } else if (next instanceof JInternalFrame.JDesktopIcon) {
 278                 JInternalFrame tmp = ((JInternalFrame.JDesktopIcon) next).getInternalFrame();
 279                 if (tmp != null) {
 280                     results.add(tmp);
 281                 }
 282             } else if (next instanceof Container) {
 283                 results.addAll(getAllFrames((Container) next));
 284             }
 285         }
 286         return results;
 287     }
 288 
 289     /** Returns the currently active <code>JInternalFrame</code>
 290       * in this <code>JDesktopPane</code>, or <code>null</code>
 291       * if no <code>JInternalFrame</code> is currently active.
 292       *
 293       * @return the currently active <code>JInternalFrame</code> or
 294       *   <code>null</code>
 295       * @since 1.3
 296       */
 297 
 298     public JInternalFrame getSelectedFrame() {
 299       return selectedFrame;
 300     }
 301 
 302     /** Sets the currently active <code>JInternalFrame</code>
 303      *  in this <code>JDesktopPane</code>. This method is used to bridge
 304      *  the package gap between JDesktopPane and the platform implementation
 305      *  code and should not be called directly. To visually select the frame
 306      *  the client must call JInternalFrame.setSelected(true) to activate
 307      *  the frame.
 308      *  @see JInternalFrame#setSelected(boolean)
 309      *
 310      * @param f the internal frame that's currently selected
 311      * @since 1.3
 312      */
 313 
 314     public void setSelectedFrame(JInternalFrame f) {
 315       selectedFrame = f;
 316     }
 317 
 318     /**
 319      * Returns all <code>JInternalFrames</code> currently displayed in the
 320      * specified layer of the desktop. Returns iconified frames as well
 321      * expanded frames.
 322      *
 323      * @param layer  an int specifying the desktop layer
 324      * @return an array of <code>JInternalFrame</code> objects
 325      * @see JLayeredPane
 326      */
 327     public JInternalFrame[] getAllFramesInLayer(int layer) {
 328         Collection<JInternalFrame> allFrames = getAllFrames(this);
 329         Iterator<JInternalFrame> iterator = allFrames.iterator();
 330         while (iterator.hasNext()) {
 331             if (iterator.next().getLayer() != layer) {
 332                 iterator.remove();
 333             }
 334         }
 335         return allFrames.toArray(new JInternalFrame[0]);
 336     }
 337 
 338     private List<JInternalFrame> getFrames() {
 339         Component c;
 340         Set<ComponentPosition> set = new TreeSet<ComponentPosition>();
 341         for (int i = 0; i < getComponentCount(); i++) {
 342             c = getComponent(i);
 343             if (c instanceof JInternalFrame) {
 344                 set.add(new ComponentPosition((JInternalFrame)c, getLayer(c),
 345                     i));
 346             }
 347             else if (c instanceof JInternalFrame.JDesktopIcon)  {
 348                 c = ((JInternalFrame.JDesktopIcon)c).getInternalFrame();
 349                 set.add(new ComponentPosition((JInternalFrame)c, getLayer(c),
 350                     i));
 351             }
 352         }
 353         List<JInternalFrame> frames = new ArrayList<JInternalFrame>(
 354                 set.size());
 355         for (ComponentPosition position : set) {
 356             frames.add(position.component);
 357         }
 358         return frames;
 359    }
 360 
 361     private static class ComponentPosition implements
 362         Comparable<ComponentPosition> {
 363         private final JInternalFrame component;
 364         private final int layer;
 365         private final int zOrder;
 366 
 367         ComponentPosition(JInternalFrame component, int layer, int zOrder) {
 368             this.component = component;
 369             this.layer = layer;
 370             this.zOrder = zOrder;
 371         }
 372 
 373         public int compareTo(ComponentPosition o) {
 374             int delta = o.layer - layer;
 375             if (delta == 0) {
 376                 return zOrder - o.zOrder;
 377             }
 378             return delta;
 379         }
 380     }
 381 
 382     private JInternalFrame getNextFrame(JInternalFrame f, boolean forward) {
 383         verifyFramesCache();
 384         if (f == null) {
 385             return getTopInternalFrame();
 386         }
 387         int i = framesCache.indexOf(f);
 388         if (i == -1 || framesCache.size() == 1) {
 389             /* error */
 390             return null;
 391         }
 392         if (forward) {
 393             // navigate to the next frame
 394             if (++i == framesCache.size()) {
 395                 /* wrap */
 396                 i = 0;
 397             }
 398         }
 399         else {
 400             // navigate to the previous frame
 401             if (--i == -1) {
 402                 /* wrap */
 403                 i = framesCache.size() - 1;
 404             }
 405         }
 406         return framesCache.get(i);
 407     }
 408 
 409     JInternalFrame getNextFrame(JInternalFrame f) {
 410         return getNextFrame(f, true);
 411     }
 412 
 413     private JInternalFrame getTopInternalFrame() {
 414         if (framesCache.size() == 0) {
 415             return null;
 416         }
 417         return framesCache.get(0);
 418     }
 419 
 420     private void updateFramesCache() {
 421         framesCache = getFrames();
 422     }
 423 
 424     private void verifyFramesCache() {
 425         // If framesCache is dirty, then recreate it.
 426         if (componentOrderChanged) {
 427             componentOrderChanged = false;
 428             updateFramesCache();
 429         }
 430     }
 431 
 432     /**
 433      * {@inheritDoc}
 434      */
 435     @Override
 436     public void remove(Component comp) {
 437         super.remove(comp);
 438         updateFramesCache();
 439     }
 440 
 441     /**
 442      * Selects the next <code>JInternalFrame</code> in this desktop pane.
 443      *
 444      * @param forward a boolean indicating which direction to select in;
 445      *        <code>true</code> for forward, <code>false</code> for
 446      *        backward
 447      * @return the JInternalFrame that was selected or <code>null</code>
 448      *         if nothing was selected
 449      * @since 1.6
 450      */
 451     public JInternalFrame selectFrame(boolean forward) {
 452         JInternalFrame selectedFrame = getSelectedFrame();
 453         JInternalFrame frameToSelect = getNextFrame(selectedFrame, forward);
 454         if (frameToSelect == null) {
 455             return null;
 456         }
 457         // Maintain navigation traversal order until an
 458         // external stack change, such as a click on a frame.
 459         setComponentOrderCheckingEnabled(false);
 460         if (forward && selectedFrame != null) {
 461             selectedFrame.moveToBack();  // For Windows MDI fidelity.
 462         }
 463         try { frameToSelect.setSelected(true);
 464         } catch (PropertyVetoException pve) {}
 465         setComponentOrderCheckingEnabled(true);
 466         return frameToSelect;
 467     }
 468 
 469     /*
 470      * Sets whether component order checking is enabled.
 471      * @param enable a boolean value, where <code>true</code> means
 472      * a change in component order will cause a change in the keyboard
 473      * navigation order.
 474      * @since 1.6
 475      */
 476     void setComponentOrderCheckingEnabled(boolean enable) {
 477         componentOrderCheckingEnabled = enable;
 478     }
 479 
 480     /**
 481      * {@inheritDoc}
 482      * @since 1.6
 483      */
 484     protected void addImpl(Component comp, Object constraints, int index) {
 485         super.addImpl(comp, constraints, index);
 486         if (componentOrderCheckingEnabled) {
 487             if (comp instanceof JInternalFrame ||
 488                 comp instanceof JInternalFrame.JDesktopIcon) {
 489                 componentOrderChanged = true;
 490             }
 491         }
 492     }
 493 
 494     /**
 495      * {@inheritDoc}
 496      * @since 1.6
 497      */
 498     public void remove(int index) {
 499         if (componentOrderCheckingEnabled) {
 500             Component comp = getComponent(index);
 501             if (comp instanceof JInternalFrame ||
 502                 comp instanceof JInternalFrame.JDesktopIcon) {
 503                 componentOrderChanged = true;
 504             }
 505         }
 506         super.remove(index);
 507     }
 508 
 509     /**
 510      * {@inheritDoc}
 511      * @since 1.6
 512      */
 513     public void removeAll() {
 514         if (componentOrderCheckingEnabled) {
 515             int count = getComponentCount();
 516             for (int i = 0; i < count; i++) {
 517                 Component comp = getComponent(i);
 518                 if (comp instanceof JInternalFrame ||
 519                     comp instanceof JInternalFrame.JDesktopIcon) {
 520                     componentOrderChanged = true;
 521                     break;
 522                 }
 523             }
 524         }
 525         super.removeAll();
 526     }
 527 
 528     /**
 529      * {@inheritDoc}
 530      * @since 1.6
 531      */
 532     public void setComponentZOrder(Component comp, int index) {
 533         super.setComponentZOrder(comp, index);
 534         if (componentOrderCheckingEnabled) {
 535             if (comp instanceof JInternalFrame ||
 536                 comp instanceof JInternalFrame.JDesktopIcon) {
 537                 componentOrderChanged = true;
 538             }
 539         }
 540     }
 541 
 542     /**
 543      * See readObject() and writeObject() in JComponent for more
 544      * information about serialization in Swing.
 545      */
 546     private void writeObject(ObjectOutputStream s) throws IOException {
 547         s.defaultWriteObject();
 548         if (getUIClassID().equals(uiClassID)) {
 549             byte count = JComponent.getWriteObjCounter(this);
 550             JComponent.setWriteObjCounter(this, --count);
 551             if (count == 0 && ui != null) {
 552                 ui.installUI(this);
 553             }
 554         }
 555     }
 556 
 557     void setUIProperty(String propertyName, Object value) {
 558         if (propertyName == "dragMode") {
 559             if (!dragModeSet) {
 560                 setDragMode(((Integer)value).intValue());
 561                 dragModeSet = false;
 562             }
 563         } else {
 564             super.setUIProperty(propertyName, value);
 565         }
 566     }
 567 
 568     /**
 569      * Returns a string representation of this <code>JDesktopPane</code>.
 570      * This method is intended to be used only for debugging purposes, and the
 571      * content and format of the returned string may vary between
 572      * implementations. The returned string may be empty but may not
 573      * be <code>null</code>.
 574      *
 575      * @return  a string representation of this <code>JDesktopPane</code>
 576      */
 577     protected String paramString() {
 578         String desktopManagerString = (desktopManager != null ?
 579                                        desktopManager.toString() : "");
 580 
 581         return super.paramString() +
 582         ",desktopManager=" + desktopManagerString;
 583     }
 584 
 585 /////////////////
 586 // Accessibility support
 587 ////////////////
 588 
 589     /**
 590      * Gets the <code>AccessibleContext</code> associated with this
 591      * <code>JDesktopPane</code>. For desktop panes, the
 592      * <code>AccessibleContext</code> takes the form of an
 593      * <code>AccessibleJDesktopPane</code>.
 594      * A new <code>AccessibleJDesktopPane</code> instance is created if necessary.
 595      *
 596      * @return an <code>AccessibleJDesktopPane</code> that serves as the
 597      *         <code>AccessibleContext</code> of this <code>JDesktopPane</code>
 598      */
 599     public AccessibleContext getAccessibleContext() {
 600         if (accessibleContext == null) {
 601             accessibleContext = new AccessibleJDesktopPane();
 602         }
 603         return accessibleContext;
 604     }
 605 
 606     /**
 607      * This class implements accessibility support for the
 608      * <code>JDesktopPane</code> class.  It provides an implementation of the
 609      * Java Accessibility API appropriate to desktop pane user-interface
 610      * elements.
 611      * <p>
 612      * <strong>Warning:</strong>
 613      * Serialized objects of this class will not be compatible with
 614      * future Swing releases. The current serialization support is
 615      * appropriate for short term storage or RMI between applications running
 616      * the same version of Swing.  As of 1.4, support for long term storage
 617      * of all JavaBeans&trade;
 618      * has been added to the <code>java.beans</code> package.
 619      * Please see {@link java.beans.XMLEncoder}.
 620      */
 621     @SuppressWarnings("serial") // Same-version serialization only
 622     protected class AccessibleJDesktopPane extends AccessibleJComponent {
 623 
 624         /**
 625          * Get the role of this object.
 626          *
 627          * @return an instance of AccessibleRole describing the role of the
 628          * object
 629          * @see AccessibleRole
 630          */
 631         public AccessibleRole getAccessibleRole() {
 632             return AccessibleRole.DESKTOP_PANE;
 633         }
 634     }
 635 }