public/fpdf_formfill.h

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