|
PostScript::BasicTypesetter - Module for basic typesetting |
PostScript::BasicTypesetter - Module for basic typesetting
# 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);
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.
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.
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.
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.
Example:
$name = $ts->real_fontname;
This routine returns the real name of the font.
$metrics = $ts->metrics;
This routine returns provides access to the associated PostScript::FontMetrics object.
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.
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.
Example:
$ts->lineskip(15);
$skip = $ts->lineskip;
Sets or gets the current lineskip.
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.
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.
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.
Example:
$width = $ts->stringwidth($str);
Returns the width of the string for the current font and size, with kerning information applied.
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.
Example:
$width = $ts->textwidth;
Returns the width of the last textbox set by this typesetter.
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.
Example:
print $ts->ps_preamble;
Produces the PostScript code for the preamble.
To be used while constructing the PostScript preamble.
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:
Sub, and the
vector will be named prefixVec.
StandardEncoding,
ISOLatin1Encodingm or ISOLatin9Encoding. It defaults to the
value supplied with a preceding reencode call, or
StandardEncoding if no such call has been issued.
"embedded" (default), the reencoding vector will be part
of the subroutine. Otherwise it will be defined separately.
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:
Sub, and the
vector will be named prefixVec.
"embedded" (default), the reencoding vector will be
assumed part of the subroutine. Otherwise it will be specified
separately.
Example:
print $ts->ps_str ($str);
Produces the PostScript representation for the given string.
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.
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.
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.
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.
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).
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 }
the PostScript::Resources manpage and the PostScript::FontMetrics manpage.
Johan Vromans, Squirrel Consultancy <jvromans@squirrel.nl>
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.
|
PostScript::BasicTypesetter - Module for basic typesetting |