1/*
2 * Copyright (c) 2013, 2016, 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
26package sun.awt;
27
28import java.awt.Component;
29import java.awt.Container;
30import java.awt.Frame;
31import java.awt.Graphics;
32import java.awt.Image;
33import java.awt.MenuBar;
34import java.awt.MenuComponent;
35import java.awt.Rectangle;
36import java.awt.Toolkit;
37import java.awt.dnd.DragGestureEvent;
38import java.awt.dnd.DragGestureListener;
39import java.awt.dnd.DragGestureRecognizer;
40import java.awt.dnd.DragSource;
41import java.awt.dnd.DropTarget;
42import java.awt.dnd.InvalidDnDOperationException;
43import java.awt.dnd.peer.DragSourceContextPeer;
44import java.awt.peer.FramePeer;
45
46/**
47 * The class provides basic functionality for a lightweight frame
48 * implementation. A subclass is expected to provide painting to an
49 * offscreen image and access to it. Thus it can be used for lightweight
50 * embedding.
51 *
52 * @author Artem Ananiev
53 * @author Anton Tarasov
54 */
55@SuppressWarnings("serial")
56public abstract class LightweightFrame extends Frame {
57
58    /**
59     * Constructs a new, initially invisible {@code LightweightFrame}
60     * instance.
61     */
62    public LightweightFrame() {
63        setUndecorated(true);
64        setResizable(true);
65        setEnabled(true);
66    }
67
68    /**
69     * Blocks introspection of a parent window by this child.
70     *
71     * @return null
72     */
73    @Override public final Container getParent() { return null; }
74
75    @Override public Graphics getGraphics() { return null; }
76
77    @Override public final boolean isResizable() { return true; }
78
79    // Block modification of any frame attributes, since they aren't
80    // applicable for a lightweight frame.
81
82    @Override public final void setTitle(String title) {}
83    @Override public final void setIconImage(Image image) {}
84    @Override public final void setIconImages(java.util.List<? extends Image> icons) {}
85    @Override public final void setMenuBar(MenuBar mb) {}
86    @Override public final void setResizable(boolean resizable) {}
87    @Override public final void remove(MenuComponent m) {}
88    @Override public final void toFront() {}
89    @Override public final void toBack() {}
90
91    @SuppressWarnings("deprecation")
92    @Override public void addNotify() {
93        synchronized (getTreeLock()) {
94            if (!isDisplayable()) {
95                SunToolkit stk = (SunToolkit)Toolkit.getDefaultToolkit();
96                try {
97                    setPeer(stk.createLightweightFrame(this));
98                } catch (Exception e) {
99                    throw new RuntimeException(e);
100                }
101            }
102            super.addNotify();
103        }
104    }
105
106    private void setPeer(final FramePeer p) {
107        AWTAccessor.getComponentAccessor().setPeer(this, p);
108    }
109
110    /**
111     * Requests the peer to emulate activation or deactivation of the
112     * frame. Peers should override this method if they are to implement
113     * this functionality.
114     *
115     * @param activate if {@code true}, activates the frame;
116     *                 otherwise, deactivates the frame
117     */
118    public void emulateActivation(boolean activate) {
119        final FramePeer peer = AWTAccessor.getComponentAccessor().getPeer(this);
120        peer.emulateActivation(activate);
121    }
122
123    /**
124     * Delegates the focus grab action to the client (embedding) application.
125     * The method is called by the AWT grab machinery.
126     *
127     * @see SunToolkit#grab(java.awt.Window)
128     */
129    public abstract void grabFocus();
130
131    /**
132     * Delegates the focus ungrab action to the client (embedding) application.
133     * The method is called by the AWT grab machinery.
134     *
135     * @see SunToolkit#ungrab(java.awt.Window)
136     */
137    public abstract void ungrabFocus();
138
139    /**
140     * Returns the scale factor of this frame. The default value is 1.
141     *
142     * @return the scale factor
143     * @see #notifyDisplayChanged(int)
144     * @Depricated replaced by {@link #getScaleFactorX()} and
145     * {@link #getScaleFactorY}
146     */
147    @Deprecated(since = "9")
148    public abstract int getScaleFactor();
149
150    /**
151     * Returns the scale factor of this frame along x coordinate. The default
152     * value is 1.
153     *
154     * @return the x coordinate scale factor
155     * @see #notifyDisplayChanged(double, double)
156     * @since 9
157     */
158    public abstract double getScaleFactorX();
159
160    /**
161     * Returns the scale factor of this frame along y coordinate. The default
162     * value is 1.
163     *
164     * @return the y coordinate scale factor
165     * @see #notifyDisplayChanged(double, double)
166     * @since 9
167     */
168    public abstract double getScaleFactorY();
169
170    /**
171     * Called when display of the hosted frame is changed.
172     *
173     * @param scaleFactor the scale factor
174     * @Depricated replaced by {@link #notifyDisplayChanged(double, double)}
175     */
176    @Deprecated(since = "9")
177    public abstract void notifyDisplayChanged(int scaleFactor);
178
179    /**
180     * Called when display of the hosted frame is changed.
181     *
182     * @param scaleFactorX the scale factor
183     * @param scaleFactorY the scale factor
184     * @since 9
185     */
186    public abstract void notifyDisplayChanged(double scaleFactorX,
187                                              double scaleFactorY);
188
189    /**
190     * Host window absolute bounds.
191     */
192    private int hostX, hostY, hostW, hostH;
193
194    /**
195     * Returns the absolute bounds of the host (embedding) window.
196     *
197     * @return the host window bounds
198     */
199    public Rectangle getHostBounds() {
200        if (hostX == 0 && hostY == 0 && hostW == 0 && hostH == 0) {
201            // The client app is probably unaware of the setHostBounds.
202            // A safe fall-back:
203            return getBounds();
204        }
205        return new Rectangle(hostX, hostY, hostW, hostH);
206    }
207
208    /**
209     * Sets the absolute bounds of the host (embedding) window.
210     */
211    public void setHostBounds(int x, int y, int w, int h) {
212        hostX = x;
213        hostY = y;
214        hostW = w;
215        hostH = h;
216    }
217
218    /**
219     * Create a drag gesture recognizer for the lightweight frame.
220     */
221    public abstract <T extends DragGestureRecognizer> T createDragGestureRecognizer(
222            Class<T> abstractRecognizerClass,
223            DragSource ds, Component c, int srcActions,
224            DragGestureListener dgl);
225
226    /**
227     * Create a drag source context peer for the lightweight frame.
228     */
229    public abstract DragSourceContextPeer createDragSourceContextPeer(DragGestureEvent dge) throws InvalidDnDOperationException;
230
231    /**
232     * Adds a drop target to the lightweight frame.
233     */
234    public abstract void addDropTarget(DropTarget dt);
235
236    /**
237     * Removes a drop target from the lightweight frame.
238     */
239    public abstract void removeDropTarget(DropTarget dt);
240
241}
242