Package org.faceless.pdf2

Class OptionalContentLayer

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class OptionalContentLayer
extends OptionalContentDescriptor

    This class represents an optional content layer in the PDF. Layers can be assigned to a PDFCanvas to allow that layer to be turned on or off in a PDF viewer. Layers can also be set to turn on or off under certain conditions; it's possible to create a layer which is never seen on screen but is printed, for example. Support for this functionality is missing from many PDF viewers.

    Here's an example showing how to add a "DRAFT" stamp to a page which is only visible when the PDF is printed or exported to a bitmap. 

     PDF pdf = new PDF(...);      // Read PDF from file
 // Create the "DRAFT" stamp and draw onto each page
 PDFCanvas draft = new PDFCanvas(300, 300);
 PDFStyle style = new PDFStyle();
 style.setFont(new StandardFont(StandardFont.HELVETICA), 80);
 style.setFontStyle(PDFStyle.FONTSTYLE_OUTLINE);
 draft.setStyle(style);
 draft.drawGlyphVector(style.createGlyphVector("DRAFT", null), 50, 50);
 draft.flush();
 for (PDFPage page : pdf.getPages()) {
    page.drawCanvas(draft, 100, 200, 100 + draft.getWidth(), 200 + draft.getHeight());
 }

 // Make "draft" canvas visible when printed only, and lock it.
 OptionalContentLayer layer = new OptionalContentLayer("Draft");
 layer.setDisclosed(false);      // Hide from user-interface in Acrobat
 layer.setEnabled(false);        // Turn layer off so it's invisible, but...
 layer.setPrint(OptionalContentLayer.When.Always);   // always print...
 layer.setExport(OptionalContentLayer.When.Always);  // ... and always export

 draft.setOptionalContentDescriptor(layer);   // Critical: add the layer to the canvas
 pdf.getOptionalContentLayers().add(layer);   // Critical: add the layer to the PDF
 pdf.render(new FileOutputStream("out.pdf"));
    Since:
    2.23.5

    • Constructor Detail

      • OptionalContentLayer

        public OptionalContentLayer()
        Create a new OptionalContentLayer. The name is mandatory and must be set an a separate call to setName(java.lang.String)

      • OptionalContentLayer

        public OptionalContentLayer​(java.lang.String name)
        Create a new OptionalContentLayer and set the name
        Parameters:
        name - the name

    • Method Detail

      • setEnabled

        public void setEnabled​(boolean enabled)
        Set whether this this layer is enabled by default. The default is true.
        Parameters:
        enabled - the enabled flag

      • setName

        public void setName​(java.lang.String name)
        Set the layer name.
        Parameters:
        name - , which must not be null

      • isLocked

        public boolean isLocked()
        Return the "locked" flag as set by setLocked(boolean)

      • setLocked

        public void setLocked​(boolean locked)
        Set whether the layer is locked in the viewer user-interface. Locked layers cannot have their "enabled" state changed by the user.
        Parameters:
        locked - the locked flag

      • isDisclosed

        public boolean isDisclosed()
        Return whether the layer is disclosed in the viewer, as set by setDisclosed(boolean)

      • setDisclosed

        public void setDisclosed​(boolean disclosed)
        Set whether the layer is disclosed in the viewer user-interface. Disclosed layers (the default) are listed in the user-interface and can have their properties inspected or possibly changed. Undisclosed layers are not listed in the user-interface.
        Parameters:
        disclosed - the disclosed flag

      • getView

        public OptionalContentLayer.When getView()
        Return under what conditions the layer is included when the PDF is displayed.

      • getPrint

        public OptionalContentLayer.When getPrint()
        Return under what conditions the layer is included when the PDF is printed

      • setPrint

        public void setPrint​(OptionalContentLayer.When when)
        Set under what conditions the layer is included when the PDF is printed. The default is "when enabled"

      • getExport

        public OptionalContentLayer.When getExport()
        Return under what conditions the layer is included when the PDF is exported to an image.

      • setExport

        public void setExport​(OptionalContentLayer.When when)
        Set under what conditions the layer is included when the PDF is exported to an image. The default is "when enabled"

      • getExclusions

        public java.util.Collection<OptionalContentLayer> getExclusions()

        Return the set of OptionalContentLayers of which at most one should be turned on. This functionality is similar to a "radio button" set. The default is the empty set, meaning there is no radio-button-like functionaity. Otherwise, a set of at least two entries is returned, one of which is this layer. All layers in the returned set should return the same value for this method.

        (note that prior to 2.25 this was phrased slightly differently and it was unclear whether "this" was included in the returned set. Now, for any non-empty return value, it's explicit that its always included.)

        Returns:
        either an empty set, or a set of at least two items making up the "radio button group" which includes this layer.

      • setExclusions

        public void setExclusions​(java.util.Collection<OptionalContentLayer> set)
        Set the set of OptionalContentLayers which must be turned off when this layer is turned on. Setting this value to null or an empty set makes this layer independent. Setting it to a set containing other layers will also adjust those other layers so all have the same exclusion set. The supplied set may or may not include this layer; a layer is always a member of its own exclusion group, so its presence is assumed.
        Parameters:
        set - the mutually-exclusive set of layers, including this one, to create a "radio-button" set from

      • getOptionalContentLayers

        public java.util.List<OptionalContentLayer> getOptionalContentLayers()
        Return ths list of OptionalContentLayers that are children of this layer. Nesting layers this way controls the way layers are presented in the user-interface, and nothing else. Invalid content (loops, null objects etc) are cleaned up when the PDF is saved, not before.
        Since:
        2.24.2

      • getProcessingStep

        public java.lang.String getProcessingStep()
        If this optional layer is a Processing Step, as defined by ISO19593, return the processing step as a string. See setProcessingStep(java.lang.String) for a list of defined values. Otherwise, return null.
        Since:
        2.24.3

      • setProcessingStep

        public void setProcessingStep​(java.lang.String key)
        Set the ISO19593 Processing Step this Optional Content layer represents. The key should be one of the following values:
        BrailleThe layer contains contours representing braille that is applied to the printed product after printing
        DimensionsThe layer contains contours giving indications (arrows, numbers and units) of physical sizes of items in the design.
        LegendThe layer contains PDF graphics objects outside the surface of the actual printed product containing job related data used in review and approval and other production steps.
        WhiteThe layer contains PDF graphics objects indicating application of white backing ink, such as might be used on transparent or metallic substrates.
        VarnishThe layer contains PDF graphics objects indicating application of varnish after printing.
        Structural.Cutting Processing step objects indicating where the printed artwork will be cut from the printed sheet e.g. with a guillotine cutter or die cutting device.
        Structural.PartialCuttingProcessing step objects indicating where the substrate will be cut partially i.e. not entirely through the material
        Structural.ReversePartialCuttingProcessing step objects indicating where the substrate will be cut partially i.e. not entirely through the material on the back side of the substrate
        Structural.CreasingProcessing step objects indicating where the substrate will be creased to guide subsequent folding.
        Structural.ReverseCreasingProcessing step objects indicating where the substrate will be creased on the back side of the substrate
        Structural.CuttingCreasingProcessing step objects indicating where the substrate will undergo alternating cutting and creasing
        Structural.ReverseCuttingCreasingProcessing step objects indicating where the substrate will undergo alternating cutting and creasing on the back side of the substrate
        Structural.PartialCuttingCreasingProcessing step objects indicating where the substrate will undergo alternating partial cutting and creasing
        Structural.ReversePartialCuttingCreasingProcessing step objects indicating where the substrate will undergo alternating partial cutting and creasing on the back side of the substrate
        Structural.DrillingProcessing step objects indicating locations where the substrate will be drilled and the intended size of the resulting hole.
        Structural.GluingProcessing step objects enclosing an area where glue will be applied.
        Structural.FoilStampingProcessing step objects enclosing an area where foil will be applied through hot foil stamping.
        Structural.ColdFoilStampingProcessing step objects enclosing an area where foil will be applied through cold foil stamping (i.e. using glue)
        Structural.EmbossingProcessing step objects enclosing an area where embossing will be applied.
        Structural.DebossingProcessing step objects enclosing an area where debossing will be applied.
        Structural.PerforatingProcessing step objects indicating where the substrate will be perforated.
        Structural.BleedProcessing step objects indicating the intended bleed for print.
        Structural.VarnishFreeProcessing step objects enclosing an area where it is not allowed to have varnish.
        Structural.InkFreeProcessing step objects enclosing an area where it is not allowed to have printing ink.
        Structural.InkVarnishFreeProcessing step objects enclosing an area where it is not allowed to have printing ink and where it is not allowed to have varnish.
        Structural.FoldingProcessing step objects indicating where the substrate will be folded without prior creasing.
        Structural.PunchingProcessing steps objects indicating the locations at which the substrate will be punched and the size and shape of the resulting holes.
        Structural.StaplingProcessing steps objects indicating the locations at which the substrate will be stapled or stitched, and the size of the staples or stitches to be used.
        Positions.HologramProcessing step objects that indicate the intended position of holograms.
        Positions.BarcodeProcessing step objects that indicate the intended position of barcodes
        Positions.ContentAreaProcessing step objects that indicate areas where it is allowed to place text and other graphical elements.
        Positions.CodingMarkingProcessing step objects specific to packaging that indicate areas where additional information not contained in the PDF will be printed on the packaging at a post-press stage, such as on filling lines where final products are being packed. Some examples of information that might be marked as CodingMarking include but are not limited to best before dates, lot numbers, production dates, and tracking codes.
        Positions.ImprintingProcessing step objects that indicate areas where additional information (e.g. variable data) will be printed on pre-printed shells which contain the bulk of the graphical content, as a secondary print stage prior to finishing.
        Other values are possible but have no significance. A value of null will remove any special significance from this layer
        Since:
        2.24.3

      • putLiteral

        public void putLiteral​(java.lang.String key,
                       java.lang.String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.

      • clone

        protected java.lang.Object clone()
        Overrides:
        clone in class java.lang.Object