Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/pdf/form.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_FORM_H
24 #define MUPDF_PDF_FORM_H
25
26 #include "mupdf/fitz/display-list.h"
27 #include "mupdf/pdf/document.h"
28
29 /* Types of widget */
30 enum pdf_widget_type
31 {
32 PDF_WIDGET_TYPE_UNKNOWN,
33 PDF_WIDGET_TYPE_BUTTON,
34 PDF_WIDGET_TYPE_CHECKBOX,
35 PDF_WIDGET_TYPE_COMBOBOX,
36 PDF_WIDGET_TYPE_LISTBOX,
37 PDF_WIDGET_TYPE_RADIOBUTTON,
38 PDF_WIDGET_TYPE_SIGNATURE,
39 PDF_WIDGET_TYPE_TEXT,
40 };
41
42 /* Types of text widget content */
43 enum pdf_widget_tx_format
44 {
45 PDF_WIDGET_TX_FORMAT_NONE,
46 PDF_WIDGET_TX_FORMAT_NUMBER,
47 PDF_WIDGET_TX_FORMAT_SPECIAL,
48 PDF_WIDGET_TX_FORMAT_DATE,
49 PDF_WIDGET_TX_FORMAT_TIME
50 };
51
52 pdf_annot *pdf_keep_widget(fz_context *ctx, pdf_annot *widget);
53 void pdf_drop_widget(fz_context *ctx, pdf_annot *widget);
54 pdf_annot *pdf_first_widget(fz_context *ctx, pdf_page *page);
55 pdf_annot *pdf_next_widget(fz_context *ctx, pdf_annot *previous);
56 int pdf_update_widget(fz_context *ctx, pdf_annot *widget);
57
58 /*
59 create a new signature widget on the specified page, with the
60 specified name.
61
62 The returns pdf_annot reference must be dropped by the caller.
63 This is a change from releases up to an including 1.18, where
64 the returned reference was owned by the page and did not need
65 to be freed by the caller.
66 */
67 pdf_annot *pdf_create_signature_widget(fz_context *ctx, pdf_page *page, char *name);
68
69 enum pdf_widget_type pdf_widget_type(fz_context *ctx, pdf_annot *widget);
70
71 fz_rect pdf_bound_widget(fz_context *ctx, pdf_annot *widget);
72
73 /*
74 get the maximum number of
75 characters permitted in a text widget
76 */
77 int pdf_text_widget_max_len(fz_context *ctx, pdf_annot *tw);
78
79 /*
80 get the type of content
81 required by a text widget
82 */
83 int pdf_text_widget_format(fz_context *ctx, pdf_annot *tw);
84
85 /*
86 get the list of options for a list box or combo box.
87
88 Returns the number of options and fills in their
89 names within the supplied array. Should first be called with a
90 NULL array to find out how big the array should be. If exportval
91 is true, then the export values will be returned and not the list
92 values if there are export values present.
93 */
94 int pdf_choice_widget_options(fz_context *ctx, pdf_annot *tw, int exportval, const char *opts[]);
95 int pdf_choice_widget_is_multiselect(fz_context *ctx, pdf_annot *tw);
96
97 /*
98 get the value of a choice widget.
99
100 Returns the number of options currently selected and fills in
101 the supplied array with their strings. Should first be called
102 with NULL as the array to find out how big the array need to
103 be. The filled in elements should not be freed by the caller.
104 */
105 int pdf_choice_widget_value(fz_context *ctx, pdf_annot *tw, const char *opts[]);
106
107 /*
108 set the value of a choice widget.
109
110 The caller should pass the number of options selected and an
111 array of their names
112 */
113 void pdf_choice_widget_set_value(fz_context *ctx, pdf_annot *tw, int n, const char *opts[]);
114
115 int pdf_choice_field_option_count(fz_context *ctx, pdf_obj *field);
116 const char *pdf_choice_field_option(fz_context *ctx, pdf_obj *field, int exportval, int i);
117
118 int pdf_widget_is_signed(fz_context *ctx, pdf_annot *widget);
119 int pdf_widget_is_readonly(fz_context *ctx, pdf_annot *widget);
120
121 /* Field flags */
122 enum
123 {
124 /* All fields */
125 PDF_FIELD_IS_READ_ONLY = 1,
126 PDF_FIELD_IS_REQUIRED = 1 << 1,
127 PDF_FIELD_IS_NO_EXPORT = 1 << 2,
128
129 /* Text fields */
130 PDF_TX_FIELD_IS_MULTILINE = 1 << 12,
131 PDF_TX_FIELD_IS_PASSWORD = 1 << 13,
132 PDF_TX_FIELD_IS_FILE_SELECT = 1 << 20,
133 PDF_TX_FIELD_IS_DO_NOT_SPELL_CHECK = 1 << 22,
134 PDF_TX_FIELD_IS_DO_NOT_SCROLL = 1 << 23,
135 PDF_TX_FIELD_IS_COMB = 1 << 24,
136 PDF_TX_FIELD_IS_RICH_TEXT = 1 << 25,
137
138 /* Button fields */
139 PDF_BTN_FIELD_IS_NO_TOGGLE_TO_OFF = 1 << 14,
140 PDF_BTN_FIELD_IS_RADIO = 1 << 15,
141 PDF_BTN_FIELD_IS_PUSHBUTTON = 1 << 16,
142 PDF_BTN_FIELD_IS_RADIOS_IN_UNISON = 1 << 25,
143
144 /* Choice fields */
145 PDF_CH_FIELD_IS_COMBO = 1 << 17,
146 PDF_CH_FIELD_IS_EDIT = 1 << 18,
147 PDF_CH_FIELD_IS_SORT = 1 << 19,
148 PDF_CH_FIELD_IS_MULTI_SELECT = 1 << 21,
149 PDF_CH_FIELD_IS_DO_NOT_SPELL_CHECK = 1 << 22,
150 PDF_CH_FIELD_IS_COMMIT_ON_SEL_CHANGE = 1 << 25,
151 };
152
153 void pdf_calculate_form(fz_context *ctx, pdf_document *doc);
154 void pdf_reset_form(fz_context *ctx, pdf_document *doc, pdf_obj *fields, int exclude);
155
156 int pdf_field_type(fz_context *ctx, pdf_obj *field);
157 const char *pdf_field_type_string(fz_context *ctx, pdf_obj *field);
158 int pdf_field_flags(fz_context *ctx, pdf_obj *field);
159
160 /*
161 Retrieve the name for a field as a C string that
162 must be freed by the caller.
163 */
164 char *pdf_load_field_name(fz_context *ctx, pdf_obj *field);
165 const char *pdf_field_value(fz_context *ctx, pdf_obj *field);
166 void pdf_create_field_name(fz_context *ctx, pdf_document *doc, const char *prefix, char *buf, size_t len);
167
168 char *pdf_field_border_style(fz_context *ctx, pdf_obj *field);
169 void pdf_field_set_border_style(fz_context *ctx, pdf_obj *field, const char *text);
170 void pdf_field_set_button_caption(fz_context *ctx, pdf_obj *field, const char *text);
171 void pdf_field_set_fill_color(fz_context *ctx, pdf_obj *field, pdf_obj *col);
172 void pdf_field_set_text_color(fz_context *ctx, pdf_obj *field, pdf_obj *col);
173 int pdf_field_display(fz_context *ctx, pdf_obj *field);
174 void pdf_field_set_display(fz_context *ctx, pdf_obj *field, int d);
175 const char *pdf_field_label(fz_context *ctx, pdf_obj *field);
176 pdf_obj *pdf_button_field_on_state(fz_context *ctx, pdf_obj *field);
177
178 int pdf_set_field_value(fz_context *ctx, pdf_document *doc, pdf_obj *field, const char *text, int ignore_trigger_events);
179
180 /*
181 Update the text of a text widget.
182
183 The text is first validated by the Field/Keystroke event processing and accepted only if it passes.
184
185 The function returns whether validation passed.
186 */
187 int pdf_set_text_field_value(fz_context *ctx, pdf_annot *widget, const char *value);
188 int pdf_set_choice_field_value(fz_context *ctx, pdf_annot *widget, const char *value);
189 int pdf_edit_text_field_value(fz_context *ctx, pdf_annot *widget, const char *value, const char *change, int *selStart, int *selEnd, char **newvalue);
190
191 typedef struct
192 {
193 char *cn;
194 char *o;
195 char *ou;
196 char *email;
197 char *c;
198 }
199 pdf_pkcs7_distinguished_name;
200
201 typedef enum
202 {
203 PDF_SIGNATURE_ERROR_OKAY,
204 PDF_SIGNATURE_ERROR_NO_SIGNATURES,
205 PDF_SIGNATURE_ERROR_NO_CERTIFICATE,
206 PDF_SIGNATURE_ERROR_DIGEST_FAILURE,
207 PDF_SIGNATURE_ERROR_SELF_SIGNED,
208 PDF_SIGNATURE_ERROR_SELF_SIGNED_IN_CHAIN,
209 PDF_SIGNATURE_ERROR_NOT_TRUSTED,
210 PDF_SIGNATURE_ERROR_NOT_SIGNED,
211 PDF_SIGNATURE_ERROR_UNKNOWN,
212 } pdf_signature_error;
213
214 /* Increment the reference count for a signer object */
215 typedef pdf_pkcs7_signer *(pdf_pkcs7_keep_signer_fn)(fz_context *ctx, pdf_pkcs7_signer *signer);
216
217 /* Drop a reference for a signer object */
218 typedef void (pdf_pkcs7_drop_signer_fn)(fz_context *ctx, pdf_pkcs7_signer *signer);
219
220 /* Obtain the distinguished name information from a signer object */
221 typedef pdf_pkcs7_distinguished_name *(pdf_pkcs7_get_signing_name_fn)(fz_context *ctx, pdf_pkcs7_signer *signer);
222
223 /* Predict the size of the digest. The actual digest returned by create_digest will be no greater in size */
224 typedef size_t (pdf_pkcs7_max_digest_size_fn)(fz_context *ctx, pdf_pkcs7_signer *signer);
225
226 /* Create a signature based on ranges of bytes drawn from a stream */
227 typedef int (pdf_pkcs7_create_digest_fn)(fz_context *ctx, pdf_pkcs7_signer *signer, fz_stream *in, unsigned char *digest, size_t digest_len);
228
229 struct pdf_pkcs7_signer
230 {
231 pdf_pkcs7_keep_signer_fn *keep;
232 pdf_pkcs7_drop_signer_fn *drop;
233 pdf_pkcs7_get_signing_name_fn *get_signing_name;
234 pdf_pkcs7_max_digest_size_fn *max_digest_size;
235 pdf_pkcs7_create_digest_fn *create_digest;
236 };
237
238 typedef struct pdf_pkcs7_verifier pdf_pkcs7_verifier;
239
240 typedef void (pdf_pkcs7_drop_verifier_fn)(fz_context *ctx, pdf_pkcs7_verifier *verifier);
241 typedef pdf_signature_error (pdf_pkcs7_check_certificate_fn)(fz_context *ctx, pdf_pkcs7_verifier *verifier, unsigned char *signature, size_t len);
242 typedef pdf_signature_error (pdf_pkcs7_check_digest_fn)(fz_context *ctx, pdf_pkcs7_verifier *verifier, fz_stream *in, unsigned char *signature, size_t len);
243 typedef pdf_pkcs7_distinguished_name *(pdf_pkcs7_get_signatory_fn)(fz_context *ctx, pdf_pkcs7_verifier *verifier, unsigned char *signature, size_t len);
244
245 struct pdf_pkcs7_verifier
246 {
247 pdf_pkcs7_drop_verifier_fn *drop;
248 pdf_pkcs7_check_certificate_fn *check_certificate;
249 pdf_pkcs7_check_digest_fn *check_digest;
250 pdf_pkcs7_get_signatory_fn *get_signatory;
251 };
252
253 int pdf_signature_is_signed(fz_context *ctx, pdf_document *doc, pdf_obj *field);
254 void pdf_signature_set_value(fz_context *ctx, pdf_document *doc, pdf_obj *field, pdf_pkcs7_signer *signer, int64_t stime);
255
256 int pdf_count_signatures(fz_context *ctx, pdf_document *doc);
257
258 char *pdf_signature_error_description(pdf_signature_error err);
259
260 pdf_pkcs7_distinguished_name *pdf_signature_get_signatory(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_document *doc, pdf_obj *signature);
261 pdf_pkcs7_distinguished_name *pdf_signature_get_widget_signatory(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_annot *widget);
262 void pdf_signature_drop_distinguished_name(fz_context *ctx, pdf_pkcs7_distinguished_name *name);
263 char *pdf_signature_format_distinguished_name(fz_context *ctx, pdf_pkcs7_distinguished_name *name);
264 char *pdf_signature_info(fz_context *ctx, const char *name, pdf_pkcs7_distinguished_name *dn, const char *reason, const char *location, int64_t date, int include_labels);
265 fz_display_list *pdf_signature_appearance_signed(fz_context *ctx, fz_rect rect, fz_text_language lang, fz_image *img, const char *left_text, const char *right_text, int include_logo);
266 fz_display_list *pdf_signature_appearance_unsigned(fz_context *ctx, fz_rect rect, fz_text_language lang);
267
268 pdf_signature_error pdf_check_digest(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_document *doc, pdf_obj *signature);
269 pdf_signature_error pdf_check_certificate(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_document *doc, pdf_obj *signature);
270 pdf_signature_error pdf_check_widget_digest(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_annot *widget);
271 pdf_signature_error pdf_check_widget_certificate(fz_context *ctx, pdf_pkcs7_verifier *verifier, pdf_annot *widget);
272
273 void pdf_clear_signature(fz_context *ctx, pdf_annot *widget);
274
275 /*
276 Sign a signature field, while assigning it an arbitrary appearance determined by a display list.
277 The function pdf_signature_appearance can generate a variety of common signature appearances.
278 */
279 void pdf_sign_signature_with_appearance(fz_context *ctx, pdf_annot *widget, pdf_pkcs7_signer *signer, int64_t date, fz_display_list *disp_list);
280
281 enum {
282 PDF_SIGNATURE_SHOW_LABELS = 1,
283 PDF_SIGNATURE_SHOW_DN = 2,
284 PDF_SIGNATURE_SHOW_DATE = 4,
285 PDF_SIGNATURE_SHOW_TEXT_NAME = 8,
286 PDF_SIGNATURE_SHOW_GRAPHIC_NAME = 16,
287 PDF_SIGNATURE_SHOW_LOGO = 32,
288 };
289
290 #define PDF_SIGNATURE_DEFAULT_APPEARANCE ( \
291 PDF_SIGNATURE_SHOW_LABELS | \
292 PDF_SIGNATURE_SHOW_DN | \
293 PDF_SIGNATURE_SHOW_DATE | \
294 PDF_SIGNATURE_SHOW_TEXT_NAME | \
295 PDF_SIGNATURE_SHOW_GRAPHIC_NAME | \
296 PDF_SIGNATURE_SHOW_LOGO )
297
298 /*
299 Sign a signature field, while assigning it a default appearance.
300 */
301 void pdf_sign_signature(fz_context *ctx, pdf_annot *widget,
302 pdf_pkcs7_signer *signer,
303 int appearance_flags,
304 fz_image *graphic,
305 const char *reason,
306 const char *location);
307
308 /*
309 Create a preview of the default signature appearance.
310 */
311 fz_display_list *pdf_preview_signature_as_display_list(fz_context *ctx,
312 float w, float h, fz_text_language lang,
313 pdf_pkcs7_signer *signer,
314 int appearance_flags,
315 fz_image *graphic,
316 const char *reason,
317 const char *location);
318
319 fz_pixmap *pdf_preview_signature_as_pixmap(fz_context *ctx,
320 int w, int h, fz_text_language lang,
321 pdf_pkcs7_signer *signer,
322 int appearance_flags,
323 fz_image *graphic,
324 const char *reason,
325 const char *location);
326
327 void pdf_drop_signer(fz_context *ctx, pdf_pkcs7_signer *signer);
328 void pdf_drop_verifier(fz_context *ctx, pdf_pkcs7_verifier *verifier);
329
330 void pdf_field_reset(fz_context *ctx, pdf_document *doc, pdf_obj *field);
331
332 pdf_obj *pdf_lookup_field(fz_context *ctx, pdf_obj *form, const char *name);
333
334 /* Form text field editing events: */
335
336 typedef struct
337 {
338 const char *value;
339 const char *change;
340 int selStart, selEnd;
341 int willCommit;
342 char *newChange;
343 char *newValue;
344 } pdf_keystroke_event;
345
346 int pdf_field_event_keystroke(fz_context *ctx, pdf_document *doc, pdf_obj *field, pdf_keystroke_event *evt);
347 int pdf_field_event_validate(fz_context *ctx, pdf_document *doc, pdf_obj *field, const char *value, char **newvalue);
348 void pdf_field_event_calculate(fz_context *ctx, pdf_document *doc, pdf_obj *field);
349 char *pdf_field_event_format(fz_context *ctx, pdf_document *doc, pdf_obj *field);
350
351 int pdf_annot_field_event_keystroke(fz_context *ctx, pdf_document *doc, pdf_annot *annot, pdf_keystroke_event *evt);
352
353 /* Call these to trigger actions from various UI events: */
354
355 void pdf_document_event_will_close(fz_context *ctx, pdf_document *doc);
356 void pdf_document_event_will_save(fz_context *ctx, pdf_document *doc);
357 void pdf_document_event_did_save(fz_context *ctx, pdf_document *doc);
358 void pdf_document_event_will_print(fz_context *ctx, pdf_document *doc);
359 void pdf_document_event_did_print(fz_context *ctx, pdf_document *doc);
360
361 void pdf_page_event_open(fz_context *ctx, pdf_page *page);
362 void pdf_page_event_close(fz_context *ctx, pdf_page *page);
363
364 void pdf_annot_event_enter(fz_context *ctx, pdf_annot *annot);
365 void pdf_annot_event_exit(fz_context *ctx, pdf_annot *annot);
366 void pdf_annot_event_down(fz_context *ctx, pdf_annot *annot);
367 void pdf_annot_event_up(fz_context *ctx, pdf_annot *annot);
368 void pdf_annot_event_focus(fz_context *ctx, pdf_annot *annot);
369 void pdf_annot_event_blur(fz_context *ctx, pdf_annot *annot);
370 void pdf_annot_event_page_open(fz_context *ctx, pdf_annot *annot);
371 void pdf_annot_event_page_close(fz_context *ctx, pdf_annot *annot);
372 void pdf_annot_event_page_visible(fz_context *ctx, pdf_annot *annot);
373 void pdf_annot_event_page_invisible(fz_context *ctx, pdf_annot *annot);
374
375 /*
376 * Bake appearances of annotations and/or widgets into static page content,
377 * and remove the corresponding interactive PDF objects.
378 */
379 void pdf_bake_document(fz_context *ctx, pdf_document *doc, int bake_annots, int bake_widgets);
380
381 #endif