Wraps FPDFAnnot_AppendObject. The page-object becomes part of the
annotation's appearance stream, which PDFium regenerates straight
away.
Arguments
- annot
A
pdfium_annotof subtype"ink"or"stamp", the only subtypes PDFium lets hold page-objects (FPDFAnnot_IsObjectSupportedSubtype). Parent doc must be readwrite.- obj
A
pdfium_objthat is a top-level object of the page handleannotbelongs to, e.g. frompdf_rect_new()orpdf_page_objects()on that page. Objects nested in a form XObject (pdf_form_objects()), objects already inside an annotation (pdf_annot_objects()) and objects on another page are rejected.
Details
PDFium takes ownership of the object it is given and expects it to
be free-standing, but every page-object creator in this package
(pdf_path_new(), pdf_rect_new(), pdf_text_new(),
pdf_image_new(), ...) inserts its object into a page. This
function therefore moves the object: it takes obj off the
annotation's page (FPDFPage_RemoveObject) and then appends it to
annot, so exactly one of them owns the object at any time.
After the call obj is no longer on the page and its handle is
closed, as are the clip paths read from it with
pdf_obj_clip_path() and, for a form object, the objects read from
it with pdf_form_objects(); reach the object through
pdf_annot_objects() instead. Other handles to the same object
(for example from an earlier pdf_page_objects() call) are stale
and must not be used, and the
page-scoped indices of the remaining page-objects shift down by
one. The move only succeeds as a whole: when annot cannot hold
page-objects, or obj is not a top-level object of the
annotation's page, nothing changes and the function errors.