Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/pdf/annot.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 // Copyright (C) 2004-2025 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_PDF_ANNOT_H
24 #define MUPDF_PDF_ANNOT_H
25
26 #include "mupdf/fitz/display-list.h"
27 #include "mupdf/fitz/stream.h"
28 #include "mupdf/fitz/structured-text.h"
29 #include "mupdf/pdf/object.h"
30 #include "mupdf/pdf/page.h"
31
32 typedef struct pdf_annot pdf_annot;
33
34 enum pdf_annot_type
35 {
36 PDF_ANNOT_TEXT,
37 PDF_ANNOT_LINK,
38 PDF_ANNOT_FREE_TEXT,
39 PDF_ANNOT_LINE,
40 PDF_ANNOT_SQUARE,
41 PDF_ANNOT_CIRCLE,
42 PDF_ANNOT_POLYGON,
43 PDF_ANNOT_POLY_LINE,
44 PDF_ANNOT_HIGHLIGHT,
45 PDF_ANNOT_UNDERLINE,
46 PDF_ANNOT_SQUIGGLY,
47 PDF_ANNOT_STRIKE_OUT,
48 PDF_ANNOT_REDACT,
49 PDF_ANNOT_STAMP,
50 PDF_ANNOT_CARET,
51 PDF_ANNOT_INK,
52 PDF_ANNOT_POPUP,
53 PDF_ANNOT_FILE_ATTACHMENT,
54 PDF_ANNOT_SOUND,
55 PDF_ANNOT_MOVIE,
56 PDF_ANNOT_RICH_MEDIA,
57 PDF_ANNOT_WIDGET,
58 PDF_ANNOT_SCREEN,
59 PDF_ANNOT_PRINTER_MARK,
60 PDF_ANNOT_TRAP_NET,
61 PDF_ANNOT_WATERMARK,
62 PDF_ANNOT_3D,
63 PDF_ANNOT_PROJECTION,
64 PDF_ANNOT_UNKNOWN = -1
65 };
66
67 /*
68 Map an annotation type to a (static) string.
69
70 The returned string must not be freed by the caller.
71 */
72 const char *pdf_string_from_annot_type(fz_context *ctx, enum pdf_annot_type type);
73
74 /*
75 Map from a (non-NULL, case sensitive) string to an annotation
76 type.
77 */
78 enum pdf_annot_type pdf_annot_type_from_string(fz_context *ctx, const char *subtype);
79
80 enum
81 {
82 PDF_ANNOT_IS_INVISIBLE = 1 << (1-1),
83 PDF_ANNOT_IS_HIDDEN = 1 << (2-1),
84 PDF_ANNOT_IS_PRINT = 1 << (3-1),
85 PDF_ANNOT_IS_NO_ZOOM = 1 << (4-1),
86 PDF_ANNOT_IS_NO_ROTATE = 1 << (5-1),
87 PDF_ANNOT_IS_NO_VIEW = 1 << (6-1),
88 PDF_ANNOT_IS_READ_ONLY = 1 << (7-1),
89 PDF_ANNOT_IS_LOCKED = 1 << (8-1),
90 PDF_ANNOT_IS_TOGGLE_NO_VIEW = 1 << (9-1),
91 PDF_ANNOT_IS_LOCKED_CONTENTS = 1 << (10-1)
92 };
93
94 enum pdf_line_ending
95 {
96 PDF_ANNOT_LE_NONE = 0,
97 PDF_ANNOT_LE_SQUARE,
98 PDF_ANNOT_LE_CIRCLE,
99 PDF_ANNOT_LE_DIAMOND,
100 PDF_ANNOT_LE_OPEN_ARROW,
101 PDF_ANNOT_LE_CLOSED_ARROW,
102 PDF_ANNOT_LE_BUTT,
103 PDF_ANNOT_LE_R_OPEN_ARROW,
104 PDF_ANNOT_LE_R_CLOSED_ARROW,
105 PDF_ANNOT_LE_SLASH
106 };
107
108 enum
109 {
110 PDF_ANNOT_Q_LEFT = 0,
111 PDF_ANNOT_Q_CENTER = 1,
112 PDF_ANNOT_Q_RIGHT = 2
113 };
114
115 enum pdf_intent
116 {
117 PDF_ANNOT_IT_DEFAULT = 0,
118 PDF_ANNOT_IT_FREETEXT_CALLOUT,
119 PDF_ANNOT_IT_FREETEXT_TYPEWRITER,
120 PDF_ANNOT_IT_LINE_ARROW,
121 PDF_ANNOT_IT_LINE_DIMENSION,
122 PDF_ANNOT_IT_POLYLINE_DIMENSION,
123 PDF_ANNOT_IT_POLYGON_CLOUD,
124 PDF_ANNOT_IT_POLYGON_DIMENSION,
125 PDF_ANNOT_IT_STAMP_IMAGE,
126 PDF_ANNOT_IT_STAMP_SNAPSHOT,
127 PDF_ANNOT_IT_UNKNOWN = 255,
128 };
129
130 const char *pdf_string_from_intent(fz_context *ctx, enum pdf_intent intent);
131 pdf_obj *pdf_name_from_intent(fz_context *ctx, enum pdf_intent intent);
132 enum pdf_intent pdf_intent_from_string(fz_context *ctx, const char *str);
133 enum pdf_intent pdf_intent_from_name(fz_context *ctx, pdf_obj *obj);
134
135 /*
136 Map from a PDF name specifying an annotation line ending
137 to an enumerated line ending value.
138 */
139 enum pdf_line_ending pdf_line_ending_from_name(fz_context *ctx, pdf_obj *end);
140
141 /*
142 Map from a (non-NULL, case sensitive) C string specifying
143 an annotation line ending to an enumerated line ending value.
144 */
145 enum pdf_line_ending pdf_line_ending_from_string(fz_context *ctx, const char *end);
146
147 /*
148 Map from an enumerated line ending to a pdf name object that
149 specifies it.
150 */
151 pdf_obj *pdf_name_from_line_ending(fz_context *ctx, enum pdf_line_ending end);
152
153 /*
154 Map from an enumerated line ending to a C string that specifies
155 it.
156
157 The caller must not free the returned string.
158 */
159 const char *pdf_string_from_line_ending(fz_context *ctx, enum pdf_line_ending end);
160
161 /*
162 Increment the reference count for an annotation.
163
164 Never throws exceptions. Returns the same pointer.
165 */
166 pdf_annot *pdf_keep_annot(fz_context *ctx, pdf_annot *annot);
167
168 /*
169 Drop the reference count for an annotation.
170
171 When the reference count reaches zero, the annotation will
172 be destroyed. Never throws exceptions.
173 */
174 void pdf_drop_annot(fz_context *ctx, pdf_annot *annot);
175
176 /*
177 Returns a borrowed reference to the first annotation on
178 a page, or NULL if none.
179
180 The caller should fz_keep this if it intends to hold the
181 pointer. Unless it fz_keeps it, it must not fz_drop it.
182 */
183 pdf_annot *pdf_first_annot(fz_context *ctx, pdf_page *page);
184
185 /*
186 Returns a borrowed reference to the next annotation
187 on a page, or NULL if none.
188
189 The caller should fz_keep this if it intends to hold the
190 pointer. Unless it fz_keeps it, it must not fz_drop it.
191 */
192 pdf_annot *pdf_next_annot(fz_context *ctx, pdf_annot *annot);
193
194 /*
195 Returns a borrowed reference to the object underlying
196 an annotation.
197
198 The caller should fz_keep this if it intends to hold the
199 pointer. Unless it fz_keeps it, it must not fz_drop it.
200 */
201 pdf_obj *pdf_annot_obj(fz_context *ctx, pdf_annot *annot);
202
203 /*
204 Returns a borrowed reference to the page to which
205 an annotation belongs.
206
207 The caller should fz_keep this if it intends to hold the
208 pointer. Unless it fz_keeps it, it must not fz_drop it.
209 */
210 pdf_page *pdf_annot_page(fz_context *ctx, pdf_annot *annot);
211
212 /*
213 Return the rectangle for an annotation on a page.
214 */
215 fz_rect pdf_bound_annot(fz_context *ctx, pdf_annot *annot);
216
217 enum pdf_annot_type pdf_annot_type(fz_context *ctx, pdf_annot *annot);
218
219 /*
220 Interpret an annotation and render it on a device.
221
222 page: A page loaded by pdf_load_page.
223
224 annot: an annotation.
225
226 dev: Device used for rendering, obtained from fz_new_*_device.
227
228 ctm: A transformation matrix applied to the objects on the page,
229 e.g. to scale or rotate the page contents as desired.
230 */
231 void pdf_run_annot(fz_context *ctx, pdf_annot *annot, fz_device *dev, fz_matrix ctm, fz_cookie *cookie);
232
233 /*
234 Lookup needle in the nametree of the document given by which.
235
236 The returned reference is borrowed, and should not be dropped,
237 unless it is kept first.
238 */
239 pdf_obj *pdf_lookup_name(fz_context *ctx, pdf_document *doc, pdf_obj *which, pdf_obj *needle);
240
241 /*
242 Load a nametree, flattening it into a single dictionary.
243
244 The caller is responsible for pdf_dropping the returned
245 reference.
246 */
247 pdf_obj *pdf_load_name_tree(fz_context *ctx, pdf_document *doc, pdf_obj *which);
248
249 /*
250 Lookup needle in the given number tree.
251
252 The returned reference is borrowed, and should not be dropped,
253 unless it is kept first.
254 */
255 pdf_obj *pdf_lookup_number(fz_context *ctx, pdf_obj *root, int needle);
256
257 /*
258 Perform a depth first traversal of a tree.
259
260 Start at tree, looking for children in the array named
261 kid_name at each level.
262
263 The arrive callback is called when we arrive at a node (i.e.
264 before all the children are walked), and then the leave callback
265 is called as we leave it (after all the children have been
266 walked).
267
268 names and values are (matching) null terminated arrays of
269 names and values to be carried down the tree, to implement
270 inheritance. NULL is a permissible value.
271 */
272 void pdf_walk_tree(fz_context *ctx, pdf_obj *tree, pdf_obj *kid_name,
273 void (*arrive)(fz_context *, pdf_obj *, void *, pdf_obj **),
274 void (*leave)(fz_context *, pdf_obj *, void *),
275 void *arg,
276 pdf_obj **names,
277 pdf_obj **values);
278
279 /*
280 Resolve a link within a document.
281 */
282 int pdf_resolve_link(fz_context *ctx, pdf_document *doc, const char *uri, float *xp, float *yp);
283 fz_link_dest pdf_resolve_link_dest(fz_context *ctx, pdf_document *doc, const char *uri);
284
285 /*
286 Create an action object given a link URI. The action will
287 be a GoTo or URI action depending on whether the link URI
288 specifies a document internal or external destination.
289 */
290 pdf_obj *pdf_new_action_from_link(fz_context *ctx, pdf_document *doc, const char *uri);
291
292 /*
293 Create a destination object given a link URI expected to adhere
294 to the Adobe specification "Parameters for Opening PDF files"
295 from the Adobe Acrobat SDK. The resulting destination object
296 will either be a PDF string, or a PDF array referring to a page
297 and suitable zoom level settings. In the latter case the page
298 can be referred to by PDF object number or by page number, this
299 is controlled by the is_remote argument. For remote destinations
300 it is not possible to refer to the page by object number, so
301 page numbers are used instead.
302 */
303 pdf_obj *pdf_new_dest_from_link(fz_context *ctx, pdf_document *doc, const char *uri, int is_remote);
304
305 /*
306 Create a link URI string according to the Adobe specification
307 "Parameters for Opening PDF files" from the Adobe Acrobat SDK,
308 version 8.1, which can, at the time of writing, be found here:
309
310 https://web.archive.org/web/20170921000830/http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf
311
312 The resulting string must be freed by the caller.
313 */
314 char *pdf_new_uri_from_explicit_dest(fz_context *ctx, fz_link_dest dest);
315
316 /*
317 Create a remote link URI string according to the Adobe specification
318 "Parameters for Opening PDF files" from the Adobe Acrobat SDK,
319 version 8.1, which can, at the time of writing, be found here:
320
321 https://web.archive.org/web/20170921000830/http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf
322
323 The file: URI scheme is used in the resulting URI if the remote document
324 is specified by a system independent path (already taking the recommendations
325 in table 3.40 of the PDF 1.7 specification into account), and either a
326 destination name or a page number and zoom level are appended:
327 file:///path/doc.pdf#page=42&view=FitV,100
328 file:///path/doc.pdf#nameddest=G42.123456
329
330 If a URL is used to specify the remote document, then its scheme takes
331 precedence and either a destination name or a page number and zoom level
332 are appended:
333 ftp://example.com/alpha.pdf#page=42&view=Fit
334 https://example.com/bravo.pdf?query=parameter#page=42&view=Fit
335
336 The resulting string must be freed by the caller.
337 */
338 char *pdf_append_named_dest_to_uri(fz_context *ctx, const char *url, const char *name);
339 char *pdf_append_explicit_dest_to_uri(fz_context *ctx, const char *url, fz_link_dest dest);
340 char *pdf_new_uri_from_path_and_named_dest(fz_context *ctx, const char *path, const char *name);
341 char *pdf_new_uri_from_path_and_explicit_dest(fz_context *ctx, const char *path, fz_link_dest dest);
342
343 /*
344 Create transform to fit appearance stream to annotation Rect
345 */
346 fz_matrix pdf_annot_transform(fz_context *ctx, pdf_annot *annot);
347
348 /*
349 Create a new link object.
350 */
351 fz_link *pdf_new_link(fz_context *ctx, pdf_page *page, fz_rect rect, const char *uri, pdf_obj *obj);
352
353 /*
354 create a new annotation of the specified type on the
355 specified page. The returned pdf_annot structure is owned by the
356 page and does not need to be freed.
357 */
358 pdf_annot *pdf_create_annot_raw(fz_context *ctx, pdf_page *page, enum pdf_annot_type type);
359
360 /*
361 create a new link on the specified page. The returned fz_link
362 structure is owned by the page and does not need to be freed.
363 */
364 fz_link *pdf_create_link(fz_context *ctx, pdf_page *page, fz_rect bbox, const char *uri);
365
366 /*
367 delete an existing link from the specified page.
368 */
369 void pdf_delete_link(fz_context *ctx, pdf_page *page, fz_link *link);
370
371 enum pdf_border_style
372 {
373 PDF_BORDER_STYLE_SOLID = 0,
374 PDF_BORDER_STYLE_DASHED,
375 PDF_BORDER_STYLE_BEVELED,
376 PDF_BORDER_STYLE_INSET,
377 PDF_BORDER_STYLE_UNDERLINE,
378 };
379
380 enum pdf_border_effect
381 {
382 PDF_BORDER_EFFECT_NONE = 0,
383 PDF_BORDER_EFFECT_CLOUDY,
384 };
385
386 /*
387 create a new annotation of the specified type on the
388 specified page. Populate it with sensible defaults per the type.
389
390 Currently this returns a reference that the caller owns, and
391 must drop when finished with it. Up until release 1.18, the
392 returned reference was owned by the page and did not need to
393 be freed.
394 */
395 pdf_annot *pdf_create_annot(fz_context *ctx, pdf_page *page, enum pdf_annot_type type);
396
397 /*
398 Delete an annotation from the page.
399
400 This unlinks the annotation from the page structure and drops
401 the pages reference to it. Any reference held by the caller
402 will not be dropped automatically, so this can safely be used
403 on a borrowed reference.
404 */
405 void pdf_delete_annot(fz_context *ctx, pdf_page *page, pdf_annot *annot);
406
407 /*
408 Edit the associated Popup annotation rectangle.
409
410 Popup annotations are used to store the size and position of the
411 popup box that is used to edit the contents of the markup annotation.
412 */
413 void pdf_set_annot_popup(fz_context *ctx, pdf_annot *annot, fz_rect rect);
414 fz_rect pdf_annot_popup(fz_context *ctx, pdf_annot *annot);
415
416 /*
417 Check to see if an annotation has a rect.
418 */
419 int pdf_annot_has_rect(fz_context *ctx, pdf_annot *annot);
420
421 /*
422 Check to see if an annotation has an ink list.
423 */
424 int pdf_annot_has_ink_list(fz_context *ctx, pdf_annot *annot);
425
426 /*
427 Check to see if an annotation has quad points data.
428 */
429 int pdf_annot_has_quad_points(fz_context *ctx, pdf_annot *annot);
430
431 /*
432 Check to see if an annotation has vertex data.
433 */
434 int pdf_annot_has_vertices(fz_context *ctx, pdf_annot *annot);
435
436 /*
437 Check to see if an annotation has line data.
438 */
439 int pdf_annot_has_line(fz_context *ctx, pdf_annot *annot);
440
441 /*
442 Check to see if an annotation has an interior color.
443 */
444 int pdf_annot_has_interior_color(fz_context *ctx, pdf_annot *annot);
445
446 /*
447 Check to see if an annotation has line ending styles.
448 */
449 int pdf_annot_has_line_ending_styles(fz_context *ctx, pdf_annot *annot);
450
451 /*
452 Check to see if an annotation has quadding.
453 */
454 int pdf_annot_has_quadding(fz_context *ctx, pdf_annot *annot);
455 /*
456 Check to see if an annotation has a border.
457 */
458 int pdf_annot_has_border(fz_context *ctx, pdf_annot *annot);
459
460 /*
461 Check to see if an annotation has a border effect.
462 */
463 int pdf_annot_has_border_effect(fz_context *ctx, pdf_annot *annot);
464
465 /*
466 Check to see if an annotation has an icon name.
467 */
468 int pdf_annot_has_icon_name(fz_context *ctx, pdf_annot *annot);
469
470 /*
471 Check to see if an annotation has an open action.
472 */
473 int pdf_annot_has_open(fz_context *ctx, pdf_annot *annot);
474
475 /*
476 Check to see if an annotation has a popup annotation.
477 */
478 int pdf_annot_has_popup(fz_context *ctx, pdf_annot *annot);
479
480 /*
481 Check to see if an annotation has author data.
482 */
483 int pdf_annot_has_author(fz_context *ctx, pdf_annot *annot);
484
485 /*
486 Check to see if an annotation has rich content.
487 */
488 int pdf_annot_has_rich_contents(fz_context *ctx, pdf_annot *annot);
489
490 /*
491 Check to see if an annotation has rich default styles.
492 */
493 int pdf_annot_has_rich_defaults(fz_context *ctx, pdf_annot *annot);
494
495 /*
496 Retrieve the annotation flags.
497 */
498 int pdf_annot_flags(fz_context *ctx, pdf_annot *annot);
499
500 /*
501 Retrieve the annotation design rectangle in doc space.
502 Note: This is NOT the same as the bounding rectangle.
503 The design rectangle is the bounding rectangle adjusted
504 by the RD padding.
505 */
506 fz_rect pdf_annot_rect(fz_context *ctx, pdf_annot *annot);
507
508 /*
509 Retrieve the annotation border line width in points.
510 DEPRECATED: Use pdf_annot_border_width instead.
511 */
512 float pdf_annot_border(fz_context *ctx, pdf_annot *annot);
513
514 /*
515 Retrieve the annotation border style.
516 */
517 enum pdf_border_style pdf_annot_border_style(fz_context *ctx, pdf_annot *annot);
518
519 /*
520 Retrieve the annotation border width in points.
521 */
522 float pdf_annot_border_width(fz_context *ctx, pdf_annot *annot);
523
524 /*
525 How many items does the annotation border dash pattern have?
526 */
527 int pdf_annot_border_dash_count(fz_context *ctx, pdf_annot *annot);
528
529 /*
530 How long is dash item i in the annotation border dash pattern?
531 */
532 float pdf_annot_border_dash_item(fz_context *ctx, pdf_annot *annot, int i);
533
534 /*
535 Retrieve the annotation border effect.
536 */
537 enum pdf_border_effect pdf_annot_border_effect(fz_context *ctx, pdf_annot *annot);
538
539 /*
540 Retrieve the annotation border effect intensity.
541 */
542 float pdf_annot_border_effect_intensity(fz_context *ctx, pdf_annot *annot);
543
544 /*
545 Retrieve the annotation opacity. (0 transparent, 1 solid).
546 */
547 float pdf_annot_opacity(fz_context *ctx, pdf_annot *annot);
548
549 /*
550 Retrieve the annotation color.
551
552 n components, each between 0 and 1.
553 n = 1 (grey), 3 (rgb) or 4 (cmyk).
554 */
555 void pdf_annot_color(fz_context *ctx, pdf_annot *annot, int *n, float color[4]);
556
557 /*
558 Retrieve the annotation interior color.
559
560 n components, each between 0 and 1.
561 n = 1 (grey), 3 (rgb) or 4 (cmyk).
562 */
563 void pdf_annot_interior_color(fz_context *ctx, pdf_annot *annot, int *n, float color[4]);
564
565 /*
566 Retrieve the annotation quadding (justification) to use.
567 0 = Left-justified
568 1 = Centered
569 2 = Right-justified
570 */
571 int pdf_annot_quadding(fz_context *ctx, pdf_annot *annot);
572
573 /*
574 Retrieve the annotations text language (either from the
575 annotation, or from the document).
576 */
577 fz_text_language pdf_annot_language(fz_context *ctx, pdf_annot *annot);
578
579 /*
580 How many quad points does an annotation have?
581 */
582 int pdf_annot_quad_point_count(fz_context *ctx, pdf_annot *annot);
583
584 /*
585 Get quadpoint i for an annotation.
586 */
587 fz_quad pdf_annot_quad_point(fz_context *ctx, pdf_annot *annot, int i);
588
589 /*
590 How many strokes in the ink list for an annotation?
591 */
592 int pdf_annot_ink_list_count(fz_context *ctx, pdf_annot *annot);
593
594 /*
595 How many vertices in stroke i of the ink list for an annotation?
596 */
597 int pdf_annot_ink_list_stroke_count(fz_context *ctx, pdf_annot *annot, int i);
598
599 /*
600 Get vertex k from stroke i of the ink list for an annotation, in
601 doc space.
602 */
603 fz_point pdf_annot_ink_list_stroke_vertex(fz_context *ctx, pdf_annot *annot, int i, int k);
604
605 /*
606 Set the flags for an annotation.
607 */
608 void pdf_set_annot_flags(fz_context *ctx, pdf_annot *annot, int flags);
609
610 /*
611 Set the stamp appearance to a custom image.
612 */
613 pdf_obj *pdf_annot_stamp_image_obj(fz_context *ctx, pdf_annot *annot);
614 void pdf_set_annot_stamp_image_obj(fz_context *ctx, pdf_annot *annot, pdf_obj *ref);
615 void pdf_set_annot_stamp_image(fz_context *ctx, pdf_annot *annot, fz_image *image);
616
617 /*
618 Set the design rectangle for an annotation, in doc space.
619 */
620 void pdf_set_annot_rect(fz_context *ctx, pdf_annot *annot, fz_rect rect);
621
622 /*
623 Set the border width for an annotation, in points.
624 DEPRECATED: Use pdf_set_annot_border_width instead.
625 */
626 void pdf_set_annot_border(fz_context *ctx, pdf_annot *annot, float width);
627
628 /*
629 Set the border style for an annotation.
630 */
631 void pdf_set_annot_border_style(fz_context *ctx, pdf_annot *annot, enum pdf_border_style style);
632
633 /*
634 Set the border width for an annotation in points;
635 */
636 void pdf_set_annot_border_width(fz_context *ctx, pdf_annot *annot, float width);
637
638 /*
639 Clear the entire border dash pattern for an annotation.
640 */
641 void pdf_clear_annot_border_dash(fz_context *ctx, pdf_annot *annot);
642
643 /*
644 Add an item to the end of the border dash pattern for an annotation.
645 */
646 void pdf_add_annot_border_dash_item(fz_context *ctx, pdf_annot *annot, float length);
647
648 /*
649 Set the border effect for an annotation.
650 */
651 void pdf_set_annot_border_effect(fz_context *ctx, pdf_annot *annot, enum pdf_border_effect effect);
652
653 /*
654 Set the border effect intensity for an annotation.
655 */
656 void pdf_set_annot_border_effect_intensity(fz_context *ctx, pdf_annot *annot, float intensity);
657
658 /*
659 Set the opacity for an annotation, between 0 (transparent) and 1
660 (solid).
661 */
662 void pdf_set_annot_opacity(fz_context *ctx, pdf_annot *annot, float opacity);
663
664 /*
665 Set the annotation color.
666
667 n components, each between 0 and 1.
668 n = 1 (grey), 3 (rgb) or 4 (cmyk).
669 */
670 void pdf_set_annot_color(fz_context *ctx, pdf_annot *annot, int n, const float *color);
671
672 /*
673 Set the annotation interior color.
674
675 n components, each between 0 and 1.
676 n = 1 (grey), 3 (rgb) or 4 (cmyk).
677 */
678 void pdf_set_annot_interior_color(fz_context *ctx, pdf_annot *annot, int n, const float *color);
679
680 /*
681 Set the quadding (justification) to use for the annotation.
682 0 = Left-justified
683 1 = Centered
684 2 = Right-justified
685 */
686 void pdf_set_annot_quadding(fz_context *ctx, pdf_annot *annot, int q);
687
688 /*
689 Set the language for the annotation.
690 */
691 void pdf_set_annot_language(fz_context *ctx, pdf_annot *annot, fz_text_language lang);
692
693 /*
694 Set the quad points for an annotation to those in the qv array
695 of length n.
696 */
697 void pdf_set_annot_quad_points(fz_context *ctx, pdf_annot *annot, int n, const fz_quad *qv);
698
699 /*
700 Clear the quadpoint data for an annotation.
701 */
702 void pdf_clear_annot_quad_points(fz_context *ctx, pdf_annot *annot);
703
704 /*
705 Append a new quad point to the quad point data in an annotation.
706 */
707 void pdf_add_annot_quad_point(fz_context *ctx, pdf_annot *annot, fz_quad quad);
708
709 /*
710 Set the ink list for an annotation.
711
712 n strokes. For 0 <= i < n, stroke i has count[i] points,
713 The vertices for all the strokes are packed into a single
714 array, pointed to by v.
715 */
716 void pdf_set_annot_ink_list(fz_context *ctx, pdf_annot *annot, int n, const int *count, const fz_point *v);
717
718 /*
719 Clear the ink list for an annotation.
720 */
721 void pdf_clear_annot_ink_list(fz_context *ctx, pdf_annot *annot);
722
723 /*
724 Add a new stroke (initially empty) to the ink list for an
725 annotation.
726 */
727 void pdf_add_annot_ink_list_stroke(fz_context *ctx, pdf_annot *annot);
728
729 /*
730 Add a new vertex to the last stroke in the ink list for an
731 annotation.
732 */
733 void pdf_add_annot_ink_list_stroke_vertex(fz_context *ctx, pdf_annot *annot, fz_point p);
734
735 /*
736 Add a new stroke to the ink list for an annotation, and
737 populate it with the n points from stroke[].
738 */
739 void pdf_add_annot_ink_list(fz_context *ctx, pdf_annot *annot, int n, fz_point stroke[]);
740
741 /*
742
743 */
744 void pdf_set_annot_icon_name(fz_context *ctx, pdf_annot *annot, const char *name);
745 void pdf_set_annot_is_open(fz_context *ctx, pdf_annot *annot, int is_open);
746
747 enum pdf_line_ending pdf_annot_line_start_style(fz_context *ctx, pdf_annot *annot);
748 enum pdf_line_ending pdf_annot_line_end_style(fz_context *ctx, pdf_annot *annot);
749 void pdf_annot_line_ending_styles(fz_context *ctx, pdf_annot *annot, enum pdf_line_ending *start_style, enum pdf_line_ending *end_style);
750 void pdf_set_annot_line_start_style(fz_context *ctx, pdf_annot *annot, enum pdf_line_ending s);
751 void pdf_set_annot_line_end_style(fz_context *ctx, pdf_annot *annot, enum pdf_line_ending e);
752 void pdf_set_annot_line_ending_styles(fz_context *ctx, pdf_annot *annot, enum pdf_line_ending start_style, enum pdf_line_ending end_style);
753
754 const char *pdf_annot_icon_name(fz_context *ctx, pdf_annot *annot);
755 int pdf_annot_is_open(fz_context *ctx, pdf_annot *annot);
756 int pdf_annot_is_standard_stamp(fz_context *ctx, pdf_annot *annot);
757
758 void pdf_annot_line(fz_context *ctx, pdf_annot *annot, fz_point *a, fz_point *b);
759 void pdf_set_annot_line(fz_context *ctx, pdf_annot *annot, fz_point a, fz_point b);
760
761 float pdf_annot_line_leader(fz_context *ctx, pdf_annot *annot);
762 float pdf_annot_line_leader_extension(fz_context *ctx, pdf_annot *annot);
763 float pdf_annot_line_leader_offset(fz_context *ctx, pdf_annot *annot);
764 void pdf_set_annot_line_leader(fz_context *ctx, pdf_annot *annot, float ll);
765 void pdf_set_annot_line_leader_extension(fz_context *ctx, pdf_annot *annot, float lle);
766 void pdf_set_annot_line_leader_offset(fz_context *ctx, pdf_annot *annot, float llo);
767
768 int pdf_annot_line_caption(fz_context *ctx, pdf_annot *annot);
769 void pdf_set_annot_line_caption(fz_context *ctx, pdf_annot *annot, int cap);
770 fz_point pdf_annot_line_caption_offset(fz_context *ctx, pdf_annot *annot);
771 void pdf_set_annot_line_caption_offset(fz_context *ctx, pdf_annot *annot, fz_point offset);
772
773 int pdf_annot_vertex_count(fz_context *ctx, pdf_annot *annot);
774 fz_point pdf_annot_vertex(fz_context *ctx, pdf_annot *annot, int i);
775
776 void pdf_set_annot_vertices(fz_context *ctx, pdf_annot *annot, int n, const fz_point *v);
777 void pdf_clear_annot_vertices(fz_context *ctx, pdf_annot *annot);
778 void pdf_add_annot_vertex(fz_context *ctx, pdf_annot *annot, fz_point p);
779 void pdf_set_annot_vertex(fz_context *ctx, pdf_annot *annot, int i, fz_point p);
780
781 const char *pdf_annot_contents(fz_context *ctx, pdf_annot *annot);
782 void pdf_set_annot_contents(fz_context *ctx, pdf_annot *annot, const char *text);
783
784 const char *pdf_annot_author(fz_context *ctx, pdf_annot *annot);
785 void pdf_set_annot_author(fz_context *ctx, pdf_annot *annot, const char *author);
786
787 int64_t pdf_annot_modification_date(fz_context *ctx, pdf_annot *annot);
788 void pdf_set_annot_modification_date(fz_context *ctx, pdf_annot *annot, int64_t time);
789 int64_t pdf_annot_creation_date(fz_context *ctx, pdf_annot *annot);
790 void pdf_set_annot_creation_date(fz_context *ctx, pdf_annot *annot, int64_t time);
791
792 int pdf_annot_has_intent(fz_context *ctx, pdf_annot *annot);
793 enum pdf_intent pdf_annot_intent(fz_context *ctx, pdf_annot *annot);
794 void pdf_set_annot_intent(fz_context *ctx, pdf_annot *annot, enum pdf_intent it);
795
796 int pdf_annot_has_callout(fz_context *ctx, pdf_annot *annot);
797 enum pdf_line_ending pdf_annot_callout_style(fz_context *ctx, pdf_annot *annot);
798 void pdf_set_annot_callout_style(fz_context *ctx, pdf_annot *annot, enum pdf_line_ending style);
799 void pdf_annot_callout_line(fz_context *ctx, pdf_annot *annot, fz_point callout[3], int *n);
800 void pdf_set_annot_callout_line(fz_context *ctx, pdf_annot *annot, fz_point callout[3], int n);
801 fz_point pdf_annot_callout_point(fz_context *ctx, pdf_annot *annot);
802 void pdf_set_annot_callout_point(fz_context *ctx, pdf_annot *annot, fz_point p);
803
804 int pdf_annot_has_default_appearance(fz_context *ctx, pdf_annot *annot);
805 void pdf_parse_default_appearance_unmapped(fz_context *ctx, const char *da, char *font_name, int font_name_len, float *size, int *n, float color[4]);
806 void pdf_parse_default_appearance(fz_context *ctx, const char *da, const char **font, float *size, int *n, float color[4]);
807 void pdf_print_default_appearance(fz_context *ctx, char *buf, int nbuf, const char *font, float size, int n, const float *color);
808 void pdf_annot_default_appearance_unmapped(fz_context *ctx, pdf_annot *annot, char *font_name, int font_name_len, float *size, int *n, float color[4]);
809 void pdf_annot_default_appearance(fz_context *ctx, pdf_annot *annot, const char **font, float *size, int *n, float color[4]);
810 void pdf_set_annot_default_appearance(fz_context *ctx, pdf_annot *annot, const char *font, float size, int n, const float *color);
811
812 const char *pdf_annot_rich_contents(fz_context *ctx, pdf_annot *annot);
813 void pdf_set_annot_rich_contents(fz_context *ctx, pdf_annot *annot, const char *plain, const char *rich);
814 const char *pdf_annot_rich_defaults(fz_context *ctx, pdf_annot *annot);
815 void pdf_set_annot_rich_defaults(fz_context *ctx, pdf_annot *annot, const char *style);
816
817 /*
818 * Request that an appearance stream should be generated for an annotation if none is present.
819 * It will be created in future calls to pdf_update_annot or pdf_update_page.
820 */
821 void pdf_annot_request_synthesis(fz_context *ctx, pdf_annot *annot);
822
823 /*
824 * Request that an appearance stream should be re-generated for an annotation
825 * the next time pdf_annot_update or pdf_page_update is called.
826 * You usually won't need to call this, because changing any annotation attributes
827 * via the pdf_annot functions will do so automatically.
828 * It will be created in future calls to pdf_update_annot or pdf_update_page.
829 */
830 void pdf_annot_request_resynthesis(fz_context *ctx, pdf_annot *annot);
831
832 int pdf_annot_needs_resynthesis(fz_context *ctx, pdf_annot *annot);
833 void pdf_set_annot_resynthesised(fz_context *ctx, pdf_annot *annot);
834 void pdf_dirty_annot(fz_context *ctx, pdf_annot *annot);
835
836 int pdf_annot_field_flags(fz_context *ctx, pdf_annot *annot);
837 const char *pdf_annot_field_value(fz_context *ctx, pdf_annot *annot);
838 const char *pdf_annot_field_label(fz_context *ctx, pdf_annot *widget);
839
840 int pdf_set_annot_field_value(fz_context *ctx, pdf_document *doc, pdf_annot *widget, const char *text, int ignore_trigger_events);
841
842 /*
843 Recreate the appearance stream for an annotation, if necessary.
844 */
845 fz_text *pdf_layout_fit_text(fz_context *ctx, fz_font *font, fz_text_language lang, const char *str, fz_rect bounds);
846
847 /*
848 Start/Stop using the annotation-local xref. This allows us to
849 generate appearance streams that don't actually hit the underlying
850 document.
851 */
852 void pdf_annot_push_local_xref(fz_context *ctx, pdf_annot *annot);
853 void pdf_annot_pop_local_xref(fz_context *ctx, pdf_annot *annot);
854 void pdf_annot_ensure_local_xref(fz_context *ctx, pdf_annot *annot);
855 void pdf_annot_pop_and_discard_local_xref(fz_context *ctx, pdf_annot *annot);
856
857 /*
858 Regenerate any appearance streams that are out of date and check for
859 cases where a different appearance stream should be selected because of
860 state changes.
861
862 Note that a call to pdf_pass_event for one page may lead to changes on
863 any other, so an app should call pdf_update_annot for every annotation
864 it currently displays. Also it is important that the pdf_annot object
865 is the one used to last render the annotation. If instead the app were
866 to drop the page or annotations and reload them then a call to
867 pdf_update_annot would not reliably be able to report all changed
868 annotations.
869
870 Returns true if the annotation appearance has changed since the last time
871 pdf_update_annot was called or the annotation was first loaded.
872 */
873 int pdf_update_annot(fz_context *ctx, pdf_annot *annot);
874
875 /*
876 Recalculate form fields if necessary.
877
878 Loop through all annotations on the page and update them. Return true
879 if any of them were changed (by either event or javascript actions, or
880 by annotation editing) and need re-rendering.
881
882 If you need more granularity, loop through the annotations and call
883 pdf_update_annot for each one to detect changes on a per-annotation
884 basis.
885 */
886 int pdf_update_page(fz_context *ctx, pdf_page *page);
887
888 /*
889 Update internal state appropriate for editing this field. When editing
890 is true, updating the text of the text widget will not have any
891 side-effects such as changing other widgets or running javascript.
892 This state is intended for the period when a text widget is having
893 characters typed into it. The state should be reverted at the end of
894 the edit sequence and the text newly updated.
895 */
896 void pdf_set_widget_editing_state(fz_context *ctx, pdf_annot *widget, int editing);
897
898 int pdf_get_widget_editing_state(fz_context *ctx, pdf_annot *widget);
899
900 /*
901 Toggle the state of a specified annotation. Applies only to check-box
902 and radio-button widgets.
903 */
904 int pdf_toggle_widget(fz_context *ctx, pdf_annot *widget);
905
906 fz_display_list *pdf_new_display_list_from_annot(fz_context *ctx, pdf_annot *annot);
907
908 /*
909 Render an annotation suitable for blending on top of the opaque
910 pixmap returned by fz_new_pixmap_from_page_contents.
911 */
912 fz_pixmap *pdf_new_pixmap_from_annot(fz_context *ctx, pdf_annot *annot, fz_matrix ctm, fz_colorspace *cs, fz_separations *seps, int alpha);
913 fz_stext_page *pdf_new_stext_page_from_annot(fz_context *ctx, pdf_annot *annot, const fz_stext_options *options);
914
915 fz_layout_block *pdf_layout_text_widget(fz_context *ctx, pdf_annot *annot);
916
917 /*
918 Parameters for and embedded file. Obtained through
919 pdf_get_filespec_params(). The creation and
920 modification date fields are < 0 if unknown.
921 */
922 typedef struct pdf_filespec_params {
923 const char *filename;
924 const char *mimetype;
925 int size;
926 int64_t created;
927 int64_t modified;
928 } pdf_filespec_params;
929
930 /*
931 Check if pdf object is a file specification.
932 */
933 int pdf_is_filespec(fz_context *ctx, pdf_obj *fs);
934
935 /*
936 Check if pdf object is a file specification where the data
937 is embedded within the PDF file.
938 */
939 int pdf_is_embedded_file(fz_context *ctx, pdf_obj *fs);
940
941 /*
942 Add an embedded file to the document. This can later
943 be passed e.g. to pdf_annot_set_filespec(). If unknown,
944 supply NULL for MIME type and -1 for the date arguments.
945 If a checksum is added it can later be verified by calling
946 pdf_verify_embedded_file_checksum().
947 */
948 pdf_obj *pdf_add_embedded_file(fz_context *ctx, pdf_document *doc, const char *filename, const char *mimetype, fz_buffer *contents, int64_t created, int64_t modified, int add_checksum);
949
950 /*
951 Obtain parameters for a filespec: name, size,
952 creation and modification dates and MIME type.
953 */
954 void pdf_get_filespec_params(fz_context *ctx, pdf_obj *fs, pdf_filespec_params *out);
955
956 /*
957 Load embedded file contents in a buffer which
958 needs to be dropped by the called after use.
959 */
960 fz_buffer *pdf_load_embedded_file_contents(fz_context *ctx, pdf_obj *fs);
961
962 /*
963 Verifies the embedded file checksum. Returns 1
964 if the verification is successful or there is no
965 checksum to be verified, or 0 if verification fails.
966 */
967 int pdf_verify_embedded_file_checksum(fz_context *ctx, pdf_obj *fs);
968
969 pdf_obj *pdf_lookup_dest(fz_context *ctx, pdf_document *doc, pdf_obj *needle);
970 fz_link *pdf_load_link_annots(fz_context *ctx, pdf_document *, pdf_page *, pdf_obj *annots, int pagenum, fz_matrix page_ctm);
971
972 void pdf_annot_MK_BG(fz_context *ctx, pdf_annot *annot, int *n, float color[4]);
973 void pdf_annot_MK_BC(fz_context *ctx, pdf_annot *annot, int *n, float color[4]);
974 int pdf_annot_MK_BG_rgb(fz_context *ctx, pdf_annot *annot, float rgb[3]);
975 int pdf_annot_MK_BC_rgb(fz_context *ctx, pdf_annot *annot, float rgb[3]);
976
977 pdf_obj *pdf_annot_ap(fz_context *ctx, pdf_annot *annot);
978
979 int pdf_annot_active(fz_context *ctx, pdf_annot *annot);
980 void pdf_set_annot_active(fz_context *ctx, pdf_annot *annot, int active);
981 int pdf_annot_hot(fz_context *ctx, pdf_annot *annot);
982 void pdf_set_annot_hot(fz_context *ctx, pdf_annot *annot, int hot);
983
984 void pdf_set_annot_appearance(fz_context *ctx, pdf_annot *annot, const char *appearance, const char *state, fz_matrix ctm, fz_rect bbox, pdf_obj *res, fz_buffer *contents);
985 void pdf_set_annot_appearance_from_display_list(fz_context *ctx, pdf_annot *annot, const char *appearance, const char *state, fz_matrix ctm, fz_display_list *list);
986
987 /*
988 Check to see if an annotation has a file specification.
989 */
990 int pdf_annot_has_filespec(fz_context *ctx, pdf_annot *annot);
991
992 /*
993 Retrieve the file specification for the given annotation.
994 */
995 pdf_obj *pdf_annot_filespec(fz_context *ctx, pdf_annot *annot);
996
997 /*
998 Set the annotation file specification.
999 */
1000 void pdf_set_annot_filespec(fz_context *ctx, pdf_annot *annot, pdf_obj *obj);
1001
1002 /*
1003 Get/set a hidden flag preventing the annotation from being
1004 rendered when it is being edited. This flag is independent
1005 of the hidden flag in the PDF annotation object described in the PDF specification.
1006 */
1007 int pdf_annot_hidden_for_editing(fz_context *ctx, pdf_annot *annot);
1008 void pdf_set_annot_hidden_for_editing(fz_context *ctx, pdf_annot *annot, int hidden);
1009
1010 /*
1011 * Apply Redaction annotation by redacting page underneath and removing the annotation.
1012 */
1013 int pdf_apply_redaction(fz_context *ctx, pdf_annot *annot, pdf_redact_options *opts);
1014
1015 #endif