From 5f597db5596f302a5ae31447e5c3eaf4320dcef1 Mon Sep 17 00:00:00 2001 From: dsinclair Date: Fri, 25 Mar 2016 09:04:54 -0700 Subject: 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 --- public/fpdf_edit.h | 347 ++++++++++++++++++++++------------------------------- 1 file changed, 141 insertions(+), 206 deletions(-) (limited to 'public/fpdf_edit.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_ -- cgit v1.2.3