Brian Jones <[EMAIL PROTECTED]> wrote on Fri, 12 Sep 2003 08:58:29 -0400:
>What parts of our code would rely upon having a ClasspathToolkit
>with the additional Font related stuff?
The JavaDoc of the enclosed classes "ClasspathToolkit" and
"ClasspathFontPeer" explains the expected uses.
Would those two classes be suitable for eventual inclusion into Classpath?
Graydon, would this FontPeer be ok, or would you like to see things done
differently?
-- Sascha
Sascha Brawer, [EMAIL PROTECTED], http://www.dandelis.ch/people/brawer/
/* ClasspathToolkit.java -- Abstract superclass for Classpath toolkits.
Copyright (C) 2003 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., 59 Temple Place, Suite 330, Boston, MA
02111-1307 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 gnu.java.awt;
import java.awt.Image;
import java.awt.Dimension;
import java.awt.DisplayMode;
import java.awt.Font;
import java.awt.FontFormatException;
import java.awt.FontMetrics;
import java.awt.GraphicsEnvironment;
import java.awt.HeadlessException;
import java.awt.Toolkit;
import java.awt.image.ColorModel;
import java.io.File;
import java.io.InputStream;
import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import gnu.java.awt.peer.ClasspathFontPeer;
/**
* An abstract superclass for Classpath toolkits.
*
* <p>There exist some parts of AWT and Java2D that are specific to
* the underlying platform, but for which the [EMAIL PROTECTED] Toolkit} class
* does not provide suitable abstractions. Examples include some
* methods of [EMAIL PROTECTED] Font} or [EMAIL PROTECTED] GraphicsEnvironment}. Those
* methods use ClasspathToolkit as a central place for obtaining
* platform-specific functionality.
*
* <p>In addition, ClasspathToolkit implements some abstract methods
* of [EMAIL PROTECTED] java.awt.Toolkit} that are not really platform-specific,
* such as the maintenance of a cache of loaded images.
*
* <p><b>Thread Safety:</b> The methods of this class may safely be
* called without external synchronization. This also hold for any
* inherited [EMAIL PROTECTED] Toolkit} methods. Subclasses are responsible for
* the necessary synchronization.
*
* @author Sascha Brawer ([EMAIL PROTECTED])
*/
public abstract class ClasspathToolkit
extends Toolkit
{
/**
* A map from URLs to previously loaded images, used by [EMAIL PROTECTED]
* #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.
*
* <p>This method is specific to GNU Classpath. It gets called by
* the Classpath implementation of [EMAIL PROTECTED]
* 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);
}
/**
* Creates a font, reading the glyph definitions from a stream.
*
* <p>This method provides the platform-specific implementation for
* the static factory method [EMAIL PROTECTED] Font#createFont(int,
* java.io.InputStream)}.
*
* @param format the format of the font data, such as [EMAIL PROTECTED]
* 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 <code>format</code> is
* not supported.
*
* @throws FontFormatException if <code>stream</code> 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 <code>stream</code>.
*/
public abstract Font createFont(int format, InputStream stream);
// FIXME: More factory methods for creating/deriving fonts.
/**
* 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.
*
* <p>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 [EMAIL PROTECTED]
* #createImage(java.lang.String)} instead.
*
* <p>The default implementation creates a file URL for the
* specified path and invokes [EMAIL PROTECTED] #getImage(URL)}.
*
* @param path A path to the image file.
*
* @return IllegalArgumentException if <code>path</code> 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.
*
* <p>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 [EMAIL PROTECTED]
* #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.
*
* <p>A new image is created every time this method gets called,
* even if the same path has been passed before.
*
* <p>The default implementation creates a file URL for the
* specified path and invokes [EMAIL PROTECTED] #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);
}
}
}
/* ClasspathFontPeer.java -- Font peer used by GNU Classpath.
Copyright (C) 2003 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., 59 Temple Place, Suite 330, Boston, MA
02111-1307 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 gnu.java.awt.peer;
import java.awt.Font;
import java.awt.FontMetrics;
import java.awt.font.FontRenderContext;
import java.awt.font.GlyphVector;
import java.awt.peer.FontPeer;
import java.text.CharacterIterator;
import java.util.Locale;
/**
* A peer for fonts that are used inside Classpath. The purpose of
* this interface is to abstract from platform-specific font handling
* in the Classpath implementation of java.awt.Font and related
* classes.
*
* <p><b>State kept by the peer:</b> Platform-specific implementations
* may vary in the amount of state they keep in their font peers. Some
* implementations may associate a separate peer to each [EMAIL PROTECTED] Font}
* instance. Others may share a single peer among the fonts that were
* derived through scaling or the application of an affine
* transformation. An implementation could even use a singleton
* <code>ClasspathFontPeer</code> for all fonts.
*
* <p><b>Thread Safety:</b> Methods of this interface may be called
* from arbitrary threads at any time. Implementations of the
* <code>ClasspathFontPeer</code> interface are required to perform
* the necessary synchronization.
*
* @see java.awt.Font#getPeer
* @see java.awt.Toolkit#getFontPeer
*
* @author Sascha Brawer ([EMAIL PROTECTED])
* @author Graydon Hoare ([EMAIL PROTECTED])
*/
public interface ClasspathFontPeer
extends FontPeer
{
/**
* Returns the full name of this font face in the specified
* locale, for example <i>“Univers Light”</i>.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getFontName()} and [EMAIL PROTECTED] Font#getFontName(Locale)}. It is
* called <code>getFullName()</code> here because this term clearly
* designates a specific name used in electronic typography, while
* “font name” would be ambiguous.
*
* @param font the font whose full name is requested.
*
* @param locale the locale for which to localize the name. If
* <code>locale</code> is <code>null</code>, the returned name is
* localized to the user’s default locale.
*
* @return the full name of the font. The result will never be
* <code>null</code> or an empty string.
*/
String getFullName(Font font, Locale locale);
/**
* Returns the name of the family to which this font face belongs,
* for example <i>“Univers”</i>.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getFamily()} and [EMAIL PROTECTED] Font#getFamily(Locale)}.
*
* @param font the font whose family name is requested.
*
* @param locale the locale for which to localize the name. If
* <code>locale</code> is <code>null</code>, the returned name is
* localized to the user’s default locale.
*
* @return the name of the font family. If the font does not provide
* a family name, the result is identical to the full name.
*/
String getFamilyName(Font font, Locale locale);
/**
* Returns the name of this font face inside the family, for example
* <i>“Light”</i>.
*
* <p>This method is currently not used by [EMAIL PROTECTED] Font}. However,
* this name would be needed by any serious desktop publishing
* application.
*
* @param font the font whose sub-family name is requested.
*
* @param locale the locale for which to localize the name. If
* <code>locale</code> is <code>null</code>, the returned name is
* localized to the user’s default locale.
*
* @return the name of the face inside its family, or
* <code>null</code> if the font does not provide a sub-family name.
*/
String getSubFamilyName(Font font, Locale locale);
/**
* Returns the PostScript name of this font face, for example
* <i>“Univers-Light”</i>.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getPSName()}.
*
* @param font the font whose PostScript name is requested.
*
* @return the PostScript name, or <code>null</code> if the font
* does not provide a PostScript name.
*/
String getPostScriptName(Font font);
/**
* Returns the italic angle of the font.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getItalicAngle()}.
*
* @param font the font whose italic angle is requested.
*
* @return the inverse slope of the insertion mark, which is 0.0 for
* an upright font.
*/
float getItalicAngle(Font font);
/**
* Returns the style of the font. The set of font styles is restricted
* to one of the following:
*
* <p><ul><li>[EMAIL PROTECTED] Font#PLAIN};</li>
* <li>[EMAIL PROTECTED] Font#BOLD};</li>
* <li>[EMAIL PROTECTED] Font#ITALIC};</li>
* <li>[EMAIL PROTECTED] Font#BOLD} + [EMAIL PROTECTED] Font#ITALIC}.</li></ul>
*
* <p>It is recommended that the closest value is returned for
* fonts whose style is not in the above list.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getStyle()}.
*
* @param font the font whose style is requested.
*/
int getStyle(Font font);
/**
* Returns the number of glyphs in this font face.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getNumGlyphs()}.
*
* @param font the font whose number of glyphs is requested.
*/
int getNumGlyphs(Font font);
/**
* Returns the index of the glyph which gets displayed if the font
* cannot map a Unicode code point to a glyph. Many fonts show this
* glyph as an empty box.
*
* <p>For TrueType fonts, the result is 0. For PostScript fonts, the
* result is the index of the glyph whose PostScript name is
* <code>“.notdef”</code>.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#getMissingGlyphCode}.
*
* @param font the font whose missing glyph code is requested.
*/
int getMissingGlyphCode(Font font);
/**
* Returns a name for the specified glyph. This is useful for
* generating PostScript or PDF files that embed some glyphs of a
* font. If the implementation follows glyph naming conventions
* specified by Adobe, search engines can extract the original text
* from the generated PostScript and PDF files.
*
* <p>This method is currently not used by GNU Classpath. However,
* it would be very useful for someone wishing to write a good
* PostScript or PDF stream provider for the
* <code>javax.print</code> package.
*
* <p><b>Names are not unique:</b> Under some rare circumstances,
* the same name can be returned for different glyphs. It is
* therefore recommended that printer drivers check whether the same
* name has already been returned for antoher glyph, and make the
* name unique by adding the string ".alt" followed by the glyph
* index.</p>
*
* <p>This situation would occur for an OpenType or TrueType font
* that has a <code>post</code> table of format 3 and provides a
* mapping from glyph IDs to Unicode sequences through a
* <code>Zapf</code> table. If the same sequence of Unicode
* codepoints leads to different glyphs (depending on contextual
* position, for example, or on typographic sophistication level),
* the same name would get synthesized for those glyphs. To avoid
* this, the font peer would have to go through the names of all
* glyphs, which would make this operation very inefficient with
* large fonts.
*
* @param font the font containing the glyph whose name is
* requested.
*
* @param glyphIndex the glyph whose name the caller wants to
* retrieve.
*
* @return the glyph name, or <code>null</code> if a font does not
* provide glyph names.
*/
String getGlyphName(Font font, int glyphIndex);
/**
* Creates a GlyphVector by mapping each character in a
* CharacterIterator to the corresponding glyph.
*
* <p>The mapping takes only the font’s <code>cmap</code>
* tables into consideration. No other operations (such as glyph
* re-ordering, composition, or ligature substitution) are
* performed. This means that the resulting GlyphVector will not be
* correct for text in languages that have complex
* character-to-glyph mappings, such as Arabic, Hebrew, Hindi, or
* Thai.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* Font#createGlyphVector(FontRenderContext, String)}, [EMAIL PROTECTED]
* Font#createGlyphVector(FontRenderContext, char[])}, and [EMAIL PROTECTED]
* Font#createGlyphVector(FontRenderContext, CharacterIterator)}.
*
* @param font the font object that the created GlyphVector will
* return when it gets asked for its font. This argument is needed
* because the public API of GlyphVector works with java.awt.Font,
* not with font peers. The implementation of
* <code>ClasspathFontPeer</code> will usually retrieve the point
* size and transform from <code>font</code>.
*
* @param frc the font rendering parameters that are used for
* measuring glyphs. The exact placement of text slightly depends on
* device-specific characteristics, for instance the device
* resolution or anti-aliasing. For this reason, any measurements
* will only be accurate if the passed
* <code>FontRenderContext</code> correctly reflects the relevant
* parameters. Hence, <code>frc</code> should be obtained from the
* same <code>Graphics2D</code> that will be used for drawing, and
* any rendering hints should be set to the desired values before
* obtaining <code>frc</code>.
*
* @param ci a CharacterIterator for iterating over the
* characters to be displayed.
*/
GlyphVector createGlyphVector(Font font,
FontRenderContext frc,
CharacterIterator ci);
// FIXME: More methods for creating glyph vectors are needed,
// e.g. for the variant taking glyph indices, and for
// layoutGlyphVector.
/**
* Returns a FontMetrics object for rendering this font on screen.
*
* <p>This method provides the implementation for [EMAIL PROTECTED]
* gnu.java.awt.ClasspathToolkit#getFontMetrics(Font)}, which is an
* abstract method introduced by [EMAIL PROTECTED] java.awt.Toolkit}.
*
* @param font the font whose metrics are retrieved.
*/
FontMetrics getFontMetrics(Font font);
}
_______________________________________________
Classpath mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/classpath
