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