1 // Copyright 2017 The PDFium Authors 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 #include <stddef.h> 9 10 // NOLINTNEXTLINE(build/include) 11 #include "fpdfview.h" 12 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 #define FPDF_ANNOT_REDACT 28 49 50 // Refer to PDF Reference (6th edition) table 8.16 for all annotation flags. 51 #define FPDF_ANNOT_FLAG_NONE 0 52 #define FPDF_ANNOT_FLAG_INVISIBLE (1 << 0) 53 #define FPDF_ANNOT_FLAG_HIDDEN (1 << 1) 54 #define FPDF_ANNOT_FLAG_PRINT (1 << 2) 55 #define FPDF_ANNOT_FLAG_NOZOOM (1 << 3) 56 #define FPDF_ANNOT_FLAG_NOROTATE (1 << 4) 57 #define FPDF_ANNOT_FLAG_NOVIEW (1 << 5) 58 #define FPDF_ANNOT_FLAG_READONLY (1 << 6) 59 #define FPDF_ANNOT_FLAG_LOCKED (1 << 7) 60 #define FPDF_ANNOT_FLAG_TOGGLENOVIEW (1 << 8) 61 62 #define FPDF_ANNOT_APPEARANCEMODE_NORMAL 0 63 #define FPDF_ANNOT_APPEARANCEMODE_ROLLOVER 1 64 #define FPDF_ANNOT_APPEARANCEMODE_DOWN 2 65 #define FPDF_ANNOT_APPEARANCEMODE_COUNT 3 66 67 // Refer to PDF Reference version 1.7 table 8.70 for field flags common to all 68 // interactive form field types. 69 #define FPDF_FORMFLAG_NONE 0 70 #define FPDF_FORMFLAG_READONLY (1 << 0) 71 #define FPDF_FORMFLAG_REQUIRED (1 << 1) 72 #define FPDF_FORMFLAG_NOEXPORT (1 << 2) 73 74 // Refer to PDF Reference version 1.7 table 8.77 for field flags specific to 75 // interactive form text fields. 76 #define FPDF_FORMFLAG_TEXT_MULTILINE (1 << 12) 77 #define FPDF_FORMFLAG_TEXT_PASSWORD (1 << 13) 78 79 // Refer to PDF Reference version 1.7 table 8.79 for field flags specific to 80 // interactive form choice fields. 81 #define FPDF_FORMFLAG_CHOICE_COMBO (1 << 17) 82 #define FPDF_FORMFLAG_CHOICE_EDIT (1 << 18) 83 #define FPDF_FORMFLAG_CHOICE_MULTI_SELECT (1 << 21) 84 85 // Additional actions type of form field: 86 // K, on key stroke, JavaScript action. 87 // F, on format, JavaScript action. 88 // V, on validate, JavaScript action. 89 // C, on calculate, JavaScript action. 90 #define FPDF_ANNOT_AACTION_KEY_STROKE 12 91 #define FPDF_ANNOT_AACTION_FORMAT 13 92 #define FPDF_ANNOT_AACTION_VALIDATE 14 93 #define FPDF_ANNOT_AACTION_CALCULATE 15 94 95 typedef enum FPDFANNOT_COLORTYPE { 96 FPDFANNOT_COLORTYPE_Color = 0, 97 FPDFANNOT_COLORTYPE_InteriorColor 98 } FPDFANNOT_COLORTYPE; 99 100 // Experimental API. 101 // Check if an annotation subtype is currently supported for creation. 102 // Currently supported subtypes: 103 // - circle 104 // - fileattachment 105 // - freetext 106 // - highlight 107 // - ink 108 // - link 109 // - popup 110 // - square, 111 // - squiggly 112 // - stamp 113 // - strikeout 114 // - text 115 // - underline 116 // 117 // subtype - the subtype to be checked. 118 // 119 // Returns true if this subtype supported. 120 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 121 FPDFAnnot_IsSupportedSubtype(FPDF_ANNOTATION_SUBTYPE subtype); 122 123 // Experimental API. 124 // Create an annotation in |page| of the subtype |subtype|. If the specified 125 // subtype is illegal or unsupported, then a new annotation will not be created. 126 // Must call FPDFPage_CloseAnnot() when the annotation returned by this 127 // function is no longer needed. 128 // 129 // page - handle to a page. 130 // subtype - the subtype of the new annotation. 131 // 132 // Returns a handle to the new annotation object, or NULL on failure. 133 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 134 FPDFPage_CreateAnnot(FPDF_PAGE page, FPDF_ANNOTATION_SUBTYPE subtype); 135 136 // Experimental API. 137 // Get the number of annotations in |page|. 138 // 139 // page - handle to a page. 140 // 141 // Returns the number of annotations in |page|. 142 FPDF_EXPORT int FPDF_CALLCONV FPDFPage_GetAnnotCount(FPDF_PAGE page); 143 144 // Experimental API. 145 // Get annotation in |page| at |index|. Must call FPDFPage_CloseAnnot() when the 146 // annotation returned by this function is no longer needed. 147 // 148 // page - handle to a page. 149 // index - the index of the annotation. 150 // 151 // Returns a handle to the annotation object, or NULL on failure. 152 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV FPDFPage_GetAnnot(FPDF_PAGE page, 153 int index); 154 155 // Experimental API. 156 // Get the index of |annot| in |page|. This is the opposite of 157 // FPDFPage_GetAnnot(). 158 // 159 // page - handle to the page that the annotation is on. 160 // annot - handle to an annotation. 161 // 162 // Returns the index of |annot|, or -1 on failure. 163 FPDF_EXPORT int FPDF_CALLCONV FPDFPage_GetAnnotIndex(FPDF_PAGE page, 164 FPDF_ANNOTATION annot); 165 166 // Experimental API. 167 // Close an annotation. Must be called when the annotation returned by 168 // FPDFPage_CreateAnnot() or FPDFPage_GetAnnot() is no longer needed. This 169 // function does not remove the annotation from the document. 170 // 171 // annot - handle to an annotation. 172 FPDF_EXPORT void FPDF_CALLCONV FPDFPage_CloseAnnot(FPDF_ANNOTATION annot); 173 174 // Experimental API. 175 // Remove the annotation in |page| at |index|. 176 // 177 // page - handle to a page. 178 // index - the index of the annotation. 179 // 180 // Returns true if successful. 181 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFPage_RemoveAnnot(FPDF_PAGE page, 182 int index); 183 184 // Experimental API. 185 // Get the subtype of an annotation. 186 // 187 // annot - handle to an annotation. 188 // 189 // Returns the annotation subtype. 190 FPDF_EXPORT FPDF_ANNOTATION_SUBTYPE FPDF_CALLCONV 191 FPDFAnnot_GetSubtype(FPDF_ANNOTATION annot); 192 193 // Experimental API. 194 // Check if an annotation subtype is currently supported for object extraction, 195 // update, and removal. 196 // Currently supported subtypes: ink and stamp. 197 // 198 // subtype - the subtype to be checked. 199 // 200 // Returns true if this subtype supported. 201 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 202 FPDFAnnot_IsObjectSupportedSubtype(FPDF_ANNOTATION_SUBTYPE subtype); 203 204 // Experimental API. 205 // Update |obj| in |annot|. |obj| must be in |annot| already and must have 206 // been retrieved by FPDFAnnot_GetObject(). Currently, only ink and stamp 207 // annotations are supported by this API. Also note that only path, image, and 208 // text objects have APIs for modification; see FPDFPath_*(), FPDFText_*(), and 209 // FPDFImageObj_*(). 210 // 211 // annot - handle to an annotation. 212 // obj - handle to the object that |annot| needs to update. 213 // 214 // Return true if successful. 215 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 216 FPDFAnnot_UpdateObject(FPDF_ANNOTATION annot, FPDF_PAGEOBJECT obj); 217 218 // Experimental API. 219 // Add a new InkStroke, represented by an array of points, to the InkList of 220 // |annot|. The API creates an InkList if one doesn't already exist in |annot|. 221 // This API works only for ink annotations. Please refer to ISO 32000-1:2008 222 // spec, section 12.5.6.13. 223 // 224 // annot - handle to an annotation. 225 // points - pointer to a FS_POINTF array representing input points. 226 // point_count - number of elements in |points| array. This should not exceed 227 // the maximum value that can be represented by an int32_t). 228 // 229 // Returns the 0-based index at which the new InkStroke is added in the InkList 230 // of the |annot|. Returns -1 on failure. 231 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_AddInkStroke(FPDF_ANNOTATION annot, 232 const FS_POINTF* points, 233 size_t point_count); 234 235 // Experimental API. 236 // Removes an InkList in |annot|. 237 // This API works only for ink annotations. 238 // 239 // annot - handle to an annotation. 240 // 241 // Return true on successful removal of /InkList entry from context of the 242 // non-null ink |annot|. Returns false on failure. 243 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 244 FPDFAnnot_RemoveInkList(FPDF_ANNOTATION annot); 245 246 // Experimental API. 247 // Add |obj| to |annot|. |obj| must have been created by 248 // FPDFPageObj_CreateNew{Path|Rect}() or FPDFPageObj_New{Text|Image}Obj(), and 249 // will be owned by |annot|. Note that an |obj| cannot belong to more than one 250 // |annot|. Currently, only ink and stamp annotations are supported by this API. 251 // Also note that only path, image, and text objects have APIs for creation. 252 // 253 // annot - handle to an annotation. 254 // obj - handle to the object that is to be added to |annot|. 255 // 256 // Return true if successful. 257 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 258 FPDFAnnot_AppendObject(FPDF_ANNOTATION annot, FPDF_PAGEOBJECT obj); 259 260 // Experimental API. 261 // Get the total number of objects in |annot|, including path objects, text 262 // objects, external objects, image objects, and shading objects. 263 // 264 // annot - handle to an annotation. 265 // 266 // Returns the number of objects in |annot|. 267 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_GetObjectCount(FPDF_ANNOTATION annot); 268 269 // Experimental API. 270 // Get the object in |annot| at |index|. 271 // 272 // annot - handle to an annotation. 273 // index - the index of the object. 274 // 275 // Return a handle to the object, or NULL on failure. 276 FPDF_EXPORT FPDF_PAGEOBJECT FPDF_CALLCONV 277 FPDFAnnot_GetObject(FPDF_ANNOTATION annot, int index); 278 279 // Experimental API. 280 // Remove the object in |annot| at |index|. 281 // 282 // annot - handle to an annotation. 283 // index - the index of the object to be removed. 284 // 285 // Return true if successful. 286 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 287 FPDFAnnot_RemoveObject(FPDF_ANNOTATION annot, int index); 288 289 // Experimental API. 290 // Set the color of an annotation. Fails when called on annotations with 291 // appearance streams already defined; instead use 292 // FPDFPath_Set{Stroke|Fill}Color(). 293 // 294 // annot - handle to an annotation. 295 // type - type of the color to be set. 296 // R, G, B - buffer to hold the RGB value of the color. Ranges from 0 to 255. 297 // A - buffer to hold the opacity. Ranges from 0 to 255. 298 // 299 // Returns true if successful. 300 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetColor(FPDF_ANNOTATION annot, 301 FPDFANNOT_COLORTYPE type, 302 unsigned int R, 303 unsigned int G, 304 unsigned int B, 305 unsigned int A); 306 307 // Experimental API. 308 // Get the color of an annotation. If no color is specified, default to yellow 309 // for highlight annotation, black for all else. Fails when called on 310 // annotations with appearance streams already defined; instead use 311 // FPDFPath_Get{Stroke|Fill}Color(). 312 // 313 // annot - handle to an annotation. 314 // type - type of the color requested. 315 // R, G, B - buffer to hold the RGB value of the color. Ranges from 0 to 255. 316 // A - buffer to hold the opacity. Ranges from 0 to 255. 317 // 318 // Returns true if successful. 319 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_GetColor(FPDF_ANNOTATION annot, 320 FPDFANNOT_COLORTYPE type, 321 unsigned int* R, 322 unsigned int* G, 323 unsigned int* B, 324 unsigned int* A); 325 326 // Experimental API. 327 // Check if the annotation is of a type that has attachment points 328 // (i.e. quadpoints). Quadpoints are the vertices of the rectangle that 329 // encompasses the texts affected by the annotation. They provide the 330 // coordinates in the page where the annotation is attached. Only text markup 331 // annotations (i.e. highlight, strikeout, squiggly, and underline) and link 332 // annotations have quadpoints. 333 // 334 // annot - handle to an annotation. 335 // 336 // Returns true if the annotation is of a type that has quadpoints, false 337 // otherwise. 338 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 339 FPDFAnnot_HasAttachmentPoints(FPDF_ANNOTATION annot); 340 341 // Experimental API. 342 // Replace the attachment points (i.e. quadpoints) set of an annotation at 343 // |quad_index|. This index needs to be within the result of 344 // FPDFAnnot_CountAttachmentPoints(). 345 // If the annotation's appearance stream is defined and this annotation is of a 346 // type with quadpoints, then update the bounding box too if the new quadpoints 347 // define a bigger one. 348 // 349 // annot - handle to an annotation. 350 // quad_index - index of the set of quadpoints. 351 // quad_points - the quadpoints to be set. 352 // 353 // Returns true if successful. 354 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 355 FPDFAnnot_SetAttachmentPoints(FPDF_ANNOTATION annot, 356 size_t quad_index, 357 const FS_QUADPOINTSF* quad_points); 358 359 // Experimental API. 360 // Append to the list of attachment points (i.e. quadpoints) of an annotation. 361 // If the annotation's appearance stream is defined and this annotation is of a 362 // type with quadpoints, then update the bounding box too if the new quadpoints 363 // define a bigger one. 364 // 365 // annot - handle to an annotation. 366 // quad_points - the quadpoints to be set. 367 // 368 // Returns true if successful. 369 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 370 FPDFAnnot_AppendAttachmentPoints(FPDF_ANNOTATION annot, 371 const FS_QUADPOINTSF* quad_points); 372 373 // Experimental API. 374 // Get the number of sets of quadpoints of an annotation. 375 // 376 // annot - handle to an annotation. 377 // 378 // Returns the number of sets of quadpoints, or 0 on failure. 379 FPDF_EXPORT size_t FPDF_CALLCONV 380 FPDFAnnot_CountAttachmentPoints(FPDF_ANNOTATION annot); 381 382 // Experimental API. 383 // Get the attachment points (i.e. quadpoints) of an annotation. 384 // 385 // annot - handle to an annotation. 386 // quad_index - index of the set of quadpoints. 387 // quad_points - receives the quadpoints; must not be NULL. 388 // 389 // Returns true if successful. 390 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 391 FPDFAnnot_GetAttachmentPoints(FPDF_ANNOTATION annot, 392 size_t quad_index, 393 FS_QUADPOINTSF* quad_points); 394 395 // Experimental API. 396 // Set the annotation rectangle defining the location of the annotation. If the 397 // annotation's appearance stream is defined and this annotation is of a type 398 // without quadpoints, then update the bounding box too if the new rectangle 399 // defines a bigger one. 400 // 401 // annot - handle to an annotation. 402 // rect - the annotation rectangle to be set. 403 // 404 // Returns true if successful. 405 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetRect(FPDF_ANNOTATION annot, 406 const FS_RECTF* rect); 407 408 // Experimental API. 409 // Get the annotation rectangle defining the location of the annotation. 410 // 411 // annot - handle to an annotation. 412 // rect - receives the rectangle; must not be NULL. 413 // 414 // Returns true if successful. 415 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_GetRect(FPDF_ANNOTATION annot, 416 FS_RECTF* rect); 417 418 // Experimental API. 419 // Get the vertices of a polygon or polyline annotation. |buffer| is an array of 420 // points of the annotation. If |length| is less than the returned length, or 421 // |annot| or |buffer| is NULL, |buffer| will not be modified. 422 // 423 // annot - handle to an annotation, as returned by e.g. FPDFPage_GetAnnot() 424 // buffer - buffer for holding the points. 425 // length - length of the buffer in points. 426 // 427 // Returns the number of points if the annotation is of type polygon or 428 // polyline, 0 otherwise. 429 FPDF_EXPORT unsigned long FPDF_CALLCONV 430 FPDFAnnot_GetVertices(FPDF_ANNOTATION annot, 431 FS_POINTF* buffer, 432 unsigned long length); 433 434 // Experimental API. 435 // Get the number of paths in the ink list of an ink annotation. 436 // 437 // annot - handle to an annotation, as returned by e.g. FPDFPage_GetAnnot() 438 // 439 // Returns the number of paths in the ink list if the annotation is of type ink, 440 // 0 otherwise. 441 FPDF_EXPORT unsigned long FPDF_CALLCONV 442 FPDFAnnot_GetInkListCount(FPDF_ANNOTATION annot); 443 444 // Experimental API. 445 // Get a path in the ink list of an ink annotation. |buffer| is an array of 446 // points of the path. If |length| is less than the returned length, or |annot| 447 // or |buffer| is NULL, |buffer| will not be modified. 448 // 449 // annot - handle to an annotation, as returned by e.g. FPDFPage_GetAnnot() 450 // path_index - index of the path 451 // buffer - buffer for holding the points. 452 // length - length of the buffer in points. 453 // 454 // Returns the number of points of the path if the annotation is of type ink, 0 455 // otherwise. 456 FPDF_EXPORT unsigned long FPDF_CALLCONV 457 FPDFAnnot_GetInkListPath(FPDF_ANNOTATION annot, 458 unsigned long path_index, 459 FS_POINTF* buffer, 460 unsigned long length); 461 462 // Experimental API. 463 // Get the starting and ending coordinates of a line annotation. 464 // 465 // annot - handle to an annotation, as returned by e.g. FPDFPage_GetAnnot() 466 // start - starting point 467 // end - ending point 468 // 469 // Returns true if the annotation is of type line, |start| and |end| are not 470 // NULL, false otherwise. 471 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_GetLine(FPDF_ANNOTATION annot, 472 FS_POINTF* start, 473 FS_POINTF* end); 474 475 // Experimental API. 476 // Set the characteristics of the annotation's border (rounded rectangle). 477 // 478 // annot - handle to an annotation 479 // horizontal_radius - horizontal corner radius, in default user space units 480 // vertical_radius - vertical corner radius, in default user space units 481 // border_width - border width, in default user space units 482 // 483 // Returns true if setting the border for |annot| succeeds, false otherwise. 484 // 485 // If |annot| contains an appearance stream that overrides the border values, 486 // then the appearance stream will be removed on success. 487 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetBorder(FPDF_ANNOTATION annot, 488 float horizontal_radius, 489 float vertical_radius, 490 float border_width); 491 492 // Experimental API. 493 // Get the characteristics of the annotation's border (rounded rectangle). 494 // 495 // annot - handle to an annotation 496 // horizontal_radius - horizontal corner radius, in default user space units 497 // vertical_radius - vertical corner radius, in default user space units 498 // border_width - border width, in default user space units 499 // 500 // Returns true if |horizontal_radius|, |vertical_radius| and |border_width| are 501 // not NULL, false otherwise. 502 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 503 FPDFAnnot_GetBorder(FPDF_ANNOTATION annot, 504 float* horizontal_radius, 505 float* vertical_radius, 506 float* border_width); 507 508 // Experimental API. 509 // Get the JavaScript of an event of the annotation's additional actions. 510 // |buffer| is only modified if |buflen| is large enough to hold the whole 511 // JavaScript string. If |buflen| is smaller, the total size of the JavaScript 512 // is still returned, but nothing is copied. If there is no JavaScript for 513 // |event| in |annot|, an empty string is written to |buf| and 2 is returned, 514 // denoting the size of the null terminator in the buffer. On other errors, 515 // nothing is written to |buffer| and 0 is returned. 516 // 517 // hHandle - handle to the form fill module, returned by 518 // FPDFDOC_InitFormFillEnvironment(). 519 // annot - handle to an interactive form annotation. 520 // event - event type, one of the FPDF_ANNOT_AACTION_* values. 521 // buffer - buffer for holding the value string, encoded in UTF-16LE. 522 // buflen - length of the buffer in bytes. 523 // 524 // Returns the length of the string value in bytes, including the 2-byte 525 // null terminator. 526 FPDF_EXPORT unsigned long FPDF_CALLCONV 527 FPDFAnnot_GetFormAdditionalActionJavaScript(FPDF_FORMHANDLE hHandle, 528 FPDF_ANNOTATION annot, 529 int event, 530 FPDF_WCHAR* buffer, 531 unsigned long buflen); 532 533 // Experimental API. 534 // Check if |annot|'s dictionary has |key| as a key. 535 // 536 // annot - handle to an annotation. 537 // key - the key to look for, encoded in UTF-8. 538 // 539 // Returns true if |key| exists. 540 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_HasKey(FPDF_ANNOTATION annot, 541 FPDF_BYTESTRING key); 542 543 // Experimental API. 544 // Get the type of the value corresponding to |key| in |annot|'s dictionary. 545 // 546 // annot - handle to an annotation. 547 // key - the key to look for, encoded in UTF-8. 548 // 549 // Returns the type of the dictionary value. 550 FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV 551 FPDFAnnot_GetValueType(FPDF_ANNOTATION annot, FPDF_BYTESTRING key); 552 553 // Experimental API. 554 // Set the string value corresponding to |key| in |annot|'s dictionary, 555 // overwriting the existing value if any. The value type would be 556 // FPDF_OBJECT_STRING after this function call succeeds. 557 // 558 // annot - handle to an annotation. 559 // key - the key to the dictionary entry to be set, encoded in UTF-8. 560 // value - the string value to be set, encoded in UTF-16LE. 561 // 562 // Returns true if successful. 563 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 564 FPDFAnnot_SetStringValue(FPDF_ANNOTATION annot, 565 FPDF_BYTESTRING key, 566 FPDF_WIDESTRING value); 567 568 // Experimental API. 569 // Get the string value corresponding to |key| in |annot|'s dictionary. |buffer| 570 // is only modified if |buflen| is longer than the length of contents. Note that 571 // if |key| does not exist in the dictionary or if |key|'s corresponding value 572 // in the dictionary is not a string (i.e. the value is not of type 573 // FPDF_OBJECT_STRING or FPDF_OBJECT_NAME), then an empty string would be copied 574 // to |buffer| and the return value would be 2. On other errors, nothing would 575 // be added to |buffer| and the return value would be 0. 576 // 577 // annot - handle to an annotation. 578 // key - the key to the requested dictionary entry, encoded in UTF-8. 579 // buffer - buffer for holding the value string, encoded in UTF-16LE. 580 // buflen - length of the buffer in bytes. 581 // 582 // Returns the length of the string value in bytes. 583 FPDF_EXPORT unsigned long FPDF_CALLCONV 584 FPDFAnnot_GetStringValue(FPDF_ANNOTATION annot, 585 FPDF_BYTESTRING key, 586 FPDF_WCHAR* buffer, 587 unsigned long buflen); 588 589 // Experimental API. 590 // Get the float value corresponding to |key| in |annot|'s dictionary. Writes 591 // value to |value| and returns True if |key| exists in the dictionary and 592 // |key|'s corresponding value is a number (FPDF_OBJECT_NUMBER), False 593 // otherwise. 594 // 595 // annot - handle to an annotation. 596 // key - the key to the requested dictionary entry, encoded in UTF-8. 597 // value - receives the value, must not be NULL. 598 // 599 // Returns True if value found, False otherwise. 600 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 601 FPDFAnnot_GetNumberValue(FPDF_ANNOTATION annot, 602 FPDF_BYTESTRING key, 603 float* value); 604 605 // Experimental API. 606 // Set the AP (appearance string) in |annot|'s dictionary for a given 607 // |appearanceMode|. 608 // 609 // annot - handle to an annotation. 610 // appearanceMode - the appearance mode (normal, rollover or down) for which 611 // to get the AP. 612 // value - the string value to be set, encoded in UTF-16LE. If 613 // nullptr is passed, the AP is cleared for that mode. If the 614 // mode is Normal, APs for all modes are cleared. 615 // 616 // Returns true if successful. 617 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 618 FPDFAnnot_SetAP(FPDF_ANNOTATION annot, 619 FPDF_ANNOT_APPEARANCEMODE appearanceMode, 620 FPDF_WIDESTRING value); 621 622 // Experimental API. 623 // Get the AP (appearance string) from |annot|'s dictionary for a given 624 // |appearanceMode|. 625 // |buffer| is only modified if |buflen| is large enough to hold the whole AP 626 // string. If |buflen| is smaller, the total size of the AP is still returned, 627 // but nothing is copied. 628 // If there is no appearance stream for |annot| in |appearanceMode|, an empty 629 // string is written to |buf| and 2 is returned. 630 // On other errors, nothing is written to |buffer| and 0 is returned. 631 // 632 // annot - handle to an annotation. 633 // appearanceMode - the appearance mode (normal, rollover or down) for which 634 // to get the AP. 635 // buffer - buffer for holding the value string, encoded in UTF-16LE. 636 // buflen - length of the buffer in bytes. 637 // 638 // Returns the length of the string value in bytes. 639 FPDF_EXPORT unsigned long FPDF_CALLCONV 640 FPDFAnnot_GetAP(FPDF_ANNOTATION annot, 641 FPDF_ANNOT_APPEARANCEMODE appearanceMode, 642 FPDF_WCHAR* buffer, 643 unsigned long buflen); 644 645 // Experimental API. 646 // Get the annotation corresponding to |key| in |annot|'s dictionary. Common 647 // keys for linking annotations include "IRT" and "Popup". Must call 648 // FPDFPage_CloseAnnot() when the annotation returned by this function is no 649 // longer needed. 650 // 651 // annot - handle to an annotation. 652 // key - the key to the requested dictionary entry, encoded in UTF-8. 653 // 654 // Returns a handle to the linked annotation object, or NULL on failure. 655 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 656 FPDFAnnot_GetLinkedAnnot(FPDF_ANNOTATION annot, FPDF_BYTESTRING key); 657 658 // Experimental API. 659 // Get the annotation flags of |annot|. 660 // 661 // annot - handle to an annotation. 662 // 663 // Returns the annotation flags. 664 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_GetFlags(FPDF_ANNOTATION annot); 665 666 // Experimental API. 667 // Set the |annot|'s flags to be of the value |flags|. 668 // 669 // annot - handle to an annotation. 670 // flags - the flag values to be set. 671 // 672 // Returns true if successful. 673 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetFlags(FPDF_ANNOTATION annot, 674 int flags); 675 676 // Experimental API. 677 // Get the annotation flags of |annot|. 678 // 679 // hHandle - handle to the form fill module, returned by 680 // FPDFDOC_InitFormFillEnvironment(). 681 // annot - handle to an interactive form annotation. 682 // 683 // Returns the annotation flags specific to interactive forms. 684 FPDF_EXPORT int FPDF_CALLCONV 685 FPDFAnnot_GetFormFieldFlags(FPDF_FORMHANDLE handle, 686 FPDF_ANNOTATION annot); 687 688 // Experimental API. 689 // Retrieves an interactive form annotation whose rectangle contains a given 690 // point on a page. Must call FPDFPage_CloseAnnot() when the annotation returned 691 // is no longer needed. 692 // 693 // 694 // hHandle - handle to the form fill module, returned by 695 // FPDFDOC_InitFormFillEnvironment(). 696 // page - handle to the page, returned by FPDF_LoadPage function. 697 // point - position in PDF "user space". 698 // 699 // Returns the interactive form annotation whose rectangle contains the given 700 // coordinates on the page. If there is no such annotation, return NULL. 701 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 702 FPDFAnnot_GetFormFieldAtPoint(FPDF_FORMHANDLE hHandle, 703 FPDF_PAGE page, 704 const FS_POINTF* point); 705 706 // Experimental API. 707 // Gets the name of |annot|, which is an interactive form annotation. 708 // |buffer| is only modified if |buflen| is longer than the length of contents. 709 // In case of error, nothing will be added to |buffer| and the return value will 710 // be 0. Note that return value of empty string is 2 for "\0\0". 711 // 712 // hHandle - handle to the form fill module, returned by 713 // FPDFDOC_InitFormFillEnvironment(). 714 // annot - handle to an interactive form annotation. 715 // buffer - buffer for holding the name string, encoded in UTF-16LE. 716 // buflen - length of the buffer in bytes. 717 // 718 // Returns the length of the string value in bytes. 719 FPDF_EXPORT unsigned long FPDF_CALLCONV 720 FPDFAnnot_GetFormFieldName(FPDF_FORMHANDLE hHandle, 721 FPDF_ANNOTATION annot, 722 FPDF_WCHAR* buffer, 723 unsigned long buflen); 724 725 // Experimental API. 726 // Gets the alternate name of |annot|, which is an interactive form annotation. 727 // |buffer| is only modified if |buflen| is longer than the length of contents. 728 // In case of error, nothing will be added to |buffer| and the return value will 729 // be 0. Note that return value of empty string is 2 for "\0\0". 730 // 731 // hHandle - handle to the form fill module, returned by 732 // FPDFDOC_InitFormFillEnvironment(). 733 // annot - handle to an interactive form annotation. 734 // buffer - buffer for holding the alternate name string, encoded in 735 // UTF-16LE. 736 // buflen - length of the buffer in bytes. 737 // 738 // Returns the length of the string value in bytes. 739 FPDF_EXPORT unsigned long FPDF_CALLCONV 740 FPDFAnnot_GetFormFieldAlternateName(FPDF_FORMHANDLE hHandle, 741 FPDF_ANNOTATION annot, 742 FPDF_WCHAR* buffer, 743 unsigned long buflen); 744 745 // Experimental API. 746 // Gets the form field type of |annot|, which is an interactive form annotation. 747 // 748 // hHandle - handle to the form fill module, returned by 749 // FPDFDOC_InitFormFillEnvironment(). 750 // annot - handle to an interactive form annotation. 751 // 752 // Returns the type of the form field (one of the FPDF_FORMFIELD_* values) on 753 // success. Returns -1 on error. 754 // See field types in fpdf_formfill.h. 755 FPDF_EXPORT int FPDF_CALLCONV 756 FPDFAnnot_GetFormFieldType(FPDF_FORMHANDLE hHandle, FPDF_ANNOTATION annot); 757 758 // Experimental API. 759 // Gets the value of |annot|, which is an interactive form annotation. 760 // |buffer| is only modified if |buflen| is longer than the length of contents. 761 // In case of error, nothing will be added to |buffer| and the return value will 762 // be 0. Note that return value of empty string is 2 for "\0\0". 763 // 764 // hHandle - handle to the form fill module, returned by 765 // FPDFDOC_InitFormFillEnvironment(). 766 // annot - handle to an interactive form annotation. 767 // buffer - buffer for holding the value string, encoded in UTF-16LE. 768 // buflen - length of the buffer in bytes. 769 // 770 // Returns the length of the string value in bytes. 771 FPDF_EXPORT unsigned long FPDF_CALLCONV 772 FPDFAnnot_GetFormFieldValue(FPDF_FORMHANDLE hHandle, 773 FPDF_ANNOTATION annot, 774 FPDF_WCHAR* buffer, 775 unsigned long buflen); 776 777 // Experimental API. 778 // Get the number of options in the |annot|'s "Opt" dictionary. Intended for 779 // use with listbox and combobox widget annotations. 780 // 781 // hHandle - handle to the form fill module, returned by 782 // FPDFDOC_InitFormFillEnvironment. 783 // annot - handle to an annotation. 784 // 785 // Returns the number of options in "Opt" dictionary on success. Return value 786 // will be -1 if annotation does not have an "Opt" dictionary or other error. 787 FPDF_EXPORT int FPDF_CALLCONV FPDFAnnot_GetOptionCount(FPDF_FORMHANDLE hHandle, 788 FPDF_ANNOTATION annot); 789 790 // Experimental API. 791 // Get the string value for the label of the option at |index| in |annot|'s 792 // "Opt" dictionary. Intended for use with listbox and combobox widget 793 // annotations. |buffer| is only modified if |buflen| is longer than the length 794 // of contents. If index is out of range or in case of other error, nothing 795 // will be added to |buffer| and the return value will be 0. Note that 796 // return value of empty string is 2 for "\0\0". 797 // 798 // hHandle - handle to the form fill module, returned by 799 // FPDFDOC_InitFormFillEnvironment. 800 // annot - handle to an annotation. 801 // index - numeric index of the option in the "Opt" array 802 // buffer - buffer for holding the value string, encoded in UTF-16LE. 803 // buflen - length of the buffer in bytes. 804 // 805 // Returns the length of the string value in bytes. 806 // If |annot| does not have an "Opt" array, |index| is out of range or if any 807 // other error occurs, returns 0. 808 FPDF_EXPORT unsigned long FPDF_CALLCONV 809 FPDFAnnot_GetOptionLabel(FPDF_FORMHANDLE hHandle, 810 FPDF_ANNOTATION annot, 811 int index, 812 FPDF_WCHAR* buffer, 813 unsigned long buflen); 814 815 // Experimental API. 816 // Determine whether or not the option at |index| in |annot|'s "Opt" dictionary 817 // is selected. Intended for use with listbox and combobox widget annotations. 818 // 819 // handle - handle to the form fill module, returned by 820 // FPDFDOC_InitFormFillEnvironment. 821 // annot - handle to an annotation. 822 // index - numeric index of the option in the "Opt" array. 823 // 824 // Returns true if the option at |index| in |annot|'s "Opt" dictionary is 825 // selected, false otherwise. 826 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 827 FPDFAnnot_IsOptionSelected(FPDF_FORMHANDLE handle, 828 FPDF_ANNOTATION annot, 829 int index); 830 831 // Experimental API. 832 // Get the float value of the font size for an |annot| with variable text. 833 // If 0, the font is to be auto-sized: its size is computed as a function of 834 // the height of the annotation rectangle. 835 // 836 // hHandle - handle to the form fill module, returned by 837 // FPDFDOC_InitFormFillEnvironment. 838 // annot - handle to an annotation. 839 // value - Required. Float which will be set to font size on success. 840 // 841 // Returns true if the font size was set in |value|, false on error or if 842 // |value| not provided. 843 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 844 FPDFAnnot_GetFontSize(FPDF_FORMHANDLE hHandle, 845 FPDF_ANNOTATION annot, 846 float* value); 847 848 // Experimental API. 849 // Get the RGB value of the font color for an |annot| with variable text. 850 // 851 // hHandle - handle to the form fill module, returned by 852 // FPDFDOC_InitFormFillEnvironment. 853 // annot - handle to an annotation. 854 // R, G, B - buffer to hold the RGB value of the color. Ranges from 0 to 255. 855 // 856 // Returns true if the font color was set, false on error or if the font 857 // color was not provided. 858 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 859 FPDFAnnot_GetFontColor(FPDF_FORMHANDLE hHandle, 860 FPDF_ANNOTATION annot, 861 unsigned int* R, 862 unsigned int* G, 863 unsigned int* B); 864 865 // Experimental API. 866 // Determine if |annot| is a form widget that is checked. Intended for use with 867 // checkbox and radio button widgets. 868 // 869 // hHandle - handle to the form fill module, returned by 870 // FPDFDOC_InitFormFillEnvironment. 871 // annot - handle to an annotation. 872 // 873 // Returns true if |annot| is a form widget and is checked, false otherwise. 874 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_IsChecked(FPDF_FORMHANDLE hHandle, 875 FPDF_ANNOTATION annot); 876 877 // Experimental API. 878 // Set the list of focusable annotation subtypes. Annotations of subtype 879 // FPDF_ANNOT_WIDGET are by default focusable. New subtypes set using this API 880 // will override the existing subtypes. 881 // 882 // hHandle - handle to the form fill module, returned by 883 // FPDFDOC_InitFormFillEnvironment. 884 // subtypes - list of annotation subtype which can be tabbed over. 885 // count - total number of annotation subtype in list. 886 // Returns true if list of annotation subtype is set successfully, false 887 // otherwise. 888 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 889 FPDFAnnot_SetFocusableSubtypes(FPDF_FORMHANDLE hHandle, 890 const FPDF_ANNOTATION_SUBTYPE* subtypes, 891 size_t count); 892 893 // Experimental API. 894 // Get the count of focusable annotation subtypes as set by host 895 // for a |hHandle|. 896 // 897 // hHandle - handle to the form fill module, returned by 898 // FPDFDOC_InitFormFillEnvironment. 899 // Returns the count of focusable annotation subtypes or -1 on error. 900 // Note : Annotations of type FPDF_ANNOT_WIDGET are by default focusable. 901 FPDF_EXPORT int FPDF_CALLCONV 902 FPDFAnnot_GetFocusableSubtypesCount(FPDF_FORMHANDLE hHandle); 903 904 // Experimental API. 905 // Get the list of focusable annotation subtype as set by host. 906 // 907 // hHandle - handle to the form fill module, returned by 908 // FPDFDOC_InitFormFillEnvironment. 909 // subtypes - receives the list of annotation subtype which can be tabbed 910 // over. Caller must have allocated |subtypes| more than or 911 // equal to the count obtained from 912 // FPDFAnnot_GetFocusableSubtypesCount() API. 913 // count - size of |subtypes|. 914 // Returns true on success and set list of annotation subtype to |subtypes|, 915 // false otherwise. 916 // Note : Annotations of type FPDF_ANNOT_WIDGET are by default focusable. 917 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 918 FPDFAnnot_GetFocusableSubtypes(FPDF_FORMHANDLE hHandle, 919 FPDF_ANNOTATION_SUBTYPE* subtypes, 920 size_t count); 921 922 // Experimental API. 923 // Gets FPDF_LINK object for |annot|. Intended to use for link annotations. 924 // 925 // annot - handle to an annotation. 926 // 927 // Returns FPDF_LINK from the FPDF_ANNOTATION and NULL on failure, 928 // if the input annot is NULL or input annot's subtype is not link. 929 FPDF_EXPORT FPDF_LINK FPDF_CALLCONV FPDFAnnot_GetLink(FPDF_ANNOTATION annot); 930 931 // Experimental API. 932 // Gets the count of annotations in the |annot|'s control group. 933 // A group of interactive form annotations is collectively called a form 934 // control group. Here, |annot|, an interactive form annotation, should be 935 // either a radio button or a checkbox. 936 // 937 // hHandle - handle to the form fill module, returned by 938 // FPDFDOC_InitFormFillEnvironment. 939 // annot - handle to an annotation. 940 // 941 // Returns number of controls in its control group or -1 on error. 942 FPDF_EXPORT int FPDF_CALLCONV 943 FPDFAnnot_GetFormControlCount(FPDF_FORMHANDLE hHandle, FPDF_ANNOTATION annot); 944 945 // Experimental API. 946 // Gets the index of |annot| in |annot|'s control group. 947 // A group of interactive form annotations is collectively called a form 948 // control group. Here, |annot|, an interactive form annotation, should be 949 // either a radio button or a checkbox. 950 // 951 // hHandle - handle to the form fill module, returned by 952 // FPDFDOC_InitFormFillEnvironment. 953 // annot - handle to an annotation. 954 // 955 // Returns index of a given |annot| in its control group or -1 on error. 956 FPDF_EXPORT int FPDF_CALLCONV 957 FPDFAnnot_GetFormControlIndex(FPDF_FORMHANDLE hHandle, FPDF_ANNOTATION annot); 958 959 // Experimental API. 960 // Gets the export value of |annot| which is an interactive form annotation. 961 // Intended for use with radio button and checkbox widget annotations. 962 // |buffer| is only modified if |buflen| is longer than the length of contents. 963 // In case of error, nothing will be added to |buffer| and the return value 964 // will be 0. Note that return value of empty string is 2 for "\0\0". 965 // 966 // hHandle - handle to the form fill module, returned by 967 // FPDFDOC_InitFormFillEnvironment(). 968 // annot - handle to an interactive form annotation. 969 // buffer - buffer for holding the value string, encoded in UTF-16LE. 970 // buflen - length of the buffer in bytes. 971 // 972 // Returns the length of the string value in bytes. 973 FPDF_EXPORT unsigned long FPDF_CALLCONV 974 FPDFAnnot_GetFormFieldExportValue(FPDF_FORMHANDLE hHandle, 975 FPDF_ANNOTATION annot, 976 FPDF_WCHAR* buffer, 977 unsigned long buflen); 978 979 // Experimental API. 980 // Add a URI action to |annot|, overwriting the existing action, if any. 981 // 982 // annot - handle to a link annotation. 983 // uri - the URI to be set, encoded in 7-bit ASCII. 984 // 985 // Returns true if successful. 986 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFAnnot_SetURI(FPDF_ANNOTATION annot, 987 const char* uri); 988 989 // Experimental API. 990 // Get the attachment from |annot|. 991 // 992 // annot - handle to a file annotation. 993 // 994 // Returns the handle to the attachment object, or NULL on failure. 995 FPDF_EXPORT FPDF_ATTACHMENT FPDF_CALLCONV 996 FPDFAnnot_GetFileAttachment(FPDF_ANNOTATION annot); 997 998 // Experimental API. 999 // Add an embedded file with |name| to |annot|. 1000 // 1001 // annot - handle to a file annotation. 1002 // name - name of the new attachment. 1003 // 1004 // Returns a handle to the new attachment object, or NULL on failure. 1005 FPDF_EXPORT FPDF_ATTACHMENT FPDF_CALLCONV 1006 FPDFAnnot_AddFileAttachment(FPDF_ANNOTATION annot, FPDF_WIDESTRING name); 1007 1008 #ifdef __cplusplus 1009 } // extern "C" 1010 #endif // __cplusplus 1011 1012 #endif // PUBLIC_FPDF_ANNOT_H_ 1013