summaryrefslogtreecommitdiff
path: root/libjava/classpath/java/awt/peer/ComponentPeer.java
blob: 736cdf3762b31e3377a5f7f1229f92c5daef1b30 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
/* ComponentPeer.java -- Toplevel component peer
   Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package java.awt.peer;

import java.awt.AWTEvent;
import java.awt.AWTException;
import java.awt.BufferCapabilities;
import java.awt.Color;
import java.awt.Component;
import java.awt.Cursor;
import java.awt.Dimension;
import java.awt.Font;
import java.awt.FontMetrics;
import java.awt.Graphics;
import java.awt.GraphicsConfiguration;
import java.awt.Image;
import java.awt.Point;
import java.awt.Rectangle;
import java.awt.Toolkit;
import java.awt.event.PaintEvent;
import java.awt.image.ColorModel;
import java.awt.image.ImageObserver;
import java.awt.image.ImageProducer;
import java.awt.image.VolatileImage;

import sun.awt.CausedFocusEvent;

/**
 * Defines the methods that a component peer is required to implement.
 */
public interface ComponentPeer
{
  /**
   * Returns the construction status of the specified image. This is called
   * by {@link Component#checkImage(Image, int, int, ImageObserver)}.
   *
   * @param img the image
   * @param width the width of the image
   * @param height the height of the image
   * @param ob the image observer to be notified of updates of the status
   *
   * @return a bitwise ORed set of ImageObserver flags
   */
  int checkImage(Image img, int width, int height,
                 ImageObserver ob);

  /**
   * Creates an image by starting the specified image producer. This is called
   * by {@link Component#createImage(ImageProducer)}.
   *
   * @param prod the image producer to be used to create the image
   *
   * @return the created image
   */
  Image createImage(ImageProducer prod);

  /**
   * Creates an empty image with the specified <code>width</code> and
   * <code>height</code>.
   *
   * @param width the width of the image to be created
   * @param height the height of the image to be created
   *
   * @return the created image
   */
  Image createImage(int width, int height);

  /**
   * Disables the component. This is called by {@link Component#disable()}.
   */
  void disable();

  /**
   * Disposes the component peer. This should release all resources held by the
   * peer. This is called when the component is no longer in use.
   */
  void dispose();

  /**
   * Enables the component. This is called by {@link Component#enable()}.
   */
  void enable();

  /**
   * Returns the color model of the component. This is currently not used.
   *
   * @return the color model of the component
   */
  ColorModel getColorModel();

  /**
   * Returns the font metrics for the specified font. This is called by
   * {@link Component#getFontMetrics(Font)}.
   *
   * @param f the font for which to query the font metrics
   *
   * @return the font metrics for the specified font
   */
  FontMetrics getFontMetrics(Font f);

  /**
   * Returns a {@link Graphics} object suitable for drawing on this component.
   * This is called by {@link Component#getGraphics()}.
   *
   * @return a graphics object suitable for drawing on this component
   */
  Graphics getGraphics();

  /**
   * Returns the location of this component in screen coordinates. This is
   * called by {@link Component#getLocationOnScreen()}.
   *
   * @return the location of this component in screen coordinates
   */
  Point getLocationOnScreen();

  /**
   * Returns the minimum size for the component. This is called by
   * {@link Component#getMinimumSize()}.
   *
   * @return the minimum size for the component
   *
   * @specnote Presumably this method got added to replace minimumSize().
   *           However, testing shows that this is never called in the RI
   *           (tested with JDK5), but instead minimumSize() is called
   *           directly. It is advisable to implement this method to delegate
   *           to minimumSize() and put the real implementation in there.
   */
  Dimension getMinimumSize();

  /**
   * Returns the preferred size for the component. This is called by
   * {@link Component#getPreferredSize()}.
   *
   * @return the preferred size for the component
   *
   * @specnote Presumably this method got added to replace preferredSize().
   *           However, testing shows that this is never called in the RI
   *           (tested with JDK5), but instead preferredSize() is called
   *           directly. It is advisable to implement this method to delegate
   *           to preferredSize() and put the real implementation in there.
   */
  Dimension getPreferredSize();

  /**
   * Returns the toolkit that created this peer.
   *
   * @return the toolkit that created this peer
   */
  Toolkit getToolkit();

  /**
   * Handles the given event. This is called from
   * {@link Component#dispatchEvent(AWTEvent)} to give the peer a chance to
   * react to events for the component.
   *
   * @param e the event
   */
  void handleEvent(AWTEvent e);

