Basic APIs and tests for creating annotations

1. Added API for adding annotations and modifying common annotation
properties
   * Added three embedder tests covering all of the API functions.

Bug=pdfium:737

Change-Id: I369d9e17f589f896f9e8c672382f082e524ae534
Reviewed-on: https://pdfium-review.googlesource.com/6351
Commit-Queue: dsinclair <dsinclair@chromium.org>
Reviewed-by: Lei Zhang <thestig@chromium.org>
Reviewed-by: dsinclair <dsinclair@chromium.org>

1 files changed, 87 insertions, 20 deletions

diff --git a/public/fpdf_annot.h b/public/fpdf_annot.h
index 29207a6f60..19265d6ddc 100644
--- a/public/fpdf_annot.h
+++ b/public/fpdf_annot.h
@@ -45,6 +45,40 @@ extern "C" {
 #define FPDF_ANNOT_RICHMEDIA 26
 #define FPDF_ANNOT_XFAWIDGET 27
 
+typedef enum FPDFANNOT_COLORTYPE {
+  FPDFANNOT_COLORTYPE_Color = 0,
+  FPDFANNOT_COLORTYPE_InteriorColor
+} FPDFANNOT_COLORTYPE;
+
+typedef enum FPDFANNOT_TEXTTYPE {
+  FPDFANNOT_TEXTTYPE_Contents = 0,
+  FPDFANNOT_TEXTTYPE_Author
+} FPDFANNOT_TEXTTYPE;
+
+// Check if an annotation subtype is currently supported for creating and
+// displaying. The supported subtypes must be consistent with the ones supported
+// by AP generation - see the list of calls to CPVT_GenerateAP::Generate*AP() in
+// CPDF_Annot::GenerateAPIfNeeded().
+//
+//   subtype   - the subtype to be checked.
+//
+// Returns true if this subtype supported, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL
+FPDFAnnot_IsSupportedSubtype(FPDF_ANNOTATION_SUBTYPE subtype);
+
+// Create an annotation in |page| of the subtype |subtype|. If the specified
+// subtype is illegal or unsupported, then a new annotation will not be created.
+//
+//   page      - handle to a page.
+//   subtype   - the subtype of the new annotation.
+//   annot     - receives the newly created annotation.
+//
+// Returns true if successful, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL
+FPDFPage_CreateAnnot(FPDF_PAGE page,
+                     FPDF_ANNOTATION_SUBTYPE subtype,
+                     FPDF_ANNOTATION* annot);
+
 // Get the number of annotations in |page|.
 //
 //   page   - handle to a page.
@@ -56,7 +90,7 @@ DLLEXPORT int STDCALL FPDFPage_GetAnnotCount(FPDF_PAGE page);
 //
 //   page  - handle to a page.
 //   index - the index of the annotation.
-//   annot - receives the annotation
+//   annot - receives the annotation.
 //
 // Returns true if successful, false otherwise.
 DLLEXPORT FPDF_BOOL STDCALL FPDFPage_GetAnnot(FPDF_PAGE page,
@@ -71,18 +105,28 @@ DLLEXPORT FPDF_BOOL STDCALL FPDFPage_GetAnnot(FPDF_PAGE page,
 DLLEXPORT FPDF_ANNOTATION_SUBTYPE STDCALL
 FPDFAnnot_GetSubtype(FPDF_ANNOTATION annot);
 
-typedef enum FPDFANNOT_COLORTYPE {
-  FPDFANNOT_COLORTYPE_Color = 0,
-  FPDFANNOT_COLORTYPE_InteriorColor
-} FPDFANNOT_COLORTYPE;
+// Set the color of an annotation.
+//
+//   annot    - handle to an annotation.
+//   type     - type of the color to be set.
+//   R, G, B  - buffer to hold the RGB value of the color. Ranges from 0 to 255.
+//   A        - buffer to hold the opacity. Ranges from 0 to 255.
+//
+// Returns true if successful, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_SetColor(FPDF_ANNOTATION annot,
+                                               FPDFANNOT_COLORTYPE type,
+                                               unsigned int R,
+                                               unsigned int G,
+                                               unsigned int B,
+                                               unsigned int A);
 
 // Get the color of an annotation. If no color is specified, default to yellow
 // for highlight annotation, black for all else.
 //
-//   annot  - handle to an annotation.
-//   type   - type of the color requested. Default to Color.
+//   annot    - handle to an annotation.
+//   type     - type of the color requested.
 //   R, G, B  - buffer to hold the RGB value of the color. Ranges from 0 to 255.
-//   A      - buffer to hold the opacity. Ranges from 0 to 255.
+//   A        - buffer to hold the opacity. Ranges from 0 to 255.
 //
 // Returns true if successful, false otherwise.
 DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_GetColor(FPDF_ANNOTATION annot,
@@ -95,9 +139,9 @@ DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_GetColor(FPDF_ANNOTATION annot,
 // Check if the annotation is of a type that has attachment points
 // (i.e. quadpoints). Quadpoints are the vertices of the rectange that
 // encompasses the texts affected by the annotation. They provide the
-// coordinates in the page where the annotation is attached. Only markup
-// annotations (i.e. highlight, strikeout, squiggly, underline, and link) have
-// quadpoints.
+// coordinates in the page where the annotation is attached. Only text markup
+// annotations (i.e. highlight, strikeout, squiggly, and underline) and link
+// annotations have quadpoints.
 //
 //   annot  - handle to an annotation.
 //
@@ -106,40 +150,63 @@ DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_GetColor(FPDF_ANNOTATION annot,
 DLLEXPORT FPDF_BOOL STDCALL
 FPDFAnnot_HasAttachmentPoints(FPDF_ANNOTATION annot);
 
+// Set the attachment points (i.e. quadpoints) of an annotation.
+//
+//   annot      - handle to an annotation.
+//   quadPoints - the quadpoints to be set.
+//
+// Returns true if successful, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL
+FPDFAnnot_SetAttachmentPoints(FPDF_ANNOTATION annot, FS_QUADPOINTSF quadPoints);
+
 // Get the attachment points (i.e. quadpoints) of an annotation.
 //
-//   annot  - handle to an annotation.
-//   quadPoints - receives the attachment points
+//   annot      - handle to an annotation.
+//   quadPoints - receives the attachment points.
 //
 // Returns true if successful, false otherwise.
 DLLEXPORT FPDF_BOOL STDCALL
 FPDFAnnot_GetAttachmentPoints(FPDF_ANNOTATION annot,
                               FS_QUADPOINTSF* quadPoints);
 
+// Set the annotation rectangle defining the location of the annotation.
+//
+//   annot  - handle to an annotation.
+//   rect   - the annotation rectangle to be set.
+//
+// Returns true if successful, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_SetRect(FPDF_ANNOTATION annot,
+                                              FS_RECTF rect);
+
 // Get the annotation rectangle defining the location of the annotation.
 //
 //   annot  - handle to an annotation.
-//   rect   - receives the annotation rectangle
+//   rect   - receives the annotation rectangle.
 //
 // Returns true if successful, false otherwise.
 DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_GetRect(FPDF_ANNOTATION annot,
                                               FS_RECTF* rect);
 
-typedef enum FPDFANNOT_TEXTTYPE {
-  FPDFANNOT_TEXTTYPE_Contents = 0,
-  FPDFANNOT_TEXTTYPE_Author
-} FPDFANNOT_TEXTTYPE;
+// Set the contents of an annotation.
+//
+//   annot  - handle to an annotation.
+//   type   - type of the text to be set.
+//   text   - the text to be set.
+//
+// Returns true if successful, false otherwise.
+DLLEXPORT FPDF_BOOL STDCALL FPDFAnnot_SetText(FPDF_ANNOTATION annot,
+                                              FPDFANNOT_TEXTTYPE type,
+                                              FPDF_WIDESTRING text);
 
 // Get the contents of an annotation. |buffer| is only modified if |buflen|
 // is longer than the length of contents.
 //
 //   annot  - handle to an annotation.
-//   type   - type of the text requested. Default to Contents.
+//   type   - type of the text requested.
 //   buffer - buffer for holding the contents string, encoded in UTF16-LE.
 //   buflen - length of the buffer.
 //
 // Returns the length of the contents.
-
 DLLEXPORT unsigned long STDCALL FPDFAnnot_GetText(FPDF_ANNOTATION annot,
                                                   FPDFANNOT_TEXTTYPE type,
                                                   char* buffer,