1TextBlock(3) User Contributed Perl Documentation TextBlock(3)
2
6 PostScript::TextBlock - An object that may be used to construct a block
7 of
8 text in PostScript.
9
11 use PostScript::TextBlock;
12 my $tb = new PostScript::TextBlock;
13 $tb->addText( text => "Hullaballo in Hoosick Falls.\n",
14 font => 'CenturySchL-Ital',
15 size => 24,
16 leading => 26
17 );
18 $tb->addText( text => "by Charba Gaspee.\n",
19 font => 'URWGothicL-Demi',
20 size => 12,
21 leading => 14
22 );
23 print 'There are '.$tb->numElements.' elements in this object.';
24 open OUT, '>psoutput.ps';
25 my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
26 print OUT $code;
27
29 The PostScript::TextBlock module implements four methods:
30 new() - Create a New PostScript::TextBlock object
32 This method instantiates a new object of class Post‐
33 Script::TextBlock.
34 addText( text=>$text, [ font=>$font ], [ size=>$size ], [ lead‐
36 ing=>$leading ] )
37 The addText() method will add a new 'text element' to the TextBlock
38 object. A 'text element' can be thought of as a section of text that
39 has the same characteristics, i.e. all the characters are the same
40 font, size and leading. this representation allows you to include
41 text rendered in multiple fonts at multiple sizes within the same
42 text block by including them as separate elements.
43 This method takes up to four attributes (note that the '[]' brackets
45 above indicate that a parameter is optional, not an array refer‐
46 ence):
47 text The text attribute is required, though nothing bad will happen
49 if you leave it out. This is simply the text to be rendered in the
50 text block. Line breaks may be inserted by including a newline "\n".
51 font The font attribute is a string indicating the name of the font
53 to be used to render this element. The PS package uses an internal
54 description of the Font Metrics of various fonts that is contained
55 in the PostScript::Metrics module. As of this writing, the Post‐
56 Script::Metrics module supports the following fonts (basically, the
57 default GhostScript fonts that have AFM files):
58 NimbusSanL-ReguCond URWGothicL-Book CenturySchL-Bold
60 CharterBT-Italic URWBookmanL-Ligh CharterBT-BoldItalic Nim‐
61 busRomNo9L-ReguItal URWBookmanL-DemiBoldItal CharterBT-Roman
62 NimbusMonL-ReguObli NimbusSanL-ReguCondItal CenturySchL-Ital Cen‐
63 turySchL-BoldItal URWPalladioL-Roma URWBookmanL-LighItal
64 CharterBT-Bold NimbusSanL-BoldCond NimbusMonL-BoldObli Nimbus‐
65 SanL-BoldCondItal URWGothicL-DemiObli NimbusSanL-Regu
66 URWPalladioL-Bold NimbusMonL-Regu NimbusSanL-ReguItal URW‐
67 GothicL-BookObli URWPalladioL-Ital
68 You can get a list of the currently supported fonts with the follow‐
70 ing:
71 use PostScript::Metrics;
73 @okfonts = PostScript::Metrics->listFonts();
74 NOTE: The font must be available to the PostScript inter‐
76 preter that is used to render the page described by the
77 program. If the interpreter cannot load the font, it will
78 ususally attempt to substitute a similar font. If a font
79 is substituted with a font with different metrics, lines
80 of text may overrun the right margin of the text block.
81 You have been warned.
82 It is very easy to create stylesheets for a document:
84 # Define the styles
86 #
87 %body = ( font => 'URWGothicL-DemiObli', size => 12, leading => 16 );
88 %head1 = ( font => 'NimbusSanL-BoldCond', size => 24, leading => 36 );
89 %head2 = ( font => 'NimbusSanL-BoldCond', size => 18, leading => 30 );
90 # Use them where appropriate
92 #
93 $tb->addText(text => "Chapter 10\n", %head1);
94 $tb->addText(text => "Spokane Sam and His Spongepants\n", %head2);
95 $tb->addText(text => "It was a dark and stormy night and Spokane Sam\'s
96 Spongepants were thirsty...", %body);
97 numElements()
99 Returns the number of elements in the text block
100 object. An 'element' is created each time the addText()
101 method is called.
102 Write( $width, $height, $xoffset, $yoffset )
104 The Write() method will generate the PostScript code
105 that will render the text on a page when passed to a
106 PostScript interpreter such as Ghostscript. The four
107 parameters are expressed in points (1/72 inch) and
108 indicate the width and height of the box within which
109 the text should be printed, and the x and y offset of
110 the upper left corner of this box.
111 Important: PostScript defines the orgin (0,0) as the
113 lower left corner of the page! This *will* mess you up.
114 Standard page sizes in points are:
116 Paper Size Width, Height (in points)
118 ......................... .........................
119 Letter 612, 792
120 Legal 612, 1008
121 Ledger 1224, 792
122 Tabloid 792, 1224
123 A0 2384, 3370
124 A1 1684, 2384
125 A2 1191, 1684
126 A3 842, 1191
127 A4 595, 842
128 A5 420, 595
129 A6 297, 420
130 A7 210, 297
131 A8 148, 210
132 A9 105, 148
133 B0 2920, 4127
134 B1 2064, 2920
135 B2 1460, 2064
136 B3 1032, 1460
137 B4 729, 1032
138 B5 516, 729
139 B6 363, 516
140 B7 258, 363
141 B8 181, 258
142 B9 127, 181
143 B10 91, 127
144 #10 Envelope 297, 684
145 C5 Envelope 461, 648
146 DL Envelope 312, 624
147 Folio 595, 935
148 Executive 522, 756
149 The write() method returns two values: a string con‐
151 sisting of the PostScript code (suitable for printing
152 to a file), and a TextBlock object containing the ele‐
153 ments (and partial elements) that did not fit within
154 the specified area, if any. If the entire text block
155 fits with the area, the remainder will be undef. The
156 remainder can be used to layout multiple pages and col‐
157 umns, etc. in a similar manner to most modern desktop
158 publishing programs. In general, the write() method
159 should be called as in the following, which writes the
160 PostScript code to a file called 'psoutput.ps':
161 open OUT, '>psoutput.ps';
163 my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
164 print OUT $code;
165 To print an entire text block that spans multiple
167 pages, you could do something like this:
168 (add enough text to the text block first..)
170 open OUT, '>psoutput.ps';
172 my $pages = 1;
173 # Create the first page
175 #
176 my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
177 print OUT "%%Page:$pages\n"; # this is required by the Adobe
178 # Document Structuring Conventions
179 print OUT $code;
180 print OUT "showpage\n";
181 # Print the rest of the pages, if any
183 #
184 while ($remainder->numElements) {
185 $pages++;
186 print OUT "%%Page:$pages\n";
187 ($code, $remainder) = $remainder->Write(572, 752, 20, 772);
188 print OUT $code;
189 print OUT "showpage\n";
190 }
191 However, if you use the PostScript::Document module to
193 construct generic multi-page PostScript documents, you
194 don't have to worry about this.
195
197 The write() method uses the module PostScript::Metrics to determine the
198 width of each character; widths vary from font to font and character to
199 character. If you were writing a stright PostScript program, you would
200 let the PostScript interpreter do this for you, but in the case of this
201 program, we need to know the width of each character in a font within
202 the Perl script. The PostScript::Metrics module contains the font met‐
203 rics (i.e., a list containing the width of each character in the font)
204 for a bunch of fonts that are listed above under the description of the
205 addText() method. This set started with the metrics for all of the
206 default fonts with AFM files that came with GhostScript. It is slowly
207 growing as more fonts are mapped. To add support for a new font, you
208 must create the array with the metrics for that font and add it to the
209 PostScript::Metrics module. For a font with an AFM file, the AFM file
210 can be parsed with Gisle Aas' Font::AFM module, available on CPAN.
211 Please send all PostScript::Metrics patches to the author at
213 shawn@as220.org.
214
216 * better compliance with Adobe's Document Structuring Conventions *
217 more font metrics descriptions * make font loading code smarter and
218 more efficient for the interpreter * support a larger character set *
219 it would be nice to add more functions, e.g. Clone() * how about set‐
220 table defaults?
221
223 Copyright 1998, 1999 Shawn Wallace. All rights reserved.
224 Contact the author: shawn@as220.org http://www.as220.org/shawn
226 Portions of code contributed by Dan Smeltz.
228 This is free software. You may use, modify, and redistribute this pack‐
230 age under the same terms as Perl itself.
231 PostScript is a trademark of Adobe Systems.
233perl v5.8.8 1999-08-11 TextBlock(3)