001 /* ComponentPeer.java -- Toplevel component peer
002 Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.awt.peer;
040
041 import java.awt.AWTEvent;
042 import java.awt.AWTException;
043 import java.awt.BufferCapabilities;
044 import java.awt.Color;
045 import java.awt.Component;
046 import java.awt.Cursor;
047 import java.awt.Dimension;
048 import java.awt.Font;
049 import java.awt.FontMetrics;
050 import java.awt.Graphics;
051 import java.awt.GraphicsConfiguration;
052 import java.awt.Image;
053 import java.awt.Point;
054 import java.awt.Rectangle;
055 import java.awt.Toolkit;
056 import java.awt.event.PaintEvent;
057 import java.awt.image.ColorModel;
058 import java.awt.image.ImageObserver;
059 import java.awt.image.ImageProducer;
060 import java.awt.image.VolatileImage;
061
062 import sun.awt.CausedFocusEvent;
063
064 /**
065 * Defines the methods that a component peer is required to implement.
066 */
067 public interface ComponentPeer
068 {
069 /**
070 * Returns the construction status of the specified image. This is called
071 * by {@link Component#checkImage(Image, int, int, ImageObserver)}.
072 *
073 * @param img the image
074 * @param width the width of the image
075 * @param height the height of the image
076 * @param ob the image observer to be notified of updates of the status
077 *
078 * @return a bitwise ORed set of ImageObserver flags
079 */
080 int checkImage(Image img, int width, int height,
081 ImageObserver ob);
082
083 /**
084 * Creates an image by starting the specified image producer. This is called
085 * by {@link Component#createImage(ImageProducer)}.
086 *
087 * @param prod the image producer to be used to create the image
088 *
089 * @return the created image
090 */
091 Image createImage(ImageProducer prod);
092
093 /**
094 * Creates an empty image with the specified <code>width</code> and
095 * <code>height</code>.
096 *
097 * @param width the width of the image to be created
098 * @param height the height of the image to be created
099 *
100 * @return the created image
101 */
102 Image createImage(int width, int height);
103
104 /**
105 * Disables the component. This is called by {@link Component#disable()}.
106 */
107 void disable();
108
109 /**
110 * Disposes the component peer. This should release all resources held by the
111 * peer. This is called when the component is no longer in use.
112 */
113 void dispose();
114
115 /**
116 * Enables the component. This is called by {@link Component#enable()}.
117 */
118 void enable();
119
120 /**
121 * Returns the color model of the component. This is currently not used.
122 *
123 * @return the color model of the component
124 */
125 ColorModel getColorModel();
126
127 /**
128 * Returns the font metrics for the specified font. This is called by
129 * {@link Component#getFontMetrics(Font)}.
130 *
131 * @param f the font for which to query the font metrics
132 *
133 * @return the font metrics for the specified font
134 */
135 FontMetrics getFontMetrics(Font f);
136
137 /**
138 * Returns a {@link Graphics} object suitable for drawing on this component.
139 * This is called by {@link Component#getGraphics()}.
140 *
141 * @return a graphics object suitable for drawing on this component
142 */
143 Graphics getGraphics();
144
145 /**
146 * Returns the location of this component in screen coordinates. This is
147 * called by {@link Component#getLocationOnScreen()}.
148 *
149 * @return the location of this component in screen coordinates
150 */
151 Point getLocationOnScreen();
152
153 /**
154 * Returns the minimum size for the component. This is called by
155 * {@link Component#getMinimumSize()}.
156 *
157 * @return the minimum size for the component
158 *
159 * @specnote Presumably this method got added to replace minimumSize().
160 * However, testing shows that this is never called in the RI
161 * (tested with JDK5), but instead minimumSize() is called
162 * directly. It is advisable to implement this method to delegate
163 * to minimumSize() and put the real implementation in there.
164 */
165 Dimension getMinimumSize();
166
167 /**
168 * Returns the preferred size for the component. This is called by
169 * {@link Component#getPreferredSize()}.
170 *
171 * @return the preferred size for the component
172 *
173 * @specnote Presumably this method got added to replace preferredSize().
174 * However, testing shows that this is never called in the RI
175 * (tested with JDK5), but instead preferredSize() is called
176 * directly. It is advisable to implement this method to delegate
177 * to preferredSize() and put the real implementation in there.
178 */
179 Dimension getPreferredSize();
180
181 /**
182 * Returns the toolkit that created this peer.
183 *
184 * @return the toolkit that created this peer
185 */
186 Toolkit getToolkit();
187
188 /**
189 * Handles the given event. This is called from
190 * {@link Component#dispatchEvent(AWTEvent)} to give the peer a chance to
191 * react to events for the component.
192 *
193 * @param e the event
194 */
195 void handleEvent(AWTEvent e);
196
197 /**
198 * Makes the component invisible. This is called from
199 * {@link Component#hide()}.
200 */
201 void hide();
202
203 /**
204 * Returns <code>true</code> if the component can receive keyboard input
205 * focus. This is called from {@link Component#isFocusTraversable()}.
206 *
207 * @specnote Part of the earlier 1.1 API, replaced by isFocusable().
208 */
209 boolean isFocusTraversable();
210
211 /**
212 * Returns <code>true</code> if the component can receive keyboard input
213 * focus. This is called from {@link Component#isFocusable()}.
214 */
215 boolean isFocusable();
216
217 /**
218 * Returns the minimum size for the component. This is called by
219 * {@link Component#minimumSize()}.
220 *
221 * @return the minimum size for the component
222 */
223 Dimension minimumSize();
224
225 /**
226 * Returns the preferred size for the component. This is called by
227 * {@link Component#getPreferredSize()}.
228 *
229 * @return the preferred size for the component
230 */
231 Dimension preferredSize();
232
233 void paint(Graphics graphics);
234
235 /**
236 * Prepares an image for rendering on this component. This is called by
237 * {@link Component#prepareImage(Image, int, int, ImageObserver)}.
238 *
239 * @param img the image to prepare
240 * @param width the desired width of the rendered image
241 * @param height the desired height of the rendered image
242 * @param ob the image observer to be notified of updates in the preparation
243 * process
244 *
245 * @return <code>true</code> if the image has been fully prepared,
246 * <code>false</code> otherwise (in which case the image observer
247 * receives updates)
248 */
249 boolean prepareImage(Image img, int width, int height,
250 ImageObserver ob);
251
252 void print(Graphics graphics);
253
254 /**
255 * Repaints the specified rectangle of this component. This is called from
256 * {@link Component#repaint(long, int, int, int, int)}.
257 *
258 * @param tm number of milliseconds to wait with repainting
259 * @param x the X coordinate of the upper left corner of the damaged rectangle
260 * @param y the Y coordinate of the upper left corner of the damaged rectangle
261 * @param width the width of the damaged rectangle
262 * @param height the height of the damaged rectangle
263 */
264 void repaint(long tm, int x, int y, int width, int height);
265
266 /**
267 * Requests that this component receives the focus. This is called from
268 * {@link Component#requestFocus()}.
269 *
270 * @specnote Part of the earlier 1.1 API, apparently replaced by argument
271 * form of the same method.
272 */
273 void requestFocus();
274
275 /**
276 * Requests that this component receives the focus. This is called from
277 * {@link Component#requestFocus()}.
278 *
279 * This method is only called for heavyweight component's peers. Lightweight
280 * components ask their nearest heavyweight component to request focus.
281 * It's up to the heavyweight peer to decide if any of it's lightweight
282 * descendants are allowed to receive keyboard input focus or not. If the
283 * focus request is finally approved, then the peer must post a FOCUS_GAINED
284 * event for the requested component.
285 *
286 * @param request the component for which the focus is requested
287 * @param temporary indicates if the focus change is temporary (true) or
288 * permanent (false)
289 * @param allowWindowFocus indicates if it's allowed to change window focus
290 * @param time the timestamp
291 */
292 boolean requestFocus(Component request, boolean temporary,
293 boolean allowWindowFocus, long time);
294
295 /**
296 * Notifies the peer that the bounds of this component have changed. This
297 * is called by {@link Component#reshape(int, int, int, int)}.
298 *
299 * @param x the X coordinate of the upper left corner of the component
300 * @param y the Y coordinate of the upper left corner of the component
301 * @param width the width of the component
302 * @param height the height of the component
303 */
304 void reshape(int x, int y, int width, int height);
305
306 /**
307 * Sets the background color of the component. This is called by
308 * {@link Component#setBackground(Color)}.
309 *
310 * @param color the background color to set
311 */
312 void setBackground(Color color);
313
314 /**
315 * Notifies the peer that the bounds of this component have changed. This
316 * is called by {@link Component#setBounds(int, int, int, int)}.
317 *
318 * @param x the X coordinate of the upper left corner of the component
319 * @param y the Y coordinate of the upper left corner of the component
320 * @param width the width of the component
321 * @param height the height of the component
322 */
323 void setBounds(int x, int y, int width, int height);
324
325 /**
326 * Sets the cursor of the component. This is called by
327 * {@link Component#setCursor(Cursor)}.
328 *
329 * @specnote Part of the earlier 1.1 API, apparently no longer needed.
330 */
331 void setCursor(Cursor cursor);
332
333 /**
334 * Sets the enabled/disabled state of this component. This is called by
335 * {@link Component#setEnabled(boolean)}.
336 *
337 * @param enabled <code>true</code> to enable the component,
338 * <code>false</code> to disable it
339 */
340 void setEnabled(boolean enabled);
341
342 /**
343 * Sets the font of the component. This is called by
344 * {@link Component#setFont(Font)}.
345 *
346 * @param font the font to set
347 */
348 void setFont(Font font);
349
350 /**
351 * Sets the foreground color of the component. This is called by
352 * {@link Component#setForeground(Color)}.
353 *
354 * @param color the foreground color to set
355 */
356 void setForeground(Color color);
357
358 /**
359 * Sets the visibility state of the component. This is called by
360 * {@link Component#setVisible(boolean)}.
361 *
362 * @param visible <code>true</code> to make the component visible,
363 * <code>false</code> to make it invisible
364 */
365 void setVisible(boolean visible);
366
367 /**
368 * Makes the component visible. This is called by {@link Component#show()}.
369 */
370 void show();
371
372 /**
373 * Get the graphics configuration of the component. The color model
374 * of the component can be derived from the configuration.
375 *
376 * @return the graphics configuration of the component
377 */
378 GraphicsConfiguration getGraphicsConfiguration();
379
380 /**
381 * Part of an older API, no longer needed.
382 */
383 void setEventMask(long mask);
384
385 /**
386 * Returns <code>true</code> if this component has been obscured,
387 * <code>false</code> otherwise. This will only work if
388 * {@link #canDetermineObscurity()} also returns <code>true</code>.
389 *
390 * @return <code>true</code> if this component has been obscured,
391 * <code>false</code> otherwise.
392 */
393 boolean isObscured();
394
395 /**
396 * Returns <code>true</code> if this component peer can determine if the
397 * component has been obscured, <code>false</code> otherwise.
398 *
399 * @return <code>true</code> if this component peer can determine if the
400 * component has been obscured, <code>false</code> otherwise
401 */
402 boolean canDetermineObscurity();
403
404 /**
405 * Coalesces the specified paint event.
406 *
407 * @param e the paint event
408 */
409 void coalescePaintEvent(PaintEvent e);
410
411 /**
412 * Updates the cursor.
413 */
414 void updateCursorImmediately();
415
416 /**
417 * Returns true, if this component can handle wheel scrolling,
418 * <code>false</code> otherwise.
419 *
420 * @return true, if this component can handle wheel scrolling,
421 * <code>false</code> otherwise
422 */
423 boolean handlesWheelScrolling();
424
425 /**
426 * A convenience method that creates a volatile image. The volatile
427 * image is created on the screen device on which this component is
428 * displayed, in the device's current graphics configuration.
429 *
430 * @param width width of the image
431 * @param height height of the image
432 *
433 * @see VolatileImage
434 *
435 * @since 1.2
436 */
437 VolatileImage createVolatileImage(int width, int height);
438
439 /**
440 * Create a number of image buffers that implement a buffering
441 * strategy according to the given capabilities.
442 *
443 * @param numBuffers the number of buffers
444 * @param caps the buffering capabilities
445 *
446 * @throws AWTException if the specified buffering strategy is not
447 * implemented
448 *
449 * @since 1.2
450 */
451 void createBuffers(int numBuffers, BufferCapabilities caps)
452 throws AWTException;
453
454 /**
455 * Return the back buffer of this component.
456 *
457 * @return the back buffer of this component.
458 *
459 * @since 1.2
460 */
461 Image getBackBuffer();
462
463 /**
464 * Perform a page flip, leaving the contents of the back buffer in
465 * the specified state.
466 *
467 * @param contents the state in which to leave the back buffer
468 *
469 * @since 1.2
470 */
471 void flip(BufferCapabilities.FlipContents contents);
472
473 /**
474 * Destroy the resources created by createBuffers.
475 *
476 * @since 1.2
477 */
478 void destroyBuffers();
479
480 /**
481 * Get the bounds of this component peer.
482 *
483 * @return component peer bounds
484 * @since 1.5
485 */
486 Rectangle getBounds();
487
488 /**
489 * Reparent this component under another container.
490 *
491 * @param parent
492 * @since 1.5
493 */
494 void reparent(ContainerPeer parent);
495
496 /**
497 * Set the bounds of this component peer.
498 *
499 * @param x the new x co-ordinate
500 * @param y the new y co-ordinate
501 * @param width the new width
502 * @param height the new height
503 * @param z the new stacking level
504 * @since 1.5
505 */
506 void setBounds (int x, int y, int width, int height, int z);
507
508 /**
509 * Check if this component supports being reparented.
510 *
511 * @return true if this component can be reparented,
512 * false otherwise.
513 * @since 1.5
514 */
515 boolean isReparentSupported();
516
517 /**
518 * Layout this component peer.
519 *
520 * @since 1.5
521 */
522 void layout();
523
524
525 /**
526 * Requests the focus on the component.
527 */
528 boolean requestFocus(Component lightweightChild, boolean temporary,
529 boolean focusedWindowChangeAllowed, long time,
530 CausedFocusEvent.Cause cause);
531
532 }