baab18ab9232363b95e01b0ad23e62ac835f125a
[pdfium.git] / public / fpdf_formfill.h
1 // Copyright 2014 PDFium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
6
7 #ifndef PUBLIC_FPDF_FORMFILL_H_
8 #define PUBLIC_FPDF_FORMFILL_H_
9
10 #include "fpdfview.h"
11
12 typedef void* FPDF_FORMHANDLE;
13
14 // Exported Functions
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19 typedef struct _IPDF_JsPlatform {
20   /**
21   * Version number of the interface. Currently must be 2.
22   **/
23   int version;
24
25   /* Version 1. */
26
27   /**
28   * Method: app_alert
29   *           pop up a dialog to show warning or hint.
30   * Interface Version:
31   *           1
32   * Implementation Required:
33   *           yes
34   * Parameters:
35   *           pThis       -   Pointer to the interface structure itself
36   *           Msg         -   A string containing the message to be displayed.
37   *           Title       -   The title of the dialog.
38   *           Type        -   The stype of button group.
39   *                           0-OK(default);
40   *                           1-OK,Cancel;
41   *                           2-Yes,NO;
42   *                           3-Yes, NO, Cancel.
43   *           nIcon       -   The Icon type.
44   *                           0-Error(default);
45   *                           1-Warning;
46   *                           2-Question;
47   *                           3-Status.
48   * Return Value:
49   *           The return value could be the folowing type:
50   *                           1-OK;
51   *                           2-Cancel;
52   *                           3-NO;
53   *                           4-Yes;
54   */
55   int (*app_alert)(struct _IPDF_JsPlatform* pThis,
56                    FPDF_WIDESTRING Msg,
57                    FPDF_WIDESTRING Title,
58                    int Type,
59                    int Icon);
60
61   /**
62   * Method: app_beep
63   *           Causes the system to play a sound.
64   * Interface Version:
65   *           1
66   * Implementation Required:
67   *           yes
68   * Parameters:
69   *           pThis       -   Pointer to the interface structure itself
70   *           nType       -   The sound type.
71   *                           0 - Error
72   *                           1 - Warning
73   *                           2 - Question
74   *                           3 - Status
75   *                           4 - Default (default value)
76   * Return Value:
77   *           None
78   */
79   void (*app_beep)(struct _IPDF_JsPlatform* pThis, int nType);
80
81   /**
82   * Method: app_response
83   *           Displays a dialog box containing a question and an entry field for
84   * the user to reply to the question.
85   * Interface Version:
86   *           1
87   * Implementation Required:
88   *           yes
89   * Parameters:
90   *           pThis       -   Pointer to the interface structure itself
91   *           Question    -   The question to be posed to the user.
92   *           Title       -   The title of the dialog box.
93   *           Default     -   A default value for the answer to the question. If
94   * not specified, no default value is presented.
95   *           cLabel      -   A short string to appear in front of and on the
96   * same line as the edit text field.
97   *           bPassword   -   If true, indicates that the user's response should
98   * show as asterisks (*) or bullets (?) to mask the response, which might be
99   * sensitive information. The default is false.
100   *           response    -   A string buffer allocated by SDK, to receive the
101   * user's response.
102   *           length      -   The length of the buffer, number of bytes.
103   * Currently, It's always be 2048.
104   * Return Value:
105   *       Number of bytes the complete user input would actually require, not
106   * including trailing zeros, regardless of the value of the length
107   *       parameter or the presence of the response buffer.
108   * Comments:
109   *       No matter on what platform, the response buffer should be always
110   * written using UTF-16LE encoding. If a response buffer is
111   *       present and the size of the user input exceeds the capacity of the
112   * buffer as specified by the length parameter, only the
113   *       first "length" bytes of the user input are to be written to the
114   * buffer.
115   */
116   int (*app_response)(struct _IPDF_JsPlatform* pThis,
117                       FPDF_WIDESTRING Question,
118                       FPDF_WIDESTRING Title,
119                       FPDF_WIDESTRING Default,
120                       FPDF_WIDESTRING cLabel,
121                       FPDF_BOOL bPassword,
122                       void* response,
123                       int length);
124
125   /*
126   * Method: Doc_getFilePath
127   *           Get the file path of the current document.
128   * Interface Version:
129   *           1
130   * Implementation Required:
131   *           yes
132   * Parameters:
133   *           pThis       -   Pointer to the interface structure itself
134   *           filePath    -   The string buffer to receive the file path. Can be
135   * NULL.
136   *           length      -   The length of the buffer, number of bytes. Can be
137   * 0.
138   * Return Value:
139   *       Number of bytes the filePath consumes, including trailing zeros.
140   * Comments:
141   *       The filePath should be always input in local encoding.
142   *
143   *       The return value always indicated number of bytes required for the
144   * buffer, even when there is
145   *       no buffer specified, or the buffer size is less then required. In this
146   * case, the buffer will not
147   *       be modified.
148   */
149   int (*Doc_getFilePath)(struct _IPDF_JsPlatform* pThis,
150                          void* filePath,
151                          int length);
152
153   /*
154   * Method: Doc_mail
155   *           Mails the data buffer as an attachment to all recipients, with or
156   * without user interaction.
157   * Interface Version:
158   *           1
159   * Implementation Required:
160   *           yes
161   * Parameters:
162   *           pThis       -   Pointer to the interface structure itself
163   *           mailData    -   Pointer to the data buffer to be sent.Can be NULL.
164   *           length      -   The size,in bytes, of the buffer pointed by
165   * mailData parameter.Can be 0.
166   *           bUI         -   If true, the rest of the parameters are used in a
167   * compose-new-message window that is displayed to the user. If false, the cTo
168   * parameter is required and all others are optional.
169   *           To          -   A semicolon-delimited list of recipients for the
170   * message.
171   *           Subject     -   The subject of the message. The length limit is 64
172   * KB.
173   *           CC          -   A semicolon-delimited list of CC recipients for
174   * the message.
175   *           BCC         -   A semicolon-delimited list of BCC recipients for
176   * the message.
177   *           Msg         -   The content of the message. The length limit is 64
178   * KB.
179   * Return Value:
180   *           None.
181   * Comments:
182   *           If the parameter mailData is NULL or length is 0, the current
183   * document will be mailed as an attachment to all recipients.
184   */
185   void (*Doc_mail)(struct _IPDF_JsPlatform* pThis,
186                    void* mailData,
187                    int length,
188                    FPDF_BOOL bUI,
189                    FPDF_WIDESTRING To,
190                    FPDF_WIDESTRING Subject,
191                    FPDF_WIDESTRING CC,
192                    FPDF_WIDESTRING BCC,
193                    FPDF_WIDESTRING Msg);
194
195   /*
196   * Method: Doc_print
197   *           Prints all or a specific number of pages of the document.
198   * Interface Version:
199   *           1
200   * Implementation Required:
201   *           yes
202   * Parameters:
203   *           pThis       -   Pointer to the interface structure itself.
204   *           bUI         -   If true, will cause a UI to be presented to the
205   * user to obtain printing information and confirm the action.
206   *           nStart      -   A 0-based index that defines the start of an
207   * inclusive range of pages.
208   *           nEnd        -   A 0-based index that defines the end of an
209   * inclusive page range.
210   *           bSilent     -   If true, suppresses the cancel dialog box while
211   * the document is printing. The default is false.
212   *           bShrinkToFit    -   If true, the page is shrunk (if necessary) to
213   * fit within the imageable area of the printed page.
214   *           bPrintAsImage   -   If true, print pages as an image.
215   *           bReverse    -   If true, print from nEnd to nStart.
216   *           bAnnotations    -   If true (the default), annotations are
217   * printed.
218   */
219   void (*Doc_print)(struct _IPDF_JsPlatform* pThis,
220                     FPDF_BOOL bUI,
221                     int nStart,
222                     int nEnd,
223                     FPDF_BOOL bSilent,
224                     FPDF_BOOL bShrinkToFit,
225                     FPDF_BOOL bPrintAsImage,
226                     FPDF_BOOL bReverse,
227                     FPDF_BOOL bAnnotations);
228
229   /*
230   * Method: Doc_submitForm
231   *           Send the form data to a specified URL.
232   * Interface Version:
233   *           1
234   * Implementation Required:
235   *           yes
236   * Parameters:
237   *           pThis       -   Pointer to the interface structure itself
238   *           formData    -   Pointer to the data buffer to be sent.
239   *           length      -   The size,in bytes, of the buffer pointed by
240   * formData parameter.
241   *           URL         -   The URL to send to.
242   * Return Value:
243   *           None.
244   *
245   */
246   void (*Doc_submitForm)(struct _IPDF_JsPlatform* pThis,
247                          void* formData,
248                          int length,
249                          FPDF_WIDESTRING URL);
250
251   /*
252   * Method: Doc_gotoPage
253   *           Jump to a specified page.
254   * Interface Version:
255   *           1
256   * Implementation Required:
257   *           yes
258   * Parameters:
259   *           pThis       -   Pointer to the interface structure itself
260   *           nPageNum    -   The specified page number, zero for the first
261   * page.
262   * Return Value:
263   *           None.
264   *
265   */
266   void (*Doc_gotoPage)(struct _IPDF_JsPlatform* pThis, int nPageNum);
267   /*
268   * Method: Field_browse
269   *           Show a file selection dialog, and return the selected file path.
270   * Interface Version:
271   *           1
272   * Implementation Required:
273   *           yes
274   * Parameters:
275   *           pThis       -   Pointer to the interface structure itself.
276   *           filePath    -   Pointer to the data buffer to receive the file
277   * path.Can be NULL.
278   *           length      -   The length of the buffer, number of bytes. Can be
279   * 0.
280   * Return Value:
281   *       Number of bytes the filePath consumes, including trailing zeros.
282   * Comments:
283   *       The filePath shoule be always input in local encoding.
284   */
285   int (*Field_browse)(struct _IPDF_JsPlatform* pThis,
286                       void* filePath,
287                       int length);
288
289   /**
290   *   pointer to FPDF_FORMFILLINFO interface.
291   **/
292   void* m_pFormfillinfo;
293
294   /* Version 2. */
295
296   void* m_isolate;               /* Unused in v3, retain for compatibility. */
297   unsigned int m_v8EmbedderSlot; /* Unused in v3, retain for compatibility. */
298
299   /* Version 3. */
300   /* Version 3 moves m_Isolate and m_v8EmbedderSlot to FPDF_LIBRARY_CONFIG. */
301
302 } IPDF_JSPLATFORM;
303
304 // Flags for Cursor type
305 #define FXCT_ARROW 0
306 #define FXCT_NESW 1
307 #define FXCT_NWSE 2
308 #define FXCT_VBEAM 3
309 #define FXCT_HBEAM 4
310 #define FXCT_HAND 5
311
312 /**
313  * Declares of a pointer type to the callback function for the FFI_SetTimer
314  *method.
315  * Parameters:
316  *          idEvent     -   Identifier of the timer.
317  * Return value:
318  *          None.
319  **/
320 typedef void (*TimerCallback)(int idEvent);
321
322 /**
323  * Declares of a struct type to the local system time.
324 **/
325 typedef struct _FPDF_SYSTEMTIME {
326   unsigned short wYear;         /* years since 1900 */
327   unsigned short wMonth;        /* months since January - [0,11] */
328   unsigned short wDayOfWeek;    /* days since Sunday - [0,6] */
329   unsigned short wDay;          /* day of the month - [1,31] */
330   unsigned short wHour;         /* hours since midnight - [0,23] */
331   unsigned short wMinute;       /* minutes after the hour - [0,59] */
332   unsigned short wSecond;       /* seconds after the minute - [0,59] */
333   unsigned short wMilliseconds; /* milliseconds after the second - [0,999] */
334 } FPDF_SYSTEMTIME;
335
336 typedef struct _FPDF_FORMFILLINFO {
337   /**
338    * Version number of the interface. Currently must be 1.
339    **/
340   int version;
341
342   /**
343 *Method: Release
344 *         Give implementation a chance to release any data after the interface
345 * is no longer used
346 *Interface Version:
347 *         1
348 *Implementation Required:
349 *         No
350 *Comments:
351 *         Called by Foxit SDK during the final cleanup process.
352 *Parameters:
353 *         pThis       -   Pointer to the interface structure itself
354 *Return Value:
355 *         None
356 */
357
358   void (*Release)(struct _FPDF_FORMFILLINFO* pThis);
359
360   /**
361    * Method: FFI_Invalidate
362    *          Invalidate the client area within the specified rectangle.
363    * Interface Version:
364    *          1
365    * Implementation Required:
366       *           yes
367    * Parameters:
368    *          pThis       -   Pointer to the interface structure itself.
369    *          page        -   Handle to the page. Returned by FPDF_LoadPage
370    *function.
371    *          left        -   Left position of the client area in PDF page
372    *coordinate.
373    *          top         -   Top  position of the client area in PDF page
374    *coordinate.
375    *          right       -   Right position of the client area in PDF page
376    *coordinate.
377    *          bottom      -   Bottom position of the client area in PDF page
378    *coordinate.
379    * Return Value:
380    *          None.
381    *
382    *comments:
383    *          All positions are measured in PDF "user space".
384    *          Implementation should call FPDF_RenderPageBitmap() function for
385    *repainting a specified page area.
386   */
387   void (*FFI_Invalidate)(struct _FPDF_FORMFILLINFO* pThis,
388                          FPDF_PAGE page,
389                          double left,
390                          double top,
391                          double right,
392                          double bottom);
393
394   /**
395    * Method: FFI_OutputSelectedRect
396    *          When user is taking the mouse to select texts on a form field,
397    * this callback function will keep
398    *          returning the selected areas to the implementation.
399    *
400    * Interface Version:
401    *          1
402    * Implementation Required:
403    *          No
404    * Parameters:
405    *          pThis       -   Pointer to the interface structure itself.
406    *          page        -   Handle to the page. Returned by FPDF_LoadPage
407    * function.
408    *          left        -   Left position of the client area in PDF page
409    * coordinate.
410    *          top         -   Top  position of the client area in PDF page
411    * coordinate.
412    *          right       -   Right position of the client area in PDF page
413    * coordinate.
414    *          bottom      -   Bottom position of the client area in PDF page
415    * coordinate.
416    * Return Value:
417    *          None.
418    *
419    * comments:
420    *          This CALLBACK function is useful for implementing special text
421    * selection effect. Implementation should
422    *          first records the returned rectangles, then draw them one by one
423    * at the painting period, last,remove all
424    *          the recorded rectangles when finish painting.
425   */
426   void (*FFI_OutputSelectedRect)(struct _FPDF_FORMFILLINFO* pThis,
427                                  FPDF_PAGE page,
428                                  double left,
429                                  double top,
430                                  double right,
431                                  double bottom);
432
433   /**
434   * Method: FFI_SetCursor
435   *           Set the Cursor shape.
436   * Interface Version:
437   *           1
438   * Implementation Required:
439   *           yes
440   * Parameters:
441   *       pThis       -   Pointer to the interface structure itself.
442   *       nCursorType -   Cursor type. see Flags for Cursor type for the
443   * details.
444   *   Return value:
445   *       None.
446   * */
447   void (*FFI_SetCursor)(struct _FPDF_FORMFILLINFO* pThis, int nCursorType);
448
449   /**
450   * Method: FFI_SetTimer
451   *           This method installs a system timer. A time-out value is
452   * specified,
453   *           and every time a time-out occurs, the system passes a message to
454   *           the TimerProc callback function.
455   * Interface Version:
456   *           1
457   * Implementation Required:
458   *           yes
459   * Parameters:
460   *       pThis       -   Pointer to the interface structure itself.
461   *       uElapse     -   Specifies the time-out value, in milliseconds.
462   *       lpTimerFunc -   A pointer to the callback function-TimerCallback.
463   *   Return value:
464   *       The timer identifier of the new timer if the function is successful.
465   *       An application passes this value to the FFI_KillTimer method to kill
466   *       the timer. Nonzero if it is successful; otherwise, it is zero.
467   * */
468   int (*FFI_SetTimer)(struct _FPDF_FORMFILLINFO* pThis,
469                       int uElapse,
470                       TimerCallback lpTimerFunc);
471
472   /**
473   * Method: FFI_KillTimer
474   *           This method kills the timer event identified by nIDEvent, set by
475   * an earlier call to FFI_SetTimer.
476   * Interface Version:
477   *           1
478   * Implementation Required:
479   *           yes
480   * Parameters:
481   *       pThis       -   Pointer to the interface structure itself.
482   *       nTimerID    -   The timer ID return by FFI_SetTimer function.
483   *   Return value:
484   *       None.
485   * */
486   void (*FFI_KillTimer)(struct _FPDF_FORMFILLINFO* pThis, int nTimerID);
487
488   /**
489   * Method: FFI_GetLocalTime
490   *           This method receives the current local time on the system.
491   * Interface Version:
492   *           1
493   * Implementation Required:
494   *           yes
495   * Parameters:
496   *       pThis       -   Pointer to the interface structure itself.
497   *   Return value:
498   *       None.
499   * */
500   FPDF_SYSTEMTIME (*FFI_GetLocalTime)(struct _FPDF_FORMFILLINFO* pThis);
501
502   /**
503   * Method: FFI_OnChange
504   *           This method will be invoked to notify implementation when the
505   * value of any FormField on the document had been changed.
506   * Interface Version:
507   *           1
508   * Implementation Required:
509   *           no
510   * Parameters:
511   *       pThis       -   Pointer to the interface structure itself.
512   *   Return value:
513   *       None.
514   * */
515   void (*FFI_OnChange)(struct _FPDF_FORMFILLINFO* pThis);
516
517   /**
518   * Method: FFI_GetPage
519   *           This method receives the page pointer associated with a specified
520   * page index.
521   * Interface Version:
522   *           1
523   * Implementation Required:
524   *           yes
525   * Parameters:
526   *       pThis       -   Pointer to the interface structure itself.
527   *       document    -   Handle to document. Returned by FPDF_LoadDocument
528   * function.
529   *       nPageIndex  -   Index number of the page. 0 for the first page.
530   * Return value:
531   *       Handle to the page. Returned by FPDF_LoadPage function.
532   * Comments:
533   *       In some cases, the document-level JavaScript action may refer to a
534   * page which hadn't been loaded yet.
535   *       To successfully run the javascript action, implementation need to load
536   * the page for SDK.
537   * */
538   FPDF_PAGE   (*FFI_GetPage)(struct _FPDF_FORMFILLINFO* pThis, FPDF_DOCUMENT document, int nPageIndex);
539
540   /**
541   * Method: FFI_GetCurrentPage
542   *       This method receives the current page pointer.
543   * Interface Version:
544   *           1
545   * Implementation Required:
546   *           yes
547   * Parameters:
548   *       pThis       -   Pointer to the interface structure itself.
549   *       document    -   Handle to document. Returned by FPDF_LoadDocument
550   * function.
551   * Return value:
552   *       Handle to the page. Returned by FPDF_LoadPage function.
553   * */
554   FPDF_PAGE   (*FFI_GetCurrentPage)(struct _FPDF_FORMFILLINFO* pThis, FPDF_DOCUMENT document);
555
556   /**
557   * Method: FFI_GetRotation
558   *           This method receives currently rotation of the page view.
559   * Interface Version:
560   *           1
561   * Implementation Required:
562   *           yes
563   * Parameters:
564   *       pThis       -   Pointer to the interface structure itself.
565   *       page        -   Handle to page. Returned by FPDF_LoadPage function.
566   * Return value:
567   *       The page rotation. Should be 0(0 degree),1(90 degree),2(180
568   * degree),3(270 degree), in a clockwise direction.
569   * */
570   int (*FFI_GetRotation)(struct _FPDF_FORMFILLINFO* pThis, FPDF_PAGE page);
571
572   /**
573   * Method: FFI_ExecuteNamedAction
574   *           This method will execute an named action.
575   * Interface Version:
576   *           1
577   * Implementation Required:
578   *           yes
579   * Parameters:
580   *       pThis           -   Pointer to the interface structure itself.
581   *       namedAction     -   A byte string which indicates the named action,
582   * terminated by 0.
583   * Return value:
584   *       None.
585   * Comments:
586   *       See the named actions description of <<PDF Reference, version 1.7>>
587   * for more details.
588   * */
589   void (*FFI_ExecuteNamedAction)(struct _FPDF_FORMFILLINFO* pThis,
590                                  FPDF_BYTESTRING namedAction);
591   /**
592   * @brief This method will be called when a text field is getting or losing a
593   * focus.
594   *
595   * @param[in] pThis      Pointer to the interface structure itself.
596   * @param[in] value      The string value of the form field, in UTF-16LE
597   * format.
598   * @param[in] valueLen   The length of the string value, number of characters
599   * (not bytes).
600   * @param[in] is_focus   True if the form field is getting a focus, False for
601   * losing a focus.
602   *
603   * @return None.
604   *
605   * @note Currently,only support text field and combobox field.
606   * */
607   void (*FFI_SetTextFieldFocus)(struct _FPDF_FORMFILLINFO* pThis,
608                                 FPDF_WIDESTRING value,
609                                 FPDF_DWORD valueLen,
610                                 FPDF_BOOL is_focus);
611
612   /**
613   * Method: FFI_DoURIAction
614   *           This action resolves to a uniform resource identifier.
615   * Interface Version:
616   *           1
617   * Implementation Required:
618   *           No
619   * Parameters:
620   *       pThis           -   Pointer to the interface structure itself.
621   *       bsURI           -   A byte string which indicates the uniform resource
622   * identifier, terminated by 0.
623   * Return value:
624   *       None.
625   * Comments:
626   *       See the URI actions description of <<PDF Reference, version 1.7>> for
627   * more details.
628   * */
629   void (*FFI_DoURIAction)(struct _FPDF_FORMFILLINFO* pThis,
630                           FPDF_BYTESTRING bsURI);
631
632   /**
633   * Method: FFI_DoGoToAction
634   *           This action changes the view to a specified destination.
635   * Interface Version:
636   *           1
637   * Implementation Required:
638   *           No
639   * Parameters:
640   *       pThis           -   Pointer to the interface structure itself.
641   *       nPageIndex      -   The index of the PDF page.
642   *       zoomMode        -   The zoom mode for viewing page.See Macros
643   *"PDFZOOM_XXX" defined in "fpdfdoc.h".
644   *       fPosArray       -   The float array which carries the position info.
645   *       sizeofArray     -   The size of float array.
646   * Return value:
647   *       None.
648   * Comments:
649   *       See the Destinations description of <<PDF Reference, version 1.7>> in
650   *8.2.1 for more details.
651   **/
652   void (*FFI_DoGoToAction)(struct _FPDF_FORMFILLINFO* pThis,
653                            int nPageIndex,
654                            int zoomMode,
655                            float* fPosArray,
656                            int sizeofArray);
657   /**
658   *   pointer to IPDF_JSPLATFORM interface
659   **/
660   IPDF_JSPLATFORM* m_pJsPlatform;
661
662 } FPDF_FORMFILLINFO;
663
664 /**
665  * Function: FPDFDOC_InitFormFillEnvironment
666  *          Init form fill environment.
667  * Comments:
668  *          This function should be called before any form fill operation.
669  * Parameters:
670  *          document        -   Handle to document. Returned by
671  *FPDF_LoadDocument function.
672  *          pFormFillInfo   -   Pointer to a FPDF_FORMFILLINFO structure.
673  * Return Value:
674  *          Return handler to the form fill module. NULL means fails.
675  **/
676 DLLEXPORT FPDF_FORMHANDLE STDCALL
677 FPDFDOC_InitFormFillEnvironment(FPDF_DOCUMENT document,
678                                 FPDF_FORMFILLINFO* formInfo);
679
680 /**
681  * Function: FPDFDOC_ExitFormFillEnvironment
682  *          Exit form fill environment.
683  * Parameters:
684  *          hHandle     -   Handle to the form fill module. Returned by
685  *FPDFDOC_InitFormFillEnvironment.
686  * Return Value:
687  *          NULL.
688  **/
689 DLLEXPORT void STDCALL FPDFDOC_ExitFormFillEnvironment(FPDF_FORMHANDLE hHandle);
690
691 /**
692  * Function: FORM_OnAfterLoadPage
693  *          This method is required for implementing all the form related
694  *functions. Should be invoked after user
695  *          successfully loaded a PDF page, and method
696  *FPDFDOC_InitFormFillEnvironment had been invoked.
697  * Parameters:
698  *          hHandle     -   Handle to the form fill module. Returned by
699  *FPDFDOC_InitFormFillEnvironment.
700  * Return Value:
701  *          NONE.
702  **/
703 DLLEXPORT void STDCALL FORM_OnAfterLoadPage(FPDF_PAGE page,
704                                             FPDF_FORMHANDLE hHandle);
705
706 /**
707  * Function: FORM_OnBeforeClosePage
708  *          This method is required for implementing all the form related
709  *functions. Should be invoked before user
710  *          close the PDF page.
711  * Parameters:
712  *          page        -   Handle to the page. Returned by FPDF_LoadPage
713  *function.
714  *          hHandle     -   Handle to the form fill module. Returned by
715  *FPDFDOC_InitFormFillEnvironment.
716  * Return Value:
717  *          NONE.
718  **/
719 DLLEXPORT void STDCALL FORM_OnBeforeClosePage(FPDF_PAGE page,
720                                               FPDF_FORMHANDLE hHandle);
721
722 /**
723 * Function: FORM_DoDocumentJSAction
724 *           This method is required for performing Document-level JavaScript
725 *action. It should be invoked after the PDF document
726 *           had been loaded.
727 * Parameters:
728 *           hHandle     -   Handle to the form fill module. Returned by
729 *FPDFDOC_InitFormFillEnvironment.
730 * Return Value:
731 *           NONE
732 * Comments:
733 *           If there is Document-level JavaScript action embedded in the
734 *document, this method will execute the javascript action;
735 *           otherwise, the method will do nothing.
736 **/
737 DLLEXPORT void STDCALL FORM_DoDocumentJSAction(FPDF_FORMHANDLE hHandle);
738
739 /**
740 * Function: FORM_DoDocumentOpenAction
741 *           This method is required for performing open-action when the document
742 *is opened.
743 * Parameters:
744 *           hHandle     -   Handle to the form fill module. Returned by
745 *FPDFDOC_InitFormFillEnvironment.
746 * Return Value:
747 *           NONE
748 * Comments:
749 *           This method will do nothing if there is no open-actions embedded in
750 *the document.
751 **/
752 DLLEXPORT void STDCALL FORM_DoDocumentOpenAction(FPDF_FORMHANDLE hHandle);
753
754 // additional actions type of document.
755 #define FPDFDOC_AACTION_WC \
756   0x10  // WC, before closing document, JavaScript action.
757 #define FPDFDOC_AACTION_WS \
758   0x11  // WS, before saving document, JavaScript action.
759 #define FPDFDOC_AACTION_DS 0x12  // DS, after saving document, JavaScript
760                                  // action.
761 #define FPDFDOC_AACTION_WP \
762   0x13  // WP, before printing document, JavaScript action.
763 #define FPDFDOC_AACTION_DP \
764   0x14  // DP, after printing document, JavaScript action.
765
766 /**
767 * Function: FORM_DoDocumentAAction
768 *           This method is required for performing the document's
769 *additional-action.
770 * Parameters:
771 *           hHandle     -   Handle to the form fill module. Returned by
772 *FPDFDOC_InitFormFillEnvironment.
773 *           aaType      -   The type of the additional-actions which defined
774 *above.
775 * Return Value:
776 *           NONE
777 * Comments:
778 *           This method will do nothing if there is no document
779 *additional-action corresponding to the specified aaType.
780 **/
781
782 DLLEXPORT void STDCALL FORM_DoDocumentAAction(FPDF_FORMHANDLE hHandle,
783                                               int aaType);
784
785 // Additional-action types of page object
786 #define FPDFPAGE_AACTION_OPEN \
787   0  // /O -- An action to be performed when the page is opened
788 #define FPDFPAGE_AACTION_CLOSE \
789   1  // /C -- An action to be performed when the page is closed
790
791 /**
792 * Function: FORM_DoPageAAction
793 *           This method is required for performing the page object's
794 *additional-action when opened or closed.
795 * Parameters:
796 *           page        -   Handle to the page. Returned by FPDF_LoadPage
797 *function.
798 *           hHandle     -   Handle to the form fill module. Returned by
799 *FPDFDOC_InitFormFillEnvironment.
800 *           aaType      -   The type of the page object's additional-actions
801 *which defined above.
802 * Return Value:
803 *           NONE
804 * Comments:
805 *           This method will do nothing if no additional-action corresponding to
806 *the specified aaType exists.
807 **/
808 DLLEXPORT void STDCALL FORM_DoPageAAction(FPDF_PAGE page,
809                                           FPDF_FORMHANDLE hHandle,
810                                           int aaType);
811
812 /**
813  * Function: FORM_OnMouseMove
814  *          You can call this member function when the mouse cursor moves.
815  * Parameters:
816  *          hHandle     -   Handle to the form fill module. Returned by
817  *FPDFDOC_InitFormFillEnvironment.
818  *          page        -   Handle to the page. Returned by FPDF_LoadPage
819  *function.
820  *          modifier        -   Indicates whether various virtual keys are down.
821  *          page_x      -   Specifies the x-coordinate of the cursor in PDF user
822  *space.
823  *          page_y      -   Specifies the y-coordinate of the cursor in PDF user
824  *space.
825  * Return Value:
826  *          TRUE indicates success; otherwise false.
827  **/
828 DLLEXPORT FPDF_BOOL STDCALL FORM_OnMouseMove(FPDF_FORMHANDLE hHandle,
829                                              FPDF_PAGE page,
830                                              int modifier,
831                                              double page_x,
832                                              double page_y);
833
834 /**
835  * Function: FORM_OnLButtonDown
836  *          You can call this member function when the user presses the left
837  *mouse button.
838  * Parameters:
839  *          hHandle     -   Handle to the form fill module. Returned by
840  *FPDFDOC_InitFormFillEnvironment.
841  *          page        -   Handle to the page. Returned by FPDF_LoadPage
842  *function.
843  *          modifier        -   Indicates whether various virtual keys are down.
844  *          page_x      -   Specifies the x-coordinate of the cursor in PDF user
845  *space.
846  *          page_y      -   Specifies the y-coordinate of the cursor in PDF user
847  *space.
848  * Return Value:
849  *          TRUE indicates success; otherwise false.
850  **/
851 DLLEXPORT FPDF_BOOL STDCALL FORM_OnLButtonDown(FPDF_FORMHANDLE hHandle,
852                                                FPDF_PAGE page,
853                                                int modifier,
854                                                double page_x,
855                                                double page_y);
856
857 /**
858  * Function: FORM_OnLButtonUp
859  *          You can call this member function when the user releases the left
860  *mouse button.
861  * Parameters:
862  *          hHandle     -   Handle to the form fill module. Returned by
863  *FPDFDOC_InitFormFillEnvironment.
864  *          page        -   Handle to the page. Returned by FPDF_LoadPage
865  *function.
866  *          modifier    -   Indicates whether various virtual keys are down.
867  *          page_x      -   Specifies the x-coordinate of the cursor in device.
868  *          page_y      -   Specifies the y-coordinate of the cursor in device.
869  * Return Value:
870  *          TRUE indicates success; otherwise false.
871  **/
872 DLLEXPORT FPDF_BOOL STDCALL FORM_OnLButtonUp(FPDF_FORMHANDLE hHandle,
873                                              FPDF_PAGE page,
874                                              int modifier,
875                                              double page_x,
876                                              double page_y);
877
878 /**
879  * Function: FORM_OnKeyDown
880  *          You can call this member function when a nonsystem key is pressed.
881  * Parameters:
882  *          hHandle     -   Handle to the form fill module. Returned by
883  *FPDFDOC_InitFormFillEnvironment.
884  *          page        -   Handle to the page. Returned by FPDF_LoadPage
885  *function.
886  *          nKeyCode    -   Indicates whether various virtual keys are down.
887  *          modifier    -   Contains the scan code, key-transition code,
888  *previous key state, and context code.
889  * Return Value:
890  *          TRUE indicates success; otherwise false.
891  **/
892 DLLEXPORT FPDF_BOOL STDCALL FORM_OnKeyDown(FPDF_FORMHANDLE hHandle,
893                                            FPDF_PAGE page,
894                                            int nKeyCode,
895                                            int modifier);
896
897 /**
898  * Function: FORM_OnKeyUp
899  *          You can call this member function when a nonsystem key is released.
900  * Parameters:
901  *          hHandle     -   Handle to the form fill module. Returned by
902  *FPDFDOC_InitFormFillEnvironment.
903  *          page        -   Handle to the page. Returned by FPDF_LoadPage
904  *function.
905  *          nKeyCode    -   The virtual-key code of the given key.
906  *          modifier    -   Contains the scan code, key-transition code,
907  *previous key state, and context code.
908  * Return Value:
909  *          TRUE indicates success; otherwise false.
910  **/
911 DLLEXPORT FPDF_BOOL STDCALL FORM_OnKeyUp(FPDF_FORMHANDLE hHandle,
912                                          FPDF_PAGE page,
913                                          int nKeyCode,
914                                          int modifier);
915
916 /**
917  * Function: FORM_OnChar
918  *          You can call this member function when a keystroke translates to a
919  *nonsystem character.
920  * Parameters:
921  *          hHandle     -   Handle to the form fill module. Returned by
922  *FPDFDOC_InitFormFillEnvironment.
923  *          page        -   Handle to the page. Returned by FPDF_LoadPage
924  *function.
925  *          nChar       -   The character code value of the key.
926  *          modifier    -   Contains the scan code, key-transition code,
927  *previous key state, and context code.
928  * Return Value:
929  *          TRUE indicates success; otherwise false.
930  **/
931 DLLEXPORT FPDF_BOOL STDCALL FORM_OnChar(FPDF_FORMHANDLE hHandle,
932                                         FPDF_PAGE page,
933                                         int nChar,
934                                         int modifier);
935
936 /**
937  * Function: FORM_ForceToKillFocus.
938  *          You can call this member function to force to kill the focus of the
939  *form field which got focus.
940  *          It would kill the focus on the form field, save the value of form
941  *field if it's changed by user.
942  * Parameters:
943  *          hHandle     -   Handle to the form fill module. Returned by
944  *FPDFDOC_InitFormFillEnvironment.
945  * Return Value:
946  *          TRUE indicates success; otherwise false.
947  **/
948 DLLEXPORT FPDF_BOOL STDCALL FORM_ForceToKillFocus(FPDF_FORMHANDLE hHandle);
949
950 // Field Types
951 #define FPDF_FORMFIELD_UNKNOWN 0      // Unknown.
952 #define FPDF_FORMFIELD_PUSHBUTTON 1   // push button type.
953 #define FPDF_FORMFIELD_CHECKBOX 2     // check box type.
954 #define FPDF_FORMFIELD_RADIOBUTTON 3  // radio button type.
955 #define FPDF_FORMFIELD_COMBOBOX 4     // combo box type.
956 #define FPDF_FORMFIELD_LISTBOX 5      // list box type.
957 #define FPDF_FORMFIELD_TEXTFIELD 6    // text field type.
958
959 /**
960  * Function: FPDFPage_HasFormFieldAtPoint
961  *     Get the form field type by point.
962  * Parameters:
963  *     hHandle     -   Handle to the form fill module. Returned by
964  *                     FPDFDOC_InitFormFillEnvironment().
965  *     page        -   Handle to the page. Returned by FPDF_LoadPage().
966  *     page_x      -   X position in PDF "user space".
967  *     page_y      -   Y position in PDF "user space".
968  * Return Value:
969  *     Return the type of the form field; -1 indicates no field.
970  *     See field types above.
971  **/
972 DLLEXPORT int STDCALL FPDFPage_HasFormFieldAtPoint(FPDF_FORMHANDLE hHandle,
973                                                    FPDF_PAGE page,
974                                                    double page_x,
975                                                    double page_y);
976
977 /**
978  * Function: FPDPage_HasFormFieldAtPoint
979  *     DEPRECATED. Please use FPDFPage_HasFormFieldAtPoint.
980  **/
981 DLLEXPORT int STDCALL FPDPage_HasFormFieldAtPoint(FPDF_FORMHANDLE hHandle,
982                                                   FPDF_PAGE page,
983                                                   double page_x,
984                                                   double page_y);
985
986 /**
987  * Function: FPDFPage_FormFieldZOrderAtPoint
988  *     Get the form field z-order by point.
989  * Parameters:
990  *     hHandle     -   Handle to the form fill module. Returned by
991  *                     FPDFDOC_InitFormFillEnvironment().
992  *     page        -   Handle to the page. Returned by FPDF_LoadPage().
993  *     page_x      -   X position in PDF "user space".
994  *     page_y      -   Y position in PDF "user space".
995  * Return Value:
996  *     Return the z-order of the form field; -1 indicates no field.
997  *     Higher numbers are closer to the front.
998  **/
999 DLLEXPORT int STDCALL FPDFPage_FormFieldZOrderAtPoint(FPDF_FORMHANDLE hHandle,
1000                                                       FPDF_PAGE page,
1001                                                       double page_x,
1002                                                       double page_y);
1003
1004 /**
1005  * Function: FPDF_SetFormFieldHighlightColor
1006  *          Set the highlight color of specified or all the form fields in the
1007  *document.
1008  * Parameters:
1009  *          hHandle     -   Handle to the form fill module. Returned by
1010  *FPDFDOC_InitFormFillEnvironment.
1011  *          doc         -   Handle to the document. Returned by
1012  *FPDF_LoadDocument function.
1013  *          fieldType   -   A 32-bit integer indicating the type of a form
1014  *field(defined above).
1015  *          color       -   The highlight color of the form field.Constructed by
1016  *0xxxrrggbb.
1017  * Return Value:
1018  *          NONE.
1019  * Comments:
1020  *          When the parameter fieldType is set to zero, the highlight color
1021  *will be applied to all the form fields in the
1022  *          document.
1023  *          Please refresh the client window to show the highlight immediately
1024  *if necessary.
1025  **/
1026 DLLEXPORT void STDCALL FPDF_SetFormFieldHighlightColor(FPDF_FORMHANDLE hHandle,
1027                                                        int fieldType,
1028                                                        unsigned long color);
1029
1030 /**
1031  * Function: FPDF_SetFormFieldHighlightAlpha
1032  *          Set the transparency of the form field highlight color in the
1033  *document.
1034  * Parameters:
1035  *          hHandle     -   Handle to the form fill module. Returned by
1036  *FPDFDOC_InitFormFillEnvironment.
1037  *          doc         -   Handle to the document. Returned by
1038  *FPDF_LoadDocument function.
1039  *          alpha       -   The transparency of the form field highlight color.
1040  *between 0-255.
1041  * Return Value:
1042  *          NONE.
1043  **/
1044 DLLEXPORT void STDCALL FPDF_SetFormFieldHighlightAlpha(FPDF_FORMHANDLE hHandle,
1045                                                        unsigned char alpha);
1046
1047 /**
1048  * Function: FPDF_RemoveFormFieldHighlight
1049  *          Remove the form field highlight color in the document.
1050  * Parameters:
1051  *          hHandle     -   Handle to the form fill module. Returned by
1052  *FPDFDOC_InitFormFillEnvironment.
1053  * Return Value:
1054  *          NONE.
1055  * Comments:
1056  *          Please refresh the client window to remove the highlight immediately
1057  *if necessary.
1058  **/
1059 DLLEXPORT void STDCALL FPDF_RemoveFormFieldHighlight(FPDF_FORMHANDLE hHandle);
1060
1061 /**
1062 * Function: FPDF_FFLDraw
1063 *           Render FormFeilds on a page to a device independent bitmap.
1064 * Parameters:
1065 *           hHandle     -   Handle to the form fill module. Returned by
1066 *FPDFDOC_InitFormFillEnvironment.
1067 *           bitmap      -   Handle to the device independent bitmap (as the
1068 *output buffer).
1069 *                           Bitmap handle can be created by FPDFBitmap_Create
1070 *function.
1071 *           page        -   Handle to the page. Returned by FPDF_LoadPage
1072 *function.
1073 *           start_x     -   Left pixel position of the display area in the
1074 *device coordinate.
1075 *           start_y     -   Top pixel position of the display area in the device
1076 *coordinate.
1077 *           size_x      -   Horizontal size (in pixels) for displaying the page.
1078 *           size_y      -   Vertical size (in pixels) for displaying the page.
1079 *           rotate      -   Page orientation: 0 (normal), 1 (rotated 90 degrees
1080 *clockwise),
1081 *                               2 (rotated 180 degrees), 3 (rotated 90 degrees
1082 *counter-clockwise).
1083 *           flags       -   0 for normal display, or combination of flags
1084 *defined above.
1085 * Return Value:
1086 *           None.
1087 * Comments:
1088 *           This method is designed to only render annotations and FormFields on
1089 *the page.
1090 *           Without FPDF_ANNOT specified for flags, Rendering functions such as
1091 *FPDF_RenderPageBitmap or FPDF_RenderPageBitmap_Start will only render page
1092 *contents(without annotations) to a bitmap.
1093 *           In order to implement the FormFill functions,Implementation should
1094 *call this method after rendering functions finish rendering the page contents.
1095 **/
1096 DLLEXPORT void STDCALL FPDF_FFLDraw(FPDF_FORMHANDLE hHandle,
1097                                     FPDF_BITMAP bitmap,
1098                                     FPDF_PAGE page,
1099                                     int start_x,
1100                                     int start_y,
1101                                     int size_x,
1102                                     int size_y,
1103                                     int rotate,
1104                                     int flags);
1105
1106 #ifdef __cplusplus
1107 }
1108 #endif
1109
1110 #endif  // PUBLIC_FPDF_FORMFILL_H_