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.swing;
27
28import javax.swing.JComponent;
29import java.awt.Component;
30import java.awt.Cursor;
31import java.awt.dnd.DragGestureEvent;
32import java.awt.dnd.DragGestureListener;
33import java.awt.dnd.DragGestureRecognizer;
34import java.awt.dnd.DragSource;
35import java.awt.dnd.DropTarget;
36import java.awt.dnd.InvalidDnDOperationException;
37import java.awt.dnd.peer.DragSourceContextPeer;
38
39/**
40 * The interface by means of which the {@link JLightweightFrame} class
41 * communicates to its client application.
42 * <p>
43 * The client application implements this interface so it can response
44 * to requests and process notifications from {@code JLightweightFrame}.
45 * An implementation of this interface is associated with a {@code
46 * JLightweightFrame} instance via the {@link JLightweightFrame#setContent}
47 * method.
48 *
49 * A hierarchy of components contained in the {@code JComponent} instance
50 * returned by the {@link #getComponent} method should not contain any
51 * heavyweight components, otherwise {@code JLightweightFrame} may fail
52 * to paint it.
53 *
54 * @author Artem Ananiev
55 * @author Anton Tarasov
56 * @author Jim Graham
57 */
58public interface LightweightContent {
59
60    /**
61     * The client application overrides this method to return the {@code
62     * JComponent} instance which the {@code JLightweightFrame} container
63     * will paint as its lightweight content. A hierarchy of components
64     * contained in this component should not contain any heavyweight objects.
65     *
66     * @return the component to paint
67     */
68    public JComponent getComponent();
69
70    /**
71     * {@code JLightweightFrame} calls this method to notify the client
72     * application that it acquires the paint lock. The client application
73     * should implement the locking mechanism in order to synchronize access
74     * to the content image data, shared between {@code JLightweightFrame}
75     * and the client application.
76     *
77     * @see #paintUnlock
78     */
79    public void paintLock();
80
81    /**
82     * {@code JLightweightFrame} calls this method to notify the client
83     * application that it releases the paint lock. The client application
84     * should implement the locking mechanism in order to synchronize access
85     * to the content image data, shared between {@code JLightweightFrame}
86     * and the client application.
87     *
88     * @see #paintLock
89     */
90    public void paintUnlock();
91
92    /**
93     * {@code JLightweightFrame} calls this method to notify the client
94     * application that a new data buffer has been set as a content pixel
95     * buffer. Typically this occurs when a buffer of a larger size is
96     * created in response to a content resize event.
97     * <p>
98     * The method reports a reference to the pixel data buffer, the content
99     * image bounds within the buffer and the line stride of the buffer.
100     * These values have the following correlation.
101     * The {@code width} and {@code height} matches the layout size of the content
102     * (the component returned from the {@link #getComponent} method). The
103     * {@code x} and {@code y} is the origin of the content, {@code (0, 0)}
104     * in the layout coordinate space of the content, appearing at
105     * {@code data[y * scale * linestride + x * scale]} in the buffer.
106     * A pixel with indices {@code (i, j)}, where {@code (0 <= i < width)} and
107     * {@code (0 <= j < height)}, in the layout coordinate space of the content
108     * is represented by a {@code scale^2} square of pixels in the physical
109     * coordinate space of the buffer. The top-left corner of the square has the
110     * following physical coordinate in the buffer:
111     * {@code data[(y + j) * scale * linestride + (x + i) * scale]}.
112     *
113     * @param data the content pixel data buffer of INT_ARGB_PRE type
114     * @param x the logical x coordinate of the image
115     * @param y the logical y coordinate of the image
116     * @param width the logical width of the image
117     * @param height the logical height of the image
118     * @param linestride the line stride of the pixel buffer
119     * @param scale the scale factor of the pixel buffer
120     * @Depricated replaced by
121     * {@link #imageBufferReset(int[],int,int,int,int,int,double,double)}
122     */
123    @Deprecated(since = "9")
124    default public void imageBufferReset(int[] data,
125                                 int x, int y,
126                                 int width, int height,
127                                 int linestride,
128                                 int scale)
129    {
130        imageBufferReset(data, x, y, width, height, linestride);
131    }
132
133    /**
134     * {@code JLightweightFrame} calls this method to notify the client
135     * application that a new data buffer has been set as a content pixel
136     * buffer. Typically this occurs when a buffer of a larger size is
137     * created in response to a content resize event.
138     * <p>
139     * The method reports a reference to the pixel data buffer, the content
140     * image bounds within the buffer and the line stride of the buffer.
141     * These values have the following correlation.
142     * The {@code width} and {@code height} matches the layout size of the
143     * content (the component returned from the {@link #getComponent} method).
144     * The {@code x} and {@code y} is the origin of the content, {@code (0, 0)}
145     * in the layout coordinate space of the content, appearing at
146     * {@code data[y * scaleY * linestride + x * scaleX]} in the buffer.
147     * A pixel with indices {@code (i, j)}, where {@code (0 <= i < width)} and
148     * {@code (0 <= j < height)}, in the layout coordinate space of the content
149     * is represented by a {@code scaleX * scaleY} square of pixels in the
150     * physical coordinate space of the buffer. The top-left corner of the
151     * square has the following physical coordinate in the buffer:
152     * {@code data[(y + j) * scaleY * linestride + (x + i) * scaleX]}.
153     *
154     * @param data the content pixel data buffer of INT_ARGB_PRE type
155     * @param x the logical x coordinate of the image
156     * @param y the logical y coordinate of the image
157     * @param width the logical width of the image
158     * @param height the logical height of the image
159     * @param linestride the line stride of the pixel buffer
160     * @param scaleX the x coordinate scale factor of the pixel buffer
161     * @param scaleY the y coordinate scale factor of the pixel buffer
162     * @since 9
163     */
164    @SuppressWarnings("deprecation")
165    default public void imageBufferReset(int[] data,
166                                         int x, int y,
167                                         int width, int height,
168                                         int linestride,
169                                         double scaleX, double scaleY)
170    {
171        imageBufferReset(data, x, y, width, height, linestride,
172                                                       (int)Math.round(scaleX));
173    }
174
175    /**
176     * The default implementation for #imageBufferReset uses a hard-coded value
177     * of 1 for the scale factor. Both the old and the new methods provide
178     * default implementations in order to allow a client application to run
179     * with any JDK version without breaking backward compatibility.
180     */
181    @SuppressWarnings("deprecation")
182    default public void imageBufferReset(int[] data,
183                                 int x, int y,
184                                 int width, int height,
185                                 int linestride)
186    {
187        imageBufferReset(data, x, y, width, height, linestride, 1);
188    }
189
190    /**
191     * {@code JLightweightFrame} calls this method to notify the client
192     * application that the content image bounds have been changed within the
193     * image's pixel buffer.
194     *
195     * @param x the x coordinate of the image
196     * @param y the y coordinate of the image
197     * @param width the width of the image
198     * @param height the height of the image
199     *
200     * @see #imageBufferReset
201     */
202    public void imageReshaped(int x, int y, int width, int height);
203
204    /**
205     * {@code JLightweightFrame} calls this method to notify the client
206     * application that a part of the content image, or the whole image has
207     * been updated. The method reports bounds of the rectangular dirty region.
208     * The {@code dirtyX} and {@code dirtyY} is the origin of the dirty
209     * rectangle, which is relative to the origin of the content, appearing
210     * at {@code data[(y + dirtyY] * linestride + (x + dirtyX)]} in the pixel
211     * buffer (see {@link #imageBufferReset}). All indices
212     * {@code data[(y + dirtyY + j) * linestride + (x + dirtyX + i)]} where
213     * {@code (0 <= i < dirtyWidth)} and {@code (0 <= j < dirtyHeight)}
214     * will represent valid pixel data, {@code (i, j)} in the coordinate space
215     * of the dirty rectangle.
216     *
217     * @param dirtyX the x coordinate of the dirty rectangle,
218     *        relative to the image origin
219     * @param dirtyY the y coordinate of the dirty rectangle,
220     *        relative to the image origin
221     * @param dirtyWidth the width of the dirty rectangle
222     * @param dirtyHeight the height of the dirty rectangle
223     *
224     * @see #imageBufferReset
225     * @see #imageReshaped
226     */
227    public void imageUpdated(int dirtyX, int dirtyY,
228                             int dirtyWidth, int dirtyHeight);
229
230    /**
231     * {@code JLightweightFrame} calls this method to notify the client
232     * application that the frame has grabbed focus.
233     */
234    public void focusGrabbed();
235
236    /**
237     * {@code JLightweightFrame} calls this method to notify the client
238     * application that the frame has ungrabbed focus.
239     */
240    public void focusUngrabbed();
241
242    /**
243     * {@code JLightweightFrame} calls this method to notify the client
244     * application that the content preferred size has changed.
245     */
246    public void preferredSizeChanged(int width, int height);
247
248    /**
249     * {@code JLightweightFrame} calls this method to notify the client
250     * application that the content maximum size has changed.
251     */
252    public void maximumSizeChanged(int width, int height);
253
254    /**
255     * {@code JLightweightFrame} calls this method to notify the client
256     * application that the content minimum size has changed.
257     */
258    public void minimumSizeChanged(int width, int height);
259
260    /**
261     * {@code JLightweightFrame} calls this method to notify the client
262     * application that in needs to set a cursor
263     * @param cursor a cursor to set
264     */
265    default public void setCursor(Cursor cursor) { }
266
267    /**
268     * Create a drag gesture recognizer for the lightweight frame.
269     */
270    default public <T extends DragGestureRecognizer> T createDragGestureRecognizer(
271            Class<T> abstractRecognizerClass,
272            DragSource ds, Component c, int srcActions,
273            DragGestureListener dgl)
274    {
275        return null;
276    }
277
278    /**
279     * Create a drag source context peer for the lightweight frame.
280     */
281    default public DragSourceContextPeer createDragSourceContextPeer(DragGestureEvent dge) throws InvalidDnDOperationException
282    {
283        return null;
284    }
285
286    /**
287     * Adds a drop target to the lightweight frame.
288     */
289    default public void addDropTarget(DropTarget dt) {}
290
291    /**
292     * Removes a drop target from the lightweight frame.
293     */
294    default public void removeDropTarget(DropTarget dt) {}
295}
296