Java Doc for Font.java in  » 6.0-JDK-Core » AWT » java » awt » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Characters and Glyphs

A glyph is a shape used to render a character or a sequence of characters. In simple writing systems, such as Latin, typically one glyph represents one character. In general, however, characters and glyphs do not have one-to-one correspondence. For example, the character 'á' LATIN SMALL LETTER A WITH ACUTE, can be represented by two glyphs: one for 'a' and one for '´'. On the other hand, the two-character string "fi" can be represented by a single glyph, an "fi" ligature. In complex writing systems, such as Arabic or the South and South-East Asian writing systems, the relationship between characters and glyphs can be more complicated and involve context-dependent selection of glyphs as well as glyph reordering. A font encapsulates the collection of glyphs needed to render a selected set of characters as well as the tables needed to map sequences of characters to corresponding sequences of glyphs.

Physical and Logical Fonts

Physical fonts are the actual font libraries containing glyph data and tables to map from character sequences to glyph sequences, using a font technology such as TrueType or PostScript Type 1. All implementations of the Java Platform must support TrueType fonts; support for other font technologies is implementation dependent. Physical fonts may use names such as Helvetica, Palatino, HonMincho, or any number of other font names. Typically, each physical font supports only a limited set of writing systems, for example, only Latin characters or only Japanese and Basic Latin. The set of available physical fonts varies between configurations. Applications that require specific fonts can bundle them and instantiate them using the Font.createFont createFont method.

Logical fonts are the five font families defined by the Java platform which must be supported by any Java runtime environment: Serif, SansSerif, Monospaced, Dialog, and DialogInput. These logical fonts are not actual font libraries. Instead, the logical font names are mapped to physical fonts by the Java runtime environment. The mapping is implementation and usually locale dependent, so the look and the metrics provided by them vary. Typically, each logical font name maps to several physical fonts in order to cover a large range of characters.

Peered AWT components, such as Label Label and TextField TextField , can only use logical fonts.

For a discussion of the relative advantages and disadvantages of using physical or logical fonts, see the Internationalization FAQ document.

Font Faces and Names

There are three different names that you can get from a Font object. The logical font name is simply the name that was used to construct the font. The font face name, or just font name for short, is the name of a particular font face, like Helvetica Bold. The family name is the name of the font family that determines the typographic design across several faces, like Helvetica.

The Font class represents an instance of a font face from a collection of font faces that are present in the system resources of the host system. As examples, Arial Bold and Courier Bold Italic are font faces. There can be several Font objects associated with a font face, each differing in size, style, transform and font features.

The GraphicsEnvironment.getAllFonts getAllFonts method of the GraphicsEnvironment class returns an array of all font faces available in the system. These font faces are returned as Font objects with a size of 1, identity transform and default font features. These base fonts can then be used to derive new Font objects with varying sizes, styles, transforms and font features via the deriveFont methods in this class.

Font and TextAttribute

Font supports most TextAttributes. This makes some operations, such as rendering underlined text, convenient since it is not necessary to explicitly construct a TextLayout object. Attributes can be set on a Font by constructing or deriving it using a Map of TextAttribute values.

The values of some TextAttributes are not serializable, and therefore attempting to serialize an instance of Font that has such values will not serialize them. This means a Font deserialized from such a stream will not compare equal to the original Font that contained the non-serializable attributes. This should very rarely pose a problem since these attributes are typically used only in special circumstances and are unlikely to be serialized.

• FOREGROUND and BACKGROUND use Paint values. The subclass Color is serializable, while GradientPaint and TexturePaint are not.
• CHAR_REPLACEMENT uses GraphicAttribute values. The subclasses ShapeGraphicAttribute and ImageGraphicAttribute are not serializable.
• INPUT_METHOD_HIGHLIGHT uses InputMethodHighlight values, which are not serializable. See java.awt.im.InputMethodHighlight .

The Map-based constructor and deriveFont APIs ignore the FONT attribute, and it is not retained by the Font; the static Font.getFont method should be used if the FONT attribute might be present. See java.awt.font.TextAttribute.FONT for more information.

Several attributes will cause additional rendering overhead and potentially invoke layout. If a Font has such attributes, the Font.hasLayoutAttributes() method will return true.

