libjava/gnu/java/awt/ClasspathToolkit.java

   1 /* ClasspathToolkit.java -- Abstract superclass for Classpath toolkits.
   2    Copyright (C) 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package gnu.java.awt;
  40
  41 import java.awt.Image;
  42 import java.awt.Dimension;
  43 import java.awt.DisplayMode;
  44 import java.awt.Font;
  45 import java.awt.FontFormatException;
  46 import java.awt.FontMetrics;
  47 import java.awt.GraphicsEnvironment;
  48 import java.awt.HeadlessException;
  49 import java.awt.Toolkit;
  50 import java.awt.image.ColorModel;
  51 import java.io.File;
  52 import java.io.InputStream;
  53 import java.io.IOException;
  54 import java.net.MalformedURLException;
  55 import java.net.URL;
  56 import java.util.HashMap;
  57 import java.util.Map;
  58
  59 import gnu.java.awt.peer.ClasspathFontPeer;
  60
  61
  62 /**
  63  * An abstract superclass for Classpath toolkits.
  64  *
  65  * <p>There exist some parts of AWT and Java2D that are specific to
  66  * the underlying platform, but for which the {@link Toolkit} class
  67  * does not provide suitable abstractions. Examples include some
  68  * methods of {@link Font} or {@link GraphicsEnvironment}. Those
  69  * methods use ClasspathToolkit as a central place for obtaining
  70  * platform-specific functionality.
  71  *
  72  * <p>In addition, ClasspathToolkit implements some abstract methods
  73  * of {@link java.awt.Toolkit} that are not really platform-specific,
  74  * such as the maintenance of a cache of loaded images.
  75  *
  76  * <p><b>Thread Safety:</b> The methods of this class may safely be
  77  * called without external synchronization. This also hold for any
  78  * inherited {@link Toolkit} methods. Subclasses are responsible for
  79  * the necessary synchronization.
  80  *
  81  * @author Sascha Brawer (brawer@dandelis.ch)
  82  */
  83 public abstract class ClasspathToolkit
  84   extends Toolkit
  85 {
  86   /**
  87    * A map from URLs to previously loaded images, used by {@link
  88    * #getImage(java.net.URL)}. For images that were loaded via a path
  89    * to an image file, the map contains a key with a file URL.
  90    */
  91   private Map imageCache;
  92
  93
  94   /**
  95    * Returns a shared instance of the local, platform-specific
  96    * graphics environment.
  97    *
  98    * <p>This method is specific to GNU Classpath. It gets called by
  99    * the Classpath implementation of {@link
 100    * GraphicsEnvironment.getLocalGraphcisEnvironment()}.
 101    */
 102   public abstract GraphicsEnvironment getLocalGraphicsEnvironment();
 103
 104
 105   /**
 106    * Determines the current size of the default, primary screen.
 107    *
 108    * @throws HeadlessException if the local graphics environment is
 109    * headless, which means that no screen is attached and no user
 110    * interaction is allowed.
 111    */
 112   public Dimension getScreenSize()
 113   {
 114     DisplayMode mode;
 115
 116     // getDefaultScreenDevice throws HeadlessException if the
 117     // local graphics environment is headless.
 118     mode = GraphicsEnvironment.getLocalGraphicsEnvironment()
 119       .getDefaultScreenDevice().getDisplayMode();
 120
 121     return new Dimension(mode.getWidth(), mode.getHeight());
 122   }
 123
 124
 125   /**
 126    * Determines the current color model of the default, primary
 127    * screen.
 128    *
 129    * @see GraphicsEnvironment#getDefaultScreenDevice()
 130    * @see java.awt.GraphicsDevice#getDefaultConfiguration()
 131    * @see java.awt.GraphicsConfiguration#getColorModel()
 132    *
 133    * @throws HeadlessException if the local graphics environment is
 134    * headless, which means that no screen is attached and no user
 135    * interaction is allowed.
 136    */
 137   public ColorModel getColorModel()
 138   {
 139     // getDefaultScreenDevice throws HeadlessException if the
 140     // local graphics environment is headless.
 141     return GraphicsEnvironment.getLocalGraphicsEnvironment()
 142       .getDefaultScreenDevice().getDefaultConfiguration()
 143       .getColorModel();
 144   }
 145
 146   /**
 147    * Retrieves the metrics for rendering a font on the screen.
 148    *
 149    * @param font the font whose metrics are requested.
 150    */
 151   public FontMetrics getFontMetrics(Font font)
 152   {
 153     return ((ClasspathFontPeer) font.getPeer ()).getFontMetrics (font);
 154   }
 155
 156
 157   /**
 158    * Acquires an appropriate {@link ClasspathFontPeer}, for use in
 159    * classpath's implementation of {@link java.awt.Font}.
 160    *
 161    * @param name The logical name of the font. This may be either a face
 162    * name or a logical font name, or may even be null. A default
 163    * implementation of name decoding is provided in
 164    * {@link ClasspathFontPeer}, but may be overridden in other toolkits.
 165    *
 166    * @param attrs Any extra {@link java.awt.font.TextAttribute} attributes
 167    * this font peer should have, such as size, weight, family name, or
 168    * transformation.
 169    */
 170
 171   public abstract ClasspathFontPeer getClasspathFontPeer (String name, Map attrs);
 172
 173
 174   /**
 175    * Creates a {@link Font}, in a platform-specific manner.
 176    *
 177    * The default implementation simply constructs a {@link Font}, but some
 178    * toolkits may wish to override this, to return {@link Font} subclasses which
 179    * implement {@link java.awt.font.OpenType} or
 180    * {@link java.awt.font.MultipleMaster}.
 181    */
 182
 183   public Font getFont (String name, Map attrs)
 184   {
 185     return new Font (name, attrs);
 186   }
 187
 188
 189   /**
 190    * Creates a font, reading the glyph definitions from a stream.
 191    *
 192    * <p>This method provides the platform-specific implementation for
 193    * the static factory method {@link Font#createFont(int,
 194    * java.io.InputStream)}.
 195    *
 196    * @param format the format of the font data, such as {@link
 197    * Font#TRUETYPE_FONT}. An implementation may ignore this argument
 198    * if it is able to automatically recognize the font format from the
 199    * provided data.
 200    *
 201    * @param stream an input stream from where the font data is read
 202    * in. The stream will be advanced to the position after the font
 203    * data, but not closed.
 204    *
 205    * @throws IllegalArgumentException if <code>format</code> is
 206    * not supported.
 207    *
 208    * @throws FontFormatException if <code>stream</code> does not
 209    * contain data in the expected format, or if required tables are
 210    * missing from a font.
 211    *
 212    * @throws IOException if a problem occurs while reading in the
 213    * contents of <code>stream</code>.
 214    */
 215   public abstract Font createFont(int format, InputStream stream);
 216
 217
 218   /**
 219    * Returns an image from the specified file, which must be in a
 220    * recognized format. The set of recognized image formats may vary
 221    * from toolkit to toolkit.
 222    *
 223    * <p>This method maintains a cache for images. If an image has been
 224    * loaded from the same path before, the cached copy will be
 225    * returned. The implementation may hold cached copies for an
 226    * indefinite time, which can consume substantial resources with
 227    * large images. Users are therefore advised to use {@link
 228    * #createImage(java.lang.String)} instead.
 229    *
 230    * <p>The default implementation creates a file URL for the
 231    * specified path and invokes {@link #getImage(URL)}.
 232    *
 233    * @param path A path to the image file.
 234    *
 235    * @return IllegalArgumentException if <code>path</code> does not
 236    * designate a valid path.
 237    */
 238   public Image getImage(String path)
 239   {
 240     try
 241     {
 242       return getImage(new File(path).toURL());
 243     }
 244     catch (MalformedURLException muex)
 245     {
 246       throw (IllegalArgumentException) new IllegalArgumentException(path)
 247         .initCause(muex);
 248     }
 249   }
 250
 251
 252   /**
 253    * Loads an image from the specified URL. The image data must be in
 254    * a recognized format. The set of recognized image formats may vary
 255    * from toolkit to toolkit.
 256    *
 257    * <p>This method maintains a cache for images. If an image has been
 258    * loaded from the same URL before, the cached copy will be
 259    * returned. The implementation may hold cached copies for an
 260    * indefinite time, which can consume substantial resources with
 261    * large images. Users are therefore advised to use {@link
 262    * #createImage(java.net.URL)} instead.
 263    *
 264    * @param url the URL from where the image is read.
 265    */
 266   public Image getImage(URL url)
 267   {
 268     Image result;
 269
 270     synchronized (this)
 271     {
 272       // Many applications never call getImage. Therefore, we lazily
 273       // create the image cache when it is actually needed.
 274       if (imageCache == null)
 275         imageCache = new HashMap();
 276       else
 277       {
 278         result = (Image) imageCache.get(url);
 279         if (result != null)
 280           return result;
 281       }
 282
 283       // The createImage(URL) method, which is specified by
 284       // java.awt.Toolkit, is not implemented by this abstract class
 285       // because it is platform-dependent. Once Classpath has support
 286       // for the javax.imageio package, it might be worth considering
 287       // that toolkits provide native stream readers. Then, the class
 288       // ClasspathToolkit could provide a general implementation that
 289       // delegates the image format parsing to javax.imageio.
 290       result = createImage(url);
 291
 292       // It is not clear whether it would be a good idea to use weak
 293       // references here. The advantage would be reduced memory
 294       // consumption, since loaded images would not be kept
 295       // forever. But on VMs that frequently perform garbage
 296       // collection (which includes VMs with a parallel or incremental
 297       // collector), the image might frequently need to be re-loaded,
 298       // possibly over a slow network connection.
 299       imageCache.put(url, result);
 300
 301       return result;
 302     }
 303   }
 304
 305
 306   /**
 307    * Returns an image from the specified file, which must be in a
 308    * recognized format.  The set of recognized image formats may vary
 309    * from toolkit to toolkit.
 310    *
 311    * <p>A new image is created every time this method gets called,
 312    * even if the same path has been passed before.
 313    *
 314    * <p>The default implementation creates a file URL for the
 315    * specified path and invokes {@link #createImage(URL)}.
 316    *
 317    * @param path A path to the file to be read in.
 318    */
 319   public Image createImage(String path)
 320   {
 321     try
 322     {
 323       // The abstract method createImage(URL) is defined by
 324       // java.awt.Toolkit, but intentionally not implemented by
 325       // ClasspathToolkit because it is platform specific.
 326       return createImage(new File(path).toURL());
 327     }
 328     catch (MalformedURLException muex)
 329     {
 330       throw (IllegalArgumentException) new IllegalArgumentException(path)
 331         .initCause(muex);
 332     }
 333   }
 334 }