The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PostScript-Font-1.10.03
River stage zero No dependents
++
/ PostScript::BasicTypesetter

NAME

PostScript::BasicTypesetter - Module for basic typesetting

SYNOPSIS

    # Create an object directly from the AFM file.
    my $ts = new PostScript::BasicTypesetter("/usr/share/metrics/times.afm");

    # Alternatively, use the Unix PostScript Resources.
    my $psres = new PostScript::Resources;
    my $m = new PostScript::FontMetrics($psres->FontAFM("Times-Roman"));
    # The metrics object can now be shared between typesetters.
    my $ts = new PostScript::BasicTypesetter($m);

    # Re-encode the font to use ISO Latin-1 encoding.
    # The resultant font will be named Times-Romand-Latin1.
    $ts->reencode("ISOLatin1Encoding", "Latin1");

    # Set the current font size to 10 points.
    $ts->fontsize(10);
    # Set the lineskip to 12 points.
    $ts->lineskip(12);

    # Add to the PostScript preamble:
    print $ts->ps_reencodesub;
    print $ts->ps_preamble;

    # Add to the PostScript Setup:
    print $ts->ps_reencode;

    # To typeset a box of text at $x, $y, width $w:
    print $ts->ps_textbox($x,$y,$w,$str);

DESCRIPTION

PostScript::BasicTypesetter is an experimental module to facilitate PostScript based typesetting. Its principal reason for existance is that it properly uses font metrics for precise typesetting and kerning.

A BasicTypesetter object maintains font information (name, encoding, and size) that can be used to typeset texts. Every operation invoked on a typesetter object is executed w.r.t. the current values for the font, encoding and size. However, once the PostScript preamble has been constructed, the font name and encoding should not be changed anymore.

CONSTRUCTOR

new

Example:

    $ts = new PostScript::BasicTypesetter ($arg);

This constructs a new typesetter object.

The argument may be a PostScript::FontMetrics object, or the name of a valid font metrics file.

If the argument refers to a FontMetrics object, this object will be associated with the Typesetter object, and it can be shared between Typesetters. If it is a file name, a private FontMetrics object will be created.

The new typesetter gets a default value of 10 for the font size, and 12 for the lineskip.

clone

Example:

    $newts = $ts->clone;        # identical
    $ts12 = $ts->clone(12);     # identical, but font size 12

Creates a new typesetter with identical contents and shared metrics. If additional arguments are present, these are passed to the fontsize method.

INSTANCE METHODS

fontname

Example:

    $name = $ts->fontname;

This routine returns the name of the font, which may differ from the real font name if the font has been reencoded. For example, re-encoding Times-Roman (the real font name) may result in a font that will be known as Times-Roman-Latin1.

real_fontname

Example:

    $name = $ts->real_fontname;

This routine returns the real name of the font.

metrics

    $metrics = $ts->metrics;

This routine returns provides access to the associated PostScript::FontMetrics object.

reencode

Example:

    $ts->reeencode ($enc, $tag, $changes);

This routine re-encodes the font associated with this typesetter according to the specified encoding, and optionally modifies the resultant encoding according to the changes vector. The new font will get the name of the original font, with -tag appended.

$baseenc must be either "StandardEncoding" (default), "ISOLatin1Encoding", or "ISOLatin9Encoding".

$changes, if specified, must be a reference to a hash. For each key of the hash, its ordinal value in the resultant encoding will be set to its value, which must be a valid glyph name.

For example, to re-encode a font to ISO-Latin1 and add the glyph ellipsis to location 0200 (octal), the following call can be used:

    $ts->reencode ("ISOLatin1Encoding", "Latin1", {"\200" => "ellipsis"});

WARNING: reencode affects the FontMetrics object that is associated with this Typesetter. When FontMetrics objects are shared between Typesetters, Calling reencode on one of the Typesetters will affect the other Typesetters as well. This is deliberate.

fontsize

Example:

    $ts->fontsize(12, 15);
    $size = $ts->fontsize;

Sets or gets the current font size. When setting, the (optional) second argument can be used to simultaneously set the lineskip.

lineskip

Example:

    $ts->lineskip(15);
    $skip = $ts->lineskip;

Sets or gets the current lineskip.

hyphens

Example:

    $ts->hyphens('-/');
    $hyphens = $ts->hyphens;

Sets or gets the current string of characters considered to be hyphens (points words can be split on a line break). Disabled by default.

linebreak

Example:

    $ts->linebreak(\&break);

Sets or gets the code to be executed when ps_textbox advances due to a line break. The subroutine is called as a method with a reference to the current vertical position and should adjust the value. The routine should return PostScript instructions that are necessary for the line break, if any.

color

Example:

    $ts->color([1,0,0]);   # RGB vector
    $color = $ts->color;

Sets or gets the current color. The argument must be either a 3-element vector for RGB color coordinates, or an 4-element vector for CMYK coordinates. In either case, each of the coordinates must be a number between 0 and 1, inclusive.

IMPORTANT: There's no such thing as a default color. Typesetters that do not have a color set will print in the current color. Use ps_setcolor, described below, to explicitly control the color of the output.

stringwidth

Example:

    $width = $ts->stringwidth($str);

Returns the width of the string for the current font and size, with kerning information applied.

tjvector

Example:

    $vec = $ts->tjvector($str);

Returns the typesetting vector for the string, with kerning information applied. This vector can be passed to the ps_tj method.

textwidth

Example:

    $width = $ts->textwidth;

Returns the width of the last textbox set by this typesetter.

char

Example:

    $char = $ts->char("quotedblleft");

