Codebase list libpdf-api2-perl / c869bb1
Restyle POD, update method names (partial) Steve Simms 2 years ago
2 changed file(s) with 334 addition(s) and 234 deletion(s). Raw diff Collapse all Expand all
+330
-230
lib/PDF/API2/Content.pm less more
685685
686686 =head1 PATH CONSTRUCTION (DRAWING)
687687
688 =over
689
690 =item $content->move($x, $y)
688 Note that paths will not appear until a path painting method is called
689 (L</"stroke">, L</"fill">, or L</"paint">).
690
691 =head2 move
692
693 $content = $content->move($x, $y);
691694
692695 Starts a new path at the specified coordinates.
693696
715718 return $self;
716719 }
717720
718 =item $content->line($x, $y)
721 =head2 line
722
723 $content = $content->line($x, $y);
719724
720725 Extends the path in a line from the current coordinates to the specified
721 coordinates, and updates the current position to be the new coordinates.
722
723 Note: The line will not appear until you call C<stroke>.
726 coordinates.
724727
725728 =cut
726729
746749 return $self;
747750 }
748751
749 =item $content->hline($x)
750
751 =item $content->vline($y)
752
753 Shortcut for drawing horizontal and vertical lines from the current position.
752 =head2 hline
753
754 $content = $content->hline($x);
755
756 Extends the path in a horizontal line from the current position to the specified
757 x coordinate.
754758
755759 =cut
756760
766770 return $self;
767771 }
768772
773 =head2 vline
774
775 $content = $content->vline($x);
776
777 Extends the path in a vertical line from the current position to the specified y
778 coordinate.
779
780 =cut
781
769782 sub vline {
770783 my ($self, $y) = @_;
771784 if ($self->_in_text_object()) {
778791 return $self;
779792 }
780793
781 =item $content->poly($x1, $y1, ..., $xn, $yn)
782
783 Shortcut for creating a polyline path. Moves to C<[$x1, $y1]>, and then extends
784 the path in lines along the specified coordinates.
785
786 =cut
787
794 =head2 polyline
795
796 $content = $content->polyline($x1, $y1, $x2, $y2, ...);
797
798 Extends the path from the current position in one or more straight lines.
799
800 =cut
801
802 sub polyline {
803 my $self = shift();
804 unless (@_ % 2 == 0) {
805 croak 'polyline requires pairs of coordinates';
806 }
807
808 while (@_) {
809 my $x = shift();
810 my $y = shift();
811 $self->line($x, $y);
812 }
813
814 return $self;
815 }
816
817 # Deprecated; replace with move and polyline. Deprecated because poly breaks
818 # the convention followed by every other path-drawing method (other than
819 # enclosed shapes) of extending the path from the current position.
788820 sub poly {
789821 my $self = shift();
790822 my $x = shift();
794826 return $self;
795827 }
796828
797 =item $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y)
829 =head2 curve
830
831 $content = $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y);
798832
799833 Extends the path in a curve from the current point to C<($x, $y)>, using the two
800 specified points to create a cubic Bezier curve, and updates the current
801 position to be the new point.
802
803 Note: The curve will not appear until you call C<stroke>.
834 specified points to create a cubic Bezier curve.
804835
805836 =cut
806837
825856 return $self;
826857 }
827858
828 =item $content->spline($cx1, $cy1, $x, $y)
829
830 Extends the path in a curve from the current point to C<($x, $y)>,
831 using the two specified points to create a spline, and updates the
832 current position to be the new point.
833
834 Note: The curve will not appear until you call C<stroke>.
859 =head2 spline
860
861 $content = $content->spline($cx1, $cy1, $x, $y);
862
863 Extends the path in a curve from the current point to C<($x, $y)>, using the two
864 specified points to create a spline.
835865
836866 =cut
837867
851881 }
852882 }
853883
854 =item $content->arc($x, $y, $a, $b, $alpha, $beta, $move)
855
856 Extends the path along an arc of an ellipse centered at C<[x, y]>. The major
857 and minor axes of the ellipse are C<$a> and C<$b>, respectively, and the arc
858 moves from C<$alpha> degrees to C<$beta> degrees. The current position is then
859 set to the endpoint of the arc.
860
861 Set C<$move> to a true value if this arc is the beginning of a new path instead
862 of the continuation of an existing path.
884 =head2 arc
885
886 $content = $content->arc($x, $y, $major, $minor, $a, $b);
887
888 Extends the path along an arc of an ellipse centered at C<[$x, $y]>. C<$major>
889 and C<$minor> represent the axes of the ellipse, and the arc moves from C<$a>
890 degrees to C<$b> degrees.
863891
864892 =cut
865893
903931 $p0_x = $x + shift(@points);
904932 $p0_y = $y + shift(@points);
905933
934 # Deprecated
906935 $self->move($p0_x, $p0_y) if $move;
907936
908937 while (scalar @points) {
921950 return $self;
922951 }
923952
924 =item $content->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)
925
926 Extends the path along an arc of a circle of the specified radius between
927 C<[x1,y1]> to C<[x2,y2]>. The current position is then set to the endpoint of
928 the arc.
929
930 Set C<$move> to a true value if this arc is the beginning of a new path instead
931 of the continuation of an existing path.
932
933 Set C<$outer> to a true value to draw the larger arc between the two points
934 instead of the smaller one.
935
936 Set C<$reverse> to a true value to draw the mirror image of the specified arc.
937
938 C<$radius * 2> cannot be smaller than the distance from C<[x1,y1]> to
939 C<[x2,y2]>.
940
941 Note: The curve will not appear until you call C<stroke>.
942
943 =cut
944
953 # Extends the path along an arc of a circle of the specified radius from
954 # C<[x1,y1]> to C<[x2,y2]>.
955 #
956 # Set C<$move> to a true value if this arc is the beginning of a new path
957 # instead of the continuation of an existing path.
958 #
959 # Set C<$outer> to a true value to draw the larger arc between the two points
960 # instead of the smaller one.
961 #
962 # Set C<$reverse> to a true value to draw the mirror image of the specified arc.
963 #
964 # C<$radius * 2> cannot be smaller than the distance from C<[x1,y1]> to
965 # C<[x2,y2]>.
966
967 # Deprecated; recreate using arc (Bogen is German for arc)
945968 sub bogen {
946969 my ($self, $x1, $y1, $x2, $y2, $r, $move, $larc, $spf) = @_;
947970 my ($p0_x, $p0_y, $p1_x, $p1_y, $p2_x, $p2_y, $p3_x, $p3_y);
10041027 return $self;
10051028 }
10061029
1007 =item $content->close()
1008
1009 Closes and ends the current path by extending a line from the current position
1010 to the starting position.
1030 =head2 close
1031
1032 $content = $content->close();
1033
1034 Closes the current path by extending a line from the current position to the
1035 starting position.
10111036
10121037 =cut
10131038
10191044 return $self;
10201045 }
10211046
1022 =item $content->endpath()
1023
1024 Ends the current path without explicitly enclosing it.
1025
1026 =cut
1027
1028 sub endpath {
1029 my $self = shift;
1047 =head2 end
1048
1049 $content = $content->end();
1050
1051 Ends the current path without filling or stroking.
1052
1053 =cut
1054
1055 # Deprecated (renamed)
1056 sub endpath { return end(@_) }
1057
1058 sub end {
1059 my $self = shift();
10301060 $self->add('n');
10311061 return $self;
10321062 }
10331063
1034 =item $content->ellipse($x, $y, $a, $b)
1035
1036 Creates an elliptical path centered on C<[$x,$y]>, with major and minor axes
1037 specified by C<$a> and C<$b>, respectively.
1038
1039 Note: The ellipse will not appear until you call C<stroke> or C<fill>.
1064 =head1 SHAPE CONSTRUCTION (DRAWING)
1065
1066 The following are convenience methods for drawing closed paths.
1067
1068 Note that shapes will not appear until a path painting method is called
1069 (L</"stroke">, L</"fill">, or L</"paint">).
1070
1071 =head2 rectangle
1072
1073 $content = $content->rectangle($x, $y, $width, $height);
1074
1075 Creates a new rectangle-shaped path, with the lower left point at C<[$x, $y]>
1076 and the specified width and height.
1077
1078 =cut
1079
1080 sub rectangle {
1081 my ($self, $x, $y, $w, $h) = @_;
1082
1083 $self->add(floats($x, $y, $w, $h), 're');
1084 $self->{' x'} = $x;
1085 $self->{' y'} = $y;
1086
1087 return $self;
1088 }
1089
1090 # Deprecated; replace with individual calls to rectangle
1091 sub rect {
1092 my $self = shift();
1093 my ($x, $y, $w, $h);
1094 while (defined($x = shift())) {
1095 $y = shift();
1096 $w = shift();
1097 $h = shift();
1098 $self->add(floats($x, $y, $w, $h), 're');
1099 }
1100 $self->{' x'} = $x;
1101 $self->{' y'} = $y;
1102 return $self;
1103 }
1104
1105 # Deprecated; replace with rectangle, converting x2/y2 to w/h.
1106 sub rectxy {
1107 my ($self, $x, $y, $x2, $y2) = @_;
1108 $self->rect($x, $y, ($x2 - $x), ($y2 - $y));
1109 return $self;
1110 }
1111
1112 =head2 circle
1113
1114 $content = $content->circle($x, $y, $radius);
1115
1116 Creates a new circular path centered on C<[$x, $y]> with the specified radius.
1117
1118 =cut
1119
1120 sub circle {
1121 my ($self, $x, $y, $r) = @_;
1122 $self->arc($x, $y, $r, $r, 0, 360, 1);
1123 $self->close();
1124 return $self;
1125 }
1126
1127 =head2 ellipse
1128
1129 $content = $content->ellipse($x, $y, $major, $minor);
1130
1131 Creates a new elliptical path centered on C<[$x, $y]> with the specified major
1132 and minor axes.
10401133
10411134 =cut
10421135
10471140 return $self;
10481141 }
10491142
1050 =item $content->circle($x, $y, $radius)
1051
1052 Creates a circular path centered on C<[$x, $y]> with the specified
1053 radius.
1054
1055 Note: The circle will not appear until you call C<stroke> or C<fill>.
1056
1057 =cut
1058
1059 sub circle {
1060 my ($self, $x, $y, $r) = @_;
1061 $self->arc($x, $y, $r, $r, 0, 360, 1);
1062 $self->close();
1063 return $self;
1064 }
1065
1066 =item $content->pie($x, $y, $a, $b, $alpha, $beta)
1067
1068 Creates a pie-shaped path from an ellipse centered on C<[$x,$y]>. The major and
1069 minor axes of the ellipse are C<$a> and C<$b>, respectively, and the arc moves
1070 from C<$alpha> degrees to C<$beta> degrees.
1071
1072 Note: The pie will not appear until you call C<stroke> or C<fill>.
1143 =head2 pie
1144
1145 $content = $content->pie($x, $y, $major, $minor, $a, $b);
1146
1147 Creates a new wedge-shaped path from an ellipse centered on C<[$x, $y]> with the
1148 specified major and minor axes, extending from C<$a> degrees to C<$b> degrees.
10731149
10741150 =cut
10751151
10831159 $self->close();
10841160 }
10851161
1086 =item $content->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)
1087
1088 Creates paths for one or more rectangles, with their lower left points at
1089 C<[$x,$y]> and with the specified widths and heights.
1090
1091 Note: The rectangles will not appear until you call C<stroke> or C<fill>.
1092
1093 =cut
1094
1095 sub rect {
1096 my $self = shift();
1097 my ($x, $y, $w, $h);
1098 while (defined($x = shift())) {
1099 $y = shift();
1100 $w = shift();
1101 $h = shift();
1102 $self->add(floats($x, $y, $w, $h), 're');
1103 }
1104 $self->{' x'} = $x;
1105 $self->{' y'} = $y;
1106 return $self;
1107 }
1108
1109 =item $content->rectxy($x1, $y1, $x2, $y2)
1110
1111 Creates a rectangular path, with C<[$x1,$y1]> and and C<[$x2,$y2]> specifying
1112 opposite corners.
1113
1114 Note: The rectangle will not appear until you call C<stroke> or C<fill>.
1115
1116 =cut
1117
1118 sub rectxy {
1119 my ($self, $x, $y, $x2, $y2) = @_;
1120 $self->rect($x, $y, ($x2 - $x), ($y2 - $y));
1121 return $self;
1122 }
1123
1124 =back
1125
11261162 =head1 PATH PAINTING (DRAWING)
11271163
1128 =over
1129
1130 =item $content->stroke
1131
1132 Strokes the current path.
1133
1134 =cut
1135
1136 sub _stroke {
1137 return 'S';
1138 }
1139
1140 sub stroke {
1141 my $self = shift();
1142 $self->add(_stroke());
1143 return $self;
1144 }
1145
1146 =item $content->fill($use_even_odd_fill)
1147
1148 Fills the current path.
1149
1150 If the path intersects with itself, the nonzero winding rule will be used to
1151 determine which part of the path is filled in. If you would prefer to use the
1152 even-odd rule, pass a true argument.
1153
1154 See the PDF Specification, section 8.5.3.3, for more details on filling.
1155
1156 =cut
1157
1158 sub fill {
1159 my $self = shift();
1160 $self->add(shift() ? 'f*' : 'f');
1161 return $self;
1162 }
1163
1164 =item $content->fillstroke($use_even_odd_fill)
1165
1166 Fills and then strokes the current path.
1167
1168 =cut
1169
1170 sub fillstroke {
1171 my $self = shift();
1172 $self->add(shift() ? 'B*' : 'B');
1173 return $self;
1174 }
1175
1176 =item $content->clip($use_even_odd_fill)
1177
1178 Modifies the current clipping path by intersecting it with the current path.
1179
1180 =cut
1181
1182 sub clip {
1183 my $self = shift();
1184 $self->add(shift() ? 'W*' : 'W');
1185 return $self;
1186 }
1187
1188 =back
1189
1190 =head1 COLORS
1191
1192 =over
1193
1194 =item $content->fillcolor($color)
1195
1196 =item $content->strokecolor($color)
1197
1198 Sets the fill or stroke color.
1164 =head2 stroke_color
1165
1166 $content = $content->stroke_color($color, @arguments);
1167
1168 Sets the stroke color, which is black by default.
11991169
12001170 # Use a named color
1201 $content->fillcolor('blue');
1171 $content->stroke_color('blue');
12021172
12031173 # Use an RGB color (start with '#')
1204 $content->fillcolor('#FF0000');
1174 $content->stroke_color('#FF0000');
12051175
12061176 # Use a CMYK color (start with '%')
1207 $content->fillcolor('%FF000000');
1208
1209 RGB and CMYK colors can have one-byte, two-byte, three-byte, or
1210 four-byte values for each color. For instance, cyan can be given as
1211 C<%F000> or C<%FFFF000000000000>.
1177 $content->stroke_color('%FF000000');
1178
1179 # Use a spot color with 100% coverage.
1180 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
1181 $content->stroke_color($spot, 1.0);
1182
1183 RGB and CMYK colors can have one-byte, two-byte, three-byte, or four-byte values
1184 for each color, depending on the level of precision needed. For instance, cyan
1185 can be given as C<%F000> or C<%FFFF000000000000>.
1186
1187 =head2 fill_color
1188
1189 $content = $content->fill_color($color, @arguments);
1190
1191 Sets the fill color, which is black by default. Arguments are the same as in
1192 L</"stroke_color">.
12121193
12131194 =cut
12141195
12201201 #
12211202 # legacy greylevel
12221203 # ... only one value
1223 #
1224 #
1225
12261204 sub _makecolor {
12271205 my ($self, $sf, @clr) = @_;
12281206
13231301 return @{$self->{' strokecolor'}};
13241302 }
13251303
1304 =head2 stroke
1305
1306 $content = $content->stroke();
1307
1308 Strokes the current path.
1309
1310 =cut
1311
1312 sub _stroke {
1313 return 'S';
1314 }
1315
1316 sub stroke {
1317 my $self = shift();
1318 $self->add(_stroke());
1319 return $self;
1320 }
1321
1322 =head2 fill
1323
1324 $content = $content->fill(rule => $rule);
1325
1326 Fills the current path.
1327
1328 C<$rule> describes which areas are filled in when the path intersects with itself.
1329
1330 =over
1331
1332 =item * nonzero (default)
1333
1334 Use the nonzero winding number rule. This tends to mean that the entire area
1335 enclosed by the path is filled in, with some exceptions depending on the
1336 direction of the path.
1337
1338 =item * even-odd
1339
1340 Use the even-odd rule. This tends to mean that the presence of fill alternates
1341 each time the path is intersected.
1342
1343 =back
1344
1345 See PDF specification 1.7 section 8.5.3.3, Filling, for more details.
1346
1347 =cut
1348
1349 sub fill {
1350 my $self = shift();
1351
1352 my $even_odd;
1353 if (@_ == 2) {
1354 my %options = @_;
1355 if (($options{'rule'} // 'nonzero') eq 'even-odd') {
1356 $even_odd = 1;
1357 }
1358 }
1359 else {
1360 # Deprecated
1361 $even_odd = shift();
1362 }
1363
1364 $self->add($even_odd ? 'f*' : 'f');
1365
1366 return $self;
1367 }
1368
1369 =head2 paint
1370
1371 $content = $content->paint(rule => $rule);
1372
1373 Fills and strokes the current path. C<$rule> is as described in L</"fill">.
1374
1375 =cut
1376
1377 # Deprecated (renamed)
1378 sub fillstroke { return paint(@_) }
1379
1380 sub paint {
1381 my $self = shift();
1382
1383 my $even_odd;
1384 if (@_ == 2) {
1385 my %options = @_;
1386 if (($options{'rule'} // 'nonzero') eq 'even-odd') {
1387 $even_odd = 1;
1388 }
1389 }
1390 else {
1391 # Deprecated
1392 $even_odd = shift();
1393 }
1394
1395 $self->add($even_odd ? 'B*' : 'B');
1396
1397 return $self;
1398 }
1399
1400 =head2 clip
1401
1402 $content = $content->clip(rule => $rule);
1403
1404 Modifies the current clipping path (initially the entire page) by intersecting
1405 it with the current path following the next path-painting command. C<$rule> is
1406 as described in L</"fill">.
1407
1408 =cut
1409
1410 sub clip {
1411 my $self = shift();
1412
1413 my $even_odd;
1414 if (@_ == 2) {
1415 my %options = @_;
1416 if (($options{'rule'} // 'nonzero') eq 'even-odd') {
1417 $even_odd = 1;
1418 }
1419 }
1420 else {
1421 # Deprecated
1422 $even_odd = shift();
1423 }
1424
1425 $self->add($even_odd ? 'W*' : 'W');
1426
1427 return $self;
1428 }
1429
13261430 sub shade {
13271431 my ($self, $shade, @cord) = @_;
13281432
13411445 return $self;
13421446 }
13431447
1344 =back
1345
13461448 =head1 EXTERNAL OBJECTS
13471449
1348 =over
1349
1350 =item $content->object($object, $x, $y, $scale_x, $scale_y)
1450 =head2 object
1451
1452 $content = $content->object($object, $x, $y, $scale_x, $scale_y);
13511453
13521454 Places an image or other external object (a.k.a. XObject) on the page in the
13531455 specified location.
14401542 $self->resource('XObject', $img->name(), $img);
14411543 return $self;
14421544 }
1443
1444 =back
14451545
14461546 =head1 TEXT STATE
14471547
+4
-4
lib/PDF/API2.pm less more
26132613 my $web = $pdf->colorspace('web');
26142614
26152615 # Fill using the spot color with 100% coverage
2616 $gfx->fillcolor($spot, 1.0);
2616 $gfx->fill_color($spot, 1.0);
26172617
26182618 # Stroke using the first color of the web-safe palette
2619 $gfx->strokecolor($web, 0);
2619 $gfx->stroke_color($web, 0);
26202620
26212621 # Add a rectangle to the page
2622 $gfx->rect(100, 100, 100, 100);
2623 $gfx->fillstroke();
2622 $gfx->rectangle(100, 100, 100, 100);
2623 $gfx->paint();
26242624
26252625 $pdf->save('sample.pdf');
26262626