1PDF::Builder::Content(3U)ser Contributed Perl DocumentatiPoDnF::Builder::Content(3)
2
6 PDF::Builder::Content - Methods for adding graphics and text to a PDF
7
9 # Start with a PDF page (new or opened)
10 my $pdf = PDF::Builder->new();
11 my $page = $pdf->page();
12 # 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 # 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 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
30 All public methods listed, except as otherwise noted, return $self, for
31 ease of chaining calls.
32 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 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 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 $content->translate($dx,$dy)
53 Moves the origin along the x and y axes by $dx and $dy
54 respectively.
55 $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 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 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 $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 $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 $content->transform(%opts)
85 Use one or more of the given %opts:
86 $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 A six element list may be given ("matrix") for a further
98 transformation matrix:
99 $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 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 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 $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 Unlike "transform", "matrix" and "point" are not supported.
125 $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 $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 In text mode, the text matrix is returned. In graphics mode, $self
139 is returned.
140 Graphics State Parameters
142 The following calls also affect the text state.
143 $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 Alternate name: "line_width"
152 This is provided for compatibility with PDF::API2.
154 $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 Alternate name: "line_cap"
161 This is provided for compatibility with PDF::API2.
163 "butt" or "b" or 0 = Butt Cap (default)
165 The stroke ends at the end of the path, with no projection.
166 "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 "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 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 Either a number or a string (case-insensitive) may be given.
179 $content->linejoin($style)
181 Sets the style of join to be used at corners of a path (within a
182 multisegment polyline).
183 Alternate name: "line_join"
185 This is provided for compatibility with PDF::API2.
187 "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 "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 "bevel" or "b" or 2 = Bevel Join
203 A filled triangle is drawn to fill in the notch between the two
204 strokes.
205 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 Either a number or a string (case-insensitive) may be given.
210 $content->miterlimit($ratio)
212 Sets the miter limit when the line join style is a miter join.
213 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 The default miter limit is 10.0 (approximately 11.5 degree cutoff
221 angle). The smaller the limit, the larger the cutoff angle.
222 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 Alternate name: "miter_limit"
227 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 $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 If called without any arguments, a solid line will be drawn.
240 If called with one argument, the dashes and gaps (strokes and
242 spaces) will have equal lengths.
243 If called with two or more arguments, the arguments represent
245 alternating dash and gap lengths.
246 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 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 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 Alternate name: "line_dash_pattern"
265 This is provided for compatibility with PDF::API2.
267 $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 The $tolerance value is silently clamped to be between 0 and 100.
278 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 Alternate name: "flatness_tolerance"
284 This is provided for compatibility with PDF::API2.
286 $content->egstate($object)
288 (Advanced) Adds an Extended Graphic State object containing
289 additional state parameters.
290 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 $content->close()
298 Closes and ends the current path by extending a line from the
299 current position to the starting position.
300 $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 Alternate name: "end"
307 This is provided for compatibility with PDF::API2. Do not confuse
309 it with the "$pdf->end()" method!
310 Straight line constructs
312 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 $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 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 $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 $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 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 Thus, while this is provided for compatibility with PDF::API2, it
346 is not really an alias or alternate name for "poly"!
347 $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 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 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 $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 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 $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 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 $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 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 Curved line constructs
402 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 $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 $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 $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 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 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 $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 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 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 $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 Within a text object, the text's baseline follows the Bezier curve.
458 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 $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 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 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 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 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 Alternate name: "spline"
490 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 $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 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 Options %opts:
517 'firstseg' => 'mode'
519 where mode is
520 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 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 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 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 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 'lastseg' => 'mode'
558 where mode is
559 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 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 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 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 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 '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 '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 "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 '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 Special cases
622 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 0 given points (after duplicate consolidation)
628 This leaves only the current point (unchanged), so it is a no-op.
629 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 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 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 Alternate name: "cbspline"
648 This is to emphasize that it is a cubic Bezier spline, as opposed to a
650 quadratic Bezier spline (see "qbspline" above).
651 $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 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 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 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 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 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 Path Painting (Drawing)
689 $content->stroke()
690 Strokes the current path.
691 $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 $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 $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 See the PDF Specification, section 8.5.3.3 (in version 1.7), for
714 more details on filling.
715 The "rule" parameter is added for PDF::API2 compatibility.
717 $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 $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 $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 See the PDF Specification, section 8.5.3.3 (in version 1.7), for
740 more details on filling.
741 The "rule" parameter is added for PDF::API2 compatibility.
743 Alternate names: "paint" and "fill_stroke"
745 "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 $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 $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 $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 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 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 The "rule" parameter is added for PDF::API2 compatibility.
799 $content->shade($shade, @coord)
801 Sets the shading matrix.
802 $shade
804 A hash reference that includes a name() method for the shade
805 name.
806 @coord
808 An array of 4 items: X-translation, Y-translation, X-scaled and
809 translated, Y-scaled and translated.
810 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 # 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 # 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 # 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 # 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 # 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 # 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 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 # 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 # 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 # 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 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 # A single reference is treated as a pattern or shading space.
873 # 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 If no value was passed in, the current fill color (or stroke color)
879 array is returned, otherwise $self is returned.
880 Alternate names: "fill_color" and "stroke_color".
882 These are provided for PDF::API2 compatibility.
884 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 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 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 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 $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 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 $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 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 For other external objects, the scale is a multiplier, where 1 (the
942 default) represents 100% (i.e. no change).
943 If coordinate transformations have been made (see Coordinate
945 Transformations above), the position and scale will be relative to
946 the updated coordinates.
947 If no coordinate transformations are needed, this method can be
949 called directly from the PDF::Builder::Page object instead.
950 Text
952 Text State Parameters
953 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 $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 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 Alternate names: "character_spacing" and "char_space"
973 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 $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 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 alternate names: "word_spacing" and "word_space"
993 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 $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 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 $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 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 $leading = $content->lead($leading)
1031 $leading = $content->lead()
1032 Deprecated, to be removed after March 2023. Use leading() now.
1033 Note that the "$self->{' lead'}" internal variable is no longer
1035 available, having been replaced by "$self->{' leading'}".
1036 $mode = $content->render($mode)
1038 Sets the text rendering mode.
1039 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 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 $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 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 %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 Note: This does not work with the "save" and "restore" commands.
1072 $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 # Example (12 point Helvetica)
1078 my $pdf = PDF::Builder->new();
1079 my $font = $pdf->font('Helvetica');
1081 $text->font($font, 24);
1082 $text->position(72, 720);
1083 $text->text('Hello, World!');
1084 $pdf->save('sample.pdf');
1086 Positioning Text
1088 $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 If called without arguments (Get), returns the current position of
1097 the cursor (before the effects of any coordinate transformation
1098 methods).
1099 Note that this is very similar in function to distance(), added
1101 recently to PDF::API2 and added here for compatibility.
1102 ($tx,$ty) = $content->textpos()
1104 Returns the current text position on the page (where next write
1105 will happen) as an array.
1106 Note: This does not affect the PDF in any way. It only tells you
1108 where the the next write will occur.
1109 Alternate name: "position" (added for compatibility with PDF::API2)
1111 $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 "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 $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 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 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 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 $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 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 $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 If leading isn't set, a default distance of 120% of the font size
1163 will be used.
1164 Added for compatibility with PDF::API2 changes; may be used to
1166 replace both "cr" and "nl" methods.
1167 $width = $content->advancewidth($string, %opts)
1169 Options %opts:
1170 '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 'fontsize' => 12
1177 Change the font size, overriding $self->{' fontsize'}. Example:
1178 12 pt font.
1179 'wordspace' => 0.8
1181 Change the additional word spacing, overriding
1182 $self->wordspace(). Example: add 0.8 pt between words.
1183 '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 'hscale' => 125
1190 Change the horizontal scaling factor, overriding
1191 $self->hscale(). Example: stretch text to 125% of its natural
1192 width.
1193 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 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 Alternate name: "text_width"
1205 This is provided for compatibility with PDF::API2.
1207 Rendering Text
1209 Single Lines
1211 $width = $content->text($text, %opts)
1213 Adds text to the page (left justified). The width used (in points)
1214 is returned.
1215 Options:
1217 'indent' => $distance
1219 Indents the text by the number of points (A value less than 0
1220 gives an outdent).
1221 '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 Example:
1233 # 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 '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 Example:
1252 # 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 $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 $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 $settings
1276 This a reference to a hash of various pieces of information
1277 that textHS() needs in order to function. They include:
1278 '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 '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 '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 '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 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 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 '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 '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 %opts
1359 This a hash of options.
1360 'underline' => underlining_instructions
1362 See text() for available instructions.
1363 'strikethru' => strikethrough_instructions
1365 See text() for available instructions.
1366 '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 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 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 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 $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 $HSarray
1406 The array reference of glyphs created by the HarfBuzz::Shaper
1407 call. See textHS() for details.
1408 $settings
1410 the hash reference of settings. See textHS() for details.
1411 'dir' => 'L' etc.
1413 the direction of the text, to know which "advance" value to
1414 sum up.
1415 %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 '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 '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 Returns total width in points.
1437 Alternate name: "text_widthHS"
1439 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 $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 $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 Be careful when doing this, as you are dabbling in the black arts,
1465 directly setting PDF operations!
1466 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 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 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 $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 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 .2399999 0 0 -.23999999 0 792 cm
1505 or similar, which is not within a save/restore (q/Q). If the stream
1507 is already compressed, this might not be possible.
1508 $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 $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 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 $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 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 $content->textend()
1534 Ends a text object (ignored if not in a text object).
1535 Note that calling this method, besides outputting an ET marker,
1537 will output any accumulated poststream content.
1538perl v5.36.0 2023-01-23 PDF::Builder::Content(3)