Note: Font rotations can cause text baselines to be rotated. In order to account for this (rare) possibility, font APIs are specified to return metrics and take parameters 'in baseline-relative coordinates'. This maps the 'x' coordinate to the advance along the baseline, (positive x is forward along the baseline), and the 'y' coordinate to a distance along the perpendicular to the baseline at 'x' (positive y is 90 degrees clockwise from the baseline vector). APIs for which this is especially important are called out as having 'baseline-relative coordinates.'

The font name can be a font face name or a font family name. It is used together with the style to find an appropriate font face. When a font family name is specified, the style argument is used to select the most appropriate face from the family.

Note: This method cannot handle supplementary characters.

• fontname-style-pointsize
• fontname-pointsize
• fontname-style
• fontname
• fontname style pointsize
• fontname pointsize
• fontname style
• fontname

A valid trailing decimal field is always interpreted as the pointsize. Therefore a fontname containing a trailing decimal value should not be used in the fontname only form.

If a style name field is not one of the valid style strings, it is interpreted as part of the font name, and the default style is used.

Only one of ' ' or '-' may be used to separate fields in the input. The identified separator is the one closest to the end of the string which separates a valid pointsize, or a valid style name from the rest of the string. Null (empty) pointsize and style fields are treated as valid fields with the default value for that field.

Large fonts can support different writing systems, and each system can use a different baseline. The character argument determines the writing system to use.

The family name of a font is font specific.

The font name can be a font face name or a font family name. It is used together with the style to find an appropriate font face. When a font family name is specified, the style argument is used to select the most appropriate face from the family. When a font face name is specified, the face's style and the style argument are merged to locate the best matching font from the same family. For example if face name "Arial Bold" is specified with style Font.ITALIC, the font system looks for a face in the "Arial" family that is bold and italic, and may associate the font instance with the physical font face "Arial Bold Italic". The style argument is merged with the specified face's style, not added or subtracted. This means, specifying a bold face and a bold style does not double-embolden the font, and specifying a bold face and a plain style does not lighten the font.

If no face for the requested style can be found, the font system may apply algorithmic styling to achieve the desired style. For example, if ITALIC is requested, but no italic face is available, glyphs from the plain face may be algorithmically obliqued (slanted).

Font name lookup is case insensitive, using the case folding rules of the US locale.

If the name parameter represents something other than a logical font, i.e. is interpreted as a physical font face or family, and this cannot be mapped by the implementation to a physical font or a compatible alternative, then the font system will map the Font instance to "Dialog", such that for example, the family as reported by Font.getFamily() getFamily will be "Dialog".

Parameters:
  name - the font name. This can be a font face name or a fontfamily name, and may represent either a logical font or a physicalfont found in this GraphicsEnvironment .The family names for logical fonts are: Dialog, DialogInput,Monospaced, Serif, or SansSerif. Pre-defined String constants existfor all of these names, for example, DIALOG . If name is null , the logical font name of the new Font as returned by getName() is set tothe name "Default".
Parameters:
  style - the style constant for the Font The style argument is an integer bitmask that maybe PLAIN , or a bitwise union of BOLD and/or ITALIC (for example, ITALIC or BOLD|ITALIC ).If the style argument does not conform to one of the expectedinteger bitmasks then the style is set to PLAIN .
Parameters:
  size - the point size of the Font
See Also:   GraphicsEnvironment.getAllFonts
See Also:   GraphicsEnvironment.getAvailableFontFamilyNames
since:
   JDK1.0

If attributes is null, a new Font is initialized with default values.
See Also:   java.awt.font.TextAttribute
Parameters:
  attributes - the attributes to assign to the newFont, or null

Note: This method cannot handle supplementary characters. To support all Unicode characters, including supplementary characters, use the Font.canDisplay(int) method or canDisplayUpTo methods.
Parameters:
  c - the character for which a glyph is needed true if this Font has a glyph for thischaracter; false otherwise.
since:
   1.2

To make the Font available to Font constructors the returned Font must be registered in the GraphicsEnviroment by calling GraphicsEnvironment.registerFont(Font) registerFont(Font) .
Parameters:
  fontFormat - the type of the Font, which isFont.TRUETYPE_FONT TRUETYPE_FONT if a TrueType resource is specified.or Font.TYPE1_FONT TYPE1_FONT if a Type 1 resource is specified.
Parameters:
  fontStream - an InputStream object representing theinput data for the font. a new Font created with the specified font type.
throws:
  IllegalArgumentException - if fontFormat is notTRUETYPE_FONTorTYPE1_FONT.
throws:
  FontFormatException - if the fontStream data doesnot contain the required font tables for the specified format.
