1 // Copyright 2017 PDFium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef PUBLIC_FPDF_ANNOT_H_ 6 #define PUBLIC_FPDF_ANNOT_H_ 7 8 // NOLINTNEXTLINE(build/include) 9 #include "fpdfview.h" 10 11 // NOLINTNEXTLINE(build/include) 12 #include "fpdf_doc.h" 13 // NOLINTNEXTLINE(build/include) 14 #include "fpdf_formfill.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif // __cplusplus 19 20 #define FPDF_ANNOT_UNKNOWN 0 21 #define FPDF_ANNOT_TEXT 1 22 #define FPDF_ANNOT_LINK 2 23 #define FPDF_ANNOT_FREETEXT 3 24 #define FPDF_ANNOT_LINE 4 25 #define FPDF_ANNOT_SQUARE 5 26 #define FPDF_ANNOT_CIRCLE 6 27 #define FPDF_ANNOT_POLYGON 7 28 #define FPDF_ANNOT_POLYLINE 8 29 #define FPDF_ANNOT_HIGHLIGHT 9 30 #define FPDF_ANNOT_UNDERLINE 10 31 #define FPDF_ANNOT_SQUIGGLY 11 32 #define FPDF_ANNOT_STRIKEOUT 12 33 #define FPDF_ANNOT_STAMP 13 34 #define FPDF_ANNOT_CARET 14 35 #define FPDF_ANNOT_INK 15 36 #define FPDF_ANNOT_POPUP 16 37 #define FPDF_ANNOT_FILEATTACHMENT 17 38 #define FPDF_ANNOT_SOUND 18 39 #define FPDF_ANNOT_MOVIE 19 40 #define FPDF_ANNOT_WIDGET 20 41 #define FPDF_ANNOT_SCREEN 21 42 #define FPDF_ANNOT_PRINTERMARK 22 43 #define FPDF_ANNOT_TRAPNET 23 44 #define FPDF_ANNOT_WATERMARK 24 45 #define FPDF_ANNOT_THREED 25 46 #define FPDF_ANNOT_RICHMEDIA 26 47 #define FPDF_ANNOT_XFAWIDGET 27 48 49 // Refer to PDF Reference (6th edition) table 8.16 for all annotation flags. 50 #define FPDF_ANNOT_FLAG_NONE 0 51 #define FPDF_ANNOT_FLAG_INVISIBLE (1 << 0) 52 #define FPDF_ANNOT_FLAG_HIDDEN (1 << 1) 53 #define FPDF_ANNOT_FLAG_PRINT (1 << 2) 54 #define FPDF_ANNOT_FLAG_NOZOOM (1 << 3) 55 #define FPDF_ANNOT_FLAG_NOROTATE (1 << 4) 56 #define FPDF_ANNOT_FLAG_NOVIEW (1 << 5) 57 #define FPDF_ANNOT_FLAG_READONLY (1 << 6) 58 #define FPDF_ANNOT_FLAG_LOCKED (1 << 7) 59 #define FPDF_ANNOT_FLAG_TOGGLENOVIEW (1 << 8) 60 61 #define FPDF_ANNOT_APPEARANCEMODE_NORMAL 0 62 #define FPDF_ANNOT_APPEARANCEMODE_ROLLOVER 1 63 #define FPDF_ANNOT_APPEARANCEMODE_DOWN 2 64 #define FPDF_ANNOT_APPEARANCEMODE_COUNT 3 65 66 #define FPDF_OBJECT_UNKNOWN 0 67 #define FPDF_OBJECT_BOOLEAN 1 68 #define FPDF_OBJECT_NUMBER 2 69 #define FPDF_OBJECT_STRING 3 70 #define FPDF_OBJECT_NAME 4 71 #define FPDF_OBJECT_ARRAY 5 72 #define FPDF_OBJECT_DICTIONARY 6 73 #define FPDF_OBJECT_STREAM 7 74 #define FPDF_OBJECT_NULLOBJ 8 75 #define FPDF_OBJECT_REFERENCE 9 76 77 // Refer to PDF Reference version 1.7 table 8.70 for field flags common to all 78 // interactive form field types. 79 #define FPDF_FORMFLAG_NONE 0 80 #define FPDF_FORMFLAG_READONLY (1 << 0) 81 #define FPDF_FORMFLAG_REQUIRED (1 << 1) 82 #define FPDF_FORMFLAG_NOEXPORT (1 << 2) 83 84 // Refer to PDF Reference version 1.7 table 8.77 for field flags specific to 85 // interactive form text fields. 86 #define FPDF_FORMFLAG_TEXT_MULTILINE (1 << 12) 87 88 // Refer to PDF Reference version 1.7 table 8.79 for field flags specific to 89 // interactive form choice fields. 90 #define FPDF_FORMFLAG_CHOICE_COMBO (1 << 17) 91 #define FPDF_FORMFLAG_CHOICE_EDIT (1 << 18) 92 93 typedef enum FPDFANNOT_COLORTYPE { 94 FPDFANNOT_COLORTYPE_Color = 0, 95 FPDFANNOT_COLORTYPE_InteriorColor 96 } FPDFANNOT_COLORTYPE; 97 98 // Experimental API. 99 // Check if an annotation subtype is currently supported for creation. 100 // Currently supported subtypes: circle, highlight, ink, popup, square, 101 // squiggly, stamp, strikeout, text, and underline. 102 // 103 // subtype - the subtype to be checked. 104 // 105 // Returns true if this subtype supported. 106 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 107 FPDFAnnot_IsSupportedSubtype(FPDF_ANNOTATION_SUBTYPE subtype); 108 109 // Experimental API. 110 // Create an annotation in |page| of the subtype |subtype|. If the specified 111 // subtype is illegal or unsupported, then a new annotation will not be created. 112 // Must call FPDFPage_CloseAnnot() when the annotation returned by this 113 // function is no longer needed. 114 // 115 // page - handle to a page. 116 // subtype - the subtype of the new annotation. 117 // 118 // Returns a handle to the new annotation object, or NULL on failure. 119 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 120 FPDFPage_CreateAnnot(FPDF_PAGE page, FPDF_ANNOTATION_SUBTYPE subtype); 121 122 // Experimental API. 123 // Get the number of annotations in |page|. 124 // 125 // page - handle to a page. 126 // 127 // Returns the number of annotations in |page|. 128 FPDF_EXPORT int FPDF_CALLCONV FPDFPage_GetAnnotCount(FPDF_PAGE page); 129 130 // Experimental API. 131 // Get annotation in |page| at |index|. Must call FPDFPage_CloseAnnot() when the 132 // annotation returned by this function is no longer needed. 133 // 134 // page - handle to a page. 135 // index - the index of the annotation. 136 // 137 // Returns a handle to the annotation object, or NULL on failure. 138 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV FPDFPage_GetAnnot(FPDF_PAGE page, 139 int index); 140 141 // Experimental API. 142 // Get the index of |annot| in |page|. This is the opposite of 143 // FPDFPage_GetAnnot(). 144 // 145 // page - handle to the page that the annotation is on. 146 // annot - handle to an annotation. 147 // 148 // Returns the index of |annot|, or -1 on failure. 149 FPDF_EXPORT int FPDF_CALLCONV FPDFPage_GetAnnotIndex(FPDF_PAGE page, 150 FPDF_ANNOTATION annot); 151 152 // Experimental API. 153 // Close an annotation. Must be called when the annotation returned by 154 // FPDFPage_CreateAnnot() or FPDFPage_GetAnnot() is no longer needed. This 155 // function does not remove the annotation from the document. 156 // 157 // annot - handle to an annotation. 158 FPDF_EXPORT void FPDF_CALLCONV FPDFPage_CloseAnnot(FPDF_ANNOTATION annot); 159 160 // Experimental API. 161 // Remove the annotation in |page| at |index|. 162 // 163 // page - handle to a page. 164 // index - the index of the annotation. 165 // 166 // Returns true if successful. 167 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFPage_RemoveAnnot(FPDF_PAGE page, 168 int index); 169 170 // Experimental API. 171 // Get the subtype of an annotation. 172 // 173 // annot - handle to an annotation. 174 // 175 // Returns the annotation subtype. 176 FPDF_EXPORT FPDF_ANNOTATION_SUBTYPE FPDF_CALLCONV 177 FPDFAnnot_GetSubtype(FPDF_ANNOTATION annot); 178 179 // Experimental API. 180 // Check if an annotation subtype is currently supported for object extraction, 181 // update, and removal. 182 // Currently supported subtypes: ink and stamp. 183 // 184 // subtype - the subtype to be checked. 185 // 186 // Returns true if this subtype supported. 187 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 188 FPDFAnnot_IsObjectSupportedSubtype(FPDF_ANNOTATION_SUBTYPE subtype); 189 190 // Experimental API. 191 // Update |obj| in |annot|. |obj| must be in |annot| already and must have 192 // been retrieved by FPDFAnnot_GetObject(). Currently, only ink and stamp 193 // annotations are supported by this API. Also note that only path, image, and 194 // text objects have APIs for modification; see FPDFPath_*(), FPDFText_*(), and 195 // FPDFImageObj_*(). 196 // 197 // annot - handle to an annotation. 198 // obj - handle to the object that |annot| needs to update. 199 // 200 // Return true if successful. 201 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 202 FPDFAnnot_UpdateObject(FPDF_ANNOTATION annot, FPDF_PAGEOBJECT obj); 203 204 // Experimental API. 205 // Add |obj| to |annot|. |obj| must have been created by 206 // FPDFPageObj_CreateNew{Path|Rect}() or FPDFPageObj_New{Text|Image}Obj(), and 207 // will be owned by |annot|. Note that an |obj| cannot belong to more than one 208 // |annot|. Currently, only ink and stamp annotations are supported by this API. 209 // Also note that only path, image, and text objects have APIs for creation. 210 // 211 // annot - handle to an annotation. 212 // obj - handle to the object that is to be added to |annot|. 213 // 214 // Return true if successful. 215 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 216 FPDFAnnot_AppendObject(FPDF_ANNOTATION annot, FPDF_PAGEOBJECT obj); 217 218 // Experimental API. 219 // Get the total number of objects in |annot|, including path objects, text 220 // objects, external objects, image objects, and shading objects. 221 // 222 // annot - handle to an annotation. 223 // 224 // Returns the number of objects in |annot|. 225 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_GetObjectCount(FPDF_ANNOTATION annot); 226 227 // Experimental API. 228 // Get the object in |annot| at |index|. 229 // 230 // annot - handle to an annotation. 231 // index - the index of the object. 232 // 233 // Return a handle to the object, or NULL on failure. 234 FPDF_EXPORT FPDF_PAGEOBJECT FPDF_CALLCONV 235 FPDFAnnot_GetObject(FPDF_ANNOTATION annot, int index); 236 237 // Experimental API. 238 // Remove the object in |annot| at |index|. 239 // 240 // annot - handle to an annotation. 241 // index - the index of the object to be removed. 242 // 243 // Return true if successful. 244 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 245 FPDFAnnot_RemoveObject(FPDF_ANNOTATION annot, int index); 246 247 // Experimental API. 248 // Set the color of an annotation. Fails when called on annotations with 249 // appearance streams already defined; instead use 250 // FPDFPath_Set{Stroke|Fill}Color(). 251 // 252 // annot - handle to an annotation. 253 // type - type of the color to be set. 254 // R, G, B - buffer to hold the RGB value of the color. Ranges from 0 to 255. 255 // A - buffer to hold the opacity. Ranges from 0 to 255. 256 // 257 // Returns true if successful. 258 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetColor(FPDF_ANNOTATION annot, 259 FPDFANNOT_COLORTYPE type, 260 unsigned int R, 261 unsigned int G, 262 unsigned int B, 263 unsigned int A); 264 265 // Experimental API. 266 // Get the color of an annotation. If no color is specified, default to yellow 267 // for highlight annotation, black for all else. Fails when called on 268 // annotations with appearance streams already defined; instead use 269 // FPDFPath_Get{Stroke|Fill}Color(). 270 // 271 // annot - handle to an annotation. 272 // type - type of the color requested. 273 // R, G, B - buffer to hold the RGB value of the color. Ranges from 0 to 255. 274 // A - buffer to hold the opacity. Ranges from 0 to 255. 275 // 276 // Returns true if successful. 277 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_GetColor(FPDF_ANNOTATION annot, 278 FPDFANNOT_COLORTYPE type, 279 unsigned int* R, 280 unsigned int* G, 281 unsigned int* B, 282 unsigned int* A); 283 284 // Experimental API. 285 // Check if the annotation is of a type that has attachment points 286 // (i.e. quadpoints). Quadpoints are the vertices of the rectange that 287 // encompasses the texts affected by the annotation. They provide the 288 // coordinates in the page where the annotation is attached. Only text markup 289 // annotations (i.e. highlight, strikeout, squiggly, and underline) and link 290 // annotations have quadpoints. 291 // 292 // annot - handle to an annotation. 293 // 294 // Returns true if the annotation is of a type that has quadpoints, false 295 // otherwise. 296 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 297 FPDFAnnot_HasAttachmentPoints(FPDF_ANNOTATION annot); 298 299 // Experimental API. 300 // Set the attachment points (i.e. quadpoints) of an annotation. If the 301 // annotation's appearance stream is defined and this annotation is of a type 302 // with quadpoints, then update the bounding box too if the new quadpoints 303 // define a bigger one. 304 // 305 // annot - handle to an annotation. 306 // quadPoints - the quadpoints to be set. 307 // 308 // Returns true if successful. 309 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 310 FPDFAnnot_SetAttachmentPoints(FPDF_ANNOTATION annot, 311 const FS_QUADPOINTSF* quadPoints); 312 313 // Experimental API. 314 // Get the attachment points (i.e. quadpoints) of an annotation. 315 // 316 // annot - handle to an annotation. 317 // quadPoints - receives the quadpoints; must not be NULL. 318 // 319 // Returns true if successful. 320 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 321 FPDFAnnot_GetAttachmentPoints(FPDF_ANNOTATION annot, 322 FS_QUADPOINTSF* quadPoints); 323 324 // Experimental API. 325 // Set the annotation rectangle defining the location of the annotation. If the 326 // annotation's appearance stream is defined and this annotation is of a type 327 // without quadpoints, then update the bounding box too if the new rectangle 328 // defines a bigger one. 329 // 330 // annot - handle to an annotation. 331 // rect - the annotation rectangle to be set. 332 // 333 // Returns true if successful. 334 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetRect(FPDF_ANNOTATION annot, 335 const FS_RECTF* rect); 336 337 // Experimental API. 338 // Get the annotation rectangle defining the location of the annotation. 339 // 340 // annot - handle to an annotation. 341 // rect - receives the rectangle; must not be NULL. 342 // 343 // Returns true if successful. 344 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_GetRect(FPDF_ANNOTATION annot, 345 FS_RECTF* rect); 346 347 // Experimental API. 348 // Check if |annot|'s dictionary has |key| as a key. 349 // 350 // annot - handle to an annotation. 351 // key - the key to look for, encoded in UTF-8. 352 // 353 // Returns true if |key| exists. 354 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_HasKey(FPDF_ANNOTATION annot, 355 FPDF_BYTESTRING key); 356 357 // Experimental API. 358 // Get the type of the value corresponding to |key| in |annot|'s dictionary. 359 // 360 // annot - handle to an annotation. 361 // key - the key to look for, encoded in UTF-8. 362 // 363 // Returns the type of the dictionary value. 364 FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV 365 FPDFAnnot_GetValueType(FPDF_ANNOTATION annot, FPDF_BYTESTRING key); 366 367 // Experimental API. 368 // Set the string value corresponding to |key| in |annot|'s dictionary, 369 // overwriting the existing value if any. The value type would be 370 // FPDF_OBJECT_STRING after this function call succeeds. 371 // 372 // annot - handle to an annotation. 373 // key - the key to the dictionary entry to be set, encoded in UTF-8. 374 // value - the string value to be set, encoded in UTF16-LE. 375 // 376 // Returns true if successful. 377 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 378 FPDFAnnot_SetStringValue(FPDF_ANNOTATION annot, 379 FPDF_BYTESTRING key, 380 FPDF_WIDESTRING value); 381 382 // Experimental API. 383 // Get the string value corresponding to |key| in |annot|'s dictionary. |buffer| 384 // is only modified if |buflen| is longer than the length of contents. Note that 385 // if |key| does not exist in the dictionary or if |key|'s corresponding value 386 // in the dictionary is not a string (i.e. the value is not of type 387 // FPDF_OBJECT_STRING or FPDF_OBJECT_NAME), then an empty string would be copied 388 // to |buffer| and the return value would be 2. On other errors, nothing would 389 // be added to |buffer| and the return value would be 0. 390 // 391 // annot - handle to an annotation. 392 // key - the key to the requested dictionary entry, encoded in UTF-8. 393 // buffer - buffer for holding the value string, encoded in UTF16-LE. 394 // buflen - length of the buffer. 395 // 396 // Returns the length of the string value. 397 FPDF_EXPORT unsigned long FPDF_CALLCONV 398 FPDFAnnot_GetStringValue(FPDF_ANNOTATION annot, 399 FPDF_BYTESTRING key, 400 void* buffer, 401 unsigned long buflen); 402 403 // Experimental API. 404 // Set the AP (appearance string) in |annot|'s dictionary for a given 405 // |appearanceMode|. 406 // 407 // annot - handle to an annotation. 408 // appearanceMode - the appearance mode (normal, rollover or down) for which 409 // to get the AP. 410 // value - the string value to be set, encoded in UTF16-LE. If 411 // nullptr is passed, the AP is cleared for that mode. If the 412 // mode is Normal, APs for all modes are cleared. 413 // 414 // Returns true if successful. 415 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 416 FPDFAnnot_SetAP(FPDF_ANNOTATION annot, 417 FPDF_ANNOT_APPEARANCEMODE appearanceMode, 418 FPDF_WIDESTRING value); 419 420 // Experimental API. 421 // Get the AP (appearance string) from |annot|'s dictionary for a given 422 // |appearanceMode|. 423 // |buffer| is only modified if |buflen| is large enough to hold the whole AP 424 // string. If |buflen| is smaller, the total size of the AP is still returned, 425 // but nothing is copied. 426 // If there is no appearance stream for |annot| in |appearanceMode|, an empty 427 // string is written to |buf| and 2 is returned. 428 // On other errors, nothing is written to |buffer| and 0 is returned. 429 // 430 // annot - handle to an annotation. 431 // appearanceMode - the appearance mode (normal, rollover or down) for which 432 // to get the AP. 433 // buffer - buffer for holding the value string, encoded in UTF16-LE. 434 // buflen - length of the buffer. 435 // 436 // Returns the length of the string value. 437 FPDF_EXPORT unsigned long FPDF_CALLCONV 438 FPDFAnnot_GetAP(FPDF_ANNOTATION annot, 439 FPDF_ANNOT_APPEARANCEMODE appearanceMode, 440 void* buffer, 441 unsigned long buflen); 442 443 // Experimental API. 444 // Get the annotation corresponding to |key| in |annot|'s dictionary. Common 445 // keys for linking annotations include "IRT" and "Popup". Must call 446 // FPDFPage_CloseAnnot() when the annotation returned by this function is no 447 // longer needed. 448 // 449 // annot - handle to an annotation. 450 // key - the key to the requested dictionary entry, encoded in UTF-8. 451 // 452 // Returns a handle to the linked annotation object, or NULL on failure. 453 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 454 FPDFAnnot_GetLinkedAnnot(FPDF_ANNOTATION annot, FPDF_BYTESTRING key); 455 456 // Experimental API. 457 // Get the annotation flags of |annot|. 458 // 459 // annot - handle to an annotation. 460 // 461 // Returns the annotation flags. 462 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_GetFlags(FPDF_ANNOTATION annot); 463 464 // Experimental API. 465 // Set the |annot|'s flags to be of the value |flags|. 466 // 467 // annot - handle to an annotation. 468 // flags - the flag values to be set. 469 // 470 // Returns true if successful. 471 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetFlags(FPDF_ANNOTATION annot, 472 int flags); 473 474 // Experimental API. 475 // Get the annotation flags of |annot|, which is an interactive form 476 // annotation in |page|. 477 // 478 // page - handle to a page. 479 // annot - handle to an interactive form annotation. 480 // 481 // Returns the annotation flags specific to interactive forms. 482 FPDF_EXPORT int FPDF_CALLCONV 483 FPDFAnnot_GetFormFieldFlags(FPDF_PAGE page, FPDF_ANNOTATION annot); 484 485 // Experimental API. 486 // Retrieves an interactive form annotation whose rectangle contains a given 487 // point on a page. Must call FPDFPage_CloseAnnot() when the annotation returned 488 // is no longer needed. 489 // 490 // 491 // hHandle - handle to the form fill module, returned by 492 // FPDFDOC_InitFormFillEnvironment. 493 // page - handle to the page, returned by FPDF_LoadPage function. 494 // page_x - X position in PDF "user space". 495 // page_y - Y position in PDF "user space". 496 // 497 // Returns the interactive form annotation whose rectangle contains the given 498 // coordinates on the page. If there is no such annotation, return NULL. 499 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 500 FPDFAnnot_GetFormFieldAtPoint(FPDF_FORMHANDLE hHandle, 501 FPDF_PAGE page, 502 double page_x, 503 double page_y); 504 505 #ifdef __cplusplus 506 } // extern "C" 507 #endif // __cplusplus 508 509 #endif // PUBLIC_FPDF_ANNOT_H_ 510