001/* ComponentPeer.java -- Toplevel component peer
002   Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt.peer;
040
041import java.awt.AWTEvent;
042import java.awt.AWTException;
043import java.awt.BufferCapabilities;
044import java.awt.Color;
045import java.awt.Component;
046import java.awt.Cursor;
047import java.awt.Dimension;
048import java.awt.Font;
049import java.awt.FontMetrics;
050import java.awt.Graphics;
051import java.awt.GraphicsConfiguration;
052import java.awt.Image;
053import java.awt.Point;
054import java.awt.Rectangle;
055import java.awt.Toolkit;
056import java.awt.event.PaintEvent;
057import java.awt.image.ColorModel;
058import java.awt.image.ImageObserver;
059import java.awt.image.ImageProducer;
060import java.awt.image.VolatileImage;
061
062import sun.awt.CausedFocusEvent;
063
064/**
065 * Defines the methods that a component peer is required to implement.
066 */
067public 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}