Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(28)

Issues Search
    My Issues | Starred     Open | Closed | All

Unified Diff: public/fpdf_edit.h

Issue 1826113003: Cleanup fpdf_edit.h and fpdf_doc.h documentation. (Closed) Base URL: https://pdfium.googlesource.com/pdfium.git@master
Patch Set: Created 4 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« public/fpdf_doc.h ('K') | « public/fpdf_doc.h ('k') | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: public/fpdf_edit.h
diff --git a/public/fpdf_edit.h b/public/fpdf_edit.h
index 4ec18ee44ac68291eeca46ffa791ea2c2ba935d8..2f1c8a4298c747885bbdd461bca22dd39a2c8bae 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,127 @@
#define FPDF_GetRValue(argb) ((uint8_t)((argb) >> 16))
#define FPDF_GetAValue(argb) ((uint8_t)((argb) >> 24))
+// TODO(dsinclair): What are these for?
Tom Sepez 2016/03/24 18:32:15 Nah, let's not check in this TODO
dsinclair 2016/03/25 02:06:09 Done.
+// 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, 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, 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 +148,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 +170,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.
Tom Sepez 2016/03/24 18:32:15 nit: false otherwise just to be pedantic. Several
dsinclair 2016/03/25 02:06:09 Acknowledged.
+//
+// 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, 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 +222,24 @@ 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.
+//
+// TODO(dsinclair): Does this have the same cache clearing requirements as
Tom Sepez 2016/03/24 18:32:15 nit: let's not commit this todo either.
dsinclair 2016/03/25 02:06:09 Done.
+// FPDFImageObj_LoadJpegFile.
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_
« public/fpdf_doc.h ('K') | « public/fpdf_doc.h ('k') | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698