diff options
| -rw-r--r-- | public/fpdf_doc.h | 448 | ||||
| -rw-r--r-- | public/fpdf_edit.h | 347 |
2 files changed, 325 insertions, 470 deletions
diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h index eae7c95e49..0b78743259 100644 --- a/public/fpdf_doc.h +++ b/public/fpdf_doc.h @@ -9,357 +9,277 @@ #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. +// 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 + +typedef struct _FS_QUADPOINTSF { + FS_FLOAT x1; + FS_FLOAT y1; + FS_FLOAT x2; + FS_FLOAT y2; + FS_FLOAT x3; + FS_FLOAT y3; + FS_FLOAT x4; + FS_FLOAT y4; +} FS_QUADPOINTSF; + +// 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); -// 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. +// 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); -// 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. +// 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); -// 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. +// 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); -// 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. +// 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); -// 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. +// 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); -#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. +// 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); -// 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. +// 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); -// 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. +// 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); -// 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. +// 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); -// 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. +// 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); -// 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(). +// 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); -// 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(). +// 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); -// 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. +// 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); -// 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. +// 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); -// 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; +// 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); -// 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; +// 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); -// 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. +// 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); -/* _FS_DEF_STRUCTURE_QUADPOINTSF_ */ -#ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_ -#define _FS_DEF_STRUCTURE_QUADPOINTSF_ -typedef struct _FS_QUADPOINTSF { - FS_FLOAT x1; - FS_FLOAT y1; - FS_FLOAT x2; - FS_FLOAT y2; - FS_FLOAT x3; - FS_FLOAT y3; - 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 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. -// -// 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. +// Get meta-data |tag| content from |document|. +// +// 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 4ec18ee44a..acec6c0d30 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 -////////////////////////////////////////////////////////////////////// -// -// Document functions +// Create a new PDF document. // -////////////////////////////////////////////////////////////////////// - -// 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 @@ DLLEXPORT void STDCALL FPDFPageObj_Transform(FPDF_PAGEOBJECT page_object, 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 @@ DLLEXPORT void STDCALL FPDFPage_TransformAnnots(FPDF_PAGE page, 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 @@ DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetMatrix(FPDF_PAGEOBJECT image_object, 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_ |