1 /*
2 * Copyright 1999-2007 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 sun.awt.ModalExclude;
30
31 /**
32 * Popups are used to display a <code>Component</code> to the user, typically
33 * on top of all the other <code>Component</code>s in a particular containment
34 * hierarchy. <code>Popup</code>s have a very small life cycle. Once you
35 * have obtained a <code>Popup</code>, and hidden it (invoked the
36 * <code>hide</code> method), you should no longer
37 * invoke any methods on it. This allows the <code>PopupFactory</code> to cache
38 * <code>Popup</code>s for later use.
39 * <p>
40 * The general contract is that if you need to change the size of the
41 * <code>Component</code>, or location of the <code>Popup</code>, you should
42 * obtain a new <code>Popup</code>.
43 * <p>
44 * <code>Popup</code> does not descend from <code>Component</code>, rather
45 * implementations of <code>Popup</code> are responsible for creating
46 * and maintaining their own <code>Component</code>s to render the
47 * requested <code>Component</code> to the user.
48 * <p>
49 * You typically do not explicitly create an instance of <code>Popup</code>,
50 * instead obtain one from a <code>PopupFactory</code>.
51 *
52 * @see PopupFactory
53 *
54 * @since 1.4
55 */
56 public class Popup {
57 /**
58 * The Component representing the Popup.
59 */
60 private Component component;
61
62 /**
63 * Creates a <code>Popup</code> for the Component <code>owner</code>
64 * containing the Component <code>contents</code>. <code>owner</code>
65 * is used to determine which <code>Window</code> the new
66 * <code>Popup</code> will parent the <code>Component</code> the
67 * <code>Popup</code> creates to.
68 * A null <code>owner</code> implies there is no valid parent.
69 * <code>x</code> and
70 * <code>y</code> specify the preferred initial location to place
71 * the <code>Popup</code> at. Based on screen size, or other paramaters,
72 * the <code>Popup</code> may not display at <code>x</code> and
73 * <code>y</code>.
74 *
75 * @param owner Component mouse coordinates are relative to, may be null
76 * @param contents Contents of the Popup
77 * @param x Initial x screen coordinate
78 * @param y Initial y screen coordinate
79 * @exception IllegalArgumentException if contents is null
80 */
81 protected Popup(Component owner, Component contents, int x, int y) {
82 this();
83 if (contents == null) {
84 throw new IllegalArgumentException("Contents must be non-null");
85 }
86 reset(owner, contents, x, y);
87 }
88
89 /**
90 * Creates a <code>Popup</code>. This is provided for subclasses.
91 */
92 protected Popup() {
93 }
94
95 /**
96 * Makes the <code>Popup</code> visible. If the <code>Popup</code> is
97 * currently visible, this has no effect.
98 */
99 public void show() {
100 Component component = getComponent();
101
102 if (component != null) {
103 component.show();
104 }
105 }
106
107 /**
108 * Hides and disposes of the <code>Popup</code>. Once a <code>Popup</code>
109 * has been disposed you should no longer invoke methods on it. A
110 * <code>dispose</code>d <code>Popup</code> may be reclaimed and later used
111 * based on the <code>PopupFactory</code>. As such, if you invoke methods
112 * on a <code>disposed</code> <code>Popup</code>, indeterminate
113 * behavior will result.
114 */
115 public void hide() {
116 Component component = getComponent();
117
118 if (component instanceof JWindow) {
119 component.hide();
120 ((JWindow)component).getContentPane().removeAll();
121 }
122 dispose();
123 }
124
125 /**
126 * Frees any resources the <code>Popup</code> may be holding onto.
127 */
128 void dispose() {
129 Component component = getComponent();
130 Window window = SwingUtilities.getWindowAncestor(component);
131
132 if (component instanceof JWindow) {
133 ((Window)component).dispose();
134 component = null;
135 }
136 // If our parent is a DefaultFrame, we need to dispose it, too.
137 if (window instanceof DefaultFrame) {
138 window.dispose();
139 }
140 }
141
142 /**
143 * Resets the <code>Popup</code> to an initial state.
144 */
145 void reset(Component owner, Component contents, int ownerX, int ownerY) {
146 if (getComponent() == null) {
147 component = createComponent(owner);
148 }
149
150 Component c = getComponent();
151
152 if (c instanceof JWindow) {
153 JWindow component = (JWindow)getComponent();
154
155 component.setLocation(ownerX, ownerY);
156 component.getContentPane().add(contents, BorderLayout.CENTER);
157 contents.invalidate();
158 if(component.isVisible()) {
159 // Do not call pack() if window is not visible to
160 // avoid early native peer creation
161 pack();
162 }
163 }
164 }
165
166
167 /**
168 * Causes the <code>Popup</code> to be sized to fit the preferred size
169 * of the <code>Component</code> it contains.
170 */
171 void pack() {
172 Component component = getComponent();
173
174 if (component instanceof Window) {
175 ((Window)component).pack();
176 }
177 }
178
179 /**
180 * Returns the <code>Window</code> to use as the parent of the
181 * <code>Window</code> created for the <code>Popup</code>. This creates
182 * a new <code>DefaultFrame</code>, if necessary.
183 */
184 private Window getParentWindow(Component owner) {
185 Window window = null;
186
187 if (owner instanceof Window) {
188 window = (Window)owner;
189 }
190 else if (owner != null) {
191 window = SwingUtilities.getWindowAncestor(owner);
192 }
193 if (window == null) {
194 window = new DefaultFrame();
195 }
196 return window;
197 }
198
199 /**
200 * Creates the Component to use as the parent of the <code>Popup</code>.
201 * The default implementation creates a <code>Window</code>, subclasses
202 * should override.
203 */
204 Component createComponent(Component owner) {
205 if (GraphicsEnvironment.isHeadless()) {
206 // Generally not useful, bail.
207 return null;
208 }
209 return new HeavyWeightWindow(getParentWindow(owner));
210 }
211
212 /**
213 * Returns the <code>Component</code> returned from
214 * <code>createComponent</code> that will hold the <code>Popup</code>.
215 */
216 Component getComponent() {
217 return component;
218 }
219
220
221 /**
222 * Component used to house window.
223 */
224 static class HeavyWeightWindow extends JWindow implements ModalExclude {
225 HeavyWeightWindow(Window parent) {
226 super(parent);
227 setFocusableWindowState(false);
228 setName("###overrideRedirect###");
229 // Popups are typically transient and most likely won't benefit
230 // from true double buffering. Turn it off here.
231 getRootPane().setUseTrueDoubleBuffering(false);
232 // Try to set "always-on-top" for the popup window.
233 // Applets usually don't have sufficient permissions to do it.
234 // In this case simply ignore the exception.
235 try {
236 setAlwaysOnTop(true);
237 } catch (SecurityException se) {
238 // setAlwaysOnTop is restricted,
239 // the exception is ignored
240 }
241 }
242
243 public void update(Graphics g) {
244 paint(g);
245 }
246
247 public void show() {
248 this.pack();
249 if (getWidth() > 0 && getHeight() > 0) {
250 super.show();
251 }
252 }
253 }
254
255
256 /**
257 * Used if no valid Window ancestor of the supplied owner is found.
258 * <p>
259 * PopupFactory uses this as a way to know when the Popup shouldn't
260 * be cached based on the Window.
261 */
262 static class DefaultFrame extends Frame {
263 }
264 }
Save This Page