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