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