Fix some formatting and wording in fpdf_formfill.h
Change-Id: Iac97258df579c095ec4e60367698d4b7ff4f07c8
Reviewed-on: https://pdfium-review.googlesource.com/c/47158
Reviewed-by: Tom Sepez <tsepez@chromium.org>
Commit-Queue: Lei Zhang <thestig@chromium.org>
diff --git a/public/fpdf_formfill.h b/public/fpdf_formfill.h
index 78a41aa..654debe 100644
--- a/public/fpdf_formfill.h
+++ b/public/fpdf_formfill.h
@@ -396,49 +396,48 @@
/* Version 1. */
/**
- *Method: Release
- * Give implementation a chance to release any data after the
- * interface is no longer used
- *Interface Version:
- * 1
- *Implementation Required:
- * No
- *Comments:
- * Called by Foxit SDK during the final cleanup process.
- *Parameters:
- * pThis - Pointer to the interface structure itself
- *Return Value:
- * None
+ * Method: Release
+ * Give the implementation a chance to release any resources after the
+ * interface is no longer used.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * No
+ * Comments:
+ * Called by PDFium during the final cleanup process.
+ * Parameters:
+ * pThis - Pointer to the interface structure itself
+ * Return Value:
+ * None
*/
void (*Release)(struct _FPDF_FORMFILLINFO* pThis);
/**
* Method: FFI_Invalidate
- * Invalidate the client area within the specified rectangle.
+ * Invalidate the client area within the specified rectangle.
* Interface Version:
- * 1
+ * 1
* Implementation Required:
- * yes
+ * yes
* Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to the page. Returned by FPDF_LoadPage
- *function.
- * left - Left position of the client area in PDF page
- *coordinate.
- * top - Top position of the client area in PDF page
- *coordinate.
- * right - Right position of the client area in PDF page
- *coordinate.
- * bottom - Bottom position of the client area in PDF page
- *coordinate.
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to the page. Returned by FPDF_LoadPage().
+ * left - Left position of the client area in PDF page
+ * coordinates.
+ * top - Top position of the client area in PDF page
+ * coordinates.
+ * right - Right position of the client area in PDF page
+ * coordinates.
+ * bottom - Bottom position of the client area in PDF page
+ * coordinates.
* Return Value:
- * None.
+ * None.
*
- *comments:
- * All positions are measured in PDF "user space".
- * Implementation should call FPDF_RenderPageBitmap() function for
- *repainting a specified page area.
- */
+ * Comments:
+ * All positions are measured in PDF "user space".
+ * Implementation should call FPDF_RenderPageBitmap() for repainting the
+ * specified page area.
+ */
void (*FFI_Invalidate)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_PAGE page,
double left,
@@ -448,36 +447,34 @@
/**
* Method: FFI_OutputSelectedRect
- * When user is taking the mouse to select texts on a form field,
- * this callback function will keep
- * returning the selected areas to the implementation.
+ * When the user selects text in form fields with the mouse, this
+ * callback function will be invoked with the selected areas.
*
* Interface Version:
- * 1
+ * 1
* Implementation Required:
- * No
+ * No
* Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to the page. Returned by FPDF_LoadPage
- * function.
- * left - Left position of the client area in PDF page
- * coordinate.
- * top - Top position of the client area in PDF page
- * coordinate.
- * right - Right position of the client area in PDF page
- * coordinate.
- * bottom - Bottom position of the client area in PDF page
- * coordinate.
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to the page. Returned by FPDF_LoadPage()/
+ * left - Left position of the client area in PDF page
+ * coordinates.
+ * top - Top position of the client area in PDF page
+ * coordinates.
+ * right - Right position of the client area in PDF page
+ * coordinates.
+ * bottom - Bottom position of the client area in PDF page
+ * coordinates.
* Return Value:
- * None.
+ * None.
*
- * comments:
- * This CALLBACK function is useful for implementing special text
- * selection effect. Implementation should
- * first records the returned rectangles, then draw them one by one
- * at the painting period, last,remove all
- * the recorded rectangles when finish painting.
- */
+ * Comments:
+ * This callback function is useful for implementing special text
+ * selection effects. An implementation should first record the returned
+ * rectangles, then draw them one by one during the next painting period.
+ * Lastly, it should remove all the recorded rectangles when finished
+ * painting.
+ */
void (*FFI_OutputSelectedRect)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_PAGE page,
double left,
@@ -486,238 +483,247 @@
double bottom);
/**
- * Method: FFI_SetCursor
- * Set the Cursor shape.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * nCursorType - Cursor type. see Flags for Cursor type for the
- * details.
- * Return value:
- * None.
- * */
+ * Method: FFI_SetCursor
+ * Set the Cursor shape.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * nCursorType - Cursor type, see Flags for Cursor type for the details.
+ * Return value:
+ * None.
+ */
void (*FFI_SetCursor)(struct _FPDF_FORMFILLINFO* pThis, int nCursorType);
/**
- * Method: FFI_SetTimer
- * This method installs a system timer. An interval value is specified,
- * and every time that interval elapses, the system must call into the
- * callback function with the timer ID as returned by this function.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * uElapse - Specifies the time-out value, in milliseconds.
- * lpTimerFunc - A pointer to the callback function-TimerCallback.
- * Return value:
- * The timer identifier of the new timer if the function is successful.
- * An application passes this value to the FFI_KillTimer method to kill
- * the timer. Nonzero if it is successful; otherwise, it is zero.
- * */
+ * Method: FFI_SetTimer
+ * This method installs a system timer. An interval value is specified,
+ * and every time that interval elapses, the system must call into the
+ * callback function with the timer ID as returned by this function.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * uElapse - Specifies the time-out value, in milliseconds.
+ * lpTimerFunc - A pointer to the callback function-TimerCallback.
+ * Return value:
+ * The timer identifier of the new timer if the function is successful.
+ * An application passes this value to the FFI_KillTimer method to kill
+ * the timer. Nonzero if it is successful; otherwise, it is zero.
+ */
int (*FFI_SetTimer)(struct _FPDF_FORMFILLINFO* pThis,
int uElapse,
TimerCallback lpTimerFunc);
/**
- * Method: FFI_KillTimer
- * This method uninstalls a system timer identified by nIDEvent, as
- * set by an earlier call to FFI_SetTimer.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * nTimerID - The timer ID returned by FFI_SetTimer function.
- * Return value:
- * None.
- * */
+ * Method: FFI_KillTimer
+ * This method uninstalls a system timer, as set by an earlier call to
+ * FFI_SetTimer.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * nTimerID - The timer ID returned by FFI_SetTimer function.
+ * Return value:
+ * None.
+ */
void (*FFI_KillTimer)(struct _FPDF_FORMFILLINFO* pThis, int nTimerID);
/**
- * Method: FFI_GetLocalTime
- * This method receives the current local time on the system.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * Return value:
- * None.
- * */
+ * Method: FFI_GetLocalTime
+ * This method receives the current local time on the system.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * Return value:
+ * The local time. See FPDF_SYSTEMTIME above for details.
+ */
FPDF_SYSTEMTIME (*FFI_GetLocalTime)(struct _FPDF_FORMFILLINFO* pThis);
/**
- * Method: FFI_OnChange
- * This method will be invoked to notify implementation when the
- * value of any FormField on the document had been changed.
- * Interface Version:
- * 1
- * Implementation Required:
- * no
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * Return value:
- * None.
- * */
+ * Method: FFI_OnChange
+ * This method will be invoked to notify the implementation when the
+ * value of any FormField on the document had been changed.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * no
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * Return value:
+ * None.
+ */
void (*FFI_OnChange)(struct _FPDF_FORMFILLINFO* pThis);
/**
- * Method: FFI_GetPage
- * This method receives the page pointer associated with a specified
- * page index.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * document - Handle to document. Returned by FPDF_LoadDocument
- * function.
- * nPageIndex - Index number of the page. 0 for the first page.
- * Return value:
- * Handle to the page. Returned by FPDF_LoadPage function.
- * Comments:
- * In some cases, the document-level JavaScript action may refer to a
- * page which hadn't been loaded yet.
- * To successfully run the javascript action, implementation need to load
- * the page for SDK.
- * */
+ * Method: FFI_GetPage
+ * This method receives the page handle associated with a specified page
+ * index.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * document - Handle to document. Returned by FPDF_LoadDocument().
+ * nPageIndex - Index number of the page. 0 for the first page.
+ * Return value:
+ * Handle to the page, as previously returned to the implementation by
+ * FPDF_LoadPage().
+ * Comments:
+ * The implementation is expected to keep track of the page handles it
+ * receives from PDFium, and their mappings to page numbers.
+ * In some cases, the document-level JavaScript action may refer to a
+ * page which hadn't been loaded yet. To successfully run the Javascript
+ * action, the implementation need to load the page.
+ */
FPDF_PAGE (*FFI_GetPage)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_DOCUMENT document,
int nPageIndex);
/**
- * Method: FFI_GetCurrentPage
- * This method receives the current page pointer.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * document - Handle to document. Returned by FPDF_LoadDocument
- * function.
- * Return value:
- * Handle to the page. Returned by FPDF_LoadPage function.
- * */
+ * Method: FFI_GetCurrentPage
+ * This method receives the handle to the current page.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * document - Handle to document. Returned by FPDF_LoadDocument().
+ * Return value:
+ * Handle to the page. Returned by FPDF_LoadPage().
+ * Comments:
+ * The implementation is expected to keep track of the current page. e.g.
+ * The current page can be the one that is most visible on screen.
+ */
FPDF_PAGE (*FFI_GetCurrentPage)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_DOCUMENT document);
/**
- * Method: FFI_GetRotation
- * This method receives currently rotation of the page view.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to page. Returned by FPDF_LoadPage function.
- * Return value:
- * The page rotation. Should be 0(0 degree),1(90 degree),2(180
- * degree),3(270 degree), in a clockwise direction.
- *
- * Note: Unused.
- * */
+ * Method: FFI_GetRotation
+ * This method receives currently rotation of the page view.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to page. Returned by FPDF_LoadPage function.
+ * Return value:
+ * A number to indicate the page rotation in 90 degree increments in a
+ * clockwise direction:
+ * 0 - 0 degrees
+ * 1 - 90 degrees
+ * 2 - 180 degrees
+ * 3 - 270 degrees
+ * Note: Unused.
+ */
int (*FFI_GetRotation)(struct _FPDF_FORMFILLINFO* pThis, FPDF_PAGE page);
/**
- * Method: FFI_ExecuteNamedAction
- * This method will execute an named action.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * namedAction - A byte string which indicates the named action,
- * terminated by 0.
- * Return value:
- * None.
- * Comments:
- * See the named actions description of <<PDF Reference, version 1.7>>
- * for more details.
- * */
+ * Method: FFI_ExecuteNamedAction
+ * This method will execute a named action.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * namedAction - A byte string which indicates the named action,
+ * terminated by 0.
+ * Return value:
+ * None.
+ * Comments:
+ * See the named actions description of <<PDF Reference, version 1.7>>
+ * for more details.
+ */
void (*FFI_ExecuteNamedAction)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_BYTESTRING namedAction);
/**
- * @brief This method will be called when a text field is getting or losing a
- * focus.
- *
- * @param[in] pThis Pointer to the interface structure itself.
- * @param[in] value The string value of the form field, in UTF-16LE
- * format.
- * @param[in] valueLen The length of the string value, number of characters
- * (not bytes).
- * @param[in] is_focus True if the form field is getting a focus, False for
- * losing a focus.
- *
- * @return None.
- *
- * @note Currently,only support text field and combobox field.
- * */
+ * Method: FFI_SetTextFieldFocus
+ * Called when a text field is getting or losing focus.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * no
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * value - The string value of the form field, in UTF-16LE
+ * format.
+ * valueLen - The length of the string value. This is the number
+ * of characters, not bytes.
+ * is_focus - True if the form field is getting focus, False if
+ * the form field is losing focus.
+ * Return value:
+ * None.
+ * Comments:
+ * Only supports text fields and combobox fields.
+ */
void (*FFI_SetTextFieldFocus)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_WIDESTRING value,
FPDF_DWORD valueLen,
FPDF_BOOL is_focus);
/**
- * Method: FFI_DoURIAction
- * This action resolves to a uniform resource identifier.
- * Interface Version:
- * 1
- * Implementation Required:
- * No
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * bsURI - A byte string which indicates the uniform resource
- * identifier, terminated by 0.
- * Return value:
- * None.
- * Comments:
- * See the URI actions description of <<PDF Reference, version 1.7>> for
- * more details.
- * */
+ * Method: FFI_DoURIAction
+ * Ask the implementation to navigate to a uniform resource identifier.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * No
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * bsURI - A byte string which indicates the uniform resource
+ * identifier, terminated by 0.
+ * Return value:
+ * None.
+ * Comments:
+ * See the URI actions description of <<PDF Reference, version 1.7>> for
+ * more details.
+ */
void (*FFI_DoURIAction)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_BYTESTRING bsURI);
/**
- * Method: FFI_DoGoToAction
- * This action changes the view to a specified destination.
- * Interface Version:
- * 1
- * Implementation Required:
- * No
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * nPageIndex - The index of the PDF page.
- * zoomMode - The zoom mode for viewing page. See below.
- * fPosArray - The float array which carries the position info.
- * sizeofArray - The size of float array.
- *
- * PDFZoom values:
- * - XYZ = 1
- * - FITPAGE = 2
- * - FITHORZ = 3
- * - FITVERT = 4
- * - FITRECT = 5
- * - FITBBOX = 6
- * - FITBHORZ = 7
- * - FITBVERT = 8
- *
- * Return value:
- * None.
- * Comments:
- * See the Destinations description of <<PDF Reference, version 1.7>> in
- *8.2.1 for more details.
- **/
+ * Method: FFI_DoGoToAction
+ * This action changes the view to a specified destination.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * No
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * nPageIndex - The index of the PDF page.
+ * zoomMode - The zoom mode for viewing page. See below.
+ * fPosArray - The float array which carries the position info.
+ * sizeofArray - The size of float array.
+ *
+ * PDFZoom values:
+ * - XYZ = 1
+ * - FITPAGE = 2
+ * - FITHORZ = 3
+ * - FITVERT = 4
+ * - FITRECT = 5
+ * - FITBBOX = 6
+ * - FITBHORZ = 7
+ * - FITBVERT = 8
+ *
+ * Return value:
+ * None.
+ * Comments:
+ * See the Destinations description of <<PDF Reference, version 1.7>> in
+ * 8.2.1 for more details.
+ */
void (*FFI_DoGoToAction)(struct _FPDF_FORMFILLINFO* pThis,
int nPageIndex,
int zoomMode,
@@ -732,27 +738,26 @@
#ifdef PDF_ENABLE_XFA
/* Version 2. */
/**
- * Method: FFI_DisplayCaret
- * This method will show the caret at specified position.
- * Interface Version:
- * 2
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to page. Returned by FPDF_LoadPage
- *function.
- * left - Left position of the client area in PDF page
- *coordinate.
- * top - Top position of the client area in PDF page
- *coordinate.
- * right - Right position of the client area in PDF page
- *coordinate.
- * bottom - Bottom position of the client area in PDF page
- *coordinate.
- * Return value:
- * None.
- **/
+ * Method: FFI_DisplayCaret
+ * This method will show the caret at specified position.
+ * Interface Version:
+ * 2
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to page. Returned by FPDF_LoadPage().
+ * left - Left position of the client area in PDF page
+ * coordinates.
+ * top - Top position of the client area in PDF page
+ * coordinates.
+ * right - Right position of the client area in PDF page
+ * coordinates.
+ * bottom - Bottom position of the client area in PDF page
+ * coordinates.
+ * Return value:
+ * None.
+ */
void (*FFI_DisplayCaret)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_PAGE page,
FPDF_BOOL bVisible,
@@ -817,27 +822,26 @@
FPDF_WIDESTRING wsURL);
/**
- * Method: FFI_GetPageViewRect
- * This method will get the current page view rectangle.
- * Interface Version:
- * 2
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to page. Returned by FPDF_LoadPage
- *function.
- * left - The pointer to receive left position of the page
- *view area in PDF page coordinate.
- * top - The pointer to receive top position of the page
- *view area in PDF page coordinate.
- * right - The pointer to receive right position of the
- *client area in PDF page coordinate.
- * bottom - The pointer to receive bottom position of the
- *client area in PDF page coordinate.
- * Return value:
- * None.
- **/
+ * Method: FFI_GetPageViewRect
+ * This method will get the current page view rectangle.
+ * Interface Version:
+ * 2
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to page. Returned by FPDF_LoadPage().
+ * left - The pointer to receive left position of the page
+ * view area in PDF page coordinates.
+ * top - The pointer to receive top position of the page
+ * view area in PDF page coordinates.
+ * right - The pointer to receive right position of the page
+ * view area in PDF page coordinates.
+ * bottom - The pointer to receive bottom position of the page
+ * view area in PDF page coordinates.
+ * Return value:
+ * None.
+ */
void (*FFI_GetPageViewRect)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_PAGE page,
double* left,
@@ -873,26 +877,26 @@
FPDF_DWORD event_type);
/**
- * Method: FFI_PopupMenu
- * This method will track the right context menu for XFA fields.
- * Interface Version:
- * 2
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * page - Handle to page. Returned by FPDF_LoadPage
- *function.
- * hWidget - Handle to XFA fields.
- * menuFlag - The menu flags. Please refer to macro definition
- *of FXFA_MENU_XXX and this can be one or a combination of these macros.
- * x - X position of the client area in PDF page
- *coordinate.
- * y - Y position of the client area in PDF page
- *coordinate.
- * Return value:
- * TRUE indicates success; otherwise false.
- **/
+ * Method: FFI_PopupMenu
+ * This method will track the right context menu for XFA fields.
+ * Interface Version:
+ * 2
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself.
+ * page - Handle to page. Returned by FPDF_LoadPage().
+ * hWidget - Handle to XFA fields.
+ * menuFlag - The menu flags. Please refer to macro definition
+ * of FXFA_MENU_XXX and this can be one or a
+ * combination of these macros.
+ * x - X position of the client area in PDF page
+ * coordinates.
+ * y - Y position of the client area in PDF page
+ * coordinates.
+ * Return value:
+ * TRUE indicates success; otherwise false.
+ */
FPDF_BOOL (*FFI_PopupMenu)(struct _FPDF_FORMFILLINFO* pThis,
FPDF_PAGE page,
FPDF_WIDGET hWidget,