Returns a one-character string that will render as the named glyph in the current encoding, or undef if this glyph is currently not encoded.

This is a convenience method that calls the char method of the associated FontMetrics object.

ps_preamble

Example:

    print $ts->ps_preamble;

Produces the PostScript code for the preamble.

To be used while constructing the PostScript preamble.

ps_reencodesub

Example:

    print $ts->ps_reencodesub (name => "ReEncode");

Produces the PostScript code to define a PostScript routine to reencode the fonts.

To be used while constructing the PostScript preamble.

Attributes:

name

The name prefix of the subroutine. If the reencoding vector is embedded (see below), this is the actual name for the routine. Otherwise, the actual name for the routine is prefixSub, and the vector will be named prefixVec.

base

The base encoding. This should be either StandardEncoding, ISOLatin1Encodingm or ISOLatin9Encoding. It defaults to the value supplied with a preceding reencode call, or StandardEncoding if no such call has been issued.

vec

If this is "embedded" (default), the reencoding vector will be part of the subroutine. Otherwise it will be defined separately.

ps_reencode

Example:

    print $ts->ps_reencode (name => "ReEncode");

Produces the PostScript code to reencode a font. Nothing is produced if the font has not been re-encoded.

To be used while constructiong the PostScript Setup section.

Attributes:

name

The name prefix of the subroutine. If the reencoding vector is embedded (see below), this is the actual name for the routine. Otherwise, the actual name for the routine is prefixSub, and the vector will be named prefixVec.

vec

If this is "embedded" (default), the reencoding vector will be assumed part of the subroutine. Otherwise it will be specified separately.

ps_str

Example:

    print $ts->ps_str ($str);

Produces the PostScript representation for the given string.

ps_setfont

Example:

    print $ts->ps_setfont;

Produces the PostScript code to designate the current font, size and color for PostScript.

This method keeps track of the settings, and will not produce anything if the current settings are already as requested. Hence use liberally.

Call with an explicit undef argument to flush the cache. This is only necessary when the PostScript code needs to maintain graphics state explicitly.

ps_setcolor

Example:

    print $ts->ps_setcolor([0,0,0]);

Produces the PostScript code to set the current PostScript color. If no arguments are passed, it sets the value for this typesetter.

This method keeps track of the settings, and will not produce anything if the current settings are already as requested. Hence use liberally.

Call with an explicit undef argument to flush the cache. This is only necessary when the PostScript code needs to maintain graphics state explicitly.

ps_tj

Example:

    print $ts->ps_tj ($tj);

Produces the PostScript code to print the text at the current position. The argument to this function must be the result of a call to tjvector.

ps_linebreak

Example:

    print $ts->ps_linebreak (\$y);

Produces the PostScript code to advance to the next logical line, advancing the value of $y. The default operation is to decrement $y with the value of $ts-lineskip>, but $tr-linebreak> may be called to install a different linebreak handler.

ps_textbox

Example:

    print $ts->ps_textbox ($x, $xi, $y, $w, $str, $align);

Produces the PostScript code to typeset a string, or a set of strings.

The string will be printed starting at base postion $x and $y. If the string exceeds the width $w a line wrap will occur and the ps_linebreak method of the typesetter is called.

The first line will be indented with $xi.

ps_textbox will take care of font changes and color settings, but will not affect the global settings.

If $str is a reference to an array, this array may contain a mix of strings, PostScript::BasicTypesetter objects, and array references (recursive). Each string is typeset according to the current typesetter; a typesetter object changes the current typesetter for the rest of the array. However, the linebreak handler of the initial typesetter is used for linewraps, regardless the typesetter currently in control.

$xi and/or $y may be references to the actual values. In this case, the corresponding values will be updated to reflect the value upon completion. In other words, the resulting $xi value will reflect the x-position directly after the last character of the last line. The $y value will reflect the baseline of the last line that was typeset. Using references to the actual values, series of calls to ps_textbox can be chained: each call will continue exactly where the preceding call left off. This is, of course, only useful with flush left alignment.

The method textwidth will return the actual width of the text that was set. Note that this may be larger than the specified width of the text box, when the text contains unbreakable items larger than the desired width.

Values for $align are "l" (default): flush left, "r": flush right, "c": centered, "j": justified.

NOTE: The string(s) should not contain tabs and newlines, since these may get a different meaning in the future. Currently, tabs and newlines are treated as whitespace (and mostly ignored).

EXAMPLE

    use PostScript::BasicTypesetter;

    my $tr = new PostScript::BasicTypesetter
      ("/usr/lib/ghostscript/fonts/Times-Roman");

    print STDOUT ("%!PS-Adobe-3.0\n",
                  "%%DocumentResources: font ",
                  $tr->metrics->FontName, " ",
                  "%%Pages: 1\n",
                  $tr->ps_preamble,
                  "%%EndPrologue\n",
                  "%%Page 1 1\n");

    $tr->fontsize(150, 200);
    print STDOUT ($tr->ps_textbox (mm(10), 0, mm(200), mm(180),
                                   "Perl Rules!", "c"));

    print STDOUT ("showpage\n",
                  "%%Trailer\n",
                  "%%EOF\n");

    # Convert millimeters to PostScript units.
    sub mm { ($_[0] * 720) / 254 }

SEE ALSO

PostScript::Resources and PostScript::FontMetrics.

AUTHOR

Johan Vromans, Squirrel Consultancy <jvromans@squirrel.nl>

COPYRIGHT and DISCLAIMER

This program is Copyright 2003,2000 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program 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 either the GNU General Public License or the Artistic License for more details.