throws:
  IOException - if the fontStreamcannot be completely read.
See Also:   GraphicsEnvironment.registerFont(Font)
since:
   1.3

To make the Font available to Font constructors thereturned Font must be registered in theGraphicsEnviroment by callingGraphicsEnvironment.registerFont(Font) registerFont(Font).
Parameters:
  fontFile - a File object representing theinput data for the font. a new Font created with the specified font type.
throws:
  IllegalArgumentException - if fontFormat is notTRUETYPE_FONTorTYPE1_FONT.
throws:
  NullPointerException - if fontFile is null.
throws:
  IOException - if the fontFile cannot be read.
throws:
  FontFormatException - if fontFile doesnot contain the required font tables for the specified format.
throws:
  SecurityException - if the executing code does not havepermission to read from the file.
See Also:   GraphicsEnvironment.registerFont(Font)
since:
   1.5

• fontname-style-pointsize
• fontname-pointsize
• fontname-style
• fontname
• fontname style pointsize
• fontname pointsize
• fontname style
• fontname

A valid trailing decimal field is always interpreted as the pointsize. Therefore a fontname containing a trailing decimal value should not be used in the fontname only form.

If a style name field is not one of the valid style strings, it is interpreted as part of the font name, and the default style is used.

Only one of ' ' or '-' may be used to separate fields in the input. The identified separator is the one closest to the end of the string which separates a valid pointsize, or a valid style name from the rest of the string. Null (empty) pointsize and style fields are treated as valid fields with the default value for that field.

Some font names may include the separator characters ' ' or '-'. If str is not formed with 3 components, e.g. such that style or pointsize fields are not present in str, and fontname also contains a character determined to be the separator character then these characters where they appear as intended to be part of fontname may instead be interpreted as separators so the font name may not be properly recognised.

The default size is 12 and the default style is PLAIN. If str does not specify a valid size, the returned Font has a size of 12. If str does not specify a valid style, the returned Font has a style of PLAIN. If you do not specify a valid font name in the str argument, this method will return a font with the family name "Dialog". To determine what font family names are available on your system, use the GraphicsEnvironment.getAvailableFontFamilyNames method. If str is null, a new Font is returned with the family name "Dialog", a size of 12 and a PLAIN style.
Parameters:
  str - the name of the font, or null the Font object that strdescribes, or a new default Font if str is null.
See Also:   Font.getFamily
since:
   JDK1.1

Large fonts can support different writing systems, and each system can use a different baseline. The character argument determines the writing system to use. Clients should not assume all characters use the same baseline.
Parameters:
  c - a character used to identify the writing system the baseline appropriate for the specified character.
See Also:   LineMetrics.getBaselineOffsets
See Also:   Font.ROMAN_BASELINE
See Also:   Font.CENTER_BASELINE
See Also:   Font.HANGING_BASELINE
since:
   1.2

The family name of a font is font specific. Two fonts such as Helvetica Italic and Helvetica Bold have the same family name, Helvetica, whereas their font face names are Helvetica Bold and Helvetica Italic. The list of available family names may be obtained by using the GraphicsEnvironment.getAvailableFontFamilyNames method.

Use getName to get the logical name of the font. Use getFontName to get the font face name of the font. a String that is the family name of thisFont.
See Also:   Font.getName
See Also:   Font.getFontName
since:
   JDK1.1

The family name of a font is font specific. Two fonts such as Helvetica Italic and Helvetica Bold have the same family name, Helvetica, whereas their font face names are Helvetica Bold and Helvetica Italic. The list of available family names may be obtained by using the GraphicsEnvironment.getAvailableFontFamilyNames method.

Use getFontName to get the font face name of the font.
Parameters:
  l - locale for which to get the family name a String representing the family name of thefont, localized for the specified locale.
See Also:   Font.getFontName
See Also:   java.util.Locale
since:
   1.2

The property value should be one of the forms accepted by Font.decode(String) If the specified property is not found, or the executing code does not have permission to read the property, the font argument is returned instead.
Parameters:
  nm - the case-insensitive property name
Parameters:
  font - a default Font to return if propertynm is not defined the Font value of the property.
throws:
  NullPointerException - if nm is null.
See Also:   Font.decode(String)

Note: The returned bounds is in baseline-relative coordinates (see java.awt.Font class notes ).
Parameters:
  frc - the specified FontRenderContext a Rectangle2D that is the bounding boxfor the character with the maximum bounds.