  /**
   * Makes the component invisible. This is called from
   * {@link Component#hide()}.
   */
  void hide();

  /**
   * Returns <code>true</code> if the component can receive keyboard input
   * focus. This is called from {@link Component#isFocusTraversable()}.
   *
   * @specnote Part of the earlier 1.1 API, replaced by isFocusable().
   */
  boolean isFocusTraversable();

  /**
   * Returns <code>true</code> if the component can receive keyboard input
   * focus. This is called from {@link Component#isFocusable()}.
   */
  boolean isFocusable();

  /**
   * Returns the minimum size for the component. This is called by
   * {@link Component#minimumSize()}.
   *
   * @return the minimum size for the component
   */
  Dimension minimumSize();

  /**
   * Returns the preferred size for the component. This is called by
   * {@link Component#getPreferredSize()}.
   *
   * @return the preferred size for the component
   */
  Dimension preferredSize();

  void paint(Graphics graphics);

  /**
   * Prepares an image for rendering on this component. This is called by
   * {@link Component#prepareImage(Image, int, int, ImageObserver)}.
   *
   * @param img the image to prepare
   * @param width the desired width of the rendered image
   * @param height the desired height of the rendered image
   * @param ob the image observer to be notified of updates in the preparation
   *        process
   *
   * @return <code>true</code> if the image has been fully prepared,
   *         <code>false</code> otherwise (in which case the image observer
   *         receives updates)
   */
  boolean prepareImage(Image img, int width, int height,
                              ImageObserver ob);

  void print(Graphics graphics);

  /**
   * Repaints the specified rectangle of this component. This is called from
   * {@link Component#repaint(long, int, int, int, int)}.
   *
   * @param tm number of milliseconds to wait with repainting
   * @param x the X coordinate of the upper left corner of the damaged rectangle
   * @param y the Y coordinate of the upper left corner of the damaged rectangle
   * @param width the width of the damaged rectangle
   * @param height the height of the damaged rectangle
   */
  void repaint(long tm, int x, int y, int width, int height);

  /**
   * Requests that this component receives the focus. This is called from
   * {@link Component#requestFocus()}.
   *
   * @specnote Part of the earlier 1.1 API, apparently replaced by argument
   *           form of the same method.
   */
  void requestFocus();

  /**
   * Requests that this component receives the focus. This is called from
   * {@link Component#requestFocus()}.
   *
   * This method is only called for heavyweight component's peers. Lightweight
   * components ask their nearest heavyweight component to request focus.
   * It's up to the heavyweight peer to decide if any of it's lightweight
   * descendants are allowed to receive keyboard input focus or not. If the
   * focus request is finally approved, then the peer must post a FOCUS_GAINED
   * event for the requested component.
   *
   * @param request the component for which the focus is requested
   * @param temporary indicates if the focus change is temporary (true) or
   *        permanent (false)
   * @param allowWindowFocus indicates if it's allowed to change window focus
   * @param time the timestamp
   */
  boolean requestFocus(Component request, boolean temporary,
                       boolean allowWindowFocus, long time);

  /**
   * Notifies the peer that the bounds of this component have changed. This
   * is called by {@link Component#reshape(int, int, int, int)}.
   *
   * @param x the X coordinate of the upper left corner of the component
   * @param y the Y coordinate of the upper left corner of the component
   * @param width the width of the component
   * @param height the height of the component
   */
  void reshape(int x, int y, int width, int height);

  /**
   * Sets the background color of the component. This is called by
   * {@link Component#setBackground(Color)}.
   *
   * @param color the background color to set
   */
  void setBackground(Color color);

  /**
   * Notifies the peer that the bounds of this component have changed. This
   * is called by {@link Component#setBounds(int, int, int, int)}.
   *
   * @param x the X coordinate of the upper left corner of the component
   * @param y the Y coordinate of the upper left corner of the component
   * @param width the width of the component
   * @param height the height of the component
   */
  void setBounds(int x, int y, int width, int height);

  /**
   * Sets the cursor of the component. This is called by
   * {@link Component#setCursor(Cursor)}.
   *
   * @specnote Part of the earlier 1.1 API, apparently no longer needed.
   */
  void setCursor(Cursor cursor);

  /**
   * Sets the enabled/disabled state of this component. This is called by
   * {@link Component#setEnabled(boolean)}.
   *
   * @param enabled <code>true</code> to enable the component,
   *        <code>false</code> to disable it
   */
  void setEnabled(boolean enabled);

