1PDF::Builder::Content(3U)ser Contributed Perl DocumentatiPoDnF::Builder::Content(3)
2
3
4

NAME

6       PDF::Builder::Content - Methods for adding graphics and text to a PDF
7

SYNOPSIS

9           # Start with a PDF page (new or opened)
10           my $pdf = PDF::Builder->new();
11           my $page = $pdf->page();
12
13           # Add new content object(s)
14           my $content = $page->gfx();
15           #   and/or (as separate object name)
16           my $content = $page->text();
17
18           # Then call the methods below to add graphics and text to the page.
19           # Note that negative coordinates can have unpredictable effects, so
20           # keep your coordinates non-negative!
21
22       These methods add content to streams output for text or graphics
23       objects.  Unless otherwise restricted by a check that we are in or out
24       of text mode, many methods listed here apply equally to text and
25       graphics streams. It is possible that there are some which have no
26       effect in one stream type or the other, but are currently lacking a
27       check to prevent them from being inserted into an inapplicable stream.
28

METHODS

30       All public methods listed, except as otherwise noted, return $self.
31
32   Coordinate Transformations
33       The methods in this section change the coordinate system for the
34       current content object relative to the rest of the document.  Note: the
35       changes are relative to the original page coordinates (and thus,
36       absolute), not to the previous position! Thus, "translate(10, 10);
37       translate(10, 10);" ends up only moving the origin to "[10, 10]",
38       rather than to "[20, 20]". There is one call, "transform_rel()", which
39       makes your changes relative to the previous position.
40
41       If you call more than one of these methods, the PDF specification
42       recommends calling them in the following order: translate, rotate,
43       scale, skew.  Each change builds on the last, and you can get
44       unexpected results when calling them in a different order.
45
46       CAUTION: a text object ($content) behaves a bit differently. Individual
47       translate, rotate, scale, and skew calls cancel out any previous
48       settings.  If you want to combine multiple transformations for text,
49       use the "transform" call.
50
51       $content->translate($dx,$dy)
52           Moves the origin along the x and y axes by $dx and $dy
53           respectively.
54
55       $content->rotate($degrees)
56           Rotates the coordinate system counter-clockwise (anti-clockwise)
57           around the current origin. Use a negative argument to rotate
58           clockwise. Note that 360 degrees will be treated as 0 degrees.
59
60           Note: Unless you have already moved (translated) the origin, it is,
61           and will remain, at the lower left corner of the visible sheet. It
62           will not automatically shift to another corner. For example, a
63           rotation of +90 degrees (counter-clockwise) will leave the entire
64           visible sheet in negative Y territory (0 at the left edge,
65           -original_width at the right edge), while X remains in positive
66           territory (0 at bottom, +original_height at the top edge).
67
68           This "rotate()" call permits any angle. Do not confuse it with the
69           page rotation "rotate" call, which only permits increments of 90
70           degrees (with opposite sign!), but does shift the origin to another
71           corner of the sheet.
72
73       $content->scale($sx,$sy)
74           Scales (stretches) the coordinate systems along the x and y axes.
75           Separate multipliers are provided for x and y.
76
77       $content->skew($skx,$sky)
78           Skews the coordinate system by $skx degrees
79           (counter-clockwise/anti-clockwise) from the x axis and $sky degrees
80           (clockwise) from the y axis.  Note that 360 degrees will be treated
81           the same as 0 degrees.
82
83       $content->transform(%opts)
84           Use one or more of the given %opts:
85
86               $content->transform(
87                   -translate => [$dx,$dy],
88                   -rotate    => $degrees,
89                   -scale     => [$sx,$sy],
90                   -skew      => [$skx,$sky],
91                   -matrix    => [$a, $b, $c, $d, $e, $f],
92                   -point     => [$x,$y]
93               )
94
95           A six element list may be given ("-matrix") for a further
96           transformation matrix:
97
98               $a = cos(rot) * scale factor for X
99               $b = sin(rot) * tan(skew for X)
100               $c = -sin(rot) * tan(skew for Y)
101               $d = cos(rot) * scale factor for Y
102               $e = translation for X
103               $f = translation for Y
104
105           Performs multiple coordinate transformations at once, in the order
106           recommended by the PDF specification (translate, rotate, scale,
107           skew).  This is equivalent to making each transformation
108           separately, in the indicated order.  A matrix of 6 values may also
109           be given ("-matrix"). The transformation matrix is updated.  A
110           "-point" may be given (a point to be multiplied [transformed] by
111           the completed matrix).
112
113       $content->transform_rel(%opts)
114           Makes transformations similarly to "transform", except that it adds
115           to the previously set values, rather than replacing them (except
116           for scale, which multiplies the new values with the old).
117
118           Unlike "transform", "-matrix" and "-point" are not supported.
119
120       $content->matrix($a, $b, $c, $d, $e, $f)
121           (Advanced) Sets the current transformation matrix manually. Unless
122           you have a particular need to enter transformations manually, you
123           should use the "transform" method instead.
124
125            $a = cos(rot) * scale factor for X
126            $b = sin(rot) * tan(skew for X)
127            $c = -sin(rot) * tan(skew for Y)
128            $d = cos(rot) * scale factor for Y
129            $e = translation for X
130            $f = translation for Y
131
132           In text mode, the text matrix is returned.  In graphics mode, $self
133           is returned.
134
135   Graphics State Parameters
136       The following calls also affect the text state.
137
138       $content->linewidth($width)
139           Sets the width of the stroke. This is the line drawn in graphics
140           mode, or the outline of a character in text mode (with appropriate
141           "render" mode).  If no $width is given, the current setting is
142           returned. If the width is being set, $self is returned so that
143           calls may be chained.
144
145       $content->linecap($style)
146           Sets the style to be used at the end of a stroke. This applies to
147           lines which come to a free-floating end, not to "joins" ("corners")
148           in polylines (see "linejoin").
149
150           0 = Butt Cap
151               The stroke ends at the end of the path, with no projection.
152
153           1 = Round Cap
154               A semicircular arc is drawn around the end of the path with a
155               diameter equal to the line width, and is filled in.
156
157           2 = Projecting Square Cap
158               The stroke continues past the end of the path for half the line
159               width.
160
161           If no $style is given, the current setting is returned. If the
162           style is being set, $self is returned so that calls may be chained.
163
164       $content->linejoin($style)
165           Sets the style of join to be used at corners of a path (within a
166           multisegment polyline).
167
168           0 = Miter Join
169               The outer edges of the strokes extend until they meet, up to
170               the limit specified by miterlimit. If the limit would be
171               surpassed, a bevel join is used instead. For a given linewidth,
172               the more acute the angle is (closer to 0 degrees), the higher
173               the ratio of miter length to linewidth will be, and that's what
174               miterlimit controls.
175
176           1 = Round Join
177               A filled circle with a diameter equal to the linewidth is drawn
178               around the corner point, producing a rounded corner. The arc
179               will meet up with the sides of the line in a smooth tangent.
180
181           2 = Bevel Join
182               A filled triangle is drawn to fill in the notch between the two
183               strokes.
184
185           If no $style is given, the current setting is returned. If the
186           style is being set, $self is returned so that calls may be chained.
187
188       $content->miterlimit($ratio)
189           Sets the miter limit when the line join style is a miter join.
190
191           The ratio is the maximum length of the miter (inner to outer
192           corner) divided by the line width. Any miter above this ratio will
193           be converted to a bevel join. The practical effect is that lines
194           meeting at shallow angles are chopped off instead of producing long
195           pointed corners.
196
197           The default miter limit is 10.0 (approximately 11.5 degree cutoff
198           angle).  The smaller the limit, the larger the cutoff angle.
199
200           If no $ratio is given, the current setting is returned. If the
201           ratio is being set, $self is returned so that calls may be chained.
202
203       $content->linedash()
204       $content->linedash($length)
205       $content->linedash($dash_length, $gap_length, ...)
206       $content->linedash(-pattern => [$dash_length, $gap_length, ...], -shift
207       => $offset)
208           Sets the line dash pattern.
209
210           If called without any arguments, a solid line will be drawn.
211
212           If called with one argument, the dashes and gaps (strokes and
213           spaces) will have equal lengths.
214
215           If called with two or more arguments, the arguments represent
216           alternating dash and gap lengths.
217
218           If called with a hash of arguments, the -pattern array may have one
219           or more elements, specifying the dash and gap lengths.  A dash
220           phase may be set (-shift), which is a positive integer specifying
221           the distance into the pattern at which to start the dashed line.
222           Note that if you wish to give a shift amount, using "-shift", you
223           need to use "-pattern" instead of one or two elements.
224
225           If an odd number of dash array elements are given, the list is
226           repeated by the reader software to form an even number of elements
227           (pairs).
228
229           If a single argument of -1 is given, the current setting is
230           returned.  This is an array consisting of two elements: an
231           anonymous array containing the dash pattern (default: empty), and
232           the shift (offset) amount (default: 0).  If the dash pattern is
233           being set, $self is returned so that calls may be chained.
234
235       $content->flatness($tolerance)
236           (Advanced) Sets the maximum variation in output pixels when drawing
237           curves. The defined range of $tolerance is 0 to 100, with 0 meaning
238           use the device default flatness. According to the PDF
239           specification, you should not try to force visible line segments
240           (the curve's approximation); results will be unpredictable.
241           Usually, results for different flatness settings will be
242           indistinguishable to the eye.
243
244           The $tolerance value is silently clamped to be between 0 and 100.
245
246           If no $tolerance is given, the current setting is returned. If the
247           tolerance is being set, $self is returned so that calls may be
248           chained.
249
250       $content->egstate($object)
251           (Advanced) Adds an Extended Graphic State object containing
252           additional state parameters.
253
254   Path Construction (Drawing)
255       $content->move($x,$y)
256           Starts a new path at the specified coordinates.  Note that multiple
257           x,y pairs can be given, although this isn't that useful (only the
258           last pair would have an effect).
259
260       $content->close()
261           Closes and ends the current path by extending a line from the
262           current position to the starting position.
263
264       $content->endpath()
265           Ends the current path without explicitly enclosing it.  That is,
266           unlike "close", there is no line segment drawn back to the starting
267           position.
268
269       Straight line constructs
270
271       Note: None of these will actually be visible until you call "stroke" or
272       "fill". They are merely setting up the path to draw.
273
274       $content->line($x,$y)
275       $content->line($x,$y, $x2,$y2,...)
276           Extends the path in a line from the current coordinates to the
277           specified coordinates, and updates the current position to be the
278           new coordinates.
279
280           Multiple additional "[$x,$y]" pairs are permitted, to draw joined
281           multiple line segments. Note that this is not equivalent to a
282           polyline (see "poly"), because the first "[$x,$y]" pair in a
283           polyline is a move operation.  Also, the "linecap" setting will be
284           used rather than the "linejoin" setting for treating the ends of
285           segments.
286
287       $content->hline($x)
288       $content->vline($y)
289           Shortcuts for drawing horizontal and vertical lines from the
290           current position. They are like "line()", but to the new x and
291           current y ("hline"), or to the the current x and new y ("vline").
292
293       $content->poly($x1,$y1, ..., $xn,$yn)
294           This is a shortcut for creating a polyline path. It moves to
295           "[$x1,$y1]", and then extends the path in line segments along the
296           specified coordinates.  The current position is changed to the last
297           "[$x,$y]" pair given.
298
299           The difference between a polyline and a "line" with multiple
300           "[$x,$y]" pairs is that the first pair in a polyline are a move,
301           while in a line they are a draw.  Also, "linejoin" instead of
302           "linecap" is used to control the appearance of the ends of line
303           segments.
304
305       $content->rect($x,$y, $w,$h)
306       $content->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)
307           This creates paths for one or more rectangles, with their lower
308           left points at "[$x,$y]" and specified widths (+x direction) and
309           heights (+y direction).  Negative widths and heights are permitted,
310           which draw to the left (-x) and below (-y) the given corner point,
311           respectively.  The current position is changed to the "[$x,$y]" of
312           the last rectangle given.  Note that this is the starting point of
313           the rectangle, not the end point.
314
315       $content->rectxy($x1,$y1, $x2,$y2)
316           This creates a rectangular path, with "[$x1,$y1]" and "[$x2,$y2]"
317           specifying opposite corners. They can be Lower Left and Upper
318           Right, or Upper Left and Lower Right, in either order, so long as
319           they are diagonally opposite each other.  The current position is
320           changed to the "[$x1,$y1]" (first) pair.
321
322       Curved line constructs
323
324       Note: None of these will actually be visible until you call "stroke" or
325       "fill". They are merely setting up the path to draw.
326
327       $content->circle($xc,$yc, $radius)
328           This creates a circular path centered on "[$xc,$yc]" with the
329           specified radius. It does not change the current position.
330
331       $content->ellipse($xc,$yc, $rx,$ry)
332           This creates a closed elliptical path centered on "[$xc,$yc]", with
333           axis radii (semidiameters) specified by $rx (x axis) and $ry (y
334           axis), respectively.  It does not change the current position.
335
336       $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
337       $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
338           This extends the path along an arc of an ellipse centered at
339           "[$xc,$yc]".  The semidiameters of the elliptical curve are $rx (x
340           axis) and $ry (y axis), respectively, and the arc sweeps from
341           $alpha degrees to $beta degrees. The current position is then set
342           to the endpoint of the arc.
343
344           Set $move to a true value if this arc is the beginning of a new
345           path instead of the continuation of an existing path. Either way,
346           the current position will be updated to the end of the arc.  Use
347           "$rx == $ry" for a circular arc.
348
349           The optional $dir arc sweep direction defaults to 0 (false), for a
350           counter-clockwise/anti-clockwise sweep. Set to 1 (true) for a
351           clockwise sweep.
352
353       $content->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)
354       $content->pie($xc,$yc, $rx,$ry, $alpha,$beta)
355           Creates a pie-shaped path from an ellipse centered on "[$xc,$yc]".
356           The x-axis and y-axis semidiameters of the ellipse are $rx and $ry,
357           respectively, and the arc sweeps from $alpha degrees to $beta
358           degrees.  It does not change the current position.  Depending on
359           the sweep angles and direction, this can draw either the pie
360           "slice" or the remaining pie (with slice removed).  Use "$rx ==
361           $ry" for a circular pie.  Use a different "[$xc,$yc]" for the
362           slice, to offset it from the remaining pie.
363
364           The optional $dir arc sweep direction defaults to 0 (false), for a
365           counter-clockwise/anti-clockwise sweep. Set to 1 (true) for a
366           clockwise sweep.
367
368           This is a shortcut to draw a section of elliptical (or circular)
369           arc and connect it to the center of the ellipse or circle, to form
370           a pie shape.
371
372       $content->curve($cx1,$cy1, $cx2,$cy2, $x,$y)
373           This extends the path in a curve from the current point to
374           "[$x,$y]", using the two specified control points to create a cubic
375           Bezier curve, and updates the current position to be the new point
376           ("[$x,$y]").
377
378           Within a text object, the text's baseline follows the Bezier curve.
379
380           Note that while multiple sets of three "[x,y]" pairs are permitted,
381           these are treated as independent cubic Bezier curves. There is no
382           attempt made to smoothly blend one curve into the next!
383
384       $content->qbspline($cx1,$cy1, $x,$y)
385           This extends the path in a curve from the current point to
386           "[$x,$y]", using the two specified points to create a quadratic
387           Bezier curve, and updates the current position to be the new point.
388
389           Internally, these splines are one or more cubic Bezier curves (see
390           "curve") with the two control points synthesized from the two given
391           points (a control point and the end point of a quadratic Bezier
392           curve).
393
394           Note that while multiple sets of two "[x,y]" pairs are permitted,
395           these are treated as independent quadratic Bezier curves. There is
396           no attempt made to smoothly blend one curve into the next!
397
398           Further note that this "spline" does not match the common
399           definition of a spline being a continuous curve passing through all
400           the given points! It is a piecewise non-continuous cubic Bezier
401           curve. Use with care, and do not make assumptions about splines for
402           you or your readers. You may wish to use the "bspline" call to have
403           a continuously smooth spline to pass through all given points.
404
405           Pairs of points (control point and end point) are consumed in a
406           loop. If one point or coordinate is left over at the end, it is
407           discarded (as usual practice for excess data to a routine). There
408           is no check for duplicate points or other degeneracies.
409
410       $content->bspline($ptsRef, %opts)
411       $content->bspline($ptsRef)
412           This extends the path in a curve from the current point to the end
413           of a list of coordinate pairs in the array referenced by $ptsRef.
414           Smoothly continuous cubic Bezier splines are used to create a curve
415           that passes through all the given points. Multiple control points
416           are synthesized; they are not supplied in the call. The current
417           position is updated to the last point.
418
419           Internally, these splines are one cubic Bezier curve (see "curve")
420           per pair of input points, with the two control points synthesized
421           from the tangent through each point as set by the polyline that
422           would connect each point to its neighbors. The intent is that the
423           resulting curve should follow reasonably closely a polyline that
424           would connect the points, and should avoid any major excursions.
425           See the discussions below for the handling of the control points at
426           the endpoints (current point and last input point). The point at
427           the end of the last line or curve drawn becomes the new current
428           point.
429
430           %opts
431
432           -firstseg => 'mode'
433               where mode is
434
435               curve
436                   This is the default behavior.  This forces the first
437                   segment (from the current point to the first given point)
438                   to be drawn as a cubic Bezier curve. This means that the
439                   direction of the curve coming off the current point is
440                   unconstrained (it will end up being a reflection of the
441                   tangent at the first given point).
442
443               line1
444                   This forces the first segment (from the current point to
445                   the first given point) to be drawn as a curve, with the
446                   tangent at the current point to be constrained as parallel
447                   to the polyline segment.
448
449               line2
450                   This forces the first segment (from the current point to
451                   the first given point) to be drawn as a line segment. This
452                   also sets the tangent through the first given point as a
453                   continuation of the line, as well as constraining the
454                   direction of the line at the current point.
455
456               constraint1
457                   This forces the first segment (from the current point to
458                   the first given point) to not be drawn, but to be an
459                   invisible curve (like mode=line1) to leave the tangent at
460                   the first given point unconstrained. A move will be made to
461                   the first given point, and the current point is otherwise
462                   ignored.
463
464               constraint2
465                   This forces the first segment (from the current point to
466                   the first given point) to not be drawn, but to be an
467                   invisible line (like mode=line2) to constrain the tangent
468                   at the first given point. A move will be made to the first
469                   given point, and the current point is otherwise ignored.
470
471           -lastseg => 'mode'
472               where mode is
473
474               curve
475                   This is the default behavior.  This forces the last segment
476                   (to the last given input point) to be drawn as a cubic
477                   Bezier curve. This means that the direction of the curve
478                   goin to the last point is unconstrained (it will end up
479                   being a reflection of the tangent at the next-to-last given
480                   point).
481
482               line1
483                   This forces the last segment (to the last given input
484                   point) to be drawn as a curve with the the tangent through
485                   the last given point parallel to the polyline segment, thus
486                   constraining the direction of the line at the last point.
487
488               line2
489                   This forces the last segment (to the last given input
490                   point) to be drawn as a line segment. This also sets the
491                   tangent through the next-to-last given point as a back
492                   continuation of the line, as well as constraining the
493                   direction of the line at the last point.
494
495               constraint1
496                   This forces the last segment (to the last given input
497                   point) to not be drawn, but to be an invisible curve (like
498                   mode=line1) to leave the tangent at the next-to-last given
499                   point unconstrained. The last given input point is ignored,
500                   and next-to-last point becomes the new current point.
501
502               constraint2
503                   This forces the last segment (to the last given input
504                   point) to not be drawn, but to be an invisible line (like
505                   mode=line2) to constrain the tangent at the next-to-last
506                   given point. The last given input point is ignored, and
507                   next-to-last point becomes the new current point.
508
509           -ratio => n
510               n is the ratio of the length from a point to a control point to
511               the length of the polyline segment on that side of the given
512               point. It must be greater than 0.1, and the default is 0.3333
513               (1/3).
514
515           -colinear => 'mode'
516               This describes how to handle the middle segment when there are
517               four or more colinear points in the input set. A mode of 'line'
518               specifies that a line segment will be drawn between each of the
519               interior colinear points. A mode of 'curve' (this is the
520               default) will draw a Bezier curve between each of those points.
521
522               "-colinear" applies only to interior runs of colinear points,
523               between curves.  It does not apply to runs at the beginning or
524               end of the point list, which are drawn as line segments or
525               linear constraints regardless of -firstseg and -lastseg
526               settings.
527
528           -debug => N
529               If N is 0 (the default), only the spline is returned. If it is
530               greater than 0, a number of additional items will be drawn:
531               (N>0) the points, (N>1) a green solid polyline connecting them,
532               (N>2) blue original tangent lines at each interior point, and
533               (N>3) red dashed lines and hollow points representing the
534               Bezier control points.
535
536       Special cases
537
538       Adjacent points which are duplicates are consolidated.  An extra
539       coordinate at the end of the input point list (not a full "[x,y]" pair)
540       will, as usual, be ignored.
541
542       0 given points (after duplicate consolidation)
543           This leaves only the current point (unchanged), so it is a no-op.
544
545       1 given point (after duplicate consolidation)
546           This leaves the current point and one point, so it is rendered as a
547           line, regardless of %opt flags.
548
549       2 given points (after duplicate consolidation)
550           This leaves the current point, an intermediate point, and the end
551           point. If the three points are colinear, two line segments will be
552           drawn. Otherwise, both segments are curves (through the tangent at
553           the intermediate point). If either end segment mode is requested to
554           be a line or constraint, it is treated as a line1 mode request
555           instead.
556
557       N colinear points at beginning or end
558           N colinear points at beginning or end of the point set causes N-1
559           line segments ("line2" or "constraint2", regardless of the settings
560           of "-firstseg", "-lastseg", and "-colinear".
561
562       $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)
563       $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)
564       $content->bogen($x1,$y1, $x2,$y2, $radius, $move)
565       $content->bogen($x1,$y1, $x2,$y2, $radius)
566           (German for bow, as in a segment (arc) of a circle. This is a
567           segment of a circle defined by the intersection of two circles of a
568           given radius, with the two intersection points as inputs. There are
569           four possible resulting arcs, which can be selected with $larger
570           and $reverse.)
571
572           This extends the path along an arc of a circle of the specified
573           radius between "[$x1,$y1]" to "[$x2,$y2]". The current position is
574           then set to the endpoint of the arc ("[$x2,$y2]").
575
576           Set $move to a true value if this arc is the beginning of a new
577           path instead of the continuation of an existing path. Note that the
578           default ($move = false) is not a straight line to P1 and then the
579           arc, but a blending into the curve from the current point. It will
580           often not pass through P1!
581
582           Set $larger to a true value to draw the larger ("outer") arc
583           between the two points, instead of the smaller one. Both arcs are
584           drawn clockwise from P1 to P2. The default value of false draws the
585           smaller arc.
586
587           Set $reverse to a true value to draw the mirror image of the
588           specified arc (flip it over, so that its center point is on the
589           other side of the line connecting the two points). Both arcs are
590           drawn counter-clockwise from P1 to P2. The default (false) draws
591           clockwise arcs.
592
593           The $radius value cannot be smaller than half the distance from
594           "[$x1,$y1]" to "[$x2,$y2]". If it is too small, the radius will be
595           set to half the distance between the points (resulting in an arc
596           that is a semicircle). This is a silent error.
597
598   Path Painting (Drawing)
599       $content->stroke()
600           Strokes the current path.
601
602       $content->fill($use_even_odd_fill)
603           Fill the current path's enclosed area.  It does not stroke the
604           enclosing path around the area.
605
606           If the path intersects with itself, the nonzero winding rule will
607           be used to determine which part of the path is filled in. This
608           basically fills in everything inside the path. If you would prefer
609           to use the even-odd rule, pass a true argument. This basically will
610           fill alternating closed sub-areas.
611
612           See the PDF Specification, section 8.5.3.3, for more details on
613           filling.
614
615       $content->fillstroke($use_even_odd_fill)
616           Fill the enclosed area and then stroke the current path.
617
618       $content->clip($use_even_odd_fill)
619       $content->clip()
620           Modifies the current clipping path by intersecting it with the
621           current path. Initially (a fresh page), the clipping path is the
622           entire media. Each definition of a path, and a "clip()" call,
623           intersects the new path with the existing clip path, so the
624           resulting clip path is no larger than the new path, and may even be
625           empty if the intersection is null.
626
627           If any $use_even_odd_fill parameter is given, use even-odd fill
628           (W*) instead of winding-rule fill (W). It is common usage to make
629           the "endpath()" call (n) after the "clip()" call, to clear the path
630           (unless you want to reuse that path, such as to fill and/or stroke
631           it to show the clip path). If you want to clip text glyphs, it gets
632           rather complicated, as a clip port cannot be created within a text
633           object (that will have an effect on text).  See the object
634           discussion in "Rendering Order" in PDF::Builder::Docs.
635
636            my $grfxC1 = $page->gfx();
637            my $textC  = $page->text();
638            my $grfxC2 = $page->gfx();
639             ...
640            $grfxC1->save();
641            $grfxC1->endpath();
642            $grfxC1->rect(...);
643            $grfxC1->clip();
644            $grfxC1->endpath();
645             ...
646            $textC->  output text to be clipped
647             ...
648            $grfxC2->restore();
649
650   Colors
651       $content->fillcolor($color)
652       $content->strokecolor($color)
653           Sets the fill (enclosed area) or stroke (path) color. The interior
654           of text characters are filled, and (if ordered by "render") the
655           outline is stroked.
656
657               # Use a named color
658               # -> RGB color model
659               # there are many hundreds of named colors defined in
660               # PDF::Builder::Resource::Colors
661               $content->fillcolor('blue');
662
663               # Use an RGB color (# followed by 3, 6, 9, or 12 hex digits)
664               # -> RGB color model
665               # This maps to 0-1.0 values for red, green, and blue
666               $content->fillcolor('#FF0000');   # red
667
668               # Use a CMYK color (% followed by 4, 8, 12, or 16 hex digits)
669               # -> CMYK color model
670               # This maps to 0-1.0 values for cyan, magenta, yellow, and black
671               $content->fillcolor('%FF000000');   # cyan
672
673               # Use an HSV color (! followed by 3, 6, 9, or 12 hex digits)
674               # -> RGB color model
675               # This maps to 0-360 degrees for the hue, and 0-1.0 values for
676               # saturation and value
677               $content->fillcolor('!FF0000');
678
679               # Use an HSL color (& followed by 3, 6, 9, or 12 hex digits)
680               # -> L*a*b color model
681               # This maps to 0-360 degrees for the hue, and 0-1.0 values for
682               # saturation and lightness. Note that 360 degrees = 0 degrees (wraps)
683               $content->fillcolor('&FF0000');
684
685               # Use an L*a*b color ($ followed by 3, 6, 9, or 12 hex digits)
686               # -> L*a*b color model
687               # This maps to 0-100 for L, -100 to 100 for a and b
688               $content->fillcolor('$FF0000');
689
690           In all cases, if too few digits are given, the given digits are
691           silently right-padded with 0's (zeros). If an incorrect number of
692           digits are given, the next lowest number of expected digits are
693           used, and the remaining digits are silently ignored.
694
695               # A single number between 0.0 (black) and 1.0 (white) is an alternate way
696               # of specifying a gray scale.
697               $content->fillcolor(0.5);
698
699               # Three array elements between 0.0 and 1.0 is an alternate way of specifying
700               # an RGB color.
701               $content->fillcolor(0.3, 0.59, 0.11);
702
703               # Four array elements between 0.0 and 1.0 is an alternate way of specifying
704               # a CMYK color.
705               $content->fillcolor(0.1, 0.9, 0.3, 1.0);
706
707           In all cases, if a number is less than 0, it is silently turned
708           into a 0. If a number is greater than 1, it is silently turned into
709           a 1. This "clamps" all values to the range 0.0-1.0.
710
711               # A single reference is treated as a pattern or shading space.
712
713               # Two or more entries with the first element a Perl reference, is treated
714               # as either an indexed colorspace reference plus color-index(es), or
715               # as a custom colorspace reference plus parameter(s).
716
717           If no value was passed in, the current fill color (or stroke color)
718           array is returned, otherwise $self is returned.
719
720       $content->shade($shade, @coord)
721           Sets the shading matrix.
722
723           $shade
724               A hash reference that includes a "name()" method for the shade
725               name.
726
727           @coord
728               An array of 4 items: X-translation, Y-translation, X-scaled and
729               translated, Y-scaled and translated.
730
731   External Objects
732       $content->image($image_object, $x,$y, $width,$height)
733       $content->image($image_object, $x,$y, $scale)
734       $content->image($image_object, $x,$y)
735       $content->image($image_object)
736               # Example
737               my $image_object = $pdf->image_jpeg($my_image_file);
738               $content->image($image_object, 100, 200);
739
740           Places an image on the page in the specified location (specifies
741           the lower left corner of the image). The default location is
742           "[0,0]".
743
744           If coordinate transformations have been made (see Coordinate
745           Transformations above), the position and scale will be relative to
746           the updated coordinates. Otherwise, "[0,0]" will represent the
747           bottom left corner of the page, and $width and $height will be
748           measured at 72dpi.
749
750           For example, if you have a 600x600 image that you would like to be
751           shown at 600dpi (i.e., one inch square), set the width and height
752           to 72.  (72 Big Points is one inch)
753
754       $content->formimage($form_object, $x,$y, $scaleX, $scaleY)
755       $content->formimage($form_object, $x,$y, $scale)
756       $content->formimage($form_object, $x,$y)
757       $content->formimage($form_object)
758           Places an XObject on the page in the specified location (giving the
759           lower left corner of the image) and scale (applied to the image's
760           native height and width). If no scale is given, use 1 for both X
761           and Y. If one scale is given, use for both X and Y.  If two scales
762           given, they are for (separately) X and Y. In general, you should
763           not greatly distort an image by using greatly different scaling
764           factors in X and Y, although it is now possible for when that
765           effect is desirable. The "$x,$y" default is "[0,0]".
766
767           Note that while this method is named form image, it is also used
768           for the pseudoimages created by the barcode routines. Images are
769           naturally dimensionless (1 point square) and need at some point to
770           be scaled up to the desired point size. Barcodes are naturally
771           sized in points, and should be scaled at approximately 1.
772           Therefore, it would greatly overscale barcodes to multiply by image
773           width and height within "formimage", and require scaling of 1/width
774           and 1/height in the call. So, we leave scaling alone within
775           "formimage" and have the user manually scale images by the image
776           width and height (in pixels) in the call to "formimage".
777
778   Text
779       Text State Parameters
780
781       All of the following parameters that take a size are applied before any
782       scaling takes place, so you don't need to adjust values to counteract
783       scaling.
784
785       $spacing = $content->charspace($spacing)
786           Sets additional spacing between characters in a line. This is in
787           points, and is initially zero.  It may be positive to give an
788           expanded effect to words, or it may be negative to give a condensed
789           effect to words.  If $spacing is given, the current setting is
790           replaced by that value and $self is returned (to permit chaining).
791           If $spacing is not given, the current setting is returned.
792
793           CAUTION: be careful about using "charspace" if you are using a
794           connected font. This might include Arabic, Devanagari, Latin
795           cursive handwriting, and so on. You don't want to leave gaps
796           between characters, or cause overlaps. For such fonts and
797           typefaces, set the "charspace" spacing to 0.
798
799       $spacing = $content->wordspace($spacing)
800           Sets additional spacing between words in a line. This is in points
801           and is initially zero (i.e., just the width of the space, without
802           anything extra). It may be negative to close up sentences a bit.
803           If $spacing is given, the current setting is replaced by that value
804           and $self is returned (to permit chaining).  If $spacing is not
805           given, the current setting is returned.
806
807           Note that it is a limitation of the PDF specification (as of
808           version 1.7, section 9.3.3) that only spacing with an ASCII space
809           (x20) is adjusted. Neither required blanks (xA0) nor any multiple-
810           byte spaces (including thin and wide spaces) are currently
811           adjusted.
812
813       $scale = $content->hscale($scale)
814           Sets the percentage of horizontal text scaling (relative sizing,
815           not spacing). This is initally 100 (percent, i.e., no scaling). A
816           scale of greater than 100 will stretch the text, while less than
817           100 will compress it.  If $scale is given, the current setting is
818           replaced by that value and $self is returned (to permit chaining).
819           If $scale is not given, the current setting is returned.
820
821           Note that scaling affects all of the character widths, interletter
822           spacing, and interword spacing. It is inadvisable to stretch or
823           compress text by a large amount, as it will quickly make the text
824           unreadable. If your objective is to justify text, you will usually
825           be better off using "charspace" and "wordspace" to expand (or
826           slightly condense) a line to fill a desired width. Also see the
827           "text_justify()" calls for this purpose.
828
829       $leading = $content->leading($leading)
830       $leading = $content->leading()
831           Sets the text leading, which is the distance between baselines.
832           This is initially zero (i.e., the lines will be printed on top of
833           each other). The unit of leading is points.  If $leading is given,
834           the current setting is replaced by that value and $self is returned
835           (to permit chaining).  If $leading is not given, the current
836           setting is returned.
837
838           Note that "leading" here is defined as used in electronic
839           typesetting and the PDF specification, which is the full interline
840           spacing (text baseline to text baseline distance, in points). In
841           cold metal typesetting, leading was usually the extra spacing
842           between lines beyond the font height itself, created by inserting
843           lead (type alloy) shims.
844
845       $leading = $content->lead($leading)
846       $leading = $content->lead()
847           Deprecated, to be removed after March 2023. Use "leading()" now.
848
849           Note that the "$self-"{' lead'}> internal variable is no longer
850           available, having been replaced by "$self-"{' leading'}>.
851
852       $mode = $content->render($mode)
853           Sets the text rendering mode.
854
855           0 = Fill text
856           1 = Stroke text (outline)
857           2 = Fill, then stroke text
858           3 = Neither fill nor stroke text (invisible)
859           4 = Fill text and add to path for clipping
860           5 = Stroke text and add to path for clipping
861           6 = Fill, then stroke text and add to path for clipping
862           7 = Add text to path for clipping
863
864           If $mode is given, the current setting is replaced by that value
865           and $self is returned (to permit chaining).  If $mode is not given,
866           the current setting is returned.
867
868       $dist = $content->rise($dist)
869           Adjusts the baseline up or down from its current location.  This is
870           initially zero. A $dist greater than 0 moves the baseline up the
871           page (y increases).
872
873           Use this for creating superscripts or subscripts (usually along
874           with an adjustment to the font size).  If $dist is given, the
875           current setting is replaced by that value and $self is returned (to
876           permit chaining).  If $dist is not given, the current setting is
877           returned.
878
879       %state = $content->textstate(charspace => $value, wordspace => $value,
880       ...)
881           This is a shortcut for setting multiple text state parameters at
882           once.  If any parameters are set, an empty hash is returned.  This
883           can also be used without arguments to retrieve the current text
884           state settings (a hash of the state is returned).
885
886           Note: This does not work with the "save" and "restore" commands.
887
888       $content->font($font_object, $size)
889           Sets the font and font size.
890
891               # Example (12 point Helvetica)
892               my $pdf = PDF::Builder->new();
893               my $fontname = $pdf->corefont('Helvetica');
894               $content->font($fontname, 12);
895
896       Positioning Text
897
898       $content->distance($dx,$dy)
899           This moves to the start of the previously-written line, plus an
900           offset by the given amounts, which are both required. "[0,0]" would
901           overwrite the previous line, while "[0,36]" would place the new
902           line 36pt above the old line (higher y). The $dx moves to the
903           right, if positive.
904
905           "distance" is analogous to graphic's "move", except that it is
906           relative to the beginning of the previous text write, not to the
907           coordinate origin.  Note that subsequent text writes will be
908           relative to this new starting (left) point and Y position! E.g., if
909           you give a non-zero $dx, subsequent lines will be indented by that
910           amount.
911
912       $content->cr()
913       $content->cr($vertical_offset)
914       $content->cr(0)
915           If passed without an argument, moves (down) to the start of the
916           next line (distance set by "leading"). This is similar to "nl()".
917
918           If passed with an argument, the "leading" distance is ignored and
919           the next line starts that far up the page (positive value) or down
920           the page (negative value) from the current line. "Y" increases
921           upward, so a negative value would normally be used to get to the
922           next line down.
923
924           An argument of 0 would simply return to the start of the present
925           line, overprinting it with new text.  That is, it acts as a simple
926           carriage return, without a linefeed.
927
928       $content->nl()
929       $content->nl($indent)
930       $content->nl(0)
931           Moves to the start of the next line (see "leading"). If $indent is
932           not given, or is 0, there is no indentation. Otherwise, indent by
933           that amount (outdent if a negative value). The unit of measure is
934           hundredths of a "unit of text space", or roughly 88 per em.
935
936       ($tx,$ty) = $content->textpos()
937           Returns the current text position on the page (where next write
938           will happen) as an array.
939
940           Note: This does not affect the PDF in any way. It only tells you
941           where the the next write will occur.
942
943       $width = $content->advancewidth($string, %opts)
944       $width = $content->advancewidth($string)
945           Options %opts:
946
947           font => $f3_TimesRoman
948               Change the font used, overriding $self->{' font'}. The font
949               must have been previously created (i.e., is not the name).
950               Example: use Times-Roman.
951
952           fontsize => 12
953               Change the font size, overriding $self->{' fontsize'}. Example:
954               12 pt font.
955
956           wordspace => 0.8
957               Change the additional word spacing, overriding
958               $self->wordspace().  Example: add 0.8 pt between words.
959
960           charspace => -2.1
961               Change the additional character spacing, overriding
962               $self->charspace().  Example: subtract 2.1 pt between letters,
963               to condense the text.
964
965           hscale => 125
966               Change the horizontal scaling factor, overriding
967               $self->hscale().  Example: stretch text to 125% of its natural
968               width.
969
970           Returns the width of the $string based on all currently set text-
971           state attributes. These can optionally be overridden with %opts.
972           Note that these values temporarily replace the existing values, not
973           scaling them up or down. For example, if the existing charspace is
974           2, and you give in options a value of 3, the value used is 3, not
975           5.
976
977           Note: This does not affect the PDF in any way. It only tells you
978           how much horizontal space a text string will take up.
979
980       Rendering Text
981
982       Single Lines
983
984       $width = $content->text($text, %opts)
985       $width = $content->text($text)
986           Adds text to the page (left justified).  The width used (in points)
987           is returned.
988
989           Options:
990
991           -indent => $distance
992               Indents the text by the number of points (A value less than 0
993               gives an outdent).
994
995           -underline => 'none'
996           -underline => 'auto'
997           -underline => $distance
998           -underline => [$distance, $thickness, ...]
999               Underlines the text. $distance is the number of units beneath
1000               the baseline, and $thickness is the width of the line.
1001               Multiple underlines can be made by passing several distances
1002               and thicknesses.  A value of 'none' means no underlining (is
1003               the default).
1004
1005               Example:
1006
1007                   # 3 underlines:
1008                   #   distance 4, thickness 1, color red
1009                   #   distance 7, thickness 1.5, color yellow
1010                   #   distance 11, thickness 2, color (strokecolor default)
1011                   -underline=>[4,[1,'red'],7,[1.5,'yellow'],11,2],
1012
1013           -strikethru => 'none'
1014           -strikethru => 'auto'
1015           -strikethru => $distance
1016           -strikethru => [$distance, $thickness, ...]
1017               Strikes through the text (like HTML s tag). A value of 'auto'
1018               places the line about 30% of the font size above the baseline,
1019               or a specified $distance (above the baseline) and $thickness
1020               (in points).  Multiple strikethroughs can be made by passing
1021               several distances and thicknesses.  A value of 'none' means no
1022               strikethrough. It is the default.
1023
1024               Example:
1025
1026                   # 2 strikethroughs:
1027                   #   distance 4, thickness 1, color red
1028                   #   distance 7, thickness 1.5, color yellow
1029                   -strikethru=>[4,[1,'red'],7,[1.5,'yellow']],
1030
1031       $width = $content->textHS($HSarray, $settings, %opts)
1032       $width = $content->textHS($HSarray, $settings)
1033           Takes an array of hashes produced by HarfBuzz::Shaper and outputs
1034           them to the PDF output file. HarfBuzz outputs glyph CIDs and
1035           positioning information.  It may rearrange and swap characters
1036           (glyphs), and the result may bear no resemblance to the original
1037           Unicode point list. You should see examples/HarfBuzz.pl, which
1038           shows a number of examples with Latin and non-Latin text, as well
1039           as vertical writing.  examples/resources/HarfBuzz_example.pdf is
1040           available in case you want to see some examples and don't yet have
1041           HarfBuzz::Shaper installed.
1042
1043           $HSarray
1044               This is the reference to array of hashes produced by
1045               HarfBuzz::Shaper, normally unchanged after being created (but
1046               can be modified). See "Using Shaper" in PDF::Builder::Docs for
1047               some things that can be done.
1048
1049           $settings
1050               This a reference to a hash of various pieces of information
1051               that "textHS()" needs in order to function. They include:
1052
1053               script => 'script_name'
1054                   This is the standard 4 letter code (e.g., 'Latn') for the
1055                   script (alphabet and writing system) you're using.
1056                   Currently, only Latn (Western writing systems) do kerning,
1057                   and 'Latn' is the default. HarfBuzz::Shaper will usually be
1058                   able to figure out from the Unicode points used what the
1059                   script is, and you might be able to use the "set_script()"
1060                   call to override its guess. However, PDF::Builder and
1061                   HarfBuzz::Shaper do not talk to each other about the script
1062                   being used.
1063
1064               features => array_of_features
1065                   This item is required, but may be empty, e.g.,
1066                   "$settings->{'features'} = ();".  It can include switches
1067                   using the standard HarfBuzz naming, and a + or - switch,
1068                   such as '-liga' to turn off ligatures. '-liga' and '-kern',
1069                   to turn off ligatures and kerning, are the only features
1070                   supported currently. Note that this is separate from any
1071                   switches for features that you send to HarfBuzz::Shaper
1072                   (with "$hb->add_features()", etc.) when you run it (before
1073                   "textHS()").
1074
1075               language => 'language_code'
1076                   This item is optional and currently does not appear to have
1077                   any substantial effect with HarfBuzz::Shaper. It is the
1078                   standard code for the language to be used, such as 'en' or
1079                   'en_US'. You might need to define this for
1080                   HarfBuzz::Shaper, in case that system can't surmise the
1081                   language rules to be used.
1082
1083               dir => 'flag'
1084                   Tell "textHS()" whether this text is to be written in a
1085                   Left-To-Right manner (L, the default), Right-To-Left (R),
1086                   Top-To-Bottom (T), or Bottom-To-Top (B). From the script
1087                   used (Unicode points), HarfBuzz::Shaper can usually figure
1088                   out what direction to write text in. Also, HarfBuzz::Shaper
1089                   does not share its information with PDF::Builder -- you
1090                   need to separately specify the direction, unless you want
1091                   to accept the default LTR direction. You can use
1092                   HarfBuzz::Shaper's "get_direction()" call (in addition to
1093                   "get_language()" and "get_script()") to see what HarfBuzz
1094                   thinks is the correct text direction. "set_direction()" may
1095                   be used to override Shaper's guess as to the direction.
1096
1097                   By the way, if the direction is RTL, HarfBuzz will reverse
1098                   the text and return an array with the last character first
1099                   (to be written LTR). Likewise, for BTT, HarfBuzz will
1100                   reverse the text and return a string to be written from the
1101                   top down. Languages which are normally written horizontally
1102                   are usually set vertically with direction TTB. If setting
1103                   text vertically, ligatures and kerning, as well as
1104                   character connectivity for cursive scripts, are
1105                   automatically turned off, so don't let the direction
1106                   default to LTR or RTL in the Shaper call, and then try to
1107                   fix it up in "textHS()".
1108
1109               align => 'flag'
1110                   Given the current output location, align the text at the
1111                   Beginning of the line (left for LTR, right for RTL),
1112                   Centered at the location, or at the End of the line (right
1113                   for LTR, left for RTL).  The default is B. Centered is
1114                   analogous to using "text_center()", and End is analogous to
1115                   using "text_right()". Similar alignments are done for TTB
1116                   and BTT.
1117
1118               dump => flag
1119                   Set to 1, it prints out positioning and glyph CID
1120                   information (to STDOUT) for each glyph in the chunk. The
1121                   default is 0 (no information dump).
1122
1123               -minKern => amount (default 1)
1124                   If the amount of kerning (font character width differs from
1125                   glyph ax value) is larger than this many character grid
1126                   units, use the unaltered ax for the width ("textHS()" will
1127                   output a kern amount in the TJ operation). Otherwise,
1128                   ignore kerning and use ax of the actual character width.
1129                   The intent is to avoid bloating the PDF code with
1130                   unnecessary tiny kerning adjustments in the TJ operation.
1131
1132           %opts
1133               This a hash of options.
1134
1135               -underline => underlining_instructions
1136                   See "text()" for available instructions.
1137
1138               -strikethru => strikethrough_instructions
1139                   See "text()" for available instructions.
1140
1141               -strokecolor => line_color
1142                   Color specification (e.g., 'green', '#FF3377') for
1143                   underline or strikethrough, if not given in an array with
1144                   their instructions.
1145
1146           Text is sent separately to HarfBuzz::Shaper in 'chunks'
1147           ('segments') of a single script (alphabet), a single direction
1148           (LTR, RTL, TTB, or BTT), a single font file, and a single font
1149           size. A chunk may consist of a large amount of text, but at
1150           present, "textHS()" can only output a single line. For long lines
1151           that need to be split into column-width lines, the best way may be
1152           to take the array of hashes returned by HarfBuzz::Shaper and split
1153           it into smaller chunks at spaces and other whitespace. You may have
1154           to query the font to see what the glyph CIDs are for space and
1155           anything else used.
1156
1157           It is expected that when "textHS()" is called, that the font and
1158           font size have already been set in PDF::Builder code, as this
1159           information is needed to interpret what HarfBuzz::Shaper is
1160           returning, and to write it to the PDF file.  Needless to say, the
1161           font should be opened from the same file as was given to
1162           HarfBuzz::Shaper ("ttfont()" only, with .ttf or .otf files), and
1163           the font size must be the same. The appropriate location on the
1164           page must also already have been specified.
1165
1166           NOTE: as HarfBuzz::Shaper is still in its early days, it is
1167           possible that there will be major changes in its API. We hope that
1168           all changes will be upwardly compatible, but do not control this
1169           package and cannot guarantee that there will not be any
1170           incompatible changes that in turn require changes to PDF::Builder
1171           ("textHS()").
1172
1173       $width = $content->advancewidthHS($HSarray, $settings, %opts)
1174       $width = $content->advancewidthHS($HSarray, $settings)
1175           Returns text chunk width (in points) for Shaper-defined glyph
1176           array.  This is the horizontal width for LTR and RTL direction, and
1177           the vertical height for TTB and BTT direction.  Note: You must
1178           define the font and font size before calling "advancewidthHS()".
1179
1180           $HSarray
1181               The array reference of glyphs created by the HarfBuzz::Shaper
1182               call.  See "textHS()" for details.
1183
1184           $settings
1185               the hash reference of settings. See "textHS()" for details.
1186
1187               dir => 'L' etc.
1188                   the direction of the text, to know which "advance" value to
1189                   sum up.
1190
1191           %opts
1192               Options. Unlike "advancewidth()", you cannot override the font,
1193               font size, etc. used by HarfBuzz::Shaper to calculate the glyph
1194               list.
1195
1196               -doKern => flag (default 1)
1197                   If 1, cancel minor kerns per "-minKern" setting. This flag
1198                   should be 0 (false) if -kern was passed to HarfBuzz::Shaper
1199                   (do not kern text).  This is treated as 0 if an ax override
1200                   setting is given.
1201
1202               -minKern => amount (default 1)
1203                   If the amount of kerning (font character width differs from
1204                   glyph ax value) is larger than this many character grid
1205                   units, use the unaltered ax for the width ("textHS()" will
1206                   output a kern amount in the TJ operation). Otherwise,
1207                   ignore kerning and use ax of the actual character width.
1208                   The intent is to avoid bloating the PDF code with
1209                   unnecessary tiny kerning adjustments in the TJ operation.
1210
1211           Returns total width in points.
1212
1213   Advanced Methods
1214       $content->save()
1215           Saves the current graphics state on a PDF stack. See PDF definition
1216           8.4.2 through 8.4.4 for details. This includes the line width, the
1217           line cap style, line join style, miter limit, line dash pattern,
1218           stroke color, fill color, current transformation matrix, current
1219           clipping port, flatness, and dictname.  This method applies to both
1220           text and gfx objects.
1221
1222       $content->restore()
1223           Restores the most recently saved graphics state (see "save"),
1224           removing it from the stack. You cannot restore the graphics state
1225           (pop it off the stack) unless you have done at least one save
1226           (pushed it on the stack).  This method applies to both text and gfx
1227           objects.
1228
1229       $content->add(@content)
1230           Add raw content (arbitrary string(s)) to the PDF stream.  You will
1231           generally want to use the other methods in this class instead,
1232           unless this is in order to implement some PDF operation that
1233           PDF::Builder does not natively support. An array of multiple
1234           strings may be given; they will be concatenated with spaces between
1235           them.
1236
1237           Be careful when doing this, as you are dabbling in the black arts,
1238           directly setting PDF operations!
1239
1240           One interesting use is to split up an overly long object stream
1241           that is giving your editor problems when exploring a PDF file. Add
1242           a newline add("\n") every few hundred bytes of output or so, to do
1243           this. Note that you must use double quotes (quotation marks),
1244           rather than single quotes (apostrophes).
1245
1246           Use extreme care if inserting BT and ET markers into the PDF
1247           stream.  You may want to use "textstart()" and "textend()" calls
1248           instead, and even then, there are many side effects either way. It
1249           is generally not useful to suspend text mode with ET/textend and
1250           BT/textstart, but it is possible, if you really need to do it.
1251
1252           Another, useful, case is when your input PDF is from the Chrome
1253           browser printing a page to PDF with headers and/or footers. In some
1254           versions, this leaves the PDF page with a strange scaling (such as
1255           the page height in points divided by 3300) and the Y-axis flipped
1256           so 0 is at the top. This causes problems when trying to add
1257           additional text or graphics in a new text or graphics record, where
1258           text is flipped (mirrored) upsidedown and at the wrong end of the
1259           page. If this happens, you might be able to cure it by adding
1260
1261               $scale = .23999999; # example, 792/3300, examine PDF or experiment!
1262                ...
1263               if ($scale != 1) {
1264                   my @pageDim = $page->mediabox();     # e.g., 0 0 612 792
1265                   my $size_page = $pageDim[3]/$scale;  # 3300 = 792/.23999999
1266                   my $invScale = 1.0/$scale;           # 4.16666684
1267                   $text->add("$invScale 0 0 -$invScale 0 $size_page cm");
1268               }
1269
1270           as the first output to the $text stream. Unfortunately, it is
1271           difficult to predict exactly what $scale should be, as it may be
1272           3300 units per page, or a fixed amount. You may need to examine an
1273           uncompressed PDF file stream to see what is being used. It might be
1274           possible to get the input (original) PDF into a string and look for
1275           a certain pattern of "cm" output
1276
1277               .2399999 0 0 -.23999999 0 792 cm
1278
1279           or similar, which is not within a save/restore (q/Q). If the stream
1280           is already compressed, this might not be possible.
1281
1282       $content->addNS(@content)
1283           Like "add()", but does not make sure there is a space between each
1284           element and before and after the new content. It is up to you to
1285           ensure that any necessary spaces in the PDF stream are placed there
1286           explicitly!
1287
1288       $content->compressFlate()
1289           Marks content for compression on output.  This is done
1290           automatically in nearly all cases, so you shouldn't need to call
1291           this yourself.
1292
1293           The "new()" call can set the -compress parameter to 'flate'
1294           (default) to compress all object streams, or 'none' to suppress
1295           compression and allow you to examine the output in an editor.
1296
1297       $content->textstart()
1298           Starts a text object (ignored if already in a text object). You
1299           will likely want to use the "text()" method (text context, not text
1300           output) instead.
1301
1302           Note that calling this method, besides outputting a BT marker, will
1303           reset most text settings to their default values. In addition, BT
1304           itself will reset some transformation matrices.
1305
1306       $content->textend()
1307           Ends a text object (ignored if not in a text object).
1308
1309           Note that calling this method, besides outputting an ET marker,
1310           will output any accumulated poststream content.
1311
1312
1313
1314perl v5.34.0                      2021-07-22          PDF::Builder::Content(3)
Impressum