diff options
Diffstat (limited to 'include/qpdf/QPDFObjectHandle.hh')
-rw-r--r-- | include/qpdf/QPDFObjectHandle.hh | 118 |
1 files changed, 37 insertions, 81 deletions
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index 4f5cde37..967e786c 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -278,37 +278,21 @@ class QPDFObjectHandle StringDecrypter* decrypter, QPDF* context); - // Helpers for parsing content streams - - // Parse a page's contents through ParserCallbacks, described - // above. This method works whether the contents are a single - // stream or an array of streams. Call on a page object. - QPDF_DLL - void parsePageContents(ParserCallbacks* callbacks); - - // Pass a page's contents through the given TokenFilter. If a - // pipeline is also provided, it will be the target of the write - // methods from the token filter. If a pipeline is not specified, - // any output generated by the token filter will be discarded. Use - // this interface if you need to pass a page's contents through - // filter for work purposes without having that filter - // automatically applied to the page's contents, as happens with - // addContentTokenFilter. See examples/pdf-count-strings.cc for an - // example. - QPDF_DLL - void filterPageContents(TokenFilter* filter, Pipeline* next = 0); - - // Pipe a page's contents through the given pipeline. This method - // works whether the contents are a single stream or an array of - // streams. Call on a page object. + // Older method: stream_or_array should be the value of /Contents + // from a page object. It's more convenient to just call + // QPDFPageObjectHelper::parsePageContents on the page object, and + // error messages will also be more useful because the page object + // information will be known. QPDF_DLL - void pipePageContents(Pipeline* p); + static void parseContentStream(QPDFObjectHandle stream_or_array, + ParserCallbacks* callbacks); // When called on a stream or stream array that is some page's // content streams, do the same as pipePageContents. This method - // is a lower level way to do what pipePageContents does, but it - // allows you to perform this operation on a contents object that - // is disconnected from a page object. The description argument + // is a lower level way to do what + // QPDFPageObjectHelper::pipePageContents does, but it allows you + // to perform this operation on a contents object that is + // disconnected from a page object. The description argument // should describe the containing page and is used in error // messages. The all_description argument is initialized to // something that could be used to describe the result of the @@ -318,32 +302,33 @@ class QPDFObjectHandle void pipeContentStreams(Pipeline* p, std::string const& description, std::string& all_description); - // Older method: stream_or_array should be the value of /Contents - // from a page object. It's more convenient to just call - // parsePageContents on the page object, and error messages will - // also be more useful because the page object information will be - // known. - QPDF_DLL - static void parseContentStream(QPDFObjectHandle stream_or_array, - ParserCallbacks* callbacks); - - // Attach a token filter to a page's contents. If the page's - // contents is an array of streams, it is automatically coalesced. - // The token filter is applied to the page's contents as a single - // stream. - QPDF_DLL - void addContentTokenFilter(PointerHolder<TokenFilter> token_filter); - // As of qpdf 8, it is possible to add custom token filters to a // stream. The tokenized stream data is passed through the token // filter after all original filters but before content stream // normalization if requested. This is a low-level interface to // add it to a stream. You will usually want to call - // addContentTokenFilter instead, which can be applied to a page - // object, and which will automatically handle the case of pages - // whose contents are split across multiple streams. + // QPDFPageObjectHelper::addContentTokenFilter instead, which can + // be applied to a page object, and which will automatically + // handle the case of pages whose contents are split across + // multiple streams. void addTokenFilter(PointerHolder<TokenFilter> token_filter); + // Legacy helpers for parsing content streams. These methods are + // not going away, but newer code should call the correspond + // methods in QPDFPageObjectHelper instead. The specification and + // behavior of these methods are the same as the identically named + // methods in that class, but newer functionality will be added + // there. + QPDF_DLL + void parsePageContents(ParserCallbacks* callbacks); + QPDF_DLL + void filterPageContents(TokenFilter* filter, Pipeline* next = 0); + QPDF_DLL + void pipePageContents(Pipeline* p); + QPDF_DLL + void addContentTokenFilter(PointerHolder<TokenFilter> token_filter); + // End legacy content stream helpers + // Type-specific factories QPDF_DLL static QPDFObjectHandle newNull(); @@ -731,51 +716,22 @@ class QPDFObjectHandle QPDF_DLL std::string unparseResolved(); - // Convenience routines for commonly performed functions - - // Returns an empty map if there are no images or no resources. - // This function does not presently support inherited resources. - // If this is a significant concern, call - // pushInheritedAttributesToPage() on the QPDF object that owns - // this page. See comment in the source for details. Return value - // is a map from XObject name to the image object, which is always - // a stream. + // Legacy helper methods for commonly performed operations on + // pages. Newer code should use QPDFPageObjectHelper instead. The + // specification and behavior of these methods are the same as the + // identically named methods in that class, but newer + // functionality will be added there. QPDF_DLL std::map<std::string, QPDFObjectHandle> getPageImages(); - - // Returns a vector of stream objects representing the content - // streams for the given page. This routine allows the caller to - // not care whether there are one or more than one content streams - // for a page. QPDF_DLL std::vector<QPDFObjectHandle> getPageContents(); - - // Add the given object as a new content stream for this page. If - // parameter 'first' is true, add to the beginning. Otherwise, add - // to the end. This routine automatically converts the page - // contents to an array if it is a scalar, allowing the caller not - // to care what the initial structure is. You can call - // coalesceContentStreams() afterwards if you want to force it to - // be a single stream. QPDF_DLL void addPageContents(QPDFObjectHandle contents, bool first); - - // Rotate a page. If relative is false, set the rotation of the - // page to angle. Otherwise, add angle to the rotation of the - // page. Angle must be a multiple of 90. Adding 90 to the rotation - // rotates clockwise by 90 degrees. QPDF_DLL void rotatePage(int angle, bool relative); - - // Coalesce a page's content streams. A page's content may be a - // stream or an array of streams. If this page's content is an - // array, concatenate the streams into a single stream. This can - // be useful when working with files that split content streams in - // arbitrary spots, such as in the middle of a token, as that can - // confuse some software. You could also call this after calling - // addPageContents. QPDF_DLL void coalesceContentStreams(); + // End legacy page helpers // Issue a warning about this object if possible. If the object // has a description, a warning will be issued. Otherwise, if |