  /**
   * Sets the font of the component. This is called by
   * {@link Component#setFont(Font)}.
   *
   * @param font the font to set
   */
  void setFont(Font font);

  /**
   * Sets the foreground color of the component. This is called by
   * {@link Component#setForeground(Color)}.
   *
   * @param color the foreground color to set
   */
  void setForeground(Color color);

  /**
   * Sets the visibility state of the component. This is called by
   * {@link Component#setVisible(boolean)}.
   *
   * @param visible <code>true</code> to make the component visible,
   *        <code>false</code> to make it invisible
   */
  void setVisible(boolean visible);

  /**
   * Makes the component visible. This is called by {@link Component#show()}.
   */
  void show();

  /**
   * Get the graphics configuration of the component. The color model
   * of the component can be derived from the configuration.
   *
   * @return the graphics configuration of the component
   */
  GraphicsConfiguration getGraphicsConfiguration();

  /**
   * Part of an older API, no longer needed.
   */
  void setEventMask(long mask);

  /**
   * Returns <code>true</code> if this component has been obscured,
   * <code>false</code> otherwise. This will only work if
   * {@link #canDetermineObscurity()} also returns <code>true</code>.
   *
   * @return <code>true</code> if this component has been obscured,
   *         <code>false</code> otherwise.
   */
  boolean isObscured();

  /**
   * Returns <code>true</code> if this component peer can determine if the
   * component has been obscured, <code>false</code> otherwise.
   *
   * @return <code>true</code> if this component peer can determine if the
   *         component has been obscured, <code>false</code> otherwise
   */
  boolean canDetermineObscurity();

  /**
   * Coalesces the specified paint event.
   *
   * @param e the paint event
   */
  void coalescePaintEvent(PaintEvent e);

  /**
   * Updates the cursor.
   */
  void updateCursorImmediately();

  /**
   * Returns true, if this component can handle wheel scrolling,
   * <code>false</code> otherwise.
   *
   * @return true, if this component can handle wheel scrolling,
   *         <code>false</code> otherwise
   */
  boolean handlesWheelScrolling();

  /**
   * A convenience method that creates a volatile image.  The volatile
   * image is created on the screen device on which this component is
   * displayed, in the device's current graphics configuration.
   *
   * @param width width of the image
   * @param height height of the image
   *
   * @see VolatileImage
   *
   * @since 1.2
   */
  VolatileImage createVolatileImage(int width, int height);

  /**
   * Create a number of image buffers that implement a buffering
   * strategy according to the given capabilities.
   *
   * @param numBuffers the number of buffers
   * @param caps the buffering capabilities
   *
   * @throws AWTException if the specified buffering strategy is not
   * implemented
   *
   * @since 1.2
   */
  void createBuffers(int numBuffers, BufferCapabilities caps)
    throws AWTException;

  /**
   * Return the back buffer of this component.
   *
   * @return the back buffer of this component.
   *
   * @since 1.2
   */
  Image getBackBuffer();

  /**
   * Perform a page flip, leaving the contents of the back buffer in
   * the specified state.
   *
   * @param contents the state in which to leave the back buffer
   *
   * @since 1.2
   */
  void flip(BufferCapabilities.FlipContents contents);

  /**
   * Destroy the resources created by createBuffers.
   *
   * @since 1.2
   */
  void destroyBuffers();

  /**
   * Get the bounds of this component peer.
   *
   * @return component peer bounds
   * @since 1.5
   */
  Rectangle getBounds();

  /**
   * Reparent this component under another container.
   *
   * @param parent
   * @since 1.5
   */
  void reparent(ContainerPeer parent);

  /**
   * Set the bounds of this component peer.
   *
   * @param x the new x co-ordinate
   * @param y the new y co-ordinate
   * @param width the new width
   * @param height the new height
   * @param z the new stacking level
   * @since 1.5
   */
  void setBounds (int x, int y, int width, int height, int z);

  /**
   * Check if this component supports being reparented.
   *
   * @return true if this component can be reparented,
   * false otherwise.
   * @since 1.5
   */
  boolean isReparentSupported();

  /**
   * Layout this component peer.
   *
   * @since 1.5
   */
  void layout();


  /**
   * Requests the focus on the component.
   */
  boolean requestFocus(Component lightweightChild, boolean temporary,
                       boolean focusedWindowChangeAllowed, long time,
                       CausedFocusEvent.Cause cause);

}