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,