Cleanup fpdf_edit.h and fpdf_doc.h documentation.
This CL cleans up the documentation in public/fpdf_doc.h and public/fpdf_edit.h.
Review URL: https://codereview.chromium.org/1826113003
diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h
index eae7c95..0b78743 100644
--- a/public/fpdf_doc.h
+++ b/public/fpdf_doc.h
@@ -9,292 +9,21 @@
#include "fpdfview.h"
-// Exported Functions
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
-// Function: FPDFBookmark_GetFirstChild
-// Get the first child of a bookmark item, or the first top level
-// bookmark item.
-// Parameters:
-// document - Handle to the document. Returned by
-// FPDF_LoadDocument or FPDF_LoadMemDocument.
-// bookmark - Handle to the current bookmark. Can be NULL if you
-// want to get the first top level item.
-// Return value:
-// Handle to the first child or top level bookmark item. NULL if no
-// child or top level bookmark found.
-//
-DLLEXPORT FPDF_BOOKMARK STDCALL
-FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
+// Unsupported action type.
+#define PDFACTION_UNSUPPORTED 0
+// Go to a destination within current document.
+#define PDFACTION_GOTO 1
+// Go to a destination within another document.
+#define PDFACTION_REMOTEGOTO 2
+// URI, including web pages and other Internet resources.
+#define PDFACTION_URI 3
+// Launch an application or open a file.
+#define PDFACTION_LAUNCH 4
-// Function: FPDFBookmark_GetNextSibling
-// Get next bookmark item at the same level.
-// Parameters:
-// document - Handle to the document. Returned by
-// FPDF_LoadDocument or FPDF_LoadMemDocument.
-// bookmark - Handle to the current bookmark. Cannot be NULL.
-// Return value:
-// Handle to the next bookmark item at the same level. NULL if this is
-// the last bookmark at this level.
-//
-DLLEXPORT FPDF_BOOKMARK STDCALL
-FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
-
-// Function: FPDFBookmark_GetTitle
-// Get title of a bookmark.
-// Parameters:
-// bookmark - Handle to the bookmark.
-// buffer - Buffer for the title. Can be NULL.
-// buflen - The length of the buffer in bytes. Can be 0.
-// Return value:
-// Number of bytes the title consumes, including trailing zeros.
-// Comments:
-// Regardless of the platform, the title is always in UTF-16LE
-// encoding. That means the buffer
-// can be treated as an array of WORD (on Intel and compatible CPUs),
-// each WORD representing the Unicode of
-// a character(some special Unicode may take 2 WORDs).The string is
-// followed by two bytes of zero
-// indicating the end of the string.
-//
-// The return value always indicates the number of bytes required for
-// the buffer, even if no buffer is specified
-// or the buffer size is less then required. In these cases, the buffer
-// will not be modified.
-//
-DLLEXPORT unsigned long STDCALL FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark,
- void* buffer,
- unsigned long buflen);
-
-// Function: FPDFBookmark_Find
-// Find a bookmark in the document, using the bookmark title.
-// Parameters:
-// document - Handle to the document. Returned by
-// FPDF_LoadDocument or FPDF_LoadMemDocument.
-// title - The UTF-16LE encoded Unicode string for the bookmark
-// title to be searched. Can't be NULL.
-// Return value:
-// Handle to the found bookmark item. NULL if the title can't be found.
-// Comments:
-// It always returns the first found bookmark if more than one
-// bookmarks have the same title.
-//
-DLLEXPORT FPDF_BOOKMARK STDCALL FPDFBookmark_Find(FPDF_DOCUMENT document,
- FPDF_WIDESTRING title);
-
-// Function: FPDFBookmark_GetDest
-// Get the destination associated with a bookmark item.
-// Parameters:
-// document - Handle to the document.
-// bookmark - Handle to the bookmark.
-// Return value:
-// Handle to the destination data. NULL if no destination is associated
-// with this bookmark.
-//
-DLLEXPORT FPDF_DEST STDCALL FPDFBookmark_GetDest(FPDF_DOCUMENT document,
- FPDF_BOOKMARK bookmark);
-
-// Function: FPDFBookmark_GetAction
-// Get the action associated with a bookmark item.
-// Parameters:
-// bookmark - Handle to the bookmark.
-// Return value:
-// Handle to the action data. NULL if no action is associated with this
-// bookmark. In this case, the
-// application should try FPDFBookmark_GetDest.
-//
-DLLEXPORT FPDF_ACTION STDCALL FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark);
-
-#define PDFACTION_UNSUPPORTED 0 // Unsupported action type.
-#define PDFACTION_GOTO 1 // Go to a destination within current document.
-#define PDFACTION_REMOTEGOTO 2 // Go to a destination within another document.
-#define PDFACTION_URI 3 // Universal Resource Identifier, including web
- // pages and other Internet based resources.
-#define PDFACTION_LAUNCH 4 // Launch an application or open a file.
-
-// Function: FPDFAction_GetType
-// Get type of an action.
-// Parameters:
-// action - Handle to the action.
-// Return value:
-// A type number as defined above.
-//
-DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action);
-
-// Function: FPDFAction_GetDest
-// Get destination of an action.
-// Parameters:
-// document - Handle to the document.
-// action - Handle to the action. It must be a GOTO or
-// REMOTEGOTO action.
-// Return value:
-// Handle to the destination data.
-// Comments:
-// In case of remote goto action, the application should first use
-// FPDFAction_GetFilePath to
-// get file path, then load that particular document, and use its
-// document handle to call this
-// function.
-//
-DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document,
- FPDF_ACTION action);
-
-// Function: FPDFAction_GetFilePath
-// Get file path of a remote goto action.
-// Parameters:
-// action - Handle to the action. Must be a REMOTEGOTO or
-// LAUNCH action.
-// buffer - A buffer for output the path string. Can be NULL.
-// buflen - The length of the buffer, number of bytes. Can be 0.
-// Return value:
-// Number of bytes the file path consumes, including trailing zero.
-//
-// Comments:
-// The file path is UTF-8 encoded. The return value is the number of
-// bytes required for the buffer, even when there is no buffer
-// specified, or the buffer size is less then required. In this case,
-// the buffer will not be modified.
-//
-DLLEXPORT unsigned long STDCALL
-FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen);
-
-// Function: FPDFAction_GetURIPath
-// Get URI path of a URI action.
-// Parameters:
-// document - Handle to the document.
-// action - Handle to the action. Must be a URI action.
-// buffer - A buffer for output the path string. Can be NULL.
-// buflen - The length of the buffer, number of bytes. Can be 0.
-// Return value:
-// Number of bytes the URI path consumes, including trailing zeros.
-// Comments:
-// The URI path is always encoded in 7-bit ASCII.
-//
-// The return value is the number of bytes required for the buffer,
-// even when there is no buffer specified, or the buffer size is less
-// then required. In this case, the buffer will not be modified.
-//
-DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document,
- FPDF_ACTION action,
- void* buffer,
- unsigned long buflen);
-
-// Function: FPDFDest_GetPageIndex
-// Get page index of a destination.
-// Parameters:
-// document - Handle to the document.
-// dest - Handle to the destination.
-// Return value:
-// The page index. Starting from 0 for the first page.
-//
-DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
- FPDF_DEST dest);
-
-// Function: FPDFLink_GetLinkAtPoint
-// Find a link at specified point on a document page.
-// Parameters:
-// page - Handle to the document page.
-// x - The x coordinate of the point, specified in page
-// coordinate system.
-// y - The y coordinate of the point, specified in page
-// coordinate system.
-// Return value:
-// Handle to the link. NULL if no link found at that point.
-// Comments:
-// The point coordinates are specified in page coordinate system. You can
-// convert coordinates from screen system to page system using
-// FPDF_DeviceToPage().
-//
-DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
- double x,
- double y);
-
-// Function: FPDFLink_GetLinkZOrderAtPoint
-// Find the z-order of a link at specified point on a document page.
-// Parameters:
-// page - Handle to the document page.
-// x - The x coordinate of the point, specified in page
-// coordinate system.
-// y - The y coordinate of the point, specified in page
-// coordinate system.
-// Return value:
-// Z-order of the link, or -1 if no link found at that point.
-// Higher numbers are closer to the front.
-// Comments:
-// The point coordinates are specified in page coordinate system. You can
-// convert coordinates from screen system to page system using
-// FPDF_DeviceToPage().
-//
-DLLEXPORT int STDCALL
-FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y);
-
-// Function: FPDFLink_GetDest
-// Get destination info of a link.
-// Parameters:
-// document - Handle to the document.
-// link - Handle to the link. Returned by
-// FPDFLink_GetLinkAtPoint.
-// Return value:
-// Handle to the destination. NULL if there is no destination
-// associated with the link, in this case
-// the application should try FPDFLink_GetAction.
-//
-DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
- FPDF_LINK link);
-
-// Function: FPDFLink_GetAction
-// Get action info of a link.
-// Parameters:
-// link - Handle to the link.
-// Return value:
-// Handle to the action. NULL if there is no action associated with the
-// link.
-//
-DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
-
-// Function: FPDFLink_Enumerate
-// This function would enumerate all the link annotations in a single
-// PDF page.
-// Parameters:
-// page[in] - Handle to the page.
-// startPos[in,out] - The start position to enumerate the link
-// annotations, which should be specified to start from
-// - 0 for the first call, and would receive the
-// next position for enumerating to start from.
-// linkAnnot[out] - Receive the link handle.
-// Return value:
-// TRUE if succceed, else False;
-//
-DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
- int* startPos,
- FPDF_LINK* linkAnnot);
-
-// Function: FPDFLink_GetAnnotRect
-// Get the annotation rectangle. (Specified by the |Rect| entry of
-// annotation dictionary).
-// Parameters:
-// linkAnnot[in] - Handle to the link annotation.
-// rect[out] - The annotation rect.
-// Return value:
-// TRUE if succceed, else False;
-//
-DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
- FS_RECTF* rect);
-
-// Function: FPDFLink_CountQuadPoints
-// Get the count of quadrilateral points to the link annotation.
-// Parameters:
-// linkAnnot[in] - Handle to the link annotation.
-// Return value:
-// The count of quadrilateral points.
-//
-DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
-
-/* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
-#ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_
-#define _FS_DEF_STRUCTURE_QUADPOINTSF_
typedef struct _FS_QUADPOINTSF {
FS_FLOAT x1;
FS_FLOAT y1;
@@ -305,61 +34,252 @@
FS_FLOAT x4;
FS_FLOAT y4;
} FS_QUADPOINTSF;
-#endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
-// Function: FPDFLink_GetQuadPoints
-// Get the quadrilateral points for the specified index in the link
-// annotation.
-// Parameters:
-// linkAnnot[in] - Handle to the link annotation.
-// quadIndex[in] - The specified quad points index.
-// quadPoints[out] - Receive the quadrilateral points.
-// Return value:
-// True if succeed, else False.
+// Get the first child of |bookmark|, or the first top-level bookmark item.
//
+// document - handle to the document.
+// bookmark - handle to the current bookmark. Pass NULL for the first top
+// level item.
+//
+// Returns a handle to the first child of |bookmark| or the first top-level
+// bookmark item. NULL if no child or top-level bookmark found.
+DLLEXPORT FPDF_BOOKMARK STDCALL
+FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
+
+// Get the next sibling of |bookmark|.
+//
+// document - handle to the document.
+// bookmark - handle to the current bookmark.
+//
+// Returns a handle to the next sibling of |bookmark|, or NULL if this is the
+// last bookmark at this level.
+DLLEXPORT FPDF_BOOKMARK STDCALL
+FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
+
+// Get the title of |bookmark|.
+//
+// bookmark - handle to the bookmark.
+// buffer - buffer for the title. May be NULL.
+// buflen - the length of the buffer in bytes. May be 0.
+//
+// Returns the number of bytes in the title, including the terminating NUL
+// character. The number of bytes is returned regardless of the |buffer| and
+// |buflen| parameters.
+//
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding. The
+// string is terminated by a UTF16 NUL character. If |buflen| is less then the
+// required length, or |buffer| is NULL, |buffer| will not be modified.
+DLLEXPORT unsigned long STDCALL FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark,
+ void* buffer,
+ unsigned long buflen);
+
+// Find the bookmark with |title| in |document|.
+//
+// document - handle to the document.
+// title - the UTF-16LE encoded Unicode title for which to search.
+//
+// Returns the handle to the bookmark, or NULL if |title| can't be found.
+//
+// |FPDFBookmark_Find| will always return the first bookmark found even if
+// multiple bookmarks have the same |title|.
+DLLEXPORT FPDF_BOOKMARK STDCALL FPDFBookmark_Find(FPDF_DOCUMENT document,
+ FPDF_WIDESTRING title);
+
+// Get the destination associated with |bookmark|.
+//
+// document - handle to the document.
+// bookmark - handle to the bookmark.
+//
+// Returns the handle to the destination data, NULL if no destination is
+// associated with |bookmark|.
+DLLEXPORT FPDF_DEST STDCALL FPDFBookmark_GetDest(FPDF_DOCUMENT document,
+ FPDF_BOOKMARK bookmark);
+
+// Get the action associated with |bookmark|.
+//
+// bookmark - handle to the bookmark.
+//
+// Returns the handle to the action data, or NULL if no action is associated
+// with |bookmark|. When NULL is returned, |FPDFBookmark_GetDest| should be
+// called to get the |bookmark| destination data.
+DLLEXPORT FPDF_ACTION STDCALL FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark);
+
+// Get the type of |action|.
+//
+// action - handle to the action.
+//
+// Returns one of:
+// PDFACTION_UNSUPPORTED
+// PDFACTION_GOTO
+// PDFACTION_REMOTEGOTO
+// PDFACTION_URI
+// PDFACTION_LAUNCH
+DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action);
+
+// Get the destination of |action|.
+//
+// document - handle to the document.
+// action - handle to the action. |action| must be a |PDFACTION_GOTO| or
+// |PDFACTION_REMOTEGOTO|.
+//
+// Returns a handle to the destination data.
+//
+// In the case of |PDFACTION_REMOTEGOTO|, you should first call
+// |FPDFAction_GetFilePath| then load that document, the document handle from
+// that document should pass as |document| to |FPDFAction_GetDest|.
+DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document,
+ FPDF_ACTION action);
+
+// Get file path of a |PDFACTION_REMOTEGOTO| |action|.
+//
+// action - handle to the action. |action| must be a |PDFACTION_LAUNCH| or
+// |PDFACTION_REMOTEGOTO|
+// buffer - a buffer for output the path string. May be NULL.
+// buflen - the length of the buffer, in bytes. May be 0.
+//
+// Returns the number of bytes in the file path, including the trailing UTF16
+// NUL character.
+//
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding.
+// If |buflen| is less then the returned length, or |buffer| is NULL, |buffer|
+// will not be modified.
+DLLEXPORT unsigned long STDCALL
+FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen);
+
+// Get the URI path of a |PDFACTION_URI| |action|.
+//
+// document - handle to the document.
+// action - handle to the action. Must be a |PDFACTION_URI|.
+// buffer - a buffer for the path string. May be NULL.
+// buflen - the length of the buffer, in bytes. May be 0.
+//
+// Returns the number of bytes in the URI path, including trailing zeros.
+//
+// The |buffer| is always encoded in 7-bit ASCII. If |buflen| is less then the
+// returned length, or |buffer| is NULL, |buffer| will not be modified.
+DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document,
+ FPDF_ACTION action,
+ void* buffer,
+ unsigned long buflen);
+
+// Get the page index of |dest|.
+//
+// document - handle to the document.
+// dest - handle to the destination.
+//
+// Returns the page index containing |dest|. Page indices start from 0.
+DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
+ FPDF_DEST dest);
+
+// Find a link at point (|x|,|y|) on |page|.
+//
+// page - handle to the document page.
+// x - the x coordinate, in the page coordinate system.
+// y - the y coordinate, in the page coordinate system.
+//
+// Returns a handle to the link, or NULL if no link found at the given point.
+//
+// You can convert coordinates from screen coordinates to page coordinates using
+// |FPDF_DeviceToPage|.
+DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
+ double x,
+ double y);
+
+// Find the Z-order of link at point (|x|,|y|) on |page|.
+//
+// page - handle to the document page.
+// x - the x coordinate, in the page coordinate system.
+// y - the y coordinate, in the page coordinate system.
+//
+// Returns the Z-order of the link, or -1 if no link found at the given point.
+// Larger Z-order numbers are closer to the front.
+//
+// You can convert coordinates from screen coordinates to page coordinates using
+// |FPDF_DeviceToPage|.
+DLLEXPORT int STDCALL
+FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y);
+
+// Get destination info for |link|.
+//
+// document - handle to the document.
+// link - handle to the link.
+//
+// Returns a handle to the destination, or NULL if there is no destination
+// associated with the link. In this case, you should call |FPDFLink_GetAction|
+// to retrieve the action associated with |link|.
+DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
+ FPDF_LINK link);
+
+// Get action info for |link|.
+//
+// link - handle to the link.
+//
+// Returns a handle to the action associated to |link|, or NULL if no action.
+DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
+
+// Enumerates all the link annotations in |page|.
+//
+// page - handle to the page.
+// startPos - the start position, should initially be 0 and is updated with
+// the next start position on return.
+// linkAnnot - the link handle for |startPos|.
+//
+// Returns TRUE on success.
+DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
+ int* startPos,
+ FPDF_LINK* linkAnnot);
+
+// Get the rectangle for |linkAnnot|.
+//
+// linkAnnot - handle to the link annotation.
+// rect - the annotation rectangle.
+//
+// Returns true on success.
+DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
+ FS_RECTF* rect);
+
+// Get the count of quadrilateral points to the |linkAnnot|.
+//
+// linkAnnot - handle to the link annotation.
+//
+// Returns the count of quadrilateral points.
+DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
+
+// Get the quadrilateral points for the specified |quadIndex| in |linkAnnot|.
+//
+// linkAnnot - handle to the link annotation.
+// quadIndex - the specified quad point index.
+// quadPoints - receives the quadrilateral points.
+//
+// Returns true on success.
DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot,
int quadIndex,
FS_QUADPOINTSF* quadPoints);
-// Function: FPDF_GetMetaText
-// Get a text from meta data of the document. Result is encoded in
-// UTF-16LE.
-// Parameters:
-// doc - Handle to a document
-// tag - The tag for the meta data. Currently, It can be
-// "Title", "Author",
-// "Subject", "Keywords", "Creator", "Producer",
-// "CreationDate", or "ModDate".
-// For detailed explanation of these tags and their
-// respective values,
-// please refer to PDF Reference 1.6, section 10.2.1,
-// "Document Information Dictionary".
-// buffer - A buffer for output the title. Can be NULL.
-// buflen - The length of the buffer, number of bytes. Can be 0.
-// Return value:
-// Number of bytes the title consumes, including trailing zeros.
-// Comments:
-// No matter on what platform, the title is always output in UTF-16LE
-// encoding, which means the buffer
-// can be regarded as an array of WORD (on Intel and compatible CPUs),
-// each WORD represent the Unicode of
-// a character (some special Unicode may take 2 WORDs). The string is
-// followed by two bytes of zero
-// indicating end of the string.
+// Get meta-data |tag| content from |document|.
//
-// The return value always indicated number of bytes required for the
-// buffer, even when there is
-// no buffer specified, or the buffer size is less then required. In
-// this case, the buffer will not
-// be modified.
+// doc - handle to the document
+// tag - the tag to retrieve. The tag can be one of:
+// Title, Author, Subject, Keywords, Creator, Producer,
+// CreationDate, or ModDate.
+// For detailed explanations of these tags and their respective
+// values, please refer to PDF Reference 1.6, section 10.2.1,
+// 'Document Information Dictionary'.
+// buffer - a buffer for the title. May be NULL.
+// buflen - the length of the buffer, in bytes. May be 0.
//
+// Returns the number of bytes in the title, including trailing zeros.
+//
+// The |buffer| is always encoded in UTF-16LE. The |buffer| is followed by two
+// bytes of zeros indicating the end of the string. If |buflen| is less then
+// the returned length, or |buffer| is NULL, |buffer| will not be modified.
DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
FPDF_BYTESTRING tag,
void* buffer,
unsigned long buflen);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_DOC_H_
diff --git a/public/fpdf_edit.h b/public/fpdf_edit.h
index 4ec18ee..acec6c0 100644
--- a/public/fpdf_edit.h
+++ b/public/fpdf_edit.h
@@ -11,10 +11,6 @@
#include "fpdfview.h"
-// Define all types used in the SDK. Note they can be simply regarded as opaque
-// pointers
-// or long integer numbers.
-
#define FPDF_ARGB(a, r, g, b) \
((uint32_t)(((uint32_t)(b)&0xff) | (((uint32_t)(g)&0xff) << 8) | \
(((uint32_t)(r)&0xff) << 16) | (((uint32_t)(a)&0xff) << 24)))
@@ -23,170 +19,126 @@
#define FPDF_GetRValue(argb) ((uint8_t)((argb) >> 16))
#define FPDF_GetAValue(argb) ((uint8_t)((argb) >> 24))
+// The page object constants.
+#define FPDF_PAGEOBJ_TEXT 1
+#define FPDF_PAGEOBJ_PATH 2
+#define FPDF_PAGEOBJ_IMAGE 3
+#define FPDF_PAGEOBJ_SHADING 4
+#define FPDF_PAGEOBJ_FORM 5
+
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
-//////////////////////////////////////////////////////////////////////
+// Create a new PDF document.
//
-// Document functions
-//
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDF_CreateNewDocument
-// Create a new PDF document.
-// Parameters:
-// None.
-// Return value:
-// A handle to a document. If failed, NULL is returned.
+// Returns a handle to a new document, or NULL on failure.
DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_CreateNewDocument();
-//////////////////////////////////////////////////////////////////////
+// Create a new PDF page.
//
-// Page functions
+// document - handle to document.
+// page_index - the index of the page to create.
+// width - the page width.
+// height - the page height.
//
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPage_New
-// Construct an empty page.
-// Parameters:
-// document - Handle to document. Returned by FPDF_LoadDocument
-// and FPDF_CreateNewDocument.
-// page_index - The index of a page.
-// width - The page width.
-// height - The page height.
-// Return value:
-// The handle to the page.
-// Comments:
-// Loaded page can be deleted by FPDFPage_Delete.
+// Returns the handle to the new page.
+//
+// The page should be deleted with |FPDFPage_Delete| when finished.
DLLEXPORT FPDF_PAGE STDCALL FPDFPage_New(FPDF_DOCUMENT document,
int page_index,
double width,
double height);
-// Function: FPDFPage_Delete
-// Delete a PDF page.
-// Parameters:
-// document - Handle to document. Returned by FPDF_LoadDocument
-// and FPDF_CreateNewDocument.
-// page_index - The index of a page.
-// Return value:
-// None.
+// Delete the page at |page_index|.
+//
+// document - handle to document.
+// page_index - the index of the page to delete.
DLLEXPORT void STDCALL FPDFPage_Delete(FPDF_DOCUMENT document, int page_index);
-// Function: FPDFPage_GetRotation
-// Get the page rotation. One of following values will be returned:
-// 0(0), 1(90), 2(180), 3(270).
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// Return value:
-// The PDF page rotation.
-// Comment:
-// The PDF page rotation is rotated clockwise.
+// Get the rotation of |page|.
+//
+// page - handle to a page
+//
+// Returns one of the following indicating the page rotation:
+// 0 - No rotation.
+// 1 - Rotated 90 degrees clockwise.
+// 2 - Rotated 180 degrees clockwise.
+// 3 - Rotated 270 degrees clockwise.
DLLEXPORT int STDCALL FPDFPage_GetRotation(FPDF_PAGE page);
-// Function: FPDFPage_SetRotation
-// Set page rotation. One of following values will be set: 0(0), 1(90),
-// 2(180), 3(270).
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// rotate - The value of the PDF page rotation.
-// Return value:
-// None.
-// Comment:
-// The PDF page rotation is rotated clockwise.
+// Set rotation for |page|.
//
+// page - handle to a page.
+// rotate - the rotation value, one of:
+// 0 - No rotation.
+// 1 - Rotated 90 degrees clockwise.
+// 2 - Rotated 180 degrees clockwise.
+// 3 - Rotated 270 degrees clockwise.
DLLEXPORT void STDCALL FPDFPage_SetRotation(FPDF_PAGE page, int rotate);
-// Function: FPDFPage_InsertObject
-// Insert an object to the page. The page object is automatically
-// freed.
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// page_obj - Handle to a page object. Returned by
-// FPDFPageObj_NewTextObj,FPDFPageObj_NewTextObjEx and
-// FPDFPageObj_NewPathObj.
-// Return value:
-// None.
+// Insert |page_obj| into |page|.
+//
+// page - handle to a page
+// page_obj - handle to a page object. The |page_obj| will be automatically
+// freed.
DLLEXPORT void STDCALL FPDFPage_InsertObject(FPDF_PAGE page,
FPDF_PAGEOBJECT page_obj);
-// Function: FPDFPage_CountObject
-// Get number of page objects inside the page.
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// Return value:
-// The number of the page object.
+// Get number of page objects inside |page|.
+//
+// page - handle to a page.
+//
+// Returns the number of objects in |page|.
DLLEXPORT int STDCALL FPDFPage_CountObject(FPDF_PAGE page);
-// Function: FPDFPage_GetObject
-// Get page object by index.
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// index - The index of a page object.
-// Return value:
-// The handle of the page object. Null for failed.
+// Get object in |page| at |index|.
+//
+// page - handle to a page.
+// index - the index of a page object.
+//
+// Returns the handle to the page object, or NULL on failed.
DLLEXPORT FPDF_PAGEOBJECT STDCALL FPDFPage_GetObject(FPDF_PAGE page, int index);
-// Function: FPDFPage_HasTransparency
-// Check that whether the content of specified PDF page contains
-// transparency.
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// Return value:
-// TRUE means that the PDF page does contains transparency.
-// Otherwise, returns FALSE.
+// Checks if |page| contains transparency.
+//
+// page - handle to a page.
+//
+// Returns TRUE if |page| contains transparency.
DLLEXPORT FPDF_BOOL STDCALL FPDFPage_HasTransparency(FPDF_PAGE page);
-// Function: FPDFPage_GenerateContent
-// Generate PDF Page content.
-// Parameters:
-// page - Handle to a page. Returned by FPDFPage_New or
-// FPDF_LoadPage.
-// Return value:
-// True if successful, false otherwise.
-// Comment:
-// Before you save the page to a file, or reload the page, you must
-// call the FPDFPage_GenerateContent function.
-// Or the changed information will be lost.
+// Generate the content of |page|.
+//
+// page - handle to a page.
+//
+// Returns TRUE on success.
+//
+// Before you save the page to a file, or reload the page, you must call
+// |FPDFPage_GenerateContent| or any changes to |page| will be lost.
DLLEXPORT FPDF_BOOL STDCALL FPDFPage_GenerateContent(FPDF_PAGE page);
-//////////////////////////////////////////////////////////////////////
+// Checks if |pageObject| contains transparency.
//
-// Page Object functions
+// pageObject - handle to a page object.
//
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPageObj_HasTransparency
-// Check that whether the specified PDF page object contains
-// transparency.
-// Parameters:
-// pageObject - Handle to a page object.
-// Return value:
-// TRUE means that the PDF page object does contains transparency.
-// Otherwise, returns FALSE.
+// Returns TRUE if |pageObject| contains transparency.
DLLEXPORT FPDF_BOOL STDCALL
FPDFPageObj_HasTransparency(FPDF_PAGEOBJECT pageObject);
-// Function: FPDFPageObj_Transform
-// Transform (scale, rotate, shear, move) page object.
-// Parameters:
-// page_object - Handle to a page object. Returned by
-// FPDFPageObj_NewImageObj.
-// a - The coefficient "a" of the matrix.
-// b - The coefficient "b" of the matrix.
-// c - The coefficient "c" of the matrix.
-// d - The coefficient "d" of the matrix.
-// e - The coefficient "e" of the matrix.
-// f - The coefficient "f" of the matrix.
-// Return value:
-// None.
+// Transform |pageObject| by the given matrix.
+//
+// page_object - handle to a page object.
+// a - matrix value.
+// b - matrix value.
+// c - matrix value.
+// d - matrix value.
+// e - matrix value.
+// f - matrix value.
+//
+// The matrix is composed as:
+// |a c e|
+// |b d f|
+// and can be used to scale, rotate, shear and translate the |page_object|.
DLLEXPORT void STDCALL FPDFPageObj_Transform(FPDF_PAGEOBJECT page_object,
double a,
double b,
@@ -195,18 +147,20 @@
double e,
double f);
-// Function: FPDFPage_TransformAnnots
-// Transform (scale, rotate, shear, move) all annots in a page.
-// Parameters:
-// page - Handle to a page.
-// a - The coefficient "a" of the matrix.
-// b - The coefficient "b" of the matrix.
-// c - The coefficient "c" of the matrix.
-// d - The coefficient "d" of the matrix.
-// e - The coefficient "e" of the matrix.
-// f - The coefficient "f" of the matrix.
-// Return value:
-// None.
+// Transform all annotations in |page|.
+//
+// page - handle to a page.
+// a - matrix value.
+// b - matrix value.
+// c - matrix value.
+// d - matrix value.
+// e - matrix value.
+// f - matrix value.
+//
+// The matrix is composed as:
+// |a c e|
+// |b d f|
+// and can be used to scale, rotate, shear and translate the |page| annotations.
DLLEXPORT void STDCALL FPDFPage_TransformAnnots(FPDF_PAGE page,
double a,
double b,
@@ -215,66 +169,50 @@
double e,
double f);
-// The page object constants.
-#define FPDF_PAGEOBJ_TEXT 1
-#define FPDF_PAGEOBJ_PATH 2
-#define FPDF_PAGEOBJ_IMAGE 3
-#define FPDF_PAGEOBJ_SHADING 4
-#define FPDF_PAGEOBJ_FORM 5
-
-//////////////////////////////////////////////////////////////////////
+// Create a new image object.
//
-// Image functions
+// document - handle to a document.
//
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPageObj_NewImgeObj
-// Create a new Image Object.
-// Parameters:
-// document - Handle to document. Returned by
-// FPDF_LoadDocument or FPDF_CreateNewDocument function.
-// Return Value:
-// Handle of image object.
+// Returns a handle to a new image object.
DLLEXPORT FPDF_PAGEOBJECT STDCALL
FPDFPageObj_NewImgeObj(FPDF_DOCUMENT document);
-// Function: FPDFImageObj_LoadJpegFile
-// Load Image from a JPEG image file and then set it to an image
-// object.
-// Parameters:
-// pages - Pointers to the start of all loaded pages, could
-// be NULL.
-// nCount - Number of pages, could be 0.
-// image_object - Handle of image object returned by
-// FPDFPageObj_NewImgeObj.
-// fileAccess - The custom file access handler, which specifies
-// the JPEG image file.
-// Return Value:
-// TRUE if successful, FALSE otherwise.
-// Note:
-// The image object might already has an associated image, which is
-// shared and cached by the loaded pages, In this case, we need to
-// clear the cache of image for all the loaded pages.
-// Pass pages and count to this API to clear the image cache.
+// Load an image from a JPEG image file and then set it into |image_object|.
+//
+// pages - pointer to the start of all loaded pages, may be NULL.
+// nCount - number of |pages|, may be 0.
+// image_object - handle to an image object.
+// fileAccess - file access handler which specifies the JPEG image file.
+//
+// Returns TRUE on success.
+//
+// The image object might already have an associated image, which is shared and
+// cached by the loaded pages. In that case, we need to clear the cached image
+// for all the loaded pages. Pass |pages| and page count (|nCount|) to this API
+// to clear the image cache. If the image is not previously shared, or NULL is a
+// valid |pages| value.
DLLEXPORT FPDF_BOOL STDCALL
FPDFImageObj_LoadJpegFile(FPDF_PAGE* pages,
int nCount,
FPDF_PAGEOBJECT image_object,
FPDF_FILEACCESS* fileAccess);
-// Function: FPDFImageObj_SetMatrix
-// Set the matrix of an image object.
-// Parameters:
-// image_object - Handle of image object returned by
-// FPDFPageObj_NewImgeObj.
-// a - The coefficient "a" of the matrix.
-// b - The coefficient "b" of the matrix.
-// c - The coefficient "c" of the matrix.
-// d - The coefficient "d" of the matrix.
-// e - The coefficient "e" of the matrix.
-// f - The coefficient "f" of the matrix.
-// Return value:
-// TRUE if successful, FALSE otherwise.
+// Set the transform matrix of |image_object|.
+//
+// image_object - handle to an image object.
+// a - matrix value.
+// b - matrix value.
+// c - matrix value.
+// d - matrix value.
+// e - matrix value.
+// f - matrix value.
+//
+// The matrix is composed as:
+// |a c e|
+// |b d f|
+// and can be used to scale, rotate, shear and translate the |page| annotations.
+//
+// Returns TRUE on success.
DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetMatrix(FPDF_PAGEOBJECT image_object,
double a,
double b,
@@ -283,24 +221,21 @@
double e,
double f);
-// Function: FPDFImageObj_SetBitmap
-// Set the bitmap to an image object.
-// Parameters:
-// pages - Pointer's to the start of all loaded pages.
-// nCount - Number of pages.
-// image_object - Handle of image object returned by
-// FPDFPageObj_NewImgeObj.
-// bitmap - The handle of the bitmap which you want to set
-// it to the image object.
-// Return value:
-// TRUE if successful, FALSE otherwise.
+// Set |bitmap| to |image_object|.
+//
+// pages - pointer to the start of all loaded pages, may be NULL.
+// nCount - number of |pages|, may be 0.
+// image_object - handle to an image object.
+// bitmap - handle of the bitmap.
+//
+// Returns TRUE on success.
DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetBitmap(FPDF_PAGE* pages,
int nCount,
FPDF_PAGEOBJECT image_object,
FPDF_BITMAP bitmap);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_EDIT_H_
