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
33 PostScript::TextBlock.
34 addText( text=>$text, [ font=>$font ], [ size=>$size ], [
36 leading=>$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
46 reference):
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
56 PostScript::Metrics module supports the following fonts (basically,
57 the default GhostScript fonts that have AFM files):
58 NimbusSanL-ReguCond URWGothicL-Book CenturySchL-Bold
60 CharterBT-Italic URWBookmanL-Ligh CharterBT-BoldItalic
61 NimbusRomNo9L-ReguItal URWBookmanL-DemiBoldItal CharterBT-Roman
62 NimbusMonL-ReguObli NimbusSanL-ReguCondItal CenturySchL-Ital
63 CenturySchL-BoldItal URWPalladioL-Roma URWBookmanL-LighItal
64 CharterBT-Bold NimbusSanL-BoldCond NimbusMonL-BoldObli
65 NimbusSanL-BoldCondItal URWGothicL-DemiObli NimbusSanL-Regu
66 URWPalladioL-Bold NimbusMonL-Regu NimbusSanL-ReguItal
67 URWGothicL-BookObli URWPalladioL-Ital
68 You can get a list of the currently supported fonts with the
70 following:
71 use PostScript::Metrics;
73 @okfonts = PostScript::Metrics->listFonts();
74 NOTE: The font must be available to the PostScript
76 interpreter that is used to render the page described by
77 the program. If the interpreter cannot load the font, it
78 will ususally attempt to substitute a similar font. If a
79 font is substituted with a font with different metrics,
80 lines of text may overrun the right margin of the text
81 block. 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
101 object. An 'element' is created each time the addText()
102 method is called.
103 Write( $width, $height, $xoffset, $yoffset )
105 The Write() method will generate the PostScript code
107 that will render the text on a page when passed to a
108 PostScript interpreter such as Ghostscript. The four
109 parameters are expressed in points (1/72 inch) and
110 indicate the width and height of the box within which
111 the text should be printed, and the x and y offset of
112 the upper left corner of this box.
113 Important: PostScript defines the orgin (0,0) as the
115 lower left corner of the page! This *will* mess you up.
116 Standard page sizes in points are:
118 Paper Size Width, Height (in points)
120 ......................... .........................
121 Letter 612, 792
122 Legal 612, 1008
123 Ledger 1224, 792
124 Tabloid 792, 1224
125 A0 2384, 3370
126 A1 1684, 2384
127 A2 1191, 1684
128 A3 842, 1191
129 A4 595, 842
130 A5 420, 595
131 A6 297, 420
132 A7 210, 297
133 A8 148, 210
134 A9 105, 148
135 B0 2920, 4127
136 B1 2064, 2920
137 B2 1460, 2064
138 B3 1032, 1460
139 B4 729, 1032
140 B5 516, 729
141 B6 363, 516
142 B7 258, 363
143 B8 181, 258
144 B9 127, 181
145 B10 91, 127
146 #10 Envelope 297, 684
147 C5 Envelope 461, 648
148 DL Envelope 312, 624
149 Folio 595, 935
150 Executive 522, 756
151 The write() method returns two values: a string
153 consisting of the PostScript code (suitable for
154 printing to a file), and a TextBlock object containing
155 the elements (and partial elements) that did not fit
156 within the specified area, if any. If the entire text
157 block fits with the area, the remainder will be undef.
158 The remainder can be used to layout multiple pages and
159 columns, etc. in a similar manner to most modern
160 desktop publishing programs. In general, the write()
161 method should be called as in the following, which
162 writes the PostScript code to a file called
163 'psoutput.ps':
164 open OUT, '>psoutput.ps';
166 my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
167 print OUT $code;
168 To print an entire text block that spans multiple
170 pages, you could do something like this:
171 (add enough text to the text block first..)
173 open OUT, '>psoutput.ps';
175 my $pages = 1;
176 # Create the first page
178 #
179 my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
180 print OUT "%%Page:$pages\n"; # this is required by the Adobe
181 # Document Structuring Conventions
182 print OUT $code;
183 print OUT "showpage\n";
184 # Print the rest of the pages, if any
186 #
187 while ($remainder->numElements) {
188 $pages++;
189 print OUT "%%Page:$pages\n";
190 ($code, $remainder) = $remainder->Write(572, 752, 20, 772);
191 print OUT $code;
192 print OUT "showpage\n";
193 }
194 However, if you use the PostScript::Document module to
196 construct generic multi-page PostScript documents, you
197 don't have to worry about this.
198
200 The write() method uses the module PostScript::Metrics to determine the
201 width of each character; widths vary from font to font and character to
202 character. If you were writing a stright PostScript program, you would
203 let the PostScript interpreter do this for you, but in the case of this
204 program, we need to know the width of each character in a font within
205 the Perl script. The PostScript::Metrics module contains the font
206 metrics (i.e., a list containing the width of each character in the
207 font) for a bunch of fonts that are listed above under the description
208 of the addText() method. This set started with the metrics for all of
209 the default fonts with AFM files that came with GhostScript. It is
210 slowly growing as more fonts are mapped. To add support for a new font,
211 you must create the array with the metrics for that font and add it to
212 the PostScript::Metrics module. For a font with an AFM file, the AFM
213 file can be parsed with Gisle Aas' Font::AFM module, available on CPAN.
214 Please send all PostScript::Metrics patches to the author at
216 shawn@as220.org.
217
219 * better compliance with Adobe's Document Structuring Conventions *
220 more font metrics descriptions * make font loading code smarter and
221 more efficient for the interpreter * support a larger character set *
222 it would be nice to add more functions, e.g. Clone() * how about
223 settable defaults?
224
226 Copyright 1998, 1999 Shawn Wallace. All rights reserved.
227 Contact the author: shawn@as220.org http://www.as220.org/shawn
229 Portions of code contributed by Dan Smeltz.
231 This is free software. You may use, modify, and redistribute this
233 package under the same terms as Perl itself.
234 PostScript is a trademark of Adobe Systems.
236
238 Hey! The above document had some coding errors, which are explained
239 below:
240 Around line 398:
242 You can't have =items (as at line 416) unless the first thing after
243 the =over is an =item
244 Around line 509:
246 You forgot a '=back' before '=head1'
247 You forgot a '=back' before '=head1'
249 You forgot a '=back' before '=head1'
251perl v5.36.0 2023-01-20 TextBlock(3)