1TextBlock(3)          User Contributed Perl Documentation         TextBlock(3)
2
3
4

NAME

6       PostScript::TextBlock - An object that may be used to construct a block
7       of
8                       text in PostScript.
9

SYNOPSIS

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

DESCRIPTION

29       The PostScript::TextBlock module implements four methods:
30
31       new() - Create a New PostScript::TextBlock object
32          This method instantiates a new object of class
33          PostScript::TextBlock.
34
35       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
44          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
48          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
52          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
59          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
69          You can get a list of the currently supported fonts with the
70          following:
71
72              use PostScript::Metrics;
73              @okfonts = PostScript::Metrics->listFonts();
74
75                    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
83                       It is very easy to create stylesheets for a document:
84
85                           # 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
91                           # 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
98                       numElements()
99
100                       Returns the number of elements in the text block
101                       object. An 'element' is created each time the addText()
102                       method is called.
103
104                       Write( $width, $height, $xoffset, $yoffset )
105
106                       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
114                       Important: PostScript defines the orgin (0,0) as the
115                       lower left corner of the page! This *will* mess you up.
116
117                       Standard page sizes in points are:
118
119                            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
152                       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
165                           open OUT, '>psoutput.ps';
166                           my ($code, $remainder) = $tb->Write(572, 752, 20, 772);
167                           print OUT $code;
168
169                       To print an entire text block that spans multiple
170                       pages, you could do something like this:
171
172                       (add enough text to the text block first..)
173
174                           open OUT, '>psoutput.ps';
175                           my $pages = 1;
176
177                           # 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
185                           # 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
195                       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

A NOTE ABOUT FONT METRICS

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
215       Please send all PostScript::Metrics patches to the author at
216       shawn@as220.org.
217

TODO

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

AUTHOR

226       Copyright 1998, 1999 Shawn Wallace. All rights reserved.
227
228       Contact the author: shawn@as220.org http://www.as220.org/shawn
229
230       Portions of code contributed by Dan Smeltz.
231
232       This is free software. You may use, modify, and redistribute this
233       package under the same terms as Perl itself.
234
235       PostScript is a trademark of Adobe Systems.
236

POD ERRORS

238       Hey! The above document had some coding errors, which are explained
239       below:
240
241       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
245       Around line 509:
246           You forgot a '=back' before '=head1'
247
248           You forgot a '=back' before '=head1'
249
250           You forgot a '=back' before '=head1'
251
252
253
254perl v5.30.0                      2019-07-26                      TextBlock(3)
Impressum