[jira] [Created] (PDFBOX-3084) More generic PDPageContentStream constructor

["Michael Klink (JIRA)" <ji...@apache.org>]

Michael Klink created PDFBOX-3084:
-------------------------------------

             Summary: More generic PDPageContentStream constructor
                 Key: PDFBOX-3084
                 URL: https://issues.apache.org/jira/browse/PDFBOX-3084
             Project: PDFBox
          Issue Type: Improvement
          Components: PDModel
    Affects Versions: 1.8.10, 2.0.0
            Reporter: Michael Klink


h3. A missing option

There already are numerous constructors of the {{PDPageContentStream}} class

{code}
public PDPageContentStream(PDDocument document, PDPage sourcePage)

public PDPageContentStream(PDDocument document, PDPage sourcePage,
    boolean appendContent, boolean compress)

public PDPageContentStream(PDDocument document, PDPage sourcePage,
    boolean appendContent, boolean compress, boolean resetContext)
{code}

_(focusing on *page* content streams)_

which still fail to cover all relevant cases, foremost the case of _prepending_ a new stream to create new background material.

Prepending a new stream has been requested by users e.g. on stackoverflow

* [how to add background image to PDF using PDFBox?|http://stackoverflow.com/q/33406920/1729265]
* [How to underlay a content stream with using PDPageContentStream?|http://stackoverflow.com/q/28502226/1729265]

Furthermore PDFBox code itself internally at some places prepends a new content stream, mostly to prepend a save-graphics-state operation before the existing content.

----

h3. A proposal

To not introduce yet another explicit flag parameter, I'd propose creating a new constructor which accepts an {{EnumSet}} parameter for an enumeration of flags ({{compress}}, {{prepend}}, {{append}}, {{reset}}, ...) instead of all those flag parameters. The former constructors could then be deprecated.

{code}
public PDPageContentStream(PDDocument document, PDPage sourcePage,
    EnumSet<StreamOptions> streamOptions)
{code}

There obviously are combinations in which some option does not make sense, e.g. {{reset}} without  {{prepend}} or {{append}}. These may either be silently ignored or rejected with some exception.

----

h3. Thinking this even further

One might even consider to make this more generic by allowing one additional parameter which may be an integer or a content stream. This constructor variant could interpret {{prepend}} and {{append}} as respectively _before_ or _after the indicated existing page content stream_.

In this case even a {{replace}} option would make sense.

I have not yet seen actual requests for a feature requiring this constructor variant, though.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org