API2/Annotation.pm

filter: Statementstmt 58.4% 90 / 154 Branchbran 21.6% 13 / 60 Conditioncond 22.2% 2 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 73.9% 17 / 23 Podpod 64.7% 11 / 17 totaltotal 49.4% 133 / 269 CC 34 SCAR 36.3
CC
34
Cov
47%
dest
156.0
link
12.6
pdf
11.0
CRAP 37.9
« API2/NamedDestination.pm ↑ Summary API2/Resource/CIDFont/CJKFont.pm »
1 package PDF::API2::Annotation;
2  
3 2 ▶use base 'PDF::API2::Basic::PDF::Dict';
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 2 our $VERSION = '2.049'; # VERSION
9  
10 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 2 ▶use PDF::API2::Basic::PDF::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 =head1 NAME
14  
15 PDF::API2::Annotation - Add annotations to a PDF
16  
17 =head1 SYNOPSIS
18  
19 my $pdf = PDF::API2->new();
20 my $font = $pdf->font('Helvetica');
21 my $page1 = $pdf->page();
22 my $page2 = $pdf->page();
23  
24 my $content = $page1->text();
25 my $message = 'Go to Page 2';
26 my $size = 18;
27 $content->distance(1 * 72, 9 * 72);
28 $content->font($font, $size);
29 $content->text($message);
30  
31 my $annotation = $page1->annotation();
32 my $width = $content->text_width($message);
33 $annotation->rect(1 * 72, 9 * 72, 1 * 72 + $width, 9 * 72 + $size);
34 $annotation->link($page2);
35  
36 $pdf->save('sample.pdf');
37  
38 =head1 METHODS
39  
40 =cut
41  
42 6 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
43 6 my $class = shift();
44 6 my $self = $class->SUPER::new();
45 6 $self->{'Type'} = PDFName('Annot');
46 6 $self->{'Border'} = PDFArray(PDFNum(0), PDFNum(0), PDFNum(0));
47 6 return $self;
48 }
49  
50 =head2 Annotation Types
51  
52 =head3 link
53  
54 $annotation = $annotation->link($destination, $location, @args);
55  
56 Link the annotation to another page in this PDF. C<$location> and C<@args> are
57 optional and set which part of the page should be displayed, as defined in
58 L<PDF::API2::NamedDestination/"destination">.
59  
60 C<$destination> can be either a L<PDF::API2::Page> object or the name of a named
61 destination defined elsewhere.
62  
63 =cut
64  
65 1 ▶sub link {
Subroutine link: called CC=7 SCAR=25.3
Pod documented
66 1 my $self = shift();
67 1 my $destination = shift();
68  
69 1 my $location;
70 my @args;
71  
72 # Deprecated options
73 1 my %options;
74 1 ▶ if ($_[0] and $_[0] =~ /^-/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] and $_[0] =~ /^-/) { } 0 1 1
Condition33%1/3
$_[0] and $_[0] =~ /^-/
!ll&&!rl&&r
100
MC/DC0%0/2
$_[0] and $_[0] =~ /^-/
$_[0] $_[0] =~ /^-/
Truth table33%1/3
A and B
A= $_[0]B= $_[0] =~ /^-/
ABresult
0X0
100
111
75 0 %options = @_;
76 }
77 else {
78 1 $location = shift();
79 1 @args = @_;
80 }
81  
82 1 $self->{'Subtype'} = PDFName('Link');
83 1 ▶ unless (ref($destination)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $destination) 0 1 1
84 0 $self->{'Dest'} = PDFStr($destination);
85 0 return $self;
86 }
87  
88 1 $self->{'A'} = PDFDict();
89 1 $self->{'A'}->{'S'} = PDFName('GoTo');
90  
91 1 ▶ unless (%options) {
Branch: 1 branch
BranchTrueFalseTotal
if (%options) { } 0 1 1
92 1 $self->{'A'}->{'D'} = _destination($destination, $location, @args);
93 }
94 else {
95 # Deprecated
96 0 $self->dest($destination, %options);
97 0 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 0 0 0
98 0 ▶ $self->border(@{$options{'-border'}}) if defined $options{'-border'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-border"} 0 0 0
99 }
100  
101 1 return $self;
102 }
103  
104 2 ▶sub _destination {
Subroutine _destination: called CC=1 SCAR=0.0
105 2 require PDF::API2::NamedDestination;
106 2 return PDF::API2::NamedDestination::_destination(@_);
107 }
108  
109 =head3 url
110  
111 $annotation = $annotation->uri($uri);
112  
113 Launch C<$uri> -- typically a web page -- when the annotation is selected.
114  
115 =cut
116  
117 # Deprecated (renamed)
118 1 ▶sub url { return uri(@_) }
Subroutine url: called CC=1 SCAR=0.0
Pod documented
119  
120 1 ▶sub uri {
Subroutine uri: called CC=3 SCAR=11.7
Pod undocumented
121 1 my ($self, $uri, %options) = @_;
122  
123 1 $self->{'Subtype'} = PDFName('Link');
124 1 $self->{'A'} = PDFDict();
125 1 $self->{'A'}->{'S'} = PDFName('URI');
126 1 $self->{'A'}->{'URI'} = PDFStr($uri);
127  
128 # Deprecated
129 0 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 0 1 1
130 0 ▶ $self->border(@{$options{'-border'}}) if defined $options{'-border'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-border"} 0 1 1
131  
132 1 return $self;
133 }
134  
135 =head3 file
136  
137 $annotation = $annotation->launch($file);
138  
139 Open C<$file> when the annotation is selected.
140  
141 =cut
142  
143 1 ▶sub file { return launch(@_) }
Subroutine file: called CC=1 SCAR=0.0
Pod documented
144  
145 1 ▶sub launch {
Subroutine launch: called CC=3 SCAR=11.7
Pod undocumented
146 1 my ($self, $file, %options) = @_;
147 1 $self->{'Subtype'} = PDFName('Link');
148 1 $self->{'A'} = PDFDict();
149 1 $self->{'A'}->{'S'} = PDFName('Launch');
150 1 $self->{'A'}->{'F'} = PDFStr($file);
151  
152 # Deprecated
153 0 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 0 1 1
154 0 ▶ $self->border(@{$options{'-border'}}) if defined $options{'-border'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-border"} 0 1 1
155  
156 1 return $self;
157 }
158  
159 =head3 pdf
160  
161 $annotation = $annotation->pdf($file, $dest, $location, @args);
162  
163 Open the PDF file located at C<$file> to the specified destination.
164 C<$location> and C<@args> are optional and set which part of the page should be
165 displayed, as defined in L<PDF::API2::NamedDestination/"destination">.
166  
167 C<$dest> can be a page number, or a named destination prefixed with C<#>.
168  
169 =cut
170  
171 # Deprecated
172 0 ▶sub pdfile { return pdf_file(@_) }
Subroutine pdfile: not called CC=1 SCAR=6.9
Pod undocumented
173 1 ▶sub pdf_file { return pdf(@_) }
Subroutine pdf_file: called CC=1 SCAR=0.0
Pod undocumented
174  
175 1 ▶sub pdf {
Subroutine pdf: called CC=7 SCAR=23.9
Pod documented
176 1 my $self = shift();
177 1 my $file = shift();
178 1 my $dest = shift();
179 1 my $location;
180 my @args;
181  
182 # Deprecated options
183 1 my %options;
184 1 ▶ if ($_[0] and $_[0] =~ /^-/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] and $_[0] =~ /^-/) { } 0 1 1
Condition33%1/3
$_[0] and $_[0] =~ /^-/
!ll&&!rl&&r
100
MC/DC0%0/2
$_[0] and $_[0] =~ /^-/
$_[0] $_[0] =~ /^-/
Truth table33%1/3
A and B
A= $_[0]B= $_[0] =~ /^-/
ABresult
0X0
100
111
185 0 %options = @_;
186 }
187 else {
188 1 $location = shift();
189 1 @args = @_;
190 }
191  
192 1 $self->{'Subtype'} = PDFName('Link');
193 1 $self->{'A'} = PDFDict();
194 1 $self->{'A'}->{'S'} = PDFName('GoToR');
195 1 $self->{'A'}->{'F'} = PDFStr($file);
196  
197 1 ▶ unless (%options) {
Branch: 1 branch
BranchTrueFalseTotal
if (%options) { } 0 1 1
198 1 ▶ if ( $dest =~ /^\/(.+)/ ) { # named dest
Branch: 1 branch
BranchTrueFalseTotal
if ($dest =~ m[^/(.+)]) { } 0 1 1
199 0 $self->{'A'}->{'D'} = PDFName($1);
200 }
201 else {
202 1 my $page_number = PDFNum($dest);
203 1 $self->{'A'}->{'D'} = _destination($page_number, $location, @args);
204 }
205 }
206 else {
207 # Deprecated
208 0 $self->dest(PDFNum($dest), %options);
209 0 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 0 0 0
210 0 ▶ $self->border(@{$options{'-border'}}) if defined $options{'-border'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-border"} 0 0 0
211 }
212  
213 1 return $self;
214 }
215  
216 =head3 text
217  
218 $annotation = $annotation->text($text);
219  
220 Define the annotation as a text note with the specified content.
221  
222 =cut
223  
224 2 ▶sub text {
Subroutine text: called CC=3 SCAR=11.2
Pod documented
225 2 my ($self, $text, %options) = @_;
226 2 $self->{'Subtype'} = PDFName('Text');
227 2 $self->content($text);
228  
229 # Deprecated
230 2 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 2 0 2
231 2 ▶ $self->open($options{'-open'}) if defined $options{'-open'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-open"} 0 2 2
232  
233 2 return $self;
234 }
235  
236 =head3 movie
237  
238 $annotation = $annotation->movie($filename, $content_type);
239  
240 Embed and link to the movie located at $filename with the specified MIME type.
241  
242 =cut
243  
244 0 ▶sub movie {
Subroutine movie: not called CC=2 SCAR=17.9
Pod documented
245 0 my ($self, $file, $content_type, %options) = @_;
246 0 $self->{'Subtype'} = PDFName('Movie');
247 0 $self->{'A'} = PDFBool(1);
248 0 $self->{'Movie'} = PDFDict();
249 0 $self->{'Movie'}->{'F'} = PDFDict();
250  
251 0 $self->{' apipdf'}->new_obj($self->{'Movie'}->{'F'});
252 0 my $f = $self->{'Movie'}->{'F'};
253 0 $f->{'Type'} = PDFName('EmbeddedFile');
254 0 $f->{'Subtype'} = PDFName($content_type);
255 0 $f->{' streamfile'} = $file;
256  
257 # Deprecated
258 0 ▶ $self->rect(@{$options{'-rect'}}) if defined $options{'-rect'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"-rect"} 0 0 0
259  
260 0 return $self;
261 }
262  
263 =head2 Common Annotation Attributes
264  
265 =head3 rect
266  
267 $annotation = $annotation->rect($llx, $lly, $urx, $ury);
268  
269 Define the rectangle around the annotation.
270  
271 =cut
272  
273 2 ▶sub rect {
Subroutine rect: called CC=2 SCAR=7.2
Pod documented
274 2 my ($self, @coordinates) = @_;
275 2 ▶ unless (scalar @coordinates == 4) {
Branch: 1 branch
BranchTrueFalseTotal
unless (scalar @coordinates == 4) 0 2 2
276 0 die "Incorrect number of parameters (expected four) for rectangle";
277 }
278 2 $self->{'Rect'} = PDFArray(map { PDFNum($_) } @coordinates);
279 2 return $self;
280 }
281  
282 =head3 border
283  
284 $annotation = $annotation->border($h_radius, $v_radius, $width);
285  
286 Define the border style. Defaults to 0, 0, 0 (no border).
287  
288 =cut
289  
290 0 ▶sub border {
Subroutine border: not called CC=2 SCAR=17.9
Pod documented
291 0 my ($self, @attributes) = @_;
292 0 ▶ unless (scalar @attributes == 3) {
Branch: 1 branch
BranchTrueFalseTotal
unless (scalar @attributes == 3) 0 0 0
293 0 croak "Incorrect number of parameters (expected three) for border";
294 }
295 0 $self->{'Border'} = PDFArray(map { PDFNum($_) } @attributes);
296 0 return $self;
297 }
298  
299 =head3 content
300  
301 $annotation = $annotation->content(@lines);
302  
303 Define the text content of the annotation, if applicable.
304  
305 =cut
306  
307 2 ▶sub content {
Subroutine content: called CC=1 SCAR=0.0
Pod documented
308 2 my ($self, @lines) = @_;
309 2 my $text = join("\n", @lines);
310 2 $self->{'Contents'} = PDFStr($text);
311 2 return $self;
312 }
313  
314 0 ▶sub name {
Subroutine name: not called CC=1 SCAR=6.9
Pod undocumented
315 0 my ($self, $name) = @_;
316 0 $self->{'Name'} = PDFName($name);
317 0 return $self;
318 }
319  
320 =head3 open
321  
322 $annotation = $annotation->open($boolean);
323  
324 Set the annotation to initially be either open or closed. Only relevant for
325 text annotations.
326  
327 =cut
328  
329 0 ▶sub open {
Subroutine open: not called CC=2 SCAR=17.9
Pod documented
330 0 my ($self, $value) = @_;
331 0 ▶ $self->{'Open'} = PDFBool($value ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$value ? : 0 0 0
332 0 return $self;
333 }
334  
335 0 ▶sub dest {
Subroutine dest: not called CC=12 SCAR=50.5
Pod undocumented
336 0 my ($self, $page, %options) = @_;
337  
338 0 ▶ unless (ref($page)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $page) 0 0 0
339 0 $self->{'Dest'} = PDFStr($page);
340 0 return $self;
341 }
342  
343 0 ▶ $self->{'A'} //= PDFDict();
Condition0%0/3
$self->{"A"} //= PDFDict()
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{"A"} //= PDFDict()
$self->{"A"} PDFDict()
Truth table0%0/3
A //= B
A= $self->{"A"}B= PDFDict()
ABresult
1X1
011
000
344 0 ▶ $options{'-xyz'} = [undef, undef, undef] unless keys %options;
Branch: 1 branch
BranchTrueFalseTotal
unless keys %options 0 0 0
345  
346 0 ▶ if (defined $options{'-fit'}) {
Branch: 8 branches
BranchTrueFalseTotal
if (defined $options{'-fit'}) { } 0 0 0
elsif (defined $options{'-fith'}) { } 0 0 0
elsif (defined $options{'-fitb'}) { } 0 0 0
elsif (defined $options{'-fitbh'}) { } 0 0 0
elsif (defined $options{'-fitv'}) { } 0 0 0
elsif (defined $options{'-fitbv'}) { } 0 0 0
elsif (defined $options{'-fitr'}) { } 0 0 0
elsif (defined $options{'-xyz'}) { } 0 0 0
347 0 $self->{'A'}->{'D'} = _destination($page, 'fit');
348 }
349 elsif (defined $options{'-fith'}) {
350 0 $self->{'A'}->{'D'} = _destination($page, 'fith', $options{'-fith'});
351 }
352 elsif (defined $options{'-fitb'}) {
353 0 $self->{'A'}->{'D'} = _destination($page, 'fitb');
354 }
355 elsif (defined $options{'-fitbh'}) {
356 0 $self->{'A'}->{'D'} = _destination($page, 'fitbh', $options{'-fitbh'});
357 }
358 elsif (defined $options{'-fitv'}) {
359 0 $self->{'A'}->{'D'} = _destination($page, 'fitv', $options{'-fitv'});
360 }
361 elsif (defined $options{'-fitbv'}) {
362 0 $self->{'A'}->{'D'} = _destination($page, 'fitbv', $options{'-fitbv'});
363 }
364 elsif (defined $options{'-fitr'}) {
365 0 $self->{'A'}->{'D'} = _destination($page, 'fitr', @{$options{'-fitr'}});
366 }
367 elsif (defined $options{'-xyz'}) {
368 0 $self->{'A'}->{'D'} = _destination($page, 'xyz', @{$options{'-xyz'}});
369 }
370  
371 0 return $self;
372 }
373  
374 2 1;
« API2/NamedDestination.pm ↑ Summary API2/Resource/CIDFont/CJKFont.pm »