PDF::Builder::Resource::CIDFont::TrueType(3)

NAME
PDF::Builder::Resource::CIDFont::TrueType - TrueType (ttfont) font support

Inherits from PDF::Builder::Resource::CIDFont

Generally also usable for OTF (Open Type) fonts

METHODS

  new
    $font = PDF::Builder::Resource::CIDFont::TrueType->new($pdf, $file, %opts)

    Returns a font object for TrueType and OpenType fonts (from "ttfont()" call).

Valid Options (%opts) are:

encode
    Changes the encoding of the font from its default (WinAnsiEncoding).

    Note that for a single byte encoding (e.g., 'latin1'), you are limited to 256 characters defined for that encoding. 'automap' does not work with TrueType. If you want more characters than that, use 'utf8' encoding with a UTF-8 encoded text string.

isocmap
    Use the ISO Unicode Map instead of the default MS Unicode Map.

unicodemap
    If 1 (default), output ToUnicode CMap to permit text searches and screen readers. Set to 0 to save space by not including the ToUnicode CMap, but text searching and screen reading will not be possible.

dokern
    Enables kerning if data is available.

    "kerning" is still accepted as an (older) alternative to "dokern".

embed
    If set (non-zero), which is the default, the font (entire or subsetted) will be embedded in the PDF file. See the comments in "noembed" about the possible hazards of not embedding the font, and limitations on embedding.

    "true" (non-zero) and "false" (zero) are the values of "embed". It is possible that in the future, some non-zero values may get special meaning (such as permission flags), so it is best to use only 0 and 1 for a value.

noembed
    noembed is ignored if embed is given. "noembed" is deprecated, while "embed" (default true) is preferred.

    Disables embedding of the font file. Note that this is potentially hazardous, as the glyphs provided on the PDF reader machine may not match what was used on the PDF writer machine (the one running PDF::Builder)! If you know for sure that all PDF readers will be using the same TTF or OTF file you're using with PDF::Builder; not embedding the font may be acceptable, in return for a smaller PDF file size. Note that the Reader needs to know where to find the font file -- it can't be in any random place, but typically needs to be listed in a path that the Reader follows. Otherwise, it will be unable to render the text!

    Some additional comments on embedding font file(s) into the PDF: besides substantially increasing the size of the PDF (even if the font is subsetted, by default), PDF::Builder does not check the font file for any flags indicating font licensing issues and limitations on use. A font foundry may not permit embedding at all, may permit a subset of the font to be embedded, may permit a full font to be embedded, and may specify what can be done with an embedded font (e.g., may or may not be extracted for further use beyond displaying this one PDF). When you choose to use (and embed) a font, you should be aware of any such licensing issues.

nosubset
    Disables subsetting of a TTF/OTF font, when embedded. By default, only the glyphs used by a document are included in the file, and not the entire font. This can result in a tremendous savings in PDF file size. If you intend to allow the PDF to be edited by users, not having the entire font glyph set available may cause problems, so be aware of that (and consider using "nosubset => 1". Setting this flag to any value results in the entire font glyph set being embedded in the file. It might be a good idea to use only the value 1, in case other values are assigned roles in the future.

debug
    If set to 1 (default is 0), diagnostic information is output about the CMap processing.

usecmf
    If set to 1 (default is 0), the first priority is to make use of one of the four ".cmap" files for CJK fonts. This is the old way of processing TTF files. If, after all is said and done, a working internal CMap hasn't been found (for usecmf=>0), "ttfont()" will fall back to using a ".cmap" file if possible.

cmaps
    This flag may be set to a string listing the Platform/Encoding pairs to look for of any internal CMaps in the font file, in the desired order (highest priority first). If one list (comma and/or space-separated pairs) is given, it is used for both Windows and non-Windows platforms (on which PDF::Builder is running, not the PDF reader's). Two lists, separated by a semicolon ; may be given, with the first being used for a Windows platform and the second for non-Windows. The default list is "0/6 3/10 0/4 3/1 0/3; 0/6 0/4 3/10 0/3 3/1". Finally, instead of a P/E list, a string "find_ms" may be given to tell it to simply call the Font::TTF "find_ms()" method to find a (preferably Windows) internal CMap. "cmaps" set to 'find_ms' would emulate the old way of looking for CMaps. Symbol fonts (3/0) always use find_ms(), and the new default lookup is (if ".cmap" isn't used, see "usecmf") to try to get a match with the default list for the appropriate OS. If none can be found, find_ms() is tried, and as last resort use the ".cmap" (if available), even if "usecmf" is not 1.

  fontfile
    $font->fontfile()

    Returns font file object (' ff' element), so its methods may be invoked.

  fontobj
    $font->fontobj()

    Returns font object, so its methods and properties may be used.

  wxByCId
    $font->wxByCId($gID)

    Returns unscaled glyph width, given its glyph ID (CID).

  haveKernPairs
    $flag = $font->haveKernPairs()

    Does the font include kerning data? Invokes fontfile's haveKernPairs(). Not clear what additional optional arguments are.

  kernPairCid
    $flag = $font->kernPairCid($gID, $n)

    Returns kerning information for? Not clear what additional arguments are. Invokes fontfile's kernPairCid() method.

  subsetByCId
    $font->subsetByCId($gID)

    Invokes subsetByCId() method from fontfile() to put the glyph into the embedded font cache in the PDF.

  subvec
    $font->subvec($gID)

    (No Information) invokes fontfile's subvec() method.

  glyphNum
    $count = $font->glyphNum()

    Number of glyphs in the font.

  outobjdeep
    $font->outobjdeep()

    (No Information) output to PDF