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