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