The Java(tm)2D API adopts the convention that one point is equivalent to one unit in user coordinates. When using a normalized transform for converting user space coordinates to device space coordinates 72 user space units equal 1 inch in device space. In this case one point is 1/72 of an inch. the point size of this Font in 1/72 of an inch units.
See Also:   Font.getSize2D
See Also:   GraphicsConfiguration.getDefaultTransform
See Also:   GraphicsConfiguration.getNormalizingTransform
since:
   JDK1.0

Note: The returned bounds is in baseline-relative coordinates (see java.awt.Font class notes ).
Parameters:
  str - the specified String
Parameters:
  frc - the specified FontRenderContext a Rectangle2D that is the bounding box of thespecified String in the specifiedFontRenderContext.
See Also:   FontRenderContext
See Also:   Font.createGlyphVector
since:
   1.2

Note: The returned bounds is in baseline-relative coordinates (see java.awt.Font class notes ).
Parameters:
  str - the specified String
Parameters:
  beginIndex - the initial offset of str
Parameters:
  limit - the end offset of str
Parameters:
  frc - the specified FontRenderContext a Rectangle2D that is the bounding box of thespecified String in the specifiedFontRenderContext.
throws:
  IndexOutOfBoundsException - if beginIndex is less than zero, or limit is greater than thelength of str, or beginIndexis greater than limit.
See Also:   FontRenderContext
See Also:   Font.createGlyphVector
since:
   1.2

Note: The returned bounds is in baseline-relative coordinates (see java.awt.Font class notes ).
Parameters:
  chars - an array of characters
Parameters:
  beginIndex - the initial offset in the array ofcharacters
Parameters:
  limit - the end offset in the array of characters
Parameters:
  frc - the specified FontRenderContext a Rectangle2D that is the bounding box of thespecified array of characters in the specifiedFontRenderContext.
throws:
  IndexOutOfBoundsException - if beginIndex is less than zero, or limit is greater than thelength of chars, or beginIndexis greater than limit.
See Also:   FontRenderContext
See Also:   Font.createGlyphVector
since:
   1.2

Note: The returned bounds is in baseline-relative coordinates (see java.awt.Font class notes ).
Parameters:
  ci - the specified CharacterIterator
Parameters:
  beginIndex - the initial offset in ci
Parameters:
  limit - the end offset in ci
Parameters:
  frc - the specified FontRenderContext a Rectangle2D that is the bounding box of thecharacters indexed in the specified CharacterIteratorin the specified FontRenderContext.
See Also:   FontRenderContext
See Also:   Font.createGlyphVector
since:
   1.2
throws:
  IndexOutOfBoundsException - if beginIndex isless than the start index of ci, or limit is greater than the end index of ci, or beginIndex is greater than limit

Typically, fonts will not be transformed. Clients generally should call Font.isTransformed first, and only call this method if isTransformed returns true. an AffineTransform object representing thetransform attribute of this Font object.

Layout requires bidi analysis, as performed by Bidi, and should only be performed on text that has a uniform direction. The direction is indicated in the flags parameter,by using LAYOUT_RIGHT_TO_LEFT to indicate a right-to-left (Arabic and Hebrew) run direction, or LAYOUT_LEFT_TO_RIGHT to indicate a left-to-right (English) run direction.

In addition, some operations, such as Arabic shaping, require context, so that the characters at the start and limit can have the proper shapes. Sometimes the data in the buffer outside the provided range does not have valid data. The values LAYOUT_NO_START_CONTEXT and LAYOUT_NO_LIMIT_CONTEXT can be added to the flags parameter to indicate that the text before start, or after limit, respectively, should not be examined for context.

All other values for the flags parameter are reserved.
Parameters:
  frc - the specified FontRenderContext
Parameters:
  text - the text to layout
Parameters:
  start - the start of the text to use for the GlyphVector
Parameters:
  limit - the limit of the text to use for the GlyphVector
Parameters:
  flags - control flags as described above a new GlyphVector representing the text betweenstart and limit, with glyphs chosen and positioned so as to best represent the text
throws:
  ArrayIndexOutOfBoundsException - if start or limit is out of bounds
See Also:   java.text.Bidi
See Also:   Font.LAYOUT_LEFT_TO_RIGHT
See Also:   Font.LAYOUT_RIGHT_TO_LEFT
See Also:   Font.LAYOUT_NO_START_CONTEXT
See Also:   Font.LAYOUT_NO_LIMIT_CONTEXT
since:
   1.4