diff options
author | Jay Berkenbilt <ejb@ql.org> | 2019-01-29 03:53:55 +0100 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2019-01-29 03:53:55 +0100 |
commit | 2d0885bc119af035ab2df4d8c19000408223ae7f (patch) | |
tree | 2801e45bcfbd58f42472c4b2212f828032e38992 /include | |
parent | 2712869cf96916bceeac7def35b6d0a54bd10316 (diff) | |
download | qpdf-2d0885bc119af035ab2df4d8c19000408223ae7f.tar.zst |
Clarify documentation for copyForeignObject regarding pages
Make explicit that copyForeignObject can be used on page objects and
will copy them properly but not update the pages tree.
Diffstat (limited to 'include')
-rw-r--r-- | include/qpdf/QPDF.hh | 23 | ||||
-rw-r--r-- | include/qpdf/QPDFPageDocumentHelper.hh | 7 |
2 files changed, 21 insertions, 9 deletions
diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh index cfb10aac..329c2756 100644 --- a/include/qpdf/QPDF.hh +++ b/include/qpdf/QPDF.hh @@ -301,12 +301,18 @@ class QPDF // // The return value of this method is an indirect reference to the // copied object in this file. This method is intended to be used - // to copy non-page objects and will not copy page objects. To - // copy page objects, pass the foreign page object directly to - // addPage (or addPageAt). If you copy objects that contain - // references to pages, you should copy the pages first using - // addPage(At). Otherwise references to the pages that have not - // been copied will be replaced with nulls. + // to copy non-page objects. To copy page objects, pass the + // foreign page object directly to addPage (or addPageAt). If you + // copy objects that contain references to pages, you should copy + // the pages first using addPage(At). Otherwise references to the + // pages that have not been copied will be replaced with nulls. It + // is possible to use copyForeignObject on page objects if you are + // not going to use them as pages. Doing so copies the object + // normally but does not update the page structure. For example, + // it is a valid use case to use copyForeignObject for a page that + // you are going to turn into a form XObject, though you can also + // use QPDFPageObjectHelper::getFormXObjectForPage for that + // purpose. // When copying objects with this method, object structure will be // preserved, so all indirectly referenced indirect objects will @@ -930,9 +936,10 @@ class QPDF QPDFObjectHandle& stream_dict, bool is_attachment_stream, std::vector<PointerHolder<Pipeline> >& heap); - // Methods to support object copying + // Unused copyForeignObject -- remove at next ABI change QPDFObjectHandle copyForeignObject( - QPDFObjectHandle foreign, bool allow_page); + QPDFObjectHandle foreign, bool unused); + // Methods to support object copying void reserveObjects(QPDFObjectHandle foreign, ObjCopier& obj_copier, bool top); QPDFObjectHandle replaceForeignIndirectObjects( diff --git a/include/qpdf/QPDFPageDocumentHelper.hh b/include/qpdf/QPDFPageDocumentHelper.hh index b49d9652..096a401c 100644 --- a/include/qpdf/QPDFPageDocumentHelper.hh +++ b/include/qpdf/QPDFPageDocumentHelper.hh @@ -73,7 +73,12 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper // indirect. If it is an indirect object from another QPDF, this // method will call pushInheritedAttributesToPage on the other // file and then copy the page to this QPDF using the same - // underlying code as copyForeignObject. + // underlying code as copyForeignObject. Note that you can call + // copyForeignObject directly to copy a page from a different + // file, but the resulting object will not be a page in the new + // file. You could do this, for example, to convert a page into a + // form XObject, though for that, you're better off using + // QPDFPageObjectHelper::getFormXObjectForPage. QPDF_DLL void addPage(QPDFPageObjectHelper newpage, bool first); |