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