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.Cursor;
30
31 /**
32 * The interface by means of which the {@link JLightweightFrame} class
33 * communicates to its client application.
34 * <p>
35 * The client application implements this interface so it can response
36 * to requests and process notifications from {@code JLightweightFrame}.
37 * An implementation of this interface is associated with a {@code
38 * JLightweightFrame} instance via the {@link JLightweightFrame#setContent}
39 * method.
40 *
41 * A hierarchy of components contained in the {@code JComponent} instance
42 * returned by the {@link #getComponent} method should not contain any
43 * heavyweight components, otherwise {@code JLightweightFrame} may fail
44 * to paint it.
45 *
46 * @author Artem Ananiev
47 * @author Anton Tarasov
48 * @author Jim Graham
49 */
50 public interface LightweightContent {
51
52 /**
53 * The client application overrides this method to return the {@code
54 * JComponent} instance which the {@code JLightweightFrame} container
55 * will paint as its lightweight content. A hierarchy of components
56 * contained in this component should not contain any heavyweight objects.
57 *
58 * @return the component to paint
59 */
60 public JComponent getComponent();
61
62 /**
63 * {@code JLightweightFrame} calls this method to notify the client
64 * application that it acquires the paint lock. The client application
65 * should implement the locking mechanism in order to synchronize access
66 * to the content image data, shared between {@code JLightweightFrame}
67 * and the client application.
68 *
69 * @see #paintUnlock
70 */
71 public void paintLock();
72
73 /**
74 * {@code JLightweightFrame} calls this method to notify the client
75 * application that it releases the paint lock. The client application
76 * should implement the locking mechanism in order to synchronize access
77 * to the content image data, shared between {@code JLightweightFrame}
78 * and the client application.
79 *
80 * @see #paintLock
81 */
82 public void paintUnlock();
83
84 /**
85 * {@code JLightweightFrame} calls this method to notify the client
86 * application that a new data buffer has been set as a content pixel
87 * buffer. Typically this occurs when a buffer of a larger size is
88 * created in response to a content resize event.
89 * <p>
90 * When a scale factor greater than one is set on a {@code JLightweightFrame}
91 * ({@link JLightweightFrame#setScaleFactor}), an {@link OffScreenHiDPIImage}
92 * is created to server the pixel buffer.
93 * <p>
94 * The method reports a reference to the pixel data buffer, the content
95 * image bounds within the buffer and the line stride of the buffer.
96 * These values have the following correlation.
97 * The {@code width} and {@code height} matches the layout size of the content
98 * (the component returned from the {@link #getComponent} method). The
99 * {@code x} and {@code y} is the origin of the content, {@code (0, 0)}
100 * in the layout coordinate space of the content, appearing at
101 * {@code data[y * scale * linestride + x * scale]} in the buffer.
102 * A pixel with indices {@code (i, j)}, where {@code (0 <= i < width)} and
103 * {@code (0 <= j < height)}, in the layout coordinate space of the content
104 * is represented by a {@code scale^2} square of pixels in the physical
105 * coordinate space of the buffer. The top-left corner of the square has the
106 * following physical coordinate in the buffer:
107 * {@code data[(y + j) * scale * linestride + (x + i) * scale]}.
108 *
109 * @param data the content pixel data buffer of INT_ARGB_PRE type
110 * @param x the logical x coordinate of the image
111 * @param y the logical y coordinate of the image
112 * @param width the logical width of the image
113 * @param height the logical height of the image
114 * @param linestride the line stride of the pixel buffer
115 * @param scale the scale factor of the pixel buffer
116 */
117 public void imageBufferReset(int[] data,
118 int x, int y,
119 int width, int height,
120 int linestride,
121 int scale);
122
123 /**
124 * {@code JLightweightFrame} calls this method to notify the client
125 * application that the content image bounds have been changed within the
126 * image's pixel buffer.
127 *
128 * @param x the x coordinate of the image
129 * @param y the y coordinate of the image
130 * @param width the width of the image
131 * @param height the height of the image
132 *
133 * @see #imageBufferReset
134 */
135 public void imageReshaped(int x, int y, int width, int height);
136
137 /**
138 * {@code JLightweightFrame} calls this method to notify the client
139 * application that a part of the content image, or the whole image has
140 * been updated. The method reports bounds of the rectangular dirty region.
141 * The {@code dirtyX} and {@code dirtyY} is the origin of the dirty
142 * rectangle, which is relative to the origin of the content, appearing
143 * at {@code data[(y + dirtyY] * linestride + (x + dirtyX)]} in the pixel
144 * buffer (see {@link #imageBufferReset}). All indices
145 * {@code data[(y + dirtyY + j) * linestride + (x + dirtyX + i)]} where
146 * {@code (0 <= i < dirtyWidth)} and {@code (0 <= j < dirtyHeight)}
147 * will represent valid pixel data, {@code (i, j)} in the coordinate space
148 * of the dirty rectangle.
149 *
150 * @param dirtyX the x coordinate of the dirty rectangle,
151 * relative to the image origin
152 * @param dirtyY the y coordinate of the dirty rectangle,
153 * relative to the image origin
154 * @param dirtyWidth the width of the dirty rectangle
155 * @param dirtyHeight the height of the dirty rectangle
156 *
157 * @see #imageBufferReset
158 * @see #imageReshaped
159 */
160 public void imageUpdated(int dirtyX, int dirtyY,
161 int dirtyWidth, int dirtyHeight);
162
163 /**
164 * {@code JLightweightFrame} calls this method to notify the client
165 * application that the frame has grabbed focus.
166 */
167 public void focusGrabbed();
168
169 /**
170 * {@code JLightweightFrame} calls this method to notify the client
171 * application that the frame has ungrabbed focus.
172 */
173 public void focusUngrabbed();
174
175 /**
176 * {@code JLightweightFrame} calls this method to notify the client
177 * application that the content preferred size has changed.
178 */
179 public void preferredSizeChanged(int width, int height);
180
181 /**
182 * {@code JLightweightFrame} calls this method to notify the client
183 * application that the content maximum size has changed.
184 */
185 public void maximumSizeChanged(int width, int height);
186
187 /**
188 * {@code JLightweightFrame} calls this method to notify the client
189 * application that the content minimum size has changed.
190 */
191 public void minimumSizeChanged(int width, int height);
192
193 /**
194 * {@code JLightweightFrame} calls this method to notify the client
195 * application that in needs to set a cursor
196 * @param cursor a cursor to set
197 */
198 default public void setCursor(Cursor cursor) { }
199 }