.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "TextBlock 3pm" .TH TextBlock 3pm "2021-01-01" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PostScript::TextBlock \- An object that may be used to construct a block of text in PostScript. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use PostScript::TextBlock; \& my $tb = new PostScript::TextBlock; \& $tb\->addText( text => "Hullaballo in Hoosick Falls.\en", \& font => \*(AqCenturySchL\-Ital\*(Aq, \& size => 24, \& leading => 26 \& ); \& $tb\->addText( text => "by Charba Gaspee.\en", \& font => \*(AqURWGothicL\-Demi\*(Aq, \& size => 12, \& leading => 14 \& ); \& print \*(AqThere are \*(Aq.$tb\->numElements.\*(Aq elements in this object.\*(Aq; \& open OUT, \*(Aq>psoutput.ps\*(Aq; \& my ($code, $remainder) = $tb\->Write(572, 752, 20, 772); \& print OUT $code; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The PostScript::TextBlock module implements four methods: .IP "\fBnew()\fR \- Create a New PostScript::TextBlock object" 3 .IX Item "new() - Create a New PostScript::TextBlock object" This method instantiates a new object of class PostScript::TextBlock. .IP "addText( text=>$text, [ font=>$font ], [ size=>$size ], [ leading=>$leading ] )" 3 .IX Item "addText( text=>$text, [ font=>$font ], [ size=>$size ], [ leading=>$leading ] )" The \fBaddText()\fR method will add a new 'text element' to the TextBlock object. A \&'text element' can be thought of as a section of text that has the same characteristics, i.e. all the characters are the same font, size and leading. this representation allows you to include text rendered in multiple fonts at multiple sizes within the same text block by including them as separate elements. .Sp This method takes up to four attributes (note that the '[]' brackets above indicate that a parameter is optional, not an array reference): .Sp text The text attribute is required, though nothing bad will happen if you leave it out. This is simply the text to be rendered in the text block. Line breaks may be inserted by including a newline \*(L"\en\*(R". .Sp font The font attribute is a string indicating the name of the font to be used to render this element. The \s-1PS\s0 package uses an internal description of the Font Metrics of various fonts that is contained in the PostScript::Metrics module. As of this writing, the PostScript::Metrics module supports the following fonts (basically, the default GhostScript fonts that have \s-1AFM\s0 files): .Sp NimbusSanL-ReguCond URWGothicL-Book CenturySchL-Bold CharterBT-Italic URWBookmanL-Ligh CharterBT-BoldItalic NimbusRomNo9L\-ReguItal URWBookmanL-DemiBoldItal CharterBT-Roman NimbusMonL-ReguObli NimbusSanL-ReguCondItal CenturySchL-Ital CenturySchL-BoldItal URWPalladioL-Roma URWBookmanL-LighItal CharterBT-Bold NimbusSanL-BoldCond NimbusMonL-BoldObli NimbusSanL-BoldCondItal URWGothicL-DemiObli NimbusSanL-Regu URWPalladioL-Bold NimbusMonL-Regu NimbusSanL-ReguItal URWGothicL-BookObli URWPalladioL-Ital .Sp You can get a list of the currently supported fonts with the following: .Sp .Vb 2 \& use PostScript::Metrics; \& @okfonts = PostScript::Metrics\->listFonts(); .Ve .Sp \&\s-1NOTE:\s0 The font must be available to the PostScript interpreter that is used to render the page described by the program. If the interpreter cannot load the font, it will ususally attempt to substitute a similar font. If a font is substituted with a font with different metrics, lines of text may overrun the right margin of the text block. You have been warned. .Sp It is very easy to create stylesheets for a document: .Sp .Vb 5 \& # Define the styles \& # \& %body = ( font => \*(AqURWGothicL\-DemiObli\*(Aq, size => 12, leading => 16 ); \& %head1 = ( font => \*(AqNimbusSanL\-BoldCond\*(Aq, size => 24, leading => 36 ); \& %head2 = ( font => \*(AqNimbusSanL\-BoldCond\*(Aq, size => 18, leading => 30 ); \& \& # Use them where appropriate \& # \& $tb\->addText(text => "Chapter 10\en", %head1); \& $tb\->addText(text => "Spokane Sam and His Spongepants\en", %head2); \& $tb\->addText(text => "It was a dark and stormy night and Spokane Sam\e\*(Aqs \& Spongepants were thirsty...", %body); .Ve .IP "\fBnumElements()\fR" 3 .IX Item "numElements()" Returns the number of elements in the text block object. An 'element' is created each time the \fBaddText()\fR method is called. .ie n .IP "Write( $width, $height, $xoffset, $yoffset )" 3 .el .IP "Write( \f(CW$width\fR, \f(CW$height\fR, \f(CW$xoffset\fR, \f(CW$yoffset\fR )" 3 .IX Item "Write( $width, $height, $xoffset, $yoffset )" The \fBWrite()\fR method will generate the PostScript code that will render the text on a page when passed to a PostScript interpreter such as Ghostscript. The four parameters are expressed in points (1/72 inch) and indicate the width and height of the box within which the text should be printed, and the x and y offset of the upper left corner of this box. .Sp Important: PostScript defines the origin (0,0) as the lower left corner of the page! This *will* mess you up. .Sp Standard page sizes in points are: .Sp .Vb 10 \& Paper Size Width, Height (in points) \& ......................... ......................... \& Letter 612, 792 \& Legal 612, 1008 \& Ledger 1224, 792 \& Tabloid 792, 1224 \& A0 2384, 3370 \& A1 1684, 2384 \& A2 1191, 1684 \& A3 842, 1191 \& A4 595, 842 \& A5 420, 595 \& A6 297, 420 \& A7 210, 297 \& A8 148, 210 \& A9 105, 148 \& B0 2920, 4127 \& B1 2064, 2920 \& B2 1460, 2064 \& B3 1032, 1460 \& B4 729, 1032 \& B5 516, 729 \& B6 363, 516 \& B7 258, 363 \& B8 181, 258 \& B9 127, 181 \& B10 91, 127 \& #10 Envelope 297, 684 \& C5 Envelope 461, 648 \& DL Envelope 312, 624 \& Folio 595, 935 \& Executive 522, 756 .Ve .Sp The \fBwrite()\fR method returns two values: a string consisting of the PostScript code (suitable for printing to a file), and a TextBlock object containing the elements (and partial elements) that did not fit within the specified area, if any. If the entire text block fits with the area, the remainder will be undef. The remainder can be used to layout multiple pages and columns, etc. in a similar manner to most modern desktop publishing programs. In general, the \&\fBwrite()\fR method should be called as in the following, which writes the PostScript code to a file called 'psoutput.ps': .Sp .Vb 3 \& open OUT, \*(Aq>psoutput.ps\*(Aq; \& my ($code, $remainder) = $tb\->Write(572, 752, 20, 772); \& print OUT $code; .Ve .Sp To print an entire text block that spans multiple pages, you could do something like this: .Sp (add enough text to the text block first..) .Sp .Vb 2 \& open OUT, \*(Aq>psoutput.ps\*(Aq; \& my $pages = 1; \& \& # Create the first page \& # \& my ($code, $remainder) = $tb\->Write(572, 752, 20, 772); \& print OUT "%%Page:$pages\en"; # this is required by the Adobe \& # Document Structuring Conventions \& print OUT $code; \& print OUT "showpage\en"; \& \& # Print the rest of the pages, if any \& # \& while ($remainder\->numElements) { \& $pages++; \& print OUT "%%Page:$pages\en"; \& ($code, $remainder) = $remainder\->Write(572, 752, 20, 772); \& print OUT $code; \& print OUT "showpage\en"; \& } .Ve .Sp However, if you use the PostScript::Document module to construct generic multi-page PostScript documents, you don't have to worry about this. .SH "A NOTE ABOUT FONT METRICS" .IX Header "A NOTE ABOUT FONT METRICS" The \fBwrite()\fR method uses the module PostScript::Metrics to determine the width of each character; widths vary from font to font and character to character. If you were writing a stright PostScript program, you would let the PostScript interpreter do this for you, but in the case of this program, we need to know the width of each character in a font within the Perl script. The PostScript::Metrics module contains the font metrics (i.e., a list containing the width of each character in the font) for a bunch of fonts that are listed above under the description of the \fBaddText()\fR method. This set started with the metrics for all of the default fonts with \s-1AFM\s0 files that came with GhostScript. It is slowly growing as more fonts are mapped. To add support for a new font, you must create the array with the metrics for that font and add it to the PostScript::Metrics module. For a font with an \s-1AFM\s0 file, the \s-1AFM\s0 file can be parsed with Gisle Aas' Font::AFM module, available on \s-1CPAN.\s0 .PP Please send all PostScript::Metrics patches to the author at shawn@as220.org. .SH "TODO" .IX Header "TODO" * better compliance with Adobe's Document Structuring Conventions * more font metrics descriptions * make font loading code smarter and more efficient for the interpreter * support a larger character set * it would be nice to add more functions, e.g. \fBClone()\fR * how about settable defaults? .SH "AUTHOR" .IX Header "AUTHOR" Copyright 1998, 1999 Shawn Wallace. All rights reserved. .PP Contact the author: shawn@as220.org http://www.as220.org/shawn .PP Portions of code contributed by Dan Smeltz. .PP This is free software. You may use, modify, and redistribute this package under the same terms as Perl itself. .PP PostScript is a trademark of Adobe Systems.