There exist some parts of AWT and Java2D that are specific to * the underlying platform, but for which the {@link Toolkit} class * does not provide suitable abstractions. Examples include some * methods of {@link Font} or {@link GraphicsEnvironment}. Those * methods use ClasspathToolkit as a central place for obtaining * platform-specific functionality. * *
In addition, ClasspathToolkit implements some abstract methods * of {@link java.awt.Toolkit} that are not really platform-specific, * such as the maintenance of a cache of loaded images. * *
Thread Safety: The methods of this class may safely be * called without external synchronization. This also hold for any * inherited {@link Toolkit} methods. Subclasses are responsible for * the necessary synchronization. * * @author Sascha Brawer (brawer@dandelis.ch) */ public abstract class ClasspathToolkit extends Toolkit { /** * A map from URLs to previously loaded images, used by {@link * #getImage(java.net.URL)}. For images that were loaded via a path * to an image file, the map contains a key with a file URL. */ private Map imageCache; /** * Returns a shared instance of the local, platform-specific * graphics environment. * *
This method is specific to GNU Classpath. It gets called by * the Classpath implementation of {@link * GraphicsEnvironment.getLocalGraphcisEnvironment()}. */ public abstract GraphicsEnvironment getLocalGraphicsEnvironment(); /** * Determines the current size of the default, primary screen. * * @throws HeadlessException if the local graphics environment is * headless, which means that no screen is attached and no user * interaction is allowed. */ public Dimension getScreenSize() { DisplayMode mode; // getDefaultScreenDevice throws HeadlessException if the // local graphics environment is headless. mode = GraphicsEnvironment.getLocalGraphicsEnvironment() .getDefaultScreenDevice().getDisplayMode(); return new Dimension(mode.getWidth(), mode.getHeight()); } /** * Determines the current color model of the default, primary * screen. * * @see GraphicsEnvironment#getDefaultScreenDevice() * @see java.awt.GraphicsDevice#getDefaultConfiguration() * @see java.awt.GraphicsConfiguration#getColorModel() * * @throws HeadlessException if the local graphics environment is * headless, which means that no screen is attached and no user * interaction is allowed. */ public ColorModel getColorModel() { // getDefaultScreenDevice throws HeadlessException if the // local graphics environment is headless. return GraphicsEnvironment.getLocalGraphicsEnvironment() .getDefaultScreenDevice().getDefaultConfiguration() .getColorModel(); } /** * Retrieves the metrics for rendering a font on the screen. * * @param font the font whose metrics are requested. */ public FontMetrics getFontMetrics(Font font) { return ((ClasspathFontPeer) font.getPeer ()).getFontMetrics (font); } /** * Acquires an appropriate {@link ClasspathFontPeer}, for use in * classpath's implementation of {@link java.awt.Font}. * * @param name The logical name of the font. This may be either a face * name or a logical font name, or may even be null. A default * implementation of name decoding is provided in * {@link ClasspathFontPeer}, but may be overridden in other toolkits. * * @param attrs Any extra {@link java.awt.font.TextAttribute} attributes * this font peer should have, such as size, weight, family name, or * transformation. */ public abstract ClasspathFontPeer getClasspathFontPeer (String name, Map attrs); /** * Creates a {@link Font}, in a platform-specific manner. * * The default implementation simply constructs a {@link Font}, but some * toolkits may wish to override this, to return {@link Font} subclasses which * implement {@link java.awt.font.OpenType} or * {@link java.awt.font.MultipleMaster}. */ public Font getFont (String name, Map attrs) { return new Font (name, attrs); } /** * Creates a font, reading the glyph definitions from a stream. * *
This method provides the platform-specific implementation for
* the static factory method {@link Font#createFont(int,
* java.io.InputStream)}.
*
* @param format the format of the font data, such as {@link
* Font#TRUETYPE_FONT}. An implementation may ignore this argument
* if it is able to automatically recognize the font format from the
* provided data.
*
* @param stream an input stream from where the font data is read
* in. The stream will be advanced to the position after the font
* data, but not closed.
*
* @throws IllegalArgumentException if format is
* not supported.
*
* @throws FontFormatException if stream does not
* contain data in the expected format, or if required tables are
* missing from a font.
*
* @throws IOException if a problem occurs while reading in the
* contents of stream.
*/
public abstract Font createFont(int format, InputStream stream);
/**
* Returns an image from the specified file, which must be in a
* recognized format. The set of recognized image formats may vary
* from toolkit to toolkit.
*
*
This method maintains a cache for images. If an image has been * loaded from the same path before, the cached copy will be * returned. The implementation may hold cached copies for an * indefinite time, which can consume substantial resources with * large images. Users are therefore advised to use {@link * #createImage(java.lang.String)} instead. * *
The default implementation creates a file URL for the
* specified path and invokes {@link #getImage(URL)}.
*
* @param path A path to the image file.
*
* @return IllegalArgumentException if path does not
* designate a valid path.
*/
public Image getImage(String path)
{
try
{
return getImage(new File(path).toURL());
}
catch (MalformedURLException muex)
{
throw (IllegalArgumentException) new IllegalArgumentException(path)
.initCause(muex);
}
}
/**
* Loads an image from the specified URL. The image data must be in
* a recognized format. The set of recognized image formats may vary
* from toolkit to toolkit.
*
*
This method maintains a cache for images. If an image has been * loaded from the same URL before, the cached copy will be * returned. The implementation may hold cached copies for an * indefinite time, which can consume substantial resources with * large images. Users are therefore advised to use {@link * #createImage(java.net.URL)} instead. * * @param url the URL from where the image is read. */ public Image getImage(URL url) { Image result; synchronized (this) { // Many applications never call getImage. Therefore, we lazily // create the image cache when it is actually needed. if (imageCache == null) imageCache = new HashMap(); else { result = (Image) imageCache.get(url); if (result != null) return result; } // The createImage(URL) method, which is specified by // java.awt.Toolkit, is not implemented by this abstract class // because it is platform-dependent. Once Classpath has support // for the javax.imageio package, it might be worth considering // that toolkits provide native stream readers. Then, the class // ClasspathToolkit could provide a general implementation that // delegates the image format parsing to javax.imageio. result = createImage(url); // It is not clear whether it would be a good idea to use weak // references here. The advantage would be reduced memory // consumption, since loaded images would not be kept // forever. But on VMs that frequently perform garbage // collection (which includes VMs with a parallel or incremental // collector), the image might frequently need to be re-loaded, // possibly over a slow network connection. imageCache.put(url, result); return result; } } /** * Returns an image from the specified file, which must be in a * recognized format. The set of recognized image formats may vary * from toolkit to toolkit. * *
A new image is created every time this method gets called, * even if the same path has been passed before. * *
The default implementation creates a file URL for the * specified path and invokes {@link #createImage(URL)}. * * @param path A path to the file to be read in. */ public Image createImage(String path) { try { // The abstract method createImage(URL) is defined by // java.awt.Toolkit, but intentionally not implemented by // ClasspathToolkit because it is platform specific. return createImage(new File(path).toURL()); } catch (MalformedURLException muex) { throw (IllegalArgumentException) new IllegalArgumentException(path) .initCause(muex); } } }