Class PDFFont

  • All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    OpenTypeFont, StandardCJKFont, StandardFont, Type1Font, Type3Font

    public abstract class PDFFont
    extends java.lang.Object

    The PDFFont is the abstract superclass for all Fonts in a PDF document. It defines properties which are common to all fonts, regardless of writing direction.

    Since:
    1.0
    See Also:
    PDFStyle, LayoutBox
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.lang.Object clone()  
      abstract float getAscender()
      Get the Ascender for the font (the maximum height above the baseline the font extends), as a proportion of the point size.
      java.lang.String[] getAvailableFeatures()
      Return the list of available features for this font.
      java.lang.String getBaseName()
      Return the Base Font Name for this font.
      float getBottom​(java.lang.String s)
      Get the bottom-most Y co-ordinate if this String was rendered in 1 point high text at position (0,0)
      abstract float getCapHeight()
      Get the Cap-Height of the font - normally the height of an upper-case 'O' character
      int getCharWidth​(char c)
      Return the width of the specified character in millipoints if the font size was 1 point.
      int getCharWidth​(int codepoint)
      Return the width of the specified character in millipoints if the font size was 1 point.
      abstract float getDefaultLeading()
      Get the default leading for this font - the preferred distance between two successive baselines of text.
      abstract java.util.BitSet getDefinedCodepoints()
      Return read-only BitSet containing all the Unicode codepoints defined in this font
      abstract float getDescender()
      Get the Descender for the font (the maximum height below the baseline the font extends), as a proportion of the point size.
      int getFeature​(java.lang.String feature)
      Returns whether the specified feature is currently set for this font.
      int getKerning​(char c1, char c2)
      Get the horizontal character-to-character (or "pair-wise") kerning in this font for the specified characters, in millipoints.
      int getKerning​(int codepoint1, int codepoint2)
      Get the horizontal character-to-character (or "pair-wise") kerning in this font for the specified characters, in millipoints.
      float getLeft​(java.lang.String s)
      Get the left-most X co-ordinate if this String was rendered in 1 point high text at position (0,0)
      java.io.Reader getMetaData()
      Return any XML metadata associated with this object.
      float getRight​(java.lang.String s)
      Get the right-most X co-ordinate if this String was rendered in 1 point high text at position (0,0).
      abstract float getStrikeoutPosition()
      Get the strikeout position, as a proportion of the font size.
      abstract float getStrikeoutThickness()
      Get the strikeout thickness, as a proportion of the font size.
      abstract float getSubscriptPosition()
      Get the recommended position of a sub-script version of this font, as a proportion of the sub-scripted font size.
      abstract float getSubscriptSize()
      Get the recommended size of a super/sub script version of this font, as a proportion of the normal font size.
      abstract float getSuperscriptPosition()
      Get the recommended position of a super-script version of this font, as a proportion of the sub-scripted font size.
      float getTop​(java.lang.String s)
      Get the top-most Y co-ordinate if this String was rendered in 1 point high text at position (0,0)
      abstract float getUnderlinePosition()
      Get the underline position, as a proportion of the font size.
      abstract float getUnderlineThickness()
      Get the underline thickness, as a proportion of the font size.
      abstract float getXHeight()
      Get the X-Height of the font - normally the height of a lower-case 'x' character.
      XMP getXMP()
      Return an XMP Metadata object representing any XML metadata associated with this object
      boolean hasFeature​(java.lang.String feature)
      Return true if the font contains the specified feature
      abstract boolean isBold()
      Return true if the font is bold
      boolean isDefined​(char c)
      Return true if the specified Unicode character is defined in the font.
      boolean isDefined​(int codepoint)
      Return true if the specified Unicode character is defined in the font.
      boolean isEmbedded()
      Return true if this font is Embedded
      boolean isHorizontal()
      Return true if the specified font is written Left-to-Right or Right-to-Left.
      abstract boolean isItalic()
      Return true if the font is italic
      abstract boolean isMonospace()
      Return true if every character has the same width (like Courier), false if every character is potentially a different width (like Times-Roman)
      abstract boolean isSerif()
      Return true if the font is serif
      boolean isSubset()
      Return true if this font is Subset
      void putLiteral​(java.lang.String key, java.lang.String tokens)
      Put a literal token sequnce.
      void setFeature​(java.lang.String feature, boolean on)
      Set or clear an optional feature on a font.
      void setFeature​(java.lang.String feature, int value)
      Set or clear an optional feature on a font.
      void setMetaData​(java.lang.String metadata)
      Set the XML metadata associated with this object.
      java.lang.String toString()  
      PDFFont versionBold()
      Return a bold version of the current font, if available.
      PDFFont versionItalic()
      Return an italic version of the current font, if available.
      PDFFont versionNonBold()
      Return a non-bold version of the current font, if available.
      PDFFont versionNonItalic()
      Return a non-italic version of the current font, if available.
      PDFFont versionRegular()
      Return a non-bold, non-italic version of the current font, if available.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • clone

        protected java.lang.Object clone()
      • getLeft

        public final float getLeft​(java.lang.String s)
        Get the left-most X co-ordinate if this String was rendered in 1 point high text at position (0,0)
      • getTop

        public final float getTop​(java.lang.String s)
        Get the top-most Y co-ordinate if this String was rendered in 1 point high text at position (0,0)
      • getBottom

        public final float getBottom​(java.lang.String s)
        Get the bottom-most Y co-ordinate if this String was rendered in 1 point high text at position (0,0)
      • getRight

        public float getRight​(java.lang.String s)
        Get the right-most X co-ordinate if this String was rendered in 1 point high text at position (0,0). This method will make it's calculation based on the features set on this font: the PDFStyle.getTextLength(java.lang.String) method can be used to perform the same calculation based on the values set in the style.
      • isItalic

        public abstract boolean isItalic()
        Return true if the font is italic
        Since:
        2.18
      • isBold

        public abstract boolean isBold()
        Return true if the font is bold
        Since:
        2.18
      • isSerif

        public abstract boolean isSerif()
        Return true if the font is serif
        Since:
        2.18
      • isDefined

        public final boolean isDefined​(char c)
        Return true if the specified Unicode character is defined in the font.
      • isDefined

        public boolean isDefined​(int codepoint)
        Return true if the specified Unicode character is defined in the font. This method is identical to isDefined(char) but takes an int, to cater for the new Unicode 4.0 codepoints added in Java 1.5.
        Parameters:
        codepoint - a Unicode codepoint between U+0000 and U+10FFFD
        Since:
        2.2.6
      • getCharWidth

        public final int getCharWidth​(char c)
        Return the width of the specified character in millipoints if the font size was 1 point.
        Since:
        1.2
      • getCharWidth

        public int getCharWidth​(int codepoint)
        Return the width of the specified character in millipoints if the font size was 1 point. This method is identical to the getCharWidth(char) method but takes an int to cater for the new Unicode 4.0 codepoints added in Java 1.5.
        Parameters:
        codepoint - a Unicode codepoint between U+0000 and U+10FFFD
        Since:
        2.2.6
      • getBaseName

        public java.lang.String getBaseName()
        Return the Base Font Name for this font.
      • getKerning

        public final int getKerning​(char c1,
                                    char c2)
        Get the horizontal character-to-character (or "pair-wise") kerning in this font for the specified characters, in millipoints. This is the distance to move the text cursor left after drawing character c1 in order to correctly position character c2. For many fonts and combinations of characters, this returns zero.
        Since:
        1.1.14
        See Also:
        PDFStyle.setTrackKerning(float)
      • getKerning

        public int getKerning​(int codepoint1,
                              int codepoint2)
        Get the horizontal character-to-character (or "pair-wise") kerning in this font for the specified characters, in millipoints. This method is identical to getKerning(char,char) but takes ints, to handle the new Unicode 4.0 characters defined in Java 1.5
        Parameters:
        codepoint1 - a Unicode codepoint between U+0000 and U+10FFFD
        codepoint2 - a Unicode codepoint between U+0000 and U+10FFFD
        Since:
        2.2.6
      • isHorizontal

        public boolean isHorizontal()
        Return true if the specified font is written Left-to-Right or Right-to-Left.
      • isMonospace

        public abstract boolean isMonospace()
        Return true if every character has the same width (like Courier), false if every character is potentially a different width (like Times-Roman)
        Since:
        1.1.23
      • getAscender

        public abstract float getAscender()
        Get the Ascender for the font (the maximum height above the baseline the font extends), as a proportion of the point size. The exact source of of this value is undefined except for OpenTypeFonts, where it comes from the "hhea.ascender" value normally, or the from "OS2.sTypoAscender" flag if the USE_TYPO_METRICS flag is set.
        Since:
        1.1, with source of value clarified in 2.23
      • getDescender

        public abstract float getDescender()
        Get the Descender for the font (the maximum height below the baseline the font extends), as a proportion of the point size. The returned value is usually negative. The exact source of this value is undefined except for OpenTypeFonts, where it comes from the "hhea.descender" value normally, or the from "OS2.sTypoDescender" flag if the USE_TYPO_METRICS flag is set.
        Since:
        1.1, with source of value clarified in 2.23
      • getDefaultLeading

        public abstract float getDefaultLeading()

        Get the default leading for this font - the preferred distance between two successive baselines of text. Values are a ratio of the font size, and are typically between 1 and 1.3

        Note that the values of the different spacing-between-lines methods have changed - in versions 1.0.4 and earlier this routine normally returned 1 and the spacing was set by the PDFStyle.setTextLineSpacing(float) method. Since 1.1, the values for these two methods are effectively reversed. See the relevant method comments in the PDFStyle class for more information.

      • getUnderlineThickness

        public abstract float getUnderlineThickness()
        Get the underline thickness, as a proportion of the font size.
        Since:
        1.1
      • getUnderlinePosition

        public abstract float getUnderlinePosition()
        Get the underline position, as a proportion of the font size. Like the getDescender() method, the returned value is almost always negative, indicating below the baseline. The distance is from the baseline to the center of the underline.
        Since:
        1.1
      • getStrikeoutThickness

        public abstract float getStrikeoutThickness()
        Get the strikeout thickness, as a proportion of the font size.
        Since:
        1.1
      • getStrikeoutPosition

        public abstract float getStrikeoutPosition()
        Get the strikeout position, as a proportion of the font size. The value is the distance from the baseline to the center of the strikeout, and shuold be positive.
        Since:
        1.1
      • getSubscriptSize

        public abstract float getSubscriptSize()

        Get the recommended size of a super/sub script version of this font, as a proportion of the normal font size. Typical value is around 0.6.

        For some fonts (like CJK or barcode fonts) where there is no concept of super or subscript, this value is entirely arbitrary.

        Since:
        1.1
      • getSuperscriptPosition

        public abstract float getSuperscriptPosition()

        Get the recommended position of a super-script version of this font, as a proportion of the sub-scripted font size. Value is always positive.

        For some fonts (like CJK or barcode fonts) where there is no concept of super or subscript, this value is entirely arbitrary.

        Since:
        1.1
      • getSubscriptPosition

        public abstract float getSubscriptPosition()

        Get the recommended position of a sub-script version of this font, as a proportion of the sub-scripted font size. Value is almost always zero or negative.

        For some fonts (like CJK or barcode fonts) where there is no concept of super or subscript, this value is entirely arbitrary.

        Since:
        1.1
      • getXHeight

        public abstract float getXHeight()
        Get the X-Height of the font - normally the height of a lower-case 'x' character.
        Since:
        2.11.18
      • getCapHeight

        public abstract float getCapHeight()
        Get the Cap-Height of the font - normally the height of an upper-case 'O' character
        Since:
        2.22.1
      • isEmbedded

        public boolean isEmbedded()
        Return true if this font is Embedded
        Since:
        2.24
      • setFeature

        public void setFeature​(java.lang.String feature,
                               int value)

        Set or clear an optional feature on a font.

        For most fonts, the only possible features are:

        • "latinligatures", which controls the use of ligatures for "fi", "fl" and so on (defaults to on)
        • "kerning" to turn on or off the standard inter-character kerning for fonts (defaults to on)
        • "requote", to substitute typographically-correct quotes for plain ones.
        • "italic", to slant text at 17° to synthesize an italic font (new in 2.22)
        • "smallcaps", to synthesize small-caps in the font (new in 2.22). For more control, set a value from 2..100 to represent the percentage of the full font size
        • "kashida", to allow arabic glyphs in this font to be justified with kashida justification. On by default (new in 2.23.4)
        • "implied" determines how the text in a structured PDF is stored. If "implied" is on, then the value of the content is derived from the glyphs. If false, it's encoded explicitly if required, which is necessary to extract text that is shaped, like arabic or hindi. The only time you would turn this flag on is if you were creating a document in Arabic, Hindi or similar and reducing the filesize was more important than being able to extract text. The default is off (since 2.23.2)
        • "synthesize-spaces", to synthesize the various Unicode spaces (if they're unavailable in this font) with a regular space and appropriate kerning (new in 2.23.6)
        • "synthesize-hyphens", to synthesize U+2010 and U+2011 with a standard ASCII hyphen if they're unavailable in this font (new in 2.23.6)
        • "superscript", to synthesize superscript positioning like the "sups" OpenType features new in 2.26.5)
        • "subscript", to synthesize subscript positioning like the "subs" OpenType features new in 2.26.5)

        Some OpenType fonts have GPOS and GSUB tables which can be used to modify the glyphs that are displayed. This is required to display some languages correctly.

        To enable this type of glyph shaping, the font must be created using a 2-byte encoding and the "opentype" feature must first be set. This will cause the default set of OpenType features to be used for layout. The full list of features available in the font can be seen by calling the getAvailableFeatures() method (go here for their explanations), and individual features may then be turned on or off as required.

        Features that are required for correct layout (the case for Indic and Arabic scripts) will be selected by default when the "opentype" feature is set.

        The value parameter is typically just 0 to turn the feature off, non-zero (but traditinally 1) to turn it on. However some features do check the value of this; for example, "opentype.salt" and "opentype.swsh" will use this value to choose between the various alternates on offer. A value greater than the number of options available will have the same effect as a value of 0.

        By default, OpenType layout is not used, as it is considerably slower. When it is used the "latinligatures" feature becomes a no-op, as ligatures should be applied using these tables (typically via the "opentype.dlig" feature). The langauge of the Locale can affect which operations are run, so this should be set with care.

        Lastly, for OpenType fonts the "correctleading" feature can be set to use the correct calculation for getDefaultLeading() rather than the one originally used in the PDF Library. For many fonts the two calculations will give similar, often identical results, but for some fonts it won't so we can't change this calculation by default without forcing a re-layout of many existing documents. However we recommend setting this feature for all new documents. The initial value of this feature can be set to true by setting the OpenTypeCorrectLeading property

        Since 2.14.1 you can set these features on the PDFStyle referencing this font by calling the PDFStyle.setFontFeature(java.lang.String, boolean) method. This is preferable to calling this method, as it allows different features to be used on the font within the same LayoutBox. This method can still be used to set a font-wide default value for each feature.

        Parameters:
        feature - the feature name
        value - the value, which is 0 for off or any other value for on - for most features the value is ignored.
        Since:
        2.22
      • hasFeature

        public boolean hasFeature​(java.lang.String feature)
        Return true if the font contains the specified feature
        Since:
        2.22
      • getFeature

        public int getFeature​(java.lang.String feature)
        Returns whether the specified feature is currently set for this font. A value of 0 means not set, any other value means it is set - for most features that is enough, but a few will make use of the actual value to select between different variations of the feature, say for swash capitals. This method provides a default value for the value returned by PDFStyle.getFontFeature(java.lang.String).
        Parameters:
        feature - the feature name
        Returns:
        0 for off, or a value greater-than-or-equal to 1 for on.
        Since:
        2.11.23 (prior to 2.22 this method returned a boolean)
        See Also:
        PDFStyle.getFontFeature(java.lang.String)
      • versionItalic

        public PDFFont versionItalic()
        Return an italic version of the current font, if available. By default this just returns this font.
        Since:
        2.11
      • versionBold

        public PDFFont versionBold()
        Return a bold version of the current font, if available. By default this just returns this font.
        Since:
        2.11
      • versionNonBold

        public PDFFont versionNonBold()
        Return a non-bold version of the current font, if available. By default this just returns this font.
        Since:
        2.11
      • versionNonItalic

        public PDFFont versionNonItalic()
        Return a non-italic version of the current font, if available. By default this just returns this font.
        Since:
        2.11
      • versionRegular

        public PDFFont versionRegular()
        Return a non-bold, non-italic version of the current font, if available. By default this just returns this font.
        Since:
        2.11
      • setMetaData

        public void setMetaData​(java.lang.String metadata)

        Set the XML metadata associated with this object. Since 2.26 this method calls getXMP().read(new StringReader(xmldata == null ? "" : xmldata)). We strongly recommend using the getXMP() method and modifying the XMP directly rather than using this method.

        Note for OpenType WOFF and WOFF2 fonts, the MetaData is transformed from the schema described in https://www.w3.org/TR/WOFF/#Metadata to an approximation of the same schema within the limitations of XMP.

        Parameters:
        metadata - the XML data to embed into the document, or null to clear any existing metadata. No validation is performed on this input.
        Since:
        2.24.3
      • getXMP

        public XMP getXMP()
        Return an XMP Metadata object representing any XML metadata associated with this object
        Returns:
        the XMP, which may be empty or invalid but wil never be null
        Since:
        2.26
      • getMetaData

        public java.io.Reader getMetaData()
                                   throws java.io.IOException

        Return any XML metadata associated with this object.

        Since 2.26 this simply returns getXMP().isEmpty() ? null : new StringReader(getXMP().toString()). It is strongly recommended that any code migrates to using the getXMP() method.

        Since 2.24.3, the returned type is guaranteed to hava a toString() method that will return the Metadata as a String.

        Returns:
        a Reader containing the source of the XML or null if no metadata is available.
        Throws:
        java.io.IOException - if the metadata can't be extracted
        Since:
        2.24.3
      • isSubset

        public boolean isSubset()
        Return true if this font is Subset
        Since:
        2.24
      • getDefinedCodepoints

        public abstract java.util.BitSet getDefinedCodepoints()
        Return read-only BitSet containing all the Unicode codepoints defined in this font
        Since:
        2.23.2
      • toString

        public java.lang.String toString()
      • putLiteral

        public void putLiteral​(java.lang.String key,
                               java.lang.String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.