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