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    }