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