1 /*
2 * Copyright (c) 2013, 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 sun.swing;
27
28 import javax.swing.JComponent;
29 import java.awt.Component;
30 import java.awt.Cursor;
31 import java.awt.dnd.DragGestureEvent;
32 import java.awt.dnd.DragGestureListener;
33 import java.awt.dnd.DragGestureRecognizer;
34 import java.awt.dnd.DragSource;
35 import java.awt.dnd.DropTarget;
36 import java.awt.dnd.InvalidDnDOperationException;
37 import 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 */
58 public 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 */
121 default public void imageBufferReset(int[] data,
122 int x, int y,
123 int width, int height,
124 int linestride,
125 int scale)
126 {
127 imageBufferReset(data, x, y, width, height, linestride);
128 }
129
130 /**
131 * The default implementation for #imageBufferReset uses a hard-coded value
132 * of 1 for the scale factor. Both the old and the new methods provide
133 * default implementations in order to allow a client application to run
134 * with any JDK version without breaking backward compatibility.
135 */
136 default public void imageBufferReset(int[] data,
137 int x, int y,
138 int width, int height,
139 int linestride)
140 {
141 imageBufferReset(data, x, y, width, height, linestride, 1);
142 }
143
144 /**
145 * {@code JLightweightFrame} calls this method to notify the client
146 * application that the content image bounds have been changed within the
147 * image's pixel buffer.
148 *
149 * @param x the x coordinate of the image
150 * @param y the y coordinate of the image
151 * @param width the width of the image
152 * @param height the height of the image
153 *
154 * @see #imageBufferReset
155 */
156 public void imageReshaped(int x, int y, int width, int height);
157
158 /**
159 * {@code JLightweightFrame} calls this method to notify the client
160 * application that a part of the content image, or the whole image has
161 * been updated. The method reports bounds of the rectangular dirty region.
162 * The {@code dirtyX} and {@code dirtyY} is the origin of the dirty
163 * rectangle, which is relative to the origin of the content, appearing
164 * at {@code data[(y + dirtyY] * linestride + (x + dirtyX)]} in the pixel
165 * buffer (see {@link #imageBufferReset}). All indices
166 * {@code data[(y + dirtyY + j) * linestride + (x + dirtyX + i)]} where
167 * {@code (0 <= i < dirtyWidth)} and {@code (0 <= j < dirtyHeight)}
168 * will represent valid pixel data, {@code (i, j)} in the coordinate space
169 * of the dirty rectangle.
170 *
171 * @param dirtyX the x coordinate of the dirty rectangle,
172 * relative to the image origin
173 * @param dirtyY the y coordinate of the dirty rectangle,
174 * relative to the image origin
175 * @param dirtyWidth the width of the dirty rectangle
176 * @param dirtyHeight the height of the dirty rectangle
177 *
178 * @see #imageBufferReset
179 * @see #imageReshaped
180 */
181 public void imageUpdated(int dirtyX, int dirtyY,
182 int dirtyWidth, int dirtyHeight);
183
184 /**
185 * {@code JLightweightFrame} calls this method to notify the client
186 * application that the frame has grabbed focus.
187 */
188 public void focusGrabbed();
189
190 /**
191 * {@code JLightweightFrame} calls this method to notify the client
192 * application that the frame has ungrabbed focus.
193 */
194 public void focusUngrabbed();
195
196 /**
197 * {@code JLightweightFrame} calls this method to notify the client
198 * application that the content preferred size has changed.
199 */
200 public void preferredSizeChanged(int width, int height);
201
202 /**
203 * {@code JLightweightFrame} calls this method to notify the client
204 * application that the content maximum size has changed.
205 */
206 public void maximumSizeChanged(int width, int height);
207
208 /**
209 * {@code JLightweightFrame} calls this method to notify the client
210 * application that the content minimum size has changed.
211 */
212 public void minimumSizeChanged(int width, int height);
213
214 /**
215 * {@code JLightweightFrame} calls this method to notify the client
216 * application that in needs to set a cursor
217 * @param cursor a cursor to set
218 */
219 default public void setCursor(Cursor cursor) { }
220
221 /**
222 * Create a drag gesture recognizer for the lightweight frame.
223 */
224 default public <T extends DragGestureRecognizer> T createDragGestureRecognizer(
225 Class<T> abstractRecognizerClass,
226 DragSource ds, Component c, int srcActions,
227 DragGestureListener dgl)
228 {
229 return null;
230 }
231
232 /**
233 * Create a drag source context peer for the lightweight frame.
234 */
235 default public DragSourceContextPeer createDragSourceContextPeer(DragGestureEvent dge) throws InvalidDnDOperationException
236 {
237 return null;
238 }
239
240 /**
241 * Adds a drop target to the lightweight frame.
242 */
243 default public void addDropTarget(DropTarget dt) {}
244
245 /**
246 * Removes a drop target from the lightweight frame.
247 */
248 default public void removeDropTarget(DropTarget dt) {}